Command Reference

A concise table of every top-level agentskit-os command with a one-line description.

All commands accept --help for detailed usage. Commands marked with a sidecar requirement need agentskit-os serve to be running.

Core workspace

Command	Description
`init [dir]`	Scaffold a new AKOS workspace (config, `.agentskitos/`, `.gitignore`)
`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
`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 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`	View the audit trail of lifecycle transitions for an agent
`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
`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 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
`runs retention prune`	Prune run records beyond the configured retention policy

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

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 `agentskit-os.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 to external agents over MCP
`migrate-to-cloud`	Migrate local workspace data to Postgres and S3
`snapshot schedule`	Persist a snapshot scheduling and retention policy

Marketplace

Command	Description
`marketplace search`	List and filter available marketplace domain packs
`marketplace install <packId>`	Apply a domain pack to the workspace (requires sidecar)

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)

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`)
`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>`	RAG retrieval (`--source`, `--top-k`, `--json`)
`rag ingest <id>`	Re-index (ingest) an existing source
`rag status`	Indexer readiness for every source

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

Costs

Command	Description
`costs summary`	Aggregate spend over a window (`--from`, `--to`, `--provider`, `--role`, `--json`)
`costs breakdown`	Per-provider / per-agent spend breakdown (same filters)
`costs budgets`	List configured spend budgets and thresholds (`--json`)

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)

Observability

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
`observability logs`	Snapshot active anomalies (`--workspace`, `--json`)
`observability status`	Telemetry exporter + anomaly-rule + cost-meter snapshot (`--json`)

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)

akos chat --interactive (or akos with no args on a TTY) opens a portable readline shell. 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
`/workspaces`, `/workspace <id\|n>`	List / switch workspace
`/sessions`, `/use <id\|n>`, `/new`	List / switch / create a chat session
`/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
`/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
`/history`, `/clear`	Print / clear the local transcript
`/quit`	Exit (Ctrl-C / Ctrl-D also exit gracefully)

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 older commands additionally use command-specific codes, documented per command: 3 (file read error), 4 (conflict / already exists), 5 (lockfile drift, for sync), 6 (unsatisfied governance gate), 7 (missing credentials), 8 (registry entry not found).

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