# Terminal (/docs/agent-ui/components/terminal)

Use a terminal when the agent runs a shell command, so readers can follow its output while it runs and check its exit code once it's done. It's a step: a header with the command, its exit code and how long it took, over a screen with the prompt and the output.

<Example caption="Press npm test, or focus it and press Enter or Space, to hide and show the output. Focus the output and use the arrow keys to scroll it.">
<h />

```tsx
import { Terminal } from "@/components/ui/terminal";

const ESC = "\x1b";

const output = [
  `${ESC}[1m> app@1.0.0 test${ESC}[0m`,
  `${ESC}[32m✓${ESC}[0m format.test.ts ${ESC}[90m(12 tests)${ESC}[0m`,
  `${ESC}[32m✓${ESC}[0m parse.test.ts ${ESC}[90m(9 tests)${ESC}[0m`,
  `${ESC}[31m✗${ESC}[0m cache.test.ts ${ESC}[90m(1 failed)${ESC}[0m`,
  `  ${ESC}[31mExpected${ESC}[0m ${ESC}[33m"hit"${ESC}[0m, received ${ESC}[36m"miss"${ESC}[0m`,
  "",
  `${ESC}[1;31mTests: 1 failed${ESC}[0m, ${ESC}[1;32m21 passed${ESC}[0m, 22 total`,
].join("\n");

export default function TerminalExample() {
  return (
    <Terminal
      command="npm test"
      output={output}
      exitCode={1}
      durationSeconds={4.2}
      defaultOpen
      className="w-full max-w-xl"
    />
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/terminal
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/terminal-web
```

## Composition [#composition]

```text
Terminal
├── TerminalTrigger
│   ├── TerminalIcon
│   ├── TerminalTitle
│   ├── TerminalExit
│   └── TerminalMeta
└── TerminalContent
    └── div[data-terminal-screen]
        ├── div[data-terminal-header]
        │   ├── TerminalCommand
        │   └── TerminalCopy
        ├── TerminalViewport
        │   └── TerminalOutput
        │       └── TerminalLine
        └── TerminalJump
```

`TerminalTrigger` opens and closes the run, with its status mark in `TerminalIcon`, the command in `TerminalTitle`, "Exit N" in `TerminalExit` and the duration in `TerminalMeta`. `TerminalContent` holds the screen, a `div` with `data-terminal-screen` that the stylesheet draws and places **Jump to latest** in. In its header row (`data-terminal-header`), `TerminalCommand` shows the command after a `$` prompt, `TerminalCopy` copies the output, and `TerminalViewport` scrolls `TerminalOutput`, which renders a `TerminalLine` for each line in view. `TerminalJump` shows while you've scrolled away from the end.

## Usage [#usage]

### Output [#output]

Pass `command` and `output`, the whole output so far with its ANSI escapes, and pass the whole output again on each update. When it continues the last one, only the new text is parsed, so a long run streams as fast as a short one. Text styles (the 16 colors, 256-color and truecolor, bold, dim, italic, underline, strikethrough and inverse) show as styled text, never HTML. Every other escape, like a cursor move or a window title, is dropped. A lone `\r` starts its line again, so a progress bar shows its last state.

The 16 colors come from `--kind-ansi-*` tokens, like `--kind-ansi-red` and `--kind-ansi-bright-blue`, tuned to read on the screen in light and dark. Set them in your theme to use your own palette.

### Status and Exit Code [#status-and-exit-code]

Without `status`, a run is `running` until you pass `exitCode`, then `complete` for 0 and `error` for anything else. A running step opens and shows a cursor after its last line; once it completes, it closes to its header, and a failed run stays open. A person who opens or closes it keeps it that way. Pass `durationSeconds` to show how long it took. The outcome is announced once: "npm test complete", or "npm test failed, exit code 1". Lines aren't announced.

```tsx
<Terminal command="npm run build" output={output} exitCode={done ? code : undefined} />
```

### Following the End [#following-the-end]

While new output arrives, the view stays at the end. Scroll up and it stays where you are while lines keep arriving, and **Jump to latest** appears; press it to go back to the end and follow again. Only the lines in view are rendered, so thousands of lines scroll as smoothly as ten. The screen grows with the output up to `--kind-terminal-max-height` (20rem), then scrolls.

### Copying [#copying]

**Copy output** shows once there's output, copies it without its escapes and shows a check for 2 seconds. Pass `onCopy` to hear about it; cancel its `details` to copy something else yourself.

### Keyboard and Motion [#keyboard-and-motion]

Tab reaches the header, **Copy output** and the output, which scrolls with the arrow keys, Page Up and Page Down. The screen opens and closes with the step's height animation; under `prefers-reduced-motion`, or with `motion="reduced"`, it fades over 120 ms and the cursor stops blinking, and with `motion="none"` nothing moves.

## API Reference [#api-reference]

### TerminalOptions

| Prop               | Type                                                                                   | Description                                                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind?`            | `string \| undefined`                                                                  | Written as `data-kind`, for styling by step type.                                                                                                                                              |
| `open?`            | `boolean \| undefined`                                                                 | Whether the content shows. Passing it controls it: change it in `onOpenChange`.                                                                                                                |
| `defaultOpen?`     | `boolean \| undefined`                                                                 | Whether the content shows at first, when `open` isn't passed. Defaults to open while `status` is `running` or `awaiting-input`, unless `autoOpen` is `"never"`.                                |
| `onOpenChange?`    | `((open: boolean, details: ChangeDetails<StepOpenChangeReason>) => void) \| undefined` | Called when the step opens or closes, with what caused it.                                                                                                                                     |
| `autoOpen?`        | `"never" \| "running"`                                                                 | With `"running"`, the step opens while running or awaiting input and closes on completion, until someone toggles it. With `"never"`, only a person or your code opens it. Default: `"running"` |
| `durationSeconds?` | `number \| undefined`                                                                  | Written as `--kind-step-duration`.                                                                                                                                                             |
| `motion?`          | `"auto" \| "none" \| "reduced"`                                                        | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                   |
| `command?`         | `string \| undefined`                                                                  | The command that ran, shown after the prompt. Also the title, unless `label` is set. Default: `""`                                                                                             |
| `output?`          | `string \| undefined`                                                                  | Everything the command printed so far, ANSI escapes included. Pass the whole output on each update: when it continues the last one, only the new text is parsed. Default: `""`                 |
| `exitCode?`        | `number \| undefined`                                                                  | The command's exit code, once it has finished. Shown as "Exit N".                                                                                                                              |
| `status?`          | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"`   | Defaults to `running` without an `exitCode`, then `complete` for 0 and `error` for any other code.                                                                                             |
| `label?`           | `string \| undefined`                                                                  | Replaces the title, which is the command, and names the run in announcements.                                                                                                                  |
| `onCopy?`          | `((output: string, details: ChangeDetails<TerminalCopyReason>) => void) \| undefined`  | Called before the output is copied, without its escapes. Cancel it to copy something else yourself.                                                                                            |

### Agent [#agent]

An agent connected with `createAgent` finds the run by its title, the command unless you pass `label`, and reads `open`, `status` and `following`. It can `expand` and `collapse` the run and, once there's output, `copy` it, which calls `onCopy` too.

### TerminalAgentActions

| Prop       | Type                                                 | Description                                                                                                                   |
| ---------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | `() => boolean`                                      | Opens the step. Returns whether the change was accepted.                                                                      |
| `collapse` | `() => boolean`                                      | Closes the step. Returns whether the change was accepted.                                                                     |
| `copy`     | `((event?: Event) => Promise<boolean>) \| undefined` | Copies the output without its escapes, and resolves with whether the clipboard write went through. Only while there's output. |

<Caption>
Runs in React and Web Components. On `<kind-terminal>`, set `output` as a property; the other props are kebab-case attributes. `onOpenChange` is the `openchange` event and `onCopy` is `terminalcopy`.
</Caption>