# Terminal
> Simulated shell with phosphor-flash output, dotted progress bars and a glowing block caret; runs a set of built-in demo commands.
- Element: `<hf-terminal>`
- React: `import { HfTerminal } from "@/components/lumesec/hf-terminal"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-terminal.json
- Page: https://elements.lumesec.ai/components/pixel-hd/terminal



Live preview: https://elements.lumesec.ai/view/hf-terminal

```html
<hf-terminal autorun="test"></hf-terminal>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-terminal
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-terminal.json
```

## Usage

React:

```tsx
import { HfTerminal } from "@/components/lumesec/hf-terminal";

export function Example() {
  return (
    <HfTerminal autorun="test" />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-terminal.js"></script>

<hf-terminal autorun="test"></hf-terminal>
```

## Behaviour

A real little shell: type `help`, `test`, `deploy` or `ultracode`. Output lines flash like phosphor, progress bars are drawn in dots and the block caret glows.

## API reference

### Attributes

| Attribute | React prop | Type     | Default | Description                                                         |
| --------- | ---------- | -------- | ------- | ------------------------------------------------------------------- |
| `autorun` | `autorun`  | `string` | —       | Command typed automatically 0.9 s after the element first connects. |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event     | React prop  | Detail                | Description                                                                   |
| --------- | ----------- | --------------------- | ----------------------------------------------------------------------------- |
| `command` | `onCommand` | `{ command: string }` | Fires when a non-empty command runs, before its output. `command` is trimmed. |

### Methods

Call them on the element, for example through a React ref.

| Method                                           | Description                                                                                     |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `exec(command: string): Promise<void>`           | Runs a command as if it were typed and Enter pressed. Ignored while another command is running. |
| `type(command: string): Promise<void>`           | Types the command into the prompt character by character, then runs it.                         |
| `print(text: string, cls?: string): HTMLElement` | Appends an output line and returns it. `cls` can be `dim`, `ok`, `err` or `acc` to colour it.   |

## Keyboard

| Keys                | Action                                             |
| ------------------- | -------------------------------------------------- |
| Enter               | Run the typed command.                             |
| ArrowUp / ArrowDown | Step back and forward through the command history. |

## Accessibility

* The output area has `role="log"` and `aria-live="polite"`.
* The command input has `aria-label="Terminal command"`; the prompt glyph is `aria-hidden`.
* The input is disabled while a command runs, and focus returns to it afterwards if it had focus.
* Progress rows carry an `aria-label` (`tests`, `build`, `upload` or the agent name) and show the percentage as text.
* Reduced motion: waits are capped at 60 ms, so typing and progress finish almost at once, bars fill without easing and the caret does not blink; the brief flash behind new lines still shows.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground` and `--lumesec`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg`, `--ui-font` and `--ui-mono`.

## Notes

* Commands and output are built-in demo content: `help`, `ls`, `test` (also `npm … test`), `deploy`, `ultracode` and `clear`. Anything else prints `command not found`.
* The terminal uses fixed dark colours in both themes.
* The output area is 196px tall and keeps the last 120 lines.