CLI Reference - OpenLegion Docs

CLI Commands

openlegion [--version] [--verbose | --quiet]
├── start [--config PATH] [-d] [--sandbox] [-p PORT]   # Start runtime + interactive REPL
├── stop                                                # Stop runtime + all openlegion_* containers
├── chat [NAME] [--port PORT]                           # Connect to a running agent
├── status [--port PORT] [--wide] [--watch N] [--json]  # Show agent status
├── projects [--port PORT] [--json]                     # List active projects
├── project <ID> [--port PORT] [--json]                 # Single project details
├── tasks [--agent NAME] [--project ID] [--status S]    # List/filter durable task records (V2)
│        [--port PORT] [--json]
├── pending [--port PORT] [--json]                      # List open pending operator actions
├── confirm <NONCE>                                     # Confirm a pending action
├── cancel <NONCE>                                      # Cancel a pending action
├── reset [--yes/-y]                                    # Stop + wipe config/data/skills/volumes
├── wallet                                              # Wallet management
│   ├── init                                            #   Generate 24-word BIP-39 seed (once)
│   └── show [AGENT_ID]                                 #   Show wallet addresses on all chains
└── version [-v]                                        # Show version info

Agent management, credential management, channel setup, blackboard / queue inspection, cron management, and other per-agent operations are available as interactive REPL commands inside openlegion start.

Command Details

`openlegion start`

Launches the mesh host, spins up agent containers, and starts the interactive REPL. On first run (no credentials configured), runs inline setup — API key entry, model selection, and optional agent creation — right in the terminal.

Flag	Description
`--config PATH`	Path to mesh config YAML file (default: `config/mesh.yaml`)
`-d`	Run in background (daemon mode); logs to `.openlegion.log`, PID in `.openlegion.pid`
`--sandbox`	Use Docker Sandbox microVMs for maximum isolation (requires Docker Desktop 4.58+; falls back to standard Docker on init failure)
`-p`, `--port PORT`	Override the mesh / dashboard port (default: 8420)

`openlegion stop`

Cleanly shuts down all openlegion_* Docker containers and the mesh host. Sends SIGTERM to the background host process if running, then cleans up any remaining containers.

`openlegion chat [NAME]`

Connect to a running agent from a separate terminal. Useful when running in daemon mode (-d). If no name is given, prompts to select from running agents.

Flag	Description
`--port PORT`	Mesh host port (default: 8420)

`openlegion status`

Show health and status of all configured and running agents.

Flag	Description
`--port PORT`	Mesh host port (default: 8420)
`--wide`, `-w`	Show additional columns (role, cost)
`--watch N`	Auto-refresh every N seconds
`--json`	Output as JSON

`openlegion projects`

List active projects in the running fleet.

Flag	Description
`--port PORT`	Mesh host port (default: 8420)
`--json`	Output as JSON

`openlegion project <ID>`

Show details for a single project (members, goal, context, recent activity).

Flag	Description
`--port PORT`	Mesh host port (default: 8420)
`--json`	Output as JSON

`openlegion tasks`

List durable task records from the V2 orchestration ledger (OPENLEGION_ORCHESTRATION_TASKS_V2=1, default ON).

Flag	Description
`--agent NAME`	Filter by assigned agent
`--project ID`	Filter by project
`--status S`	Filter by task status
`--port PORT`	Mesh host port (default: 8420)
`--json`	Output as JSON

`openlegion pending`

List open pending operator actions. Some operator-initiated edits (model, permissions, budget, thinking) require explicit confirmation via confirm within 30 minutes; soft edits (instructions, soul, heartbeat, interface, role) have a 5-minute undo window.

Flag	Description
`--port PORT`	Mesh host port (default: 8420)
`--json`	Output as JSON

`openlegion confirm <NONCE>`

Confirm a pending operator action. Use openlegion pending to find the nonce.

`openlegion cancel <NONCE>`

Cancel a pending operator action without applying it.

`openlegion reset`

Stop the runtime and wipe config/, data/, agent skills, and Docker volumes. Keeps .env so your API keys survive. Pass --yes/-y to skip the confirmation prompt.

`openlegion wallet init`

