---
title: Command Reference
description: A concise table of every top-level akos command with a one-line description.
---

All commands accept `--help` for detailed usage. Commands marked with a sidecar requirement need `akos serve` to be running (or `AKOS_HEADLESS_URL` pointing at a remote sidecar).

**Topic walkthroughs** (examples and operator loops): [Authentication](/docs/cli/authentication) · [Connections](/docs/cli/connections) · [Agents](/docs/cli/agents) · [Flows and Runs](/docs/cli/flows-and-runs) · [Processes](/docs/cli/pipelines) · [Triggers](/docs/cli/triggers) · [Knowledge and RAG](/docs/cli/knowledge-and-rag) · [Security and Governance](/docs/cli/security-governance) · [Costs and Observability](/docs/cli/costs-observability) · [Chat](/docs/cli/chat) · [Configuration](/docs/cli/configuration) · [Migrating](/docs/cli/migrating) · [Deploying](/docs/cli/deploying).

## Core workspace

| Command | Description |
|---|---|
| `init [dir]` | Scaffold a new AKOS workspace (config, `.agentskitos/`, `.gitignore`) |
| `init-ci` | Scaffold GitHub Actions CI templates for an AKOS project |
| `wizard` | Interactive first-run template wizard |
| `new [template-id]` | Scaffold a workspace from a starter template (`--list` to browse) |
| `doctor` | Diagnose the CLI environment: Node version, platform, credentials, connectivity |
| `status` | Show sidecar connection, active workspace, auth state, recent runs/triggers/anomalies |
| `workspaces list` | List sidecar workspaces and mark the active one (requires sidecar) |
| `workspaces use <id>` | Switch the active workspace (requires sidecar) |
| `workspaces create <id>` | Create a workspace; idempotent on id (requires sidecar) |
| `workspaces delete <id>` | Delete a workspace; rejects the active one. Requires `--confirm` in non-TTY (requires sidecar) |
| `workspaces clone <new-id>` | Clone the active workspace into a new id (requires sidecar) |
| `upgrade` | Check for a newer CLI version and print the upgrade command |
| `completion <shell>` | Emit a shell completion script (`bash`, `zsh`, `fish`) |
| `version` | Print the installed CLI version |

## Authentication and credentials

| Command | Description |
|---|---|
| `auth login` | Sign in via device-code OAuth and persist a session token |
| `auth logout` | Clear the persisted session token |
| `auth whoami` | Print the active session identity (requires sidecar) |
| `auth status` | Show the current auth session state |
| `tenant list` | List accessible tenants (requires `oem:tenant:admin`; falls back to current tenant) |
| `tenant use <id>` | Switch the active tenant locally; hosted/cloud switching is server-side |
| `creds list` | List known providers and their required vault keys |
| `creds check` | Verify that required credential keys are present (values never shown) |
| `creds set` | Interactively store a provider credential |
| `creds guide` | Print the guided credential onboarding playbook |
| `vault list` | List workspace secret keys stored in the vault (values hidden) |
| `vault put <key> <value>` | Write a secret to the workspace vault |
| `secrets list` | List provisioned secret keys via the sidecar (values hidden) |
| `secrets set <key> <value>` | Provision a secret headless via the sidecar |
| `connections list` | List provisioned integration connections |
| `connections get <id>` | Read a single integration connection |
| `connections guide [providerId]` | Print setup guidance from the integration registry (`--category`, `--implemented-only`) |
| `connections sql-get <id>` | Read a single SQL connection (`--json`) |
| `connections set` | Provision (create or replace) an integration connection |
| `connections rm <id>` | Remove an integration connection |

## Agents

| Command | Description |
|---|---|
| `agents list` | List inline agents from the sidecar (`--json`) |
| `agents show <id>` | Show a single inline agent (`--json`) |
| `agents run <id>` | Invoke an agent now (`--input`, `--mode`, requires `--confirm` in non-TTY) |
| `agent register` | Persist a new agent registry entry (local registry) |
| `agent list` | List agents in the local workspace registry |
| `agent from-nl <description>` | Generate an agent draft from a natural-language description |
| `agent promote` | Validate a lifecycle transition and emit an audit event |
| `agent version-list` | View the version history for an agent (`--id`, `--json`) |
| `agent bump` | Mint a new agent version (auto-suggest, manual confirm) |
| `agent diff` | Diff two agent versions (defaults to last two) |
| `agent compare <evaluations.json>` | Rank agent variants by pass rate, cost, and latency |
| `agent changelog` | View the change event history for an agent |

