CLI reference¶
The arcana command is a thin Typer wrapper
around arcana-core.
Auto-generated
Everything below is generated from the live CLI at build time, so it always
matches the released version — commands, subcommands, flags, and help text
can't drift from the code. New arcana commands appear here automatically on
the next docs deploy. For install and first-run steps, see
Getting started.
arcana¶
Arcana OS — The OS that gives your agents a soul.
Usage¶
arcana [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--install-completion |
Install completion for the current shell. | No | - |
--show-completion |
Show completion for the current shell, to copy it or customize the installation. | No | - |
--help |
Show this message and exit. | No | - |
Commands¶
| Name | Description |
|---|---|
run |
Run a prompt specifying --agent directly. |
chat |
Start an interactive REPL with a... |
init |
Initialise Arcana OS — creates ~/.arcana/... |
status |
Show full system status — agents,... |
agent |
Manage agents. |
cards |
Browse the 22 Major Arcana card definitions. |
providers |
Manage model provider connections (list /... |
soul |
Manage your soul.md — global user context... |
Subcommands¶
arcana run¶
Run a prompt specifying --agent directly.
Usage¶
arcana run [OPTIONS] PROMPT
Arguments¶
| Name | Description | Required |
|---|---|---|
PROMPT |
The prompt to run | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-a, --agent TEXT |
Agent name or UUID | No | - |
-s, --stream |
Stream output token by token | No | - |
--session TEXT |
Resume a specific session by UUID | No | - |
--continue |
Resume the agent's most recent session | No | - |
--no-memory |
Run stateless — do not load or persist memory | No | - |
--help |
Show this message and exit. | No | - |
arcana chat¶
Start an interactive REPL with a card-configured agent.
Usage¶
arcana chat [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-a, --agent TEXT |
Agent name or UUID | No | - |
--session TEXT |
Resume a specific session by UUID | No | - |
--no-memory |
Run stateless — do not load or persist memory | No | - |
--help |
Show this message and exit. | No | - |
arcana init¶
Initialise Arcana OS — creates ~/.arcana/ and sets up The World.
Usage¶
arcana init [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana status¶
Show full system status — agents, connections, The World.
Usage¶
arcana status [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana agent¶
Manage agents.
Usage¶
arcana agent [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
Subcommands¶
arcana agent create¶
Create a new agent. Interactive if no flags provided.
Usage¶
arcana agent create [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --name TEXT |
Agent name | No | - |
-c, --card TEXT |
Card id (e.g. 'hermit') | No | - |
-m, --model TEXT |
Model reference (e.g. 'anthropic/claude-sonnet-4-6', 'anthropic:work/claude-sonnet-4-6', 'anthropic') | No | - |
--help |
Show this message and exit. | No | - |
arcana agent list¶
List all registered agents.
Usage¶
arcana agent list [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana agent show¶
Show full config for an agent.
Usage¶
arcana agent show [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
NAME |
Agent name or UUID | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana agent edit¶
Edit an agent's name, description, card, model, or tags.
Usage¶
arcana agent edit [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
NAME |
Agent name or UUID | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --name TEXT |
New name | No | - |
-d, --description TEXT |
Description | No | - |
-c, --card TEXT |
Card id | No | - |
-m, --model TEXT |
Model reference (e.g. 'anthropic/claude-sonnet-4-6') | No | - |
-t, --tags TEXT |
Comma-separated tags | No | - |
--help |
Show this message and exit. | No | - |
arcana agent delete¶
Delete an agent (soft-delete).
Usage¶
arcana agent delete [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
NAME |
Agent name or UUID | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-y, --yes |
Skip confirmation | No | - |
--help |
Show this message and exit. | No | - |
arcana cards¶
Browse the 22 Major Arcana card definitions.
Usage¶
arcana cards [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
Subcommands¶
arcana cards show¶
Show full card details — prompt ingredients, memory weights, synergies.
Usage¶
arcana cards show [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
NAME |
Card name or key (e.g. 'hermit', 'the-hermit') | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana providers¶
Manage model provider connections (list / add / show / edit / remove).
Usage¶
arcana providers [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
Subcommands¶
arcana providers list¶
List all saved model provider connections.
Usage¶
arcana providers list [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana providers add¶
Add or update a model provider connection.
Usage¶
arcana providers add [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-p, --provider TEXT |
ollama | anthropic | openai |
-m, --model-id TEXT |
Model ID (e.g. hermes-3, claude-sonnet-4-6) | No | - |
-n, --name TEXT |
Connection name | No | - |
-e, --endpoint TEXT |
Custom base URL | No | - |
-k, --api-key TEXT |
API key (stored in OS keyring) | No | - |
--help |
Show this message and exit. | No | - |
arcana providers show¶
Show a connection's details. Secrets are never printed.
Usage¶
arcana providers show [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
NAME |
Connection name (see: arcana providers list) | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana providers edit¶
Edit an existing model connection's mutable fields.
Runs interactively by default — blank input preserves the current value. Use flags for scriptable / non-interactive edits.
provider and adapter_type are immutable. To change them, remove and recreate:
arcana providers remove
Usage¶
arcana providers edit [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
NAME |
Connection name (see: arcana providers list) | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--base-url TEXT |
New base URL / endpoint | No | - |
--rotate-key |
Rotate the stored API key (interactive hidden prompt) | No | - |
--api-key-env VAR |
Read new API key from this environment variable | No | - |
--header TEXT |
Set a custom header as 'Key: Value' (repeatable; custom adapter only) | No | - |
--no-verify |
Skip post-edit health check | No | - |
--help |
Show this message and exit. | No | - |
arcana providers remove¶
Remove a model provider connection and its stored credential.
Scans for dependent agents and aborts unless --force is given.
Usage¶
arcana providers remove [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
NAME |
Connection name (see: arcana providers list) | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-y, --yes |
Skip confirmation prompt | No | - |
--force |
Remove even if dependent agents exist | No | - |
--help |
Show this message and exit. | No | - |
arcana soul¶
Manage your soul.md — global user context injected into every agent.
Usage¶
arcana soul [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
Subcommands¶
arcana soul edit¶
Open soul.md in $EDITOR, creating it from a template on first use.
Usage¶
arcana soul edit [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
arcana soul show¶
Print the current soul.md, or a hint if it doesn't exist.
Usage¶
arcana soul show [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |