---
title: "CLI & TUI"
description: "Drive Carina from the terminal — CLI golden path and interactive TUI surface."
source: https://carina.nebutra.com/use/cli-tui/
---

# CLI & TUI

> Drive Carina from the terminal — CLI golden path and interactive TUI surface.

The CLI and TUI share the same daemon, policy kernel, and audit trail as JSON-RPC.

## Golden path

    ```bash frame="none"
    carina doctor
    ```

    ```bash frame="none"
    cd /path/to/repo
    carina run "your task"
    # or interactive:
    carina
    ```
    `carina run` creates a **safe-edit** session in `cwd` and waits for the task (unless `--background`).
    Bare `carina` opens the interactive TUI and **auto-starts** the daemon when needed.

    ```bash frame="none"
    carina sessions
    carina audit SESSION
    carina audit verify SESSION
    carina patch list SESSION
    ```

## Interactive TUI

Open with `carina` (TTY required). This is the primary operator surface for the **0.8** line.

### Discoverability

| Input | Behavior |
| --- | --- |
| `?` | Toggle the help surface (same content as `/help`) |
| `/` | Open the slash-command palette (type to filter) |
| `Esc` | Close overlays / dismiss |
| `Ctrl-C` | Interrupt the active run (default; remappable) |
| `Ctrl-O` | Expand truncated tool output (default; remappable) |

Footer status often shows help/command hints, plus **context pressure** (`ctx%` / estimates), **HITL** approval state, and **queue depth** when relevant. Prefer the on-screen footer over memorizing keys.

### Slash commands

Registered in the TUI (`crates/carina-tui/src/command.rs`). `/exit` aliases `/quit`. Dynamic skill commands (e.g. `/review`) appear when the daemon registers them.

| Command | Purpose |
| --- | --- |
| `/settings` | Open settings |
| `/status` | Runtime and session status |
| `/context` | Context pressure and compaction receipt detail |
| `/changes` | Review patch transactions, files, hunks, and rollback |
| `/density` | Toggle Compact / Comfortable transcript density |
| `/symbols` | Preview and choose terminal symbols |
| `/provider` | Choose or reconfigure a provider |
| `/model` | Choose a model |
| `/plan` | Toggle plan mode (exit may require governed approval) |
| `/build` | Switch to build mode |
| `/sessions` | Browse sessions |
| `/import` | Import local Claude Code or Codex conversations |
| `/resume` | Resume a session |
| `/cancel` | Cancel the active run (only when a run is active) |
| `/queue` | Inspect / drop follow-up execution queue |
| `/minimal` | Screen mode: minimal chrome |
| `/fullscreen` | Screen mode: fullscreen review |
| `/inline` | Screen mode: inline / capability fallback |
| `/keymap` | Keybinding reference |
| `/doctor` | Health checks and recovery UI |
| `/help` | Full help surface |
| `/quit` | Quit Carina (`/exit` alias) |

List from the CLI (daemon-backed registry, includes skills when available):

```bash frame="none"
carina commands list
```

### Transcript density

<Badge variant="accent">Compact</Badge> is the default: routine successful reads collapse and verified edits stay reviewable without filling the transcript. <Badge variant="info">Comfortable</Badge> adds spacing and opens routine tool detail by default. Use `/density` or the Density row in Settings; both persist the same `tui_density` preference. An explicit expand/collapse choice always wins over the density default.

Density changes presentation only. It does not change screen mode, policy, approval state, patch identity, or daemon data.

### Terminal symbols

Open `/symbols` or choose **Symbols** in Settings to compare four preferences in place:

| Preference | Behavior |
| --- | --- |
| Automatic | Unicode by default; ASCII for established legacy-terminal safety signals |
| Unicode | Standard symbols for fonts with common Unicode coverage |
| Nerd Font | An explicit opt-in that requires Nerd Font Mono |
| ASCII | Maximum font compatibility |

The saved setting is `tui_glyphs: "auto" | "unicode" | "nerd" | "ascii"` in the normal global/project config cascade. Candidate rows preview immediately without saving; Apply commits the choice, while Esc keeps the previous one. This is presentation only and preserves the draft, transcript state, selection, disclosure, policy, and screen mode.

Automatic cannot reliably detect installed terminal fonts and never selects Nerd Font. Its conservative ASCII signals include `TERM=dumb` and legacy native Windows consoles; font coverage can still vary in Windows Terminal and on macOS or Linux. Choose the preview row that remains aligned. Boxes or misaligned symbols mean the font is missing coverage, so use ASCII as the recovery tier.

