Command Reference

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 · Connections · Agents · Flows and Runs · Processes · Triggers · Knowledge and RAG · Security and Governance · Costs and Observability · Chat · Configuration · Migrating · Deploying.

Core workspace

Authentication and credentials

Agents

Flows and runs

Pipelines

Triggers

Configuration

Deploying and operating

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:

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

Packs

Templates

Marketplace

Tools

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

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.

Security & governance

Sandbox

Costs

Audit

Compliance

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.

Admin

Dev and coding-agent

Chat

chat opens an interactive or streaming session with the workspace assistant. Walkthrough (one-shot, --interactive, --tui, sessions): Chat and Interactive Shell. Slash-command reference: Interactive shell below.

Copilot

Slash/mention parsing and proactive cards via the sidecar.

Telemetry

---

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 below. Slash commands mirror the scriptable surface and remember the last list you viewed, so you can select by number:

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:

  {
    "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.

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:

Exit codes

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

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 — install, doctor, shell completion, CI tokens
• Using the App — screen guides for the same workspace
• 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.