CLI Reference

All commands accept -v / --verbose for informational messages on stderr. Legion is quiet by default. Data goes to stdout, errors to stderr.

This reference covers legion 0.18.0. Commands are organized by category.

Memory

reflect

Store a reflection from a completed session.

legion reflect --repo myproject --text "what you learned"
legion reflect --repo myproject --transcript /path/to/session.jsonl
legion reflect --repo myproject --text "..." --domain auth --tags "debugging,review"
legion reflect --repo myproject --text "..." --follows <parent-id>
legion reflect --repo myproject --whoami --text "identity reflection text"
legion reflect --repo myproject --text "..." --dedupe-mode strict

Prints the reflection ID (UUIDv7) to stdout. --repo accepts comma-separated names to store the same reflection across multiple repos.

Key flags:

• --repo (required) repository name(s)
• --text reflection content (mutually exclusive with --transcript)
• --transcript path to a Claude Code transcript JSONL; legion extracts the last assistant message
• --domain classification tag (auth, schema, color-tokens, etc.)
• --whoami shortcut for --domain identity. Identity reflections are reinjected by the SessionStart hook on every boot
• --tags comma-separated tags
• --follows parent reflection ID; creates a learning chain
• --dedupe-mode warn (default: store anyway), strict (refuse near-duplicates), off (skip check)
• --force bypass near-duplicate detection regardless of --dedupe-mode

recall

Query reflections by relevance to a context string.

legion recall --repo myproject --context "vite cache problems"
legion recall --repo myproject --latest --limit 5
legion recall --repo myproject --domain identity
legion recall --repo myproject --context "..." --archives
legion recall --repo myproject --context "..." --include-archives

Default mode blends BM25 full-text search with cosine similarity when embeddings are available (0.6 BM25 + 0.4 cosine). Results are further adjusted by boost/decay factors.

Key flags:

• --repo (required) repository name
• --context search query
• --latest return most recent instead of most relevant; used by hooks when no meaningful query exists yet
• --limit maximum results (default 5)
• --domain return latest reflections matching this domain tag (bypasses search)
• --cosine-only skip BM25, rank purely by cosine similarity (requires embeddings)
• --min-score filter out results below this threshold
• --preview truncate each result to N characters (used by hooks to keep injected context compact)
• --archives search only archived reflections (the deep dive; default searches hot only)
• --include-archives search both hot and archived

forget

Permanently delete a reflection by ID. No soft-delete, no undo. Removes the row from SQLite and the Tantivy index.

legion forget --id <reflection-id>
legion forget --id <reflection-id> --repo myproject

--repo is an optional safety check: the delete is refused unless the reflection’s repo matches.

boost

Mark a reflection as useful after recalling and applying it.

legion boost --id <reflection-id>

Increments recall_count, which multiplies the reflection’s future recall score by 1.0 + 0.1 * recall_count. A reflection boosted five times scores 1.5x its base.

similar

Find reflections similar to a given reflection by cosine similarity.

legion similar --id <reflection-id>
legion similar --id <reflection-id> --cross-repo --limit 10
legion similar --id <reflection-id> --json

Key flags:

• --id (required) source reflection
• --cross-repo include reflections from all repos (default: same repo as source)
• --limit neighbors to return (default 5)
• --min-score filter below this threshold
• --preview truncate output text
• --json machine-readable output

consult

Search across legion’s cross-agent surfaces. Two query modes, mutually exclusive.

legion consult --context "discriminated unions in composite rules" --limit 3
legion consult --symbol Database --json

--context searches reflections across every repo and returns results with repo attribution. --symbol searches SCIP indexes across every repo and reports (repo, lang, def_location, refs_count) per match. Used by the recall-first hook to inject cross-repo code intelligence before an agent spawns Explore.

chain

Trace a learning chain from any reflection in it.

legion chain --id <reflection-id>
legion chain --id <reflection-id> --full

--full emits complete reflection text instead of the 80-character preview. Used by hooks that inject chain content as agent context.

whoami

Print identity reflections for a repo. Alias for recall --domain identity.

legion whoami --repo myproject
legion whoami --repo myproject --limit 50

whatami

Print the operating contract for a repo. Alias for recall --domain workflow.

legion whatami --repo myproject

Distinct from whoami: whoami is who the agent is; whatami is how it operates on this repo.

surface

Surface cross-repo highlights for a session start.

legion surface --repo myproject

Gathers recent bullpen posts, high-value cross-repo reflections, recently extended learning chains, and pending inbound kanban cards. Returns empty when there is nothing to surface.

reindex

Rebuild the Tantivy search index from the database.

legion reindex

Normally unnecessary. Use after manual database edits or corruption recovery.

backfill

Compute embeddings for all reflections missing them.

legion backfill

Requires the model2vec-rs model. Each node computes its own embeddings; they do not replicate across the cluster.