## Flows and runs

| Command | Description |
|---|---|
| `flow new [template-id]` | Scaffold a flow from a built-in template into a workspace config |
| `flow export <id>` | Export a flow as a portable `FlowEnvelope` JSON |
| `flow import-json <file>` | Import a `FlowEnvelope` JSON into an existing config |
| `flows list` | List inline flows in the active workspace (`--json`) |
| `flows show <id>` | Show a single inline flow (`--json`) |
| `flows validate <id>` | Validate an inline flow against the `FlowConfig` schema |
| `flows run <id>` | Run an inline flow now (`--mode`, requires `--confirm` in non-TTY) |
| `flows edit <id>` | Edit an inline flow in `$EDITOR`; validates before applying (TTY only) |
| `run [configPath]` | Execute (or resume) a flow (default mode: `dry_run`) |
| `runs list` | List recent flow runs (`--workspace`, `--status`, `--limit`, `--json`) |
| `runs get <id>` | Fetch a single run row via the sidecar (`runs.get`; null when missing) (`--json`) |
| `runs show <id>` | Enriched run detail: status, flow, timings, cost/tokens, counts, recent events (`--json`) |
| `runs watch <id>` | Follow one run's status/detail until completion (`--once`, `--json`) |
| `runs cancel <id>` | Cancel an in-flight run (requires `--confirm` in non-TTY) |
| `runs retry <id>` | Re-dispatch the flow behind a run (`--mode`, requires `--confirm` in non-TTY) |
| `runs logs <id>` | Print the span/tool event timeline of a run (`--json`) |
| `runs artifacts <id>` | List artifacts produced by a run (`--limit`, `--json`) |
| `explain` | Explain a coding run from its persisted artifact bundle |
| `whatif <runs.json>` | Project cost/latency/pass-rate impact of a hypothetical change |
| `inbox list` | List pending HITL approvals (`--status`, `--json`) |
| `inbox show <id>` | Show full approval context + risk notes (`--json`) |
| `inbox approve <id>` | Approve a pending approval (`--note`, requires `--confirm` in non-TTY) |
| `inbox reject <id>` | Reject a pending approval (`--note` reason required, `--confirm` in non-TTY) |
| `hitl list` | List human-in-the-loop escalations (alias surface of `inbox`) |
| `hitl approve <id>` | Approve an escalation |
| `hitl reject <id>` | Reject an escalation (note required) |
| `hitl reassign <id> <assignee>` | Reassign a pending escalation |
| `hitl modify <id> <proposal>` | Submit a counter-proposal for an escalation |
| `hitl dead-letter` | List HITL escalations dead-lettered by a decision-SLA timeout |
| `hitl ledger append` | Append a signed entry to the HITL ledger chain |
| `runs tail` | Stream new run entries live (poll-based; `--interval`, `--workspace`) |
| `runs retention prune` | Prune run records beyond the configured retention policy |

## Pipelines

| Command | Description |
|---|---|
| `pipelines list` | List pipelines in the workspace (`--json`) |
| `pipelines show <id>` | Show a single pipeline by id (`--json`) |
| `pipelines runs <id>` | List runs for a pipeline (`--limit`, `--json`) |
| `pipelines run <id>` | Dispatch a new pipeline run (`--mode`, `--input`, `--json`) |
| `pipelines resume <runId>` | Resume a pipeline run paused at an approval gate (`--json`) |
| `pipelines cancel <runId>` | Cancel an in-flight pipeline run (`--json`) |

## Triggers

| Command | Description |
|---|---|
| `triggers kinds` | List all supported trigger kinds |
| `triggers list` | List triggers defined in a config file |
| `triggers add` | Add a trigger to a config file |
| `triggers remove <id>` | Remove a trigger from a config file |
| `triggers test <id>` | Send a synthetic event through a trigger (requires sidecar) |
| `triggers runs <id>` | View recent executions for a trigger (requires sidecar) |
| `triggers url <id>` | Print the inbound URL for a webhook trigger (requires sidecar) |
| `triggers toggle <id>` | Enable or disable a trigger (requires sidecar) |
| `trigger preset list` | List built-in trigger presets |
| `trigger preset show <id>` | Show the configuration for a named preset |
| `triggers tail` | Stream new trigger-fired events live (poll-based; `--interval`) |
| `triggers contracts` | List every registered trigger contract via the sidecar |

