CLI & TUI

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

Golden path

1. Doctor

   carina doctor

2. Run or open TUI

   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.

3. Inspect

   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):

carina commands list

Transcript density

Compact is the default: routine successful reads collapse and verified edits stay reviewable without filling the transcript. Comfortable 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

next

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:

carina approve SESSION DECISION_ID
carina deny SESSION DECISION_ID "reason"

See 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.

Conversation migration: 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

Tip

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