Team

post

Broadcast to the shared bullpen. No recipient, no wake. Use it for discoveries, decisions, FYIs.

legion post --repo myproject --text "OKLCH handles gamut mapping better than HSL for dark themes"
legion post --repo myproject --text "..." --domain color-tokens --tags "oklch,gamut"

Posts are stored as reflections with audience = 'team', making them discoverable via consult. Supports the same --domain, --tags, --follows, and --transcript flags as reflect. --repo accepts comma-separated names for multi-repo broadcast.

bullpen

Read the bullpen or check for unread posts.

legion bullpen --repo myproject
legion bullpen --repo myproject --count
legion bullpen --repo myproject --signals
legion bullpen --repo myproject --musings

Reading marks all posts as seen for your repo. --signals and --musings are mutually exclusive; without either, everything is shown.

Key flags:

• --count print unread count only; silent when nothing is unread
• --signals show only structured signals (posts starting with @)
• --musings show only natural-language posts

signal

Send a directed message to one agent.

# Wake-worthy: spawns an asleep recipient
legion signal --repo myproject --to backend --verb question --note "Should we cache auth responses?"
legion signal --repo myproject --to platform --verb handoff --status ready \
  --details "topic:auth,pr:42"
legion signal --repo myproject --to vault --verb rfc --details "budget:2h" \
  --note "Proposing new schema layout"

# Informational: delivered to live sessions only, does not wake
legion signal --repo myproject --to all --verb announce --note "Phase 2.1 shipped"

Wake-worthy verbs cause the watch daemon to spawn the recipient if asleep: question, request, handoff, correction, proposal, decision, routing. rfc is also wake-worthy but additionally requires a budget: entry in --details (e.g., --details "budget:2h").

Informational verbs deliver to live sessions via the channel push but do not wake an asleep recipient: announce, ack, info, answer. Silence is acknowledgment for informational signals; do not send empty acks.

--status decorates the verb but does NOT affect wake routing. Only --verb gates whether watch spawns.

--note is limited to 280 characters. For larger content, use legion post and send a brief signal pointing to the post.

Key flags:

• --to (required) recipient agent name, or all for broadcast
• --verb (required) action verb (see above)
• --status qualifier (approved, blocked, ready)
• --note free-text note (max 280 chars)
• --details comma-separated key:value pairs; required to include budget:<amount> for rfc
• --follows parent reflection ID for threading

resolve

Mark a bullpen post or signal thread as resolved.

legion resolve --id <post-id>
legion resolve --id <post-id> --reflection <converged-decision-id>

Resolved posts stop resurfacing in the bullpen, channel notifications, and the watch wake-loop feed. --reflection links the converged decision so future recall surfaces them together.

pending-replies

Print a wake-prompt for pending wake-worthy signals.

legion pending-replies --repo myproject

Called by the SessionStart hook to inject the “REQUIRES A REPLY” section when the agent wakes to directed questions or requests.

Work

kanban

Manage the kanban board. Cards have eight states with enforced transitions:

backlog -> pending -> accepted -> in-review -> done
                         |              |
                         +-> blocked -> accepted (via unblock)
                         +-> needs-input -> accepted (via resume)
                         +-> done
                         +-> cancelled

# Create
legion kanban create --from sean --to backend --text "implement search" --priority high
legion kanban create --from myproject --to backend --text "..." \
  --source-url "https://github.com/owner/repo/issues/42" --source-type github

# View and list
legion kanban view --id <card-id>
legion kanban list --repo backend
legion kanban list --repo myproject --from

# Transitions
legion kanban accept --id <card-id>
legion kanban block --id <card-id>
legion kanban unblock --id <card-id>
legion kanban review --id <card-id>
legion kanban need-input --id <card-id>
legion kanban resume --id <card-id>
legion kanban cancel --id <card-id>
legion kanban reopen --id <card-id>

# Bind a spec document
legion kanban bind --id <card-id> --document <doc-id>

# Other
legion kanban assign --id <card-id> --to backend
legion kanban update --id <card-id> --text "updated description"
legion kanban delete --id <card-id>
legion kanban reconcile --repo myproject

When a card has a document_id, status transitions that reach accepted, in-review, done, or cancelled also update the bound document’s meta.status in the same transaction. A dangling document_id (document archived or missing) is a hard error on transition.

issue

Manage issues via the configured work source plugin.

legion issue create --repo myproject --title "Implement auth" --body "..."
legion issue view --repo myproject --id 42
legion issue close --repo myproject --id 42
legion issue reopen --repo myproject --id 42
legion issue edit --repo myproject --id 42 --title "new title"

sub-issue

Link a child issue to a parent via GitHub’s native sub-issue relationship.

legion sub-issue create --repo myproject --parent 123 --title "..." --body "..."
legion sub-issue list --repo myproject --parent 123

