--- title: CLI Commands url: https://arcana.otnelhq.com/docs/cli --- # CLI Commands Complete reference for the Arcana CLI. Run `arcana --help` or `arcana --help` for the latest flags. Package name is `arcana-ai`; the binary is always `arcana`. ## Core ### `arcana` / `arcana run` Start an interactive agent session (TUI) or run a one-shot prompt. ```bash # Interactive TUI session arcana arcana run # One-shot prompt arcana run "explain this codebase" arcana "review open PRs for bugs" # Check system health first arcana doctor ``` ### `arcana doctor` Diagnose config, API keys, cache, and runtime environment. Run this first when something looks wrong. ```bash arcana doctor arcana doctor --web # also checks the optional web dashboard package ``` ### `arcana console login` Pair the CLI with your Arcana account via device flow (opens the browser seal at arcana.otnelhq.com). ```bash arcana console login ``` ### `arcana trust` Trust the current workspace so project plugins, tools, and local MCP servers can load. ```bash # Trust current workspace (most common) arcana trust # Trust a specific path arcana trust grant /path/to/workspace # Show trust status arcana trust status # List all trusted workspaces arcana trust list # Revoke trust for current workspace arcana trust revoke # Revoke trust for a specific path arcana trust revoke /path/to/workspace ``` ## Models & Providers ### `arcana models` List available models from detected providers. ### `arcana providers` Manage provider credentials. Keys are usually set via environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) and auto-detected. ## Sessions ### `arcana session list` List past sessions. ### `arcana history` Browse, inspect, and resume previous sessions. ```bash arcana history list arcana history show --id arcana history resume --id ``` ### `arcana stats` Usage and cost statistics. ## Memory ### `arcana memory` FTS5-powered session memory, facts, and artifacts. ```bash arcana memory search "deployment config" arcana memory sessions --limit 10 arcana memory facts arcana memory stats ``` ## Skills ### `arcana skills` List, search, and inspect skills. ```bash arcana skills list arcana skills list --query "python testing" arcana skills info --skill "python-testing" arcana skills ranked ``` ## Cron ### `arcana cron` Scheduled autonomous agent jobs. ```bash # Add jobs arcana cron add --name "review PRs" --schedule "0 */4 * * *" --prompt "review open PRs for bugs" arcana cron add --name "daily digest" --schedule "@daily" --prompt "summarize today's changes" # Manage arcana cron list arcana cron remove --id arcana cron pause --id arcana cron resume --id arcana cron run --id # run now arcana cron start # daemon (blocking) ``` ## Gateway ### `arcana gateway` Run chat adapters for Telegram, Discord, Slack, and WhatsApp. Configure tokens and allowlists in your `arcana.json` (project or `~/.config/arcana/`) — see [Gateway](/docs/gateway). Requires Pro/Enterprise license after `arcana console login`. ```bash arcana gateway arcana gateway install # platform setup helper ``` ## Server ### `arcana serve` Local headless HTTP server (loopback by default). Non-loopback binds require `ARCANA_SERVER_PASSWORD`. ```bash arcana serve arcana serve --host 127.0.0.1 --port 3000 ``` ### `arcana daemon` Background daemon that keeps sessions warm for fast startup. ```bash arcana daemon status arcana daemon stop arcana daemon start ``` ### `arcana feedback` Submit feedback about your Arcana experience. Drains the in-TUI feedback queue and records ratings, notes, and categories. ```bash arcana feedback ``` ## Configuration & Appearance ### `arcana config` Inspect and initialize configuration. ```bash arcana config show arcana config show --key provider arcana config init ``` ### `arcana theme` / `arcana lexicon` Switch between 21 built-in themes (plus an auto-generated `system` theme) and choose the interface voice. See [Themes](/docs/themes). ```bash arcana theme set --name bloodmoon arcana theme list arcana lexicon set --name plain # or: arcane (default) ``` ## MCP ### `arcana mcp` Manage Model Context Protocol servers. See [MCP & Tools](/docs/mcp) for setup guides. ```bash arcana mcp list arcana mcp add [name] arcana mcp auth [name] # OAuth login for remote servers arcana mcp logout [name] arcana mcp debug ``` ## Governance — Proof, Replay & Capabilities ### `arcana proof` Inspect and verify cryptographic RunProof records of what the agent executed. ```bash arcana proof inspect [session-id] arcana proof verify [session-id] arcana proof export [session-id] --format json ``` ### `arcana replay` ```bash arcana replay audit arcana replay deterministic ``` ### `arcana capability` Revoke a capability granted during a session. ```bash arcana capability revoke ``` ### `arcana epistemic` Inspect the epistemic record of a session: claims, assumptions, contract, obligations, and proof status. ```bash arcana epistemic claims [session-id] arcana epistemic assumptions [session-id] arcana epistemic contract [session-id] arcana epistemic obligations [session-id] arcana epistemic proof [session-id] ``` ### `arcana audit` Query audit logs. **Requires a Team or Enterprise license** — run `arcana license status` to check your plan. ```bash arcana audit events [--limit 20] [--action ] [--actor ] arcana audit status ``` ## Distributed Node ### `arcana node` Enroll this machine as an Arcana node in a distributed authority deployment. See the deployment runbook in the main repository. ```bash arcana node enroll --token --endpoint arcana node status [--json] arcana node key rotate --endpoint arcana node proof upload --endpoint arcana node sync policy|revocation --endpoint ``` ## External Runtimes ### `arcana launch` Launch an external coding agent (Codex, Claude Code, Gemini CLI) under Arcana supervision with durable evidence records. Use `--dry-run` to preview the declaration without executing. ```bash arcana launch codex arcana launch claude --dry-run arcana launch gemini --directory ./my-project ``` ## License & Proxy ### `arcana license` ```bash arcana license activate arcana license status arcana license deactivate ``` ### `arcana proxy` Inspect your Arcana proxy account. See the [Proxy API](/docs/proxy) reference. ```bash arcana proxy status arcana proxy models [query] arcana proxy usage arcana proxy balance ``` ## Agents & Plugins ### `arcana agent` ```bash arcana agent create # interactive: name, description, mode, permissions arcana agent list ``` ### `arcana plugin-store` ```bash arcana plugin-store search [query] arcana plugin-store install arcana plugin-store create arcana plugin-store publish ``` ## Web Dashboard ### `arcana web` Run the local web dashboard (enterprise package). ```bash arcana web --host 127.0.0.1 --port 3000 --open arcana web --build ``` ## Learn ### `arcana learn` Self-improving knowledge pipeline. After multi-turn sessions the agent extracts learnings into wiki files and a map of consciousness. ```bash arcana learn list arcana learn show --slug kebab-case-slug arcana learn moc ``` ## Global flags | Flag | Description | | --- | --- | | `--help` | Show help for any command | | `--version` | Print installed version | | `--json` | Machine-readable JSON output (see [JSON & Exit Codes](/docs/cli-json)) | | `--print-logs` | Print logs to stderr | | `--log-level ` | `DEBUG`, `INFO`, `WARN`, or `ERROR` | Every converted command exits with a deterministic code: `0` success, `1` user/validation error, `2` internal error. Full contract in [JSON & Exit Codes](/docs/cli-json). ## Install reminder ```bash npx arcana-ai@latest # or npm install -g arcana-ai arcana ```