## Configuration

| Command | Description |
|---|---|
| `config validate <path>` | Validate a config file against the AKOS schema |
| `config get <path> [key]` | Read a value (dotted key) from a config file, or the whole config |
| `config set <path> <key> <value>` | Set a value (dotted key); validates before writing. Requires `--confirm` in non-TTY |
| `config edit <path>` | Open a config file in `$EDITOR`; validates on save (TTY only) |
| `config diff <prev> <next>` | Show a structural diff between two config files |
| `config explain` | Show which config layer set each leaf value |
| `config migrate <path>` | Migrate a config file to the current schema version |
| `lock <configPath>` | Generate or verify `akos.lock` |
| `sync` | Check or apply version drift between the lockfile and installed packages |

## Deploying and operating

| Command | Description |
|---|---|
| `publish [dir]` | Build a signed plugin bundle for marketplace upload |
| `deploy [bundle]` | Verify asset integrity and ship a bundle to a publisher backend |
| `install <url>` | Fetch, verify, and install a plugin from a registry URL |
| `serve` | Start the local workspace sidecar (JSON-RPC over stdio) |
| `mcp-serve` | Serve the AKOS capability catalog and security tools to external agents over MCP |
| `mcp discover` | Discover MCP server definitions from local agent config files |
| `import <input>` | Translate an n8n / LangChain / LangGraph / Langflow / Flowise / Dify workflow into AKOS config (`--apply` to upsert into the workspace) |
| `migrate-to-cloud` | Migrate local workspace data to Postgres and S3 |
| `docs export` | Emit the for-agents catalog (JSON + `llms.txt`; RFC-0012) |
| `seed` | Materialise demo pack data into sidecar stores (`--vertical`, `--reset`) |
| `prod seed` | Ledgered production seeds — demo packs or assistant-knowledge folders (`--dry-run`, `--apply`, `--target demo\|assistant-knowledge`, `--force`, `--vertical`, `--base-dir`) |
| `snapshot create` | Create a workspace snapshot |
| `snapshot restore` | Restore a workspace from a snapshot |
| `snapshot schedule` | Persist a snapshot scheduling and retention policy |
| `snapshot retention` | Apply the configured retention policy and prune old snapshots |

### MCP security tools

`mcp-serve` exposes agent-operable security management (ADR-0136). An agent can
read and reconfigure the firewall, egress policy, and PII profiles at runtime —
no redeploy — via these MCP tools:

| MCP tool | Description |
|---|---|
| `firewall.rules.list` | List firewall rules (optionally by tier) |
| `firewall.rules.upsert` | Create or update a firewall rule |
| `firewall.rules.delete` | Delete a firewall rule by id |
| `firewall.rules.shadow` | Toggle a rule into/out of `dry_run` (shadow / log-only) mode |
| `egress.policy.get` / `egress.policy.set` | Read or replace the outbound network policy |
| `pii.profiles.list` / `pii.profiles.upsert` / `pii.profiles.delete` | Manage custom PII redaction profiles |

> Every security tool requires the `security:admin` capability. The MCP server
> forwards each call to the running sidecar, where the RBAC access gate
> authorizes it — an unauthorized principal receives `AUTHZ_DENIED`. There is no
> path that bypasses the gate.

## Plugins

| Command | Description |
|---|---|
| `plugins list` | List installed plugins (`--workspace`, `--json`) |
| `plugins get <id>` | Show a plugin with its capability grants (`--json`) |
| `plugins install <manifest>` | Install a plugin from a manifest |
| `plugins enable <id>` | Enable an installed plugin |
| `plugins disable <id>` | Disable an installed plugin |
| `plugins uninstall <id>` | Uninstall a plugin and remove its files |

## Packs

| Command | Description |
|---|---|
| `packs list` | List available domain packs (`--json`) |
| `packs install <id>` | Install a domain pack into the workspace |
| `packs seed` | Materialise a demo seed bundle (alias of `seed`) |

## Templates

| Command | Description |
|---|---|
| `templates list` | List starter flow templates (`--json`) |

## Marketplace