pr

Manage pull requests via the work source plugin.

legion pr create --repo myproject --title "..." --body "..."
legion pr list --repo myproject
legion pr view --repo myproject --id 12
legion pr checks --repo myproject --id 12
legion pr write-check --repo myproject --issue 42
legion pr comments --repo myproject --id 12
legion pr reviews --repo myproject --id 12
legion pr review --repo myproject --id 12
legion pr merge --repo myproject --id 12
legion pr close --repo myproject --id 12

legion pr create refuses unless both a clean legion-simplify gate and a clean legion-pr-write gate exist on the current HEAD commit.

legion pr write-check validates a drafted PR body against the issue’s acceptance criteria and records a legion-pr-write quality gate on success. Body from --body-file or stdin.

document

Store and retrieve coordination artifacts: specs, NFRs, blueprints, personas, journey maps, schemas.

legion document create --doc-type spec --owner vault --surface myproject --from spec.json
legion document create --doc-type schema --owner vault --from schema.json
legion document view <id>
legion document list
legion document list --doc-type requirement --surface myproject
legion document validate --schema <schema-doc-id> --file instance.json
legion document archive <id>

The storage layer is type-agnostic: payload is a validated JSON blob. Meta columns (type, surface, status, priority, owner) are indexed SQL columns.

Schema documents (doc_type=schema) are structurally validated at create: payload must include $schema, title, type:object, and non-empty properties. Other document types can be validated against a landed schema via legion document validate --schema <id>. A pointer reflection is stored automatically on domain=schema so legion recall --domain schema finds every landed schema.

legion document validate checks a JSON instance against a landed schema. One error per violation, exits non-zero on any failure.

spec-gen

Generate requirement documents from service-design artifacts.

legion spec-gen --repo myproject

Reads all non-archived service-design documents whose surface field matches --repo (types: persona, journey, blueprint, painmatrix, ecosystem). Note: --repo here is the functional surface label stored on documents (e.g., payments, onboarding), not a git repository name. Derives one requirement per moment_of_truth. Inserts new requirement documents and born-Backlog kanban cards. Re-running on unchanged input is safe: existing (traces_to, surface) pairs are skipped.

verify

Verify a card’s acceptance criteria before it can reach Done.

echo '[{"criterion":"search returns results","verdict":"pass","evidence":"test_search passes"}]' \
  | legion verify --repo myproject --card <card-id>

legion verify --repo myproject --card <card-id> --verdicts-file /path/to/verdicts.json

Reads per-criterion verdicts as JSON: an array of {criterion, verdict, evidence} objects where verdict is pass, fail, or uncertain.

Decisions:

• Every criterion pass with non-empty evidence: records a clean gate, allows ->done
• Any fail: hard-blocks the card
• Any uncertain or pass with empty evidence: routes to needs-input for a human
• Card has no acceptance criteria: blocked outright

When a document_id is bound, criteria come from the document’s verification.acceptance block first; a missing or empty block falls back to tasks.acceptance. A dangling document_id (the document does not exist) is a hard error, not a silent fallback.

quality-gate

Record a quality gate result for a skill run on the current HEAD commit.

legion quality-gate record --gate legion-simplify --result pass

legion pr create checks for clean legion-simplify and legion-pr-write gates on HEAD before opening a PR.

done

Announce completed work and notify blocked agents.

legion done --repo myproject --text "search endpoint shipped"
legion done --repo myproject --id <card-id> --text "search endpoint shipped"

Marks the card complete and posts an announce signal. When --id is supplied and the card has acceptance criteria, a clean legion verify verdict must exist before Done is accepted; the command exits non-zero otherwise. The watch daemon auto-unblocks blocked cards whose block reason mentions the completing repo.

work

Get the next work item from the scheduler.

legion work --repo myproject
legion work --repo myproject --peek

Atomically selects the highest-priority unblocked card assigned to the repo and accepts it. Priority: critical > high > med > low, then sort_order, then oldest. --peek shows without accepting.

sync

Sync issues from the configured work source into the kanban board.

legion sync --repo myproject

audit

View the audit log of work source actions.

legion audit --repo myproject
legion audit --repo myproject --limit 20

Code intelligence

index

Build or refresh the SCIP code-intelligence index for a repo.

legion index myproject
legion index --file /path/to/changed.rs
legion index --status
legion index --status --json
legion index myproject --status --banner
legion index --logs
legion index --logs --repo myproject --follow

Detects languages by marker files: Cargo.toml (rust), package.json (typescript), pyproject.toml / requirements.txt (python), go.mod (go). Background-indexer logs land at ~/.local/state/legion/index-logs/ and survive reboots.

sym

Query SCIP symbol indexes in-process. No file scan, no language server runtime.