A valid `CARINA_TUI_GLYPHS=auto|unicode|nerd|ascii` has highest priority. When it is unset, a truthy legacy `CARINA_ASCII` forces ASCII ahead of the saved preference. Settings discloses when an environment override owns the active tier. `NO_COLOR` is independent: it disables product color without changing the symbol tier.

### Composer status

The composer keeps one stable two-row status surface. The first row owns the current action or recovery notice. The second row owns **Run**, **Queue**, **HITL**, **Isolation**, **Context**, and **ScreenMode**. Starting work, receiving output, or waiting for approval does not move the composer or replace those controls with a different layout.

At narrow widths, lower-priority context is compacted before governance state. Run, HITL, Isolation, and a non-zero Queue remain visible; warning or critical context pressure is also protected.

### Failure recovery

A failure cell records the model that actually served the failed run. The model
in the header is the preference for the next run, so changing it never rewrites
the history shown in an older failure.

| Action | Behavior |
| --- | --- |
| **Retry current** | Reuses the failed prompt with the session's current model and reasoning preference |
| **Replay original** | Reuses the failed run's original governed model and reasoning configuration |
| **Details** | Shows the retry root, latest run, and failure event identities |
| **Copy ID** | Copies the failure identity for audit or support |

Each retry creates a new immutable run linked to the original; it does not
overwrite the failed outcome. Related attempts stay in one failure cell with an
attempt count. Once recovery is queued, the retry actions are disabled until a
new terminal result arrives.

Actions are visible and clickable. With an empty composer and no active run,
press `Tab` to focus the newest retryable failure, use `Tab` or the arrow keys to
move, `Enter` to activate, and `Esc` to return to the composer. Existing drafts
and active-run follow-up behavior keep ownership of `Tab`.

### Review workbench

<Badge variant="accent">next</Badge>

In Fullscreen mode, `/changes` projects each patch as a transaction → file → numbered hunk review. The selected file keeps A/M/D state, addition/deletion totals, hunk attribution, and a bounded diff window. Large diffs show an explicit continuation instead of blocking the frame loop; verify and rollback still operate on the complete daemon transaction.

Rollback confirmation is bound to the exact previewed `patch_id` and `transaction_id`, and only opens while the workspace still matches that preview. Navigation is frozen until confirm or cancel, so moving a row cannot retarget a destructive action. Minimal and Inline modes keep the compact changes surface and native scrollback behavior.

### Motion & accessibility

Motion communicates active execution or background validation; static approval/input waits do not animate. Set `CARINA_REDUCED_MOTION=1` to remove decorative animation deadlines while preserving state, layout, keyboard actions, and progress text.

### Approvals in the TUI

Risky side effects surface an **approval overlay** (dual-axis HITL: isolation + approval queue). You can also resolve from another terminal:

```bash frame="none"
carina approve SESSION DECISION_ID
carina deny SESSION DECISION_ID "reason"
```

See [Policy](/concepts/policy/).

### Keybindings

Defaults live in the TUI; project/global config can override via `tui_keybindings` (see product config). Prefer the on-screen footer, `?`, and `/keymap` over memorizing keys.

## CLI command groups

| Area | Commands |
| --- | --- |
| Lifecycle | `init`, `status`, `doctor`, `update`, `daemon *`, `runtime *`, `runtimes` |
| Work | `run`, `ask`, `resume`, `fork`, `steer`, `answer`, `import *` |
| Inspect | `sessions`, `items`, `watch`, `cost`, `session review`, `checkpoint *` |
| Governance | `approve`, `deny`, `profile`, `audit*`, `patch*`, `report`, `export` |
| Orchestration | `workflow *`, `worker *`, `schedule *` |
| Memory / context | `memory *`, `context *` |
| Providers | `auth *`, `providers list` |

Full tables: [CLI reference](/reference/cli/).

Conversation migration: [Import conversations](/use/import-conversations/).

## Source of truth

- Live binary: `carina --help`  
- TUI slash registry: `crates/carina-tui/src/command.rs` · capability ledger: `crates/carina-tui/CAPABILITIES.md`  
- Recipes: [Common workflows](/getting-started/common-workflows/)  

  Prefer `carina doctor` before debugging “nothing happens” — most issues are PATH, socket, or daemon down.

---
Source: https://carina.nebutra.com/use/cli-tui/
Markdown: https://carina.nebutra.com/use/cli-tui/index.md