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.

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

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

arcana console login

arcana trust

Trust the current workspace so project plugins, tools, and local MCP servers can load.

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

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.

arcana memory search "deployment config"
arcana memory sessions --limit 10
arcana memory facts
arcana memory stats

Skills

arcana skills

List, search, and inspect skills.

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.

# 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. Requires a Pro license or higher after arcana console login.

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.

arcana serve
arcana serve --host 127.0.0.1 --port 3000

arcana daemon

Background daemon that keeps sessions warm for fast startup.

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.

arcana feedback

Configuration & Appearance

arcana config

Inspect and initialize configuration.

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.

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 for setup guides.

arcana mcp list
arcana mcp add [name]
arcana mcp auth [name]      # OAuth login for remote servers
arcana mcp logout [name]
arcana mcp debug <name>

Governance — Proof, Replay & Capabilities

arcana proof

Inspect and verify cryptographic RunProof records of what the agent executed.

arcana proof inspect [session-id]
arcana proof verify [session-id]
arcana proof export [session-id] --format json

arcana replay

arcana replay audit <session-id>
arcana replay deterministic <session-id>

arcana capability

Revoke a capability granted during a session.

arcana capability revoke <sessionID> <capabilityID>

arcana epistemic

Inspect the epistemic record of a session: claims, assumptions, contract, obligations, and proof status.

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 Pro license or higher — run arcana license status to check your plan.

arcana audit events [--limit 20] [--action <type>] [--actor <id>]
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.

arcana node enroll --token <token> --endpoint <url>
arcana node status [--json]
arcana node key rotate --endpoint <url>
arcana node proof upload --endpoint <url>
arcana node sync policy|revocation --endpoint <url>

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.

arcana launch codex
arcana launch claude --dry-run
arcana launch gemini --directory ./my-project

License & Proxy

arcana license

arcana license activate <key>
arcana license status
arcana license deactivate

arcana proxy

Inspect your Arcana proxy account. See the Proxy API reference.

arcana proxy status
arcana proxy models [query]
arcana proxy usage
arcana proxy balance

Agents & Plugins

arcana agent

arcana agent create    # interactive: name, description, mode, permissions
arcana agent list

arcana plugin-store

arcana plugin-store search [query]
arcana plugin-store install <name>
arcana plugin-store create <name>
arcana plugin-store publish <name>

Web Dashboard

arcana web

Run the local web dashboard.

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.

arcana learn list
arcana learn show --slug kebab-case-slug
arcana learn moc

Global flags

Every converted command exits with a deterministic code: 0 success, 1 user/validation error, 2 internal error. Full contract in JSON & Exit Codes.

Install reminder

npx arcana-ai@latest
# or
npm install -g arcana-ai
arcana