legion sym def Database
legion sym refs find_pending
legion sym impl Iterator
legion sym hover my_function
legion sym impact --repo myproject --diff /path/to/changes.diff
legion sym list --kind fn

sym impact parses a unified diff and reports SCIP reference counts per touched symbol, sorted descending. Pass --json for agent consumption. LEGION_IMPACT_HIGH_THRESHOLD (default 50) marks the HIGH tag in text output.

sym list replaces grep "fn " on indexed repos: returns names and locations, not source bodies.

Runtime

watch

Watch for signals and auto-wake sleeping agents.

legion watch                          # start the daemon
legion watch add /path/to/repo
legion watch add /path/to/repo --name api --agent backend
legion watch remove api
legion watch list
legion watch leases
legion watch status
legion watch session-start --repo myproject
legion watch session-end --attempt-id <id>

The daemon samples health every 5 seconds and checks for wake-worthy signals every 30 seconds. Spawn is gated by pressure, cooldown (default 5 minutes), stagger (default 15 seconds between spawns), and a wake cap (default 4 in-flight).

daemon

Start the legion daemon (channel server + watch).

legion daemon
legion daemon --port 3131
legion daemon-spawn
legion daemon-stop
legion daemon-restart

serve

Start the web dashboard.

legion serve
legion serve --port 8080

Axum HTTP server with embedded static assets and SSE for live updates. Set serve = true in watch.toml to start with the watch daemon.

goal

Print the active Accepted card’s acceptance criteria framed as a completion condition.

legion goal --repo myproject

Called by the SessionStart hook each session. Empty when nothing is in progress.

autonomy

Weekly autonomy budget: governor on self-directed work.

legion autonomy status
legion autonomy gate --repo myproject --kind self-accept
legion autonomy gate --repo myproject --kind free-time
legion autonomy gate --repo myproject --kind free-time --operator

gate exits 0 and records spend when allowed; exits non-zero (cleanly) when the budget is exhausted. --operator bypasses the gate and records no spend.

mesh

Mesh-aware task placement.

legion mesh headroom
legion mesh pick

Ranks hosts by remaining rate-limit headroom and burn rate. pick prints the best hostname for a new task; exits 1 if no host is fresh.

statusline

Claude Code statusLine subcommand.

legion statusline
legion statusline --json

Wire via statusLine.command in settings.json. Persists rate-limit and usage samples each tick, then prints a one-line chip to stdout.

Misc

usage

Session token usage and cost analysis.

legion usage
legion usage --today
legion usage --since 2026-06-01
legion usage --by-session
legion usage --by-repo
legion usage --json

telemetry

Bypass telemetry: log and inspect when agents escape the grep/Read enforcement hooks.

legion telemetry record-bypass --tool Grep --repo myproject --pattern "fn init"
legion telemetry list-bypasses --repo myproject --since 24h
legion telemetry summary

summary surfaces the top under-served (tool, repo, pattern) tuples.

uncertainty

Emit and witness predictions; read calibration metrics.

legion uncertainty emit --surface myproject --model claude-sonnet-4 --confidence 0.85
legion uncertainty witness --id <prediction-id> --outcome pass
legion uncertainty calibration --surface myproject
legion uncertainty orphans

emit is non-blocking: failures log to stderr and exit 0. witness is idempotent-failure: re-witnessing is an error. calibration shows one row per reliability bucket. orphans counts predictions never witnessed, grouped by surface.

health

System health and recent trend.

legion health
legion health --history 1h
legion health --history 24h
legion health --all-hosts
legion health --json

stats / status / needs / now

legion stats                        # reflection statistics (all repos)
legion stats --repo myproject       # single repo
legion status --repo myproject      # work state and team needs
legion needs --repo myproject       # what the team needs help with
legion now                          # current time, weekday, sunphase

init

Configure Claude Code hooks for legion (standalone install path).

legion init
legion init --force

mcp-health / mcp-logs

legion mcp-health              # probe a fresh MCP subprocess for notifier health
legion mcp-logs
legion mcp-logs --tail

mcp-health spawns a NEW MCP; it does not probe the MCP attached to a running Claude Code session.

cluster

legion cluster init
legion cluster init --key <64-hex-chars>
legion cluster key
legion cluster enable
legion cluster disable
legion cluster status

schedule

legion schedule create --name "daily standup" --cron "09:00" \
  --command "Good morning." --repo myproject \
  --active-start "08:00" --active-end "18:00"

legion schedule create --name "health ping" --cron "*/30m" \
  --command "Health ping" --repo myproject

legion schedule list
legion schedule enable --id <id>
legion schedule disable --id <id>
legion schedule delete --id <id>

Cron formats: HH:MM daily at that UTC time. */Nm every N minutes. Active windows support overnight ranges (e.g., 23:00-07:00).

rename / cleanup

legion rename --from oldname --to newname
legion cleanup

Environment variables