| Command | Description |
|---|---|
| `marketplace search` | List and filter available marketplace domain packs |
| `marketplace install <packId>` | Apply a domain pack to the workspace (requires sidecar) |
| `marketplace featured` | Show the editorial featured-listing rotation |
| `marketplace suggestions` | Show connection suggestions inferred from workspace + recent runs |
| `marketplace report` | File an abuse / policy report against a listing (`--listing`, `--reason`) |
| `marketplace private-library` | List private (non-marketplace) plugins available for install |
| `marketplace publisher-keys` | List pinned publisher keys with their current trust level |
| `marketplace installed` | List installed plugins for the active workspace |
| `marketplace fetch` | Fetch the marketplace catalog |
| `marketplace apply-monitoring-pack <packId>` | Apply a monitoring pack to the workspace |
| `marketplace apply-security-pack <packId>` | Apply a security pack to the workspace |

## Tools

| Command | Description |
|---|---|
| `tools list` | List built-in + plugin tools in the workspace (`--workspace`, `--json`) |
| `tools show <id>` | Show a tool descriptor: category, stability, side-effects, capabilities, args schema (`--json`) |

> Direct ad-hoc tool invocation has no sidecar contract — tools execute inside governed runs. Run a tool by adding it to a flow/agent and using `flows run` / `agents run`.

## Connectors

| Command | Description |
|---|---|
| `connectors test --workspace <id>` | Preflight connections — reports missing credential **keys** (never values), `--kind`, `--json` |

> Connection CRUD lives under `connections list/get/set/rm`. `connectors` adds the readiness check.

## Knowledge (RAG)

`knowledge` manages knowledge sources (list, add, remove, reindex, status, search). `rag` is a companion command focused on retrieval and ingestion (search, ingest, status). Both commands are real and shipped; use `knowledge` for source management and `rag` for agent-facing retrieval.

| Command | Description |
|---|---|
| `knowledge list` | List configured knowledge sources (`--json`) |
| `knowledge add <id> <location>` | Add a source (`--kind`, `--name`); loader secrets provisioned via `secrets`, never passed here |
| `knowledge remove <id>` | Remove a source and drop its index |
| `knowledge search <text>` | Search the knowledge index (alias: `query`; `--source`, `--top-k`, `--json`); see also: `rag search` |
| `knowledge reindex <id>` | Drop and re-run the digest for a source (alias: `rebuild`) |
| `knowledge status` | Indexer status for every source (`--json`) |
| `rag search <text>` | Agent-facing RAG retrieval (`--source`, `--top-k`, `--json`); see also: `knowledge search` |
| `rag ingest <id>` | Re-index (ingest) an existing source |
| `rag status` | Indexer readiness for every source (`--json`) |

## Security & governance

| Command | Description |
|---|---|
| `security policy` | Live governance posture: air-gap, firewall, PII, sandbox, RBAC, egress, audit (`--json`) |
| `security rbac` | List operator roles and assignments (`--json`) |
| `security egress` | Show the egress policy slice of the posture (`--json`) |
| `security firewall rules` | List firewall rules (`--tier`, `--shadow` for dry-run-only, `--json`) |
| `security firewall set` | Create or update a firewall rule (`--id`, `--tier`, `--pattern`, `--action`, `--shadow`, `--severity`, `--scope`, `--json`) |
| `security firewall test` | Evaluate sample text against a tier; shows enforced and shadow matches (`--text`, `--tier`, `--shadow`, `--json`) |

## Sandbox

| Command | Description |
|---|---|
| `sandbox state` | Show the active sandbox isolation level and live sandbox count |
| `sandbox policy` | Get or set the sandbox isolation policy |
| `sandbox denials` | List recent sandbox denial events (`--limit`, `--json`) |
| `sandbox preview` | Preview what a policy change would deny before applying it |

## Costs

| Command | Description |
|---|---|
| `costs summary` | Aggregate spend over a window (`--workspace`, `--window-hours`, `--json`) |
| `costs breakdown` | Detailed spend breakdown (`--group-by`, `--from`, `--to`, `--provider`, `--role`, `--workspace`, `--json`) |
| `costs budgets` | List configured spend budgets and thresholds (`--json`) |
| `costs list` | List itemized cost rows (for filtering / CSV export) (`--json`) |
| `costs alerts` | List active cost alerts derived from budget consumption (`--json`) |
| `costs usage` | Show tenant usage state from the backend usage meter (`--json`) |
| `usage status`, `usage watch` | Inspect, poll, or stream tenant usage state with `--sse`; exits non-zero when usage is exceeded or blocked |

