> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# TerminalHandle

> Handle for controlling and monitoring terminals created via createTerminal

## Overview

Handle for controlling and monitoring a terminal created via `createTerminal`.

Provides methods to:

* Get current output without waiting
* Wait for command completion
* Kill the running command
* Release terminal resources

**Important:** Always call `release()` when done with the terminal to free resources.

The terminal supports async disposal via `Symbol.asyncDispose` for automatic cleanup. You can use `await using` to ensure the terminal is automatically released when it goes out of scope.

## Constructor

```typescript theme={null}
constructor(
  public id: string,
  sessionId: string,
  conn: Connection
)
```

Creates a new terminal handle. This is typically not called directly - use `AgentSideConnection.createTerminal()` instead.

<ParamField path="id" type="string" required>
  The terminal ID
</ParamField>

<ParamField path="sessionId" type="string" required>
  The session ID this terminal belongs to
</ParamField>

<ParamField path="conn" type="Connection" required>
  The underlying connection object
</ParamField>

## Properties

### id

```typescript theme={null}
id: string
```

The unique identifier for this terminal. This ID can be used in `ToolCallContent` with type "terminal" to embed the terminal in tool calls.

## Methods

### currentOutput

```typescript theme={null}
async currentOutput(): Promise<TerminalOutputResponse>
```

Gets the current terminal output without waiting for the command to exit.

Returns immediately with the current state of the terminal, including any output generated so far. If the command has already exited, the exit status will be included.

<ResponseField name="response" type="TerminalOutputResponse">
  The current terminal output and exit status (if available)
</ResponseField>

### waitForExit

```typescript theme={null}
async waitForExit(): Promise<WaitForTerminalExitResponse>
```

Waits for the terminal command to complete and returns its exit status.

This method blocks until the command finishes execution and provides the final exit code or signal information.

<ResponseField name="response" type="WaitForTerminalExitResponse">
  The exit status of the terminal command
</ResponseField>

### kill

```typescript theme={null}
async kill(): Promise<KillTerminalResponse>
```

Kills the terminal command without releasing the terminal.

The terminal remains valid after killing, allowing you to:

* Get the final output with `currentOutput()`
* Check the exit status
* Release the terminal when done

Useful for implementing timeouts or cancellation.

<ResponseField name="response" type="KillTerminalResponse">
  An empty object on success
</ResponseField>

### release

```typescript theme={null}
async release(): Promise<ReleaseTerminalResponse | void>
```

Releases the terminal and frees all associated resources.

If the command is still running, it will be killed. After release, the terminal ID becomes invalid and cannot be used with other terminal methods.

Tool calls that already reference this terminal will continue to display its output.

**Important:** Always call this method when done with the terminal.

<ResponseField name="response" type="ReleaseTerminalResponse | void">
  An empty object on success
</ResponseField>

### \[Symbol.asyncDispose]

```typescript theme={null}
async [Symbol.asyncDispose](): Promise<void>
```

Async disposal method for automatic resource cleanup.

This allows the terminal to be used with `await using` syntax for automatic cleanup:

```typescript theme={null}
// Terminal is automatically released when it goes out of scope
await using terminal = await connection.createTerminal({
  sessionId: 'session-123',
  command: 'npm test'
});

const output = await terminal.currentOutput();
// terminal.release() is called automatically at the end of the block
```

<ResponseField name="Promise<void>" type="Promise<void>">
  A promise that resolves when the terminal has been released
</ResponseField>