Generate a 24-word BIP-39 mnemonic and store it in .env as OPENLEGION_SYSTEM_WALLET_MASTER_SEED. The seed is shown once — there is no second-chance reveal. Per-agent EVM keys derive via BIP-44 (m/44'/60'/{agent_index}'/0/0); per-agent Solana keys via HMAC-SHA512 over a PBKDF2 of the seed.

`openlegion wallet show [AGENT_ID]`

Show wallet addresses on all supported chains (EVM: ethereum, base, arbitrum, polygon, sepolia; Solana: mainnet, devnet). Pass an agent ID to scope to that agent.

`openlegion version`

Show version and environment information.

Flag	Description
`-v`	Show extended info (Python version, Docker version, OS, config path, agent count)

Interactive REPL Commands

When running openlegion start, you’re in the interactive REPL. These commands are only available inside the REPL session:

Command	Description
`@agent <message>`	Send message to a specific agent
`/use <agent>`	Switch active agent
`/status`	Show agent health (also aliased as `/agents`)
`/broadcast <msg>`	Send message to all agents
`/steer <msg>`	Inject message into a busy agent’s context (rate-limited: 10 wakeups / 3600s)
`/reset`	Clear conversation with active agent
`/history`	View conversation history with active agent
`/help`	Show available commands
`/quit`	Exit and stop runtime

Agent Management

Command	Description
`/add`	Add a new agent (hot-adds to running system)
`/agent [cmd]`	Inspect or edit a specific agent
`/remove [name]`	Remove an agent
`/restart [name]`	Restart a running agent

Monitoring & Debugging

Command	Description
`/costs`	Show today’s spend, context usage, and model health
`/traces`	Show recent request traces (aliased as `/debug`)
`/logs`	View agent logs
`/blackboard [cmd]`	View/edit shared blackboard entries (list, get, set, del)
`/queue`	Show agent task queue / lane status

Automation

Command	Description
`/cron [cmd]`	Manage cron jobs and heartbeats (list, del, pause, resume, run)

5-field cron (minute granularity) or every N[s/m/h/d] interval syntax. No 6-field / seconds support. Pass heartbeat=true for autonomous monitoring with built-in probes.

Credentials & Channels

Command	Description
`/addkey <svc> [key]`	Add an API credential to the vault at runtime (intentionally not a slash-command in chat-channel UIs — the value would be visible)
`/removekey [name]`	Remove a credential from the vault
`/credential [cmd]`	Manage vault credentials (add, list, remove)

Projects

Command	Description
`/project [cmd]`	Project management (list, use, info)

Aliases: /exit = /quit, /traces = /debug, /agents = /status.

Team Templates

Templates offered during first-run setup (via openlegion start) and applied via the operator’s apply_template tool (per-slot — not atomic; mid-loop failures leave earlier-created agents in place).

Template	Agents	Description
`starter`	assistant	Single general-purpose agent
`content`	researcher, writer	Blog / social / email from briefs
`deep-research`	scout, analyst	Multi-source synthesis with citations
`devteam`	pm, engineer, reviewer	Software development team
`monitor`	watcher, analyst	Always-on monitoring
`sales`	researcher, qualifier, outreach	Sales pipeline
`competitive-intel`	tracker, analyst	Competitor pricing/product tracking
`lead-enrichment`	enricher, verifier	Lead list research
`price-intelligence`	crawler, analyst	Price monitoring with anti-bot browser
`review-ops`	collector, responder	G2 / Trustpilot / Capterra / App Store / Google reviews + reply drafts
`social-listening`	listener, reporter	Reddit / HN / X competitor pain-point monitor
`research`	researcher	General-purpose researcher
`opportunity-finder`	scout, evaluator, modeler	Gap-scout + evaluation + modeling

Each template references models via the "{default_model}" placeholder, substituted at apply time. apply_template accepts agent_overrides per slot (model, instructions ≤12K chars, soul ≤4K, heartbeat, interface ≤4K; role is template-fixed).

​CLI Commands

​Command Details

​openlegion start

​openlegion stop

​openlegion chat [NAME]

​openlegion status

​openlegion projects

​openlegion project <ID>

​openlegion tasks

​openlegion pending

​openlegion confirm <NONCE>

​openlegion cancel <NONCE>

​openlegion reset

​openlegion wallet init

​openlegion wallet show [AGENT_ID]

​openlegion version

​Interactive REPL Commands

​Chat & Navigation

​Agent Management

​Monitoring & Debugging

​Automation

​Credentials & Channels

​Projects

​Team Templates