## Audit

| Command | Description |
|---|---|
| `audit list` | List audit ledger entries (`--actor`, `--kind`, `--workspace`, `--limit`, `--json`) |
| `audit show <id>` | Show a single audit entry by id/seq |
| `audit export` | Export a signed audit batch (`--workspace`, `--limit`) |
| `audit verify` | Verify ledger integrity (hash chain + signatures); exit 1 on failure |
| `audit tail` | Follow audit entries live (see streaming commands) |

## Compliance

| Command | Description |
|---|---|
| `compliance export` | Export compliance records (e-discovery, audit export) |
| `compliance legal-hold` | Place or release a legal hold on workspace data |
| `compliance delete` | DSAR / right-to-erasure delete of data for a subject |

## Observability

`observability` covers traces, metrics, logs, and exporter status. `obs` is a companion command that adds anomaly-rule inspection not covered by `observability`. Both commands are real and shipped; neither replaces the other.

| Command | Description |
|---|---|
| `observability metrics <metric>` | Timeseries (`tokens.in`/`tokens.out`/`cost.totalUsd`/`errors.count`/`p99.latencyMs`; `--range`, `--json`) |
| `observability traces <runId>` | Span/tool event timeline for a run (`--json`) |
| `observability logs` | Snapshot active anomalies (`--workspace`, `--json`) |
| `observability status` | Telemetry exporter + anomaly-rule + cost-meter snapshot (`--json`) |
| `logs tail` | Stream live anomaly/observability events (poll-based; `--interval`, `--workspace`) |
| `obs anomaly-rules` | List structured anomaly rules with their paused state (`--json`); see also: `observability` |

## Admin

| Command | Description |
|---|---|
| `users list` | List workspace users (`--json`) |
| `users get <id>` | Show a user (`--json`) |
| `users upsert` | Create or update a user |
| `users delete <id>` | Remove a user |
| `users role <id> <role>` | Assign or revoke a role for a user |
| `teams list` | List teams (`--json`) |
| `teams get <id>` | Show a team (`--json`) |
| `teams upsert` | Create or update a team |
| `teams delete <id>` | Remove a team |
| `teams member` | Add or remove a team member |
| `teams role <id> <role>` | Assign or revoke a role for a team |
| `topologies list` | List agent topologies (`--json`) |
| `topologies upsert` | Create or update a topology |
| `topologies delete <id>` | Remove a topology |
| `topologies run <id>` | Dispatch a topology run |

## Dev and coding-agent

| Command | Description |
|---|---|
| `dev worktree` | Manage git worktrees for parallel development |
| `dev issue-pr` | Create or link a PR to a tracked issue |
| `coding-agent delegate` | Delegate a coding task to the coding agent |
| `coding-agent benchmark` | Run the coding-agent benchmark suite |
| `coding-agent conformance` | Run the coding-agent conformance checks |
| `coding-agent smoke` | Run a quick smoke test of the coding-agent surface |

## Chat

`chat` opens an interactive or streaming session with the workspace assistant. Walkthrough (one-shot, `--interactive`, `--tui`, sessions): **[Chat and Interactive Shell](/docs/cli/chat)**. Slash-command reference: [Interactive shell](#interactive-shell) below.

| Command | Description |
|---|---|
| `chat [message]` | Send a message to the workspace assistant (`--stream`, `--interactive`, `--tui`) |
| `chat sessions` | List saved chat sessions (`--json`) |
| `chat show <id>` | Show the transcript for a session (`--json`) |
| `chat cancel <id>` | Cancel an in-progress chat session |
| `chat delete <id>` | Delete a chat session and its transcript |

## Copilot

Slash/mention parsing and proactive cards via the sidecar.

| Command | Description |
|---|---|
| `copilot slash list` | List supported copilot slash commands and their dispatch methods |
| `copilot slash parse <raw>` | Parse a chat message for a leading slash command; returns the dispatch method |
| `copilot mention parse <text>` | Parse @-mentions out of a chat message |
| `copilot proactive <eventJson>` | Turn a sidecar event (JSON object) into a proactive action card, or null |

## Telemetry

| Command | Description |
|---|---|
| `telemetry status` | Show current telemetry consent state |
| `telemetry enable` | Opt in to anonymous usage telemetry |
| `telemetry disable` | Opt out of telemetry |
| `telemetry export` | Export stored telemetry events (JSON or CSV) |

---

## Interactive shell

`akos chat --interactive` (or `akos` with no args on a TTY) opens a portable
readline shell. `akos chat --tui` opens the **full-screen Ink TUI** (transcript
pane, themes, autocomplete, governance badges, proposal cards) over the *same*
slash-command registry — it requires a TTY and falls back to `chat --interactive`
otherwise. See [Full-screen TUI](#full-screen-tui-akos-chat---tui) below.
Slash commands mirror the scriptable surface and remember the last list you
viewed, so you can select by number:

| Slash | Action |
|---|---|
| `/help` | List available slash commands |
| `/session` | Show the active session ID and workspace |
| `/workspaces`, `/workspace <id\|n>` | List / switch workspace |
| `/sessions`, `/use <id\|n>`, `/new` | List / switch / create a chat session. In the `--tui`, `/sessions` opens an interactive picker (↑↓ select, ⏎ switch, Esc cancel) and switching re-loads that session's transcript |
| `/flows`, `/flow <id\|n>`, `/run-flow <id\|n>` | List / show / run a flow |
| `/agents`, `/agent <id\|n>` | List / show an agent |
| `/inbox`, `/approve <id\|n>`, `/reject <id\|n>` | List pending approvals / approve / reject |
| `/tools`, `/tool <id\|n>`, `/knowledge` | Browse tools / show a tool / list knowledge sources |
| `/runs`, `/run <id\|n>` | List recent runs / show one |
| `/tail <id\|n>` | Snapshot a run's current status + recent events |
| `/watch <id\|n>` | Follow a run until it finishes (polls to a terminal state) |
| `/logs <id\|n>` | Show a run's span/tool event timeline |
| `/artifacts <id\|n>` | List a run's artifacts |
| `/cancel <id\|n>`, `/retry <id\|n>` | Cancel / re-dispatch a run |
| `/apply <n>` | Apply the n-th proposal on the latest assistant turn (approves it so the agent materializes the flow/agent it proposed) |
| `/verticals`, `/vertical <id\|n>`, `/vertical use <id\|n>` | List the whitelabel catalog / show a vertical's config / switch the CLI's active vertical |
| `/connect`, `/connect <id\|n> <api-key>`, `/connect <id\|n> <code> <state>` | List providers / store an API key / finish a browser OAuth flow |
| `/cost`, `/logs <id\|n>` | Cost summary / run logs (also available as cockpit verbs) |
| `/theme [name]`, `/config` | Switch color theme (`ocean`, `grape`, `forest`, `ember`, `mono`, plus truecolor `midnight`, `sunset`, `nord`) / show configuration |
| `/compact`, `/export [path]` | Toggle dense spacing / save the conversation to markdown |
| `/resend` | Resend the last message (TUI built-in; distinct from the runs cockpit `/retry`) |
| `/history`, `/clear` | Print / clear the local transcript |
| `/quit` | Exit (Ctrl-C / Ctrl-D also exit gracefully) |

### Full-screen TUI (`akos chat --tui`)

The TUI layers a richer experience over the same slash commands and streaming:

- **Themes & color.** `/theme <name>` switches palettes live and persists the
  choice to `~/.akos/tui.json`. Three 24-bit truecolor palettes (`midnight`,
  `sunset`, `nord`) render on truecolor terminals and downsample elsewhere.
  Setting `NO_COLOR` forces the monochrome palette.
- **Code rendering.** Assistant markdown renders headers, lists, inline/fenced
  code with a language label and lightweight syntax highlighting.
- **Editing.** Readline-style line editing — `←`/`→`, `Ctrl+A`/`E` (start/end),
  `Ctrl+W` (delete word), `Ctrl+U`/`Ctrl+K` (kill to start/end), and `Ctrl+Y`
  (yank the last killed text). `↑`/`↓` recall input history; `Tab` completes
  `/commands` and `@mentions`.
- **Keybindings.** The discrete action keys — approve gate, cancel turn, scroll
  up/down — are configurable via `~/.akos/keys.json`. Each action maps to a chord
  `{ "ctrl": true, "char": "g" }` or `{ "key": "pageUp" }`; defaults match the
  shipped bindings, so the file is optional. Example:

  ```json
  {
    "approve": { "ctrl": true, "char": "g" },
    "cancel": { "key": "escape" },
    "scrollUp": { "key": "pageUp" },
    "scrollDown": { "key": "pageDown" }
  }
  ```

- **Governance & cost.** Header badges show pending HITL approvals and in-flight
  runs (polled); `Ctrl+G` approves the next gate inline. The footer shows session
  token usage and spend over the cost window.
- **Proposals.** When the assistant proposes a flow/agent, it renders as a card
  with the target tool, action tier, and estimated cost; `/apply <n>` approves it.
- **Resume.** A session's transcript is reloaded from the sidecar on launch and
  when switching sessions, so history is not lost. `Ctrl+C` prints how to resume.
- **Offline.** If the sidecar is unreachable the header shows an offline banner;
  the CLI auto-starts a local sidecar on first use.

## Streaming

Live, incremental output (ADR-0133). Streaming is **polling-based** today — the
sidecar transport is request/response, so there is no server-push channel yet; a
future sidecar contract can add one behind the same subscription interface.

| Command | Description |
|---|---|
| `chat <message> --stream` | Render assistant tokens incrementally as they arrive (falls back to `--wait` polling) |
| `runs tail` / `runs watch <id>` | Poll-based live run/event tails |
| `logs tail` / `audit tail` / `triggers tail` | Poll-based live event tails |

Streams are cancellable and deadline-bounded (`--timeout-ms`,
`AKOS_STREAM_INTERVAL_MS`) so they never block a CI pipeline. When streaming is
unavailable, the polling fallback remains.

## Global flags

These flags are accepted by most commands:

| Flag | Description |
|---|---|
| `--help`, `-h` | Display help for the command |
| `--json` | Emit machine-readable JSON output (where supported) |
| `--stream` | (chat) render incremental assistant tokens |

## Exit codes

Cross-cutting codes shared by the sidecar-backed command families (the
canonical contract; centralised in `os-cli`'s `lib/exit-codes.ts`):

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Runtime / network / I/O error |
| `2` | Invalid arguments, usage, or invalid config |
| `5` | Requested resource not found (run, flow, agent, tool, inbox item) |

Some commands additionally use command-specific codes, documented per command:
`3` (pre-flight / input-file read failure), `4` (conflict / already exists),
`6` (unsatisfied governance gate), `7` (missing credentials), `8` (registry
entry not found), `9` (state mismatch — stored state diverges from request),
`10` (lockfile drift — `lock --check` found drift vs the current config).

> Note: lockfile drift is exit code `10`, distinct from `5` (NOT_FOUND).

## Related topics

- **[CLI index](/docs/cli)** — install, `doctor`, shell completion, CI tokens
- **[Using the App](/docs/using-the-app)** — screen guides for the same workspace
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — governed path behind `run`, `pipelines`, and `audit`

## Server, CI, and non-TTY usage

`akos` is safe to run on headless servers, in SSH sessions, and in CI without a
graphical shell:

- **Authentication.** Set `AKOS_TOKEN` in the environment to skip the
  interactive `auth login` device-code flow. `auth login` detects the variable
  and exits `0`.
- **Machine output.** Pass `--json` to any `list`/`show`/`get`/`status` command
  for parseable stdout. Diagnostics go to stderr, so `... --json | jq` stays clean.
- **Mutations never block.** Destructive commands (`workspaces delete`,
  `config set`) require `--confirm`. In a non-TTY context they fail fast with a
  hint instead of waiting for input — they never hang a pipeline.
- **`config edit` is interactive only.** It opens `$EDITOR` and therefore
  requires a TTY. In CI use `config set <path> <key> <value> --confirm` (scripted)
  or `config validate` (read-only) instead.
- **Sidecar reachability.** Commands marked "requires sidecar" call the local
  workspace sidecar (`akos serve`). Point the CLI at a remote sidecar with
  `AKOS_HEADLESS_URL`; tune the per-call deadline with `AKOS_SIDECAR_TIMEOUT_MS`
  (default 15 000 ms). Sidecar calls have deadlines and render typed errors with
  actionable hints. `akos status` reports whether the sidecar is reachable.
- **Color.** ANSI color is disabled automatically when stdout is not a TTY, when
  `NO_COLOR` is set, or under `CI`. Set `FORCE_COLOR` to override. Watch/tail
  commands emit plain newline-delimited records suitable for log capture.