CLI reference

Generated by scripts/docgen/cli-ref. Do not edit by hand. Run make docs-regen after changing internal/cli/cli.go or internal/cli/catalog.go.

canary is one binary with 29 subcommands, listed here in registry order. canary status comes first on purpose: when anything else fails, it is the command that says whether the daemon is running and the gateway is reachable. Running canary with no arguments prints the grouped command summary.

Add --json to a data command for machine-readable output instead of a table. Commands that accept --watch redraw on an interval set by --rate, as in canary account --watch --rate 1s. Color is on for terminals and off for pipes; NO_COLOR=1 turns it off, and CANARY_COLOR=always or CANARY_COLOR=never forces it either way.

The flag tables below come from the shared command catalog. Run canary <command> --help for the flags a command parses today, with their help text. That output is the authority if the two ever disagree.

The guard column says what a command does: read-only reads and prints, local writes local setup or configuration state, and confirm reaches something a human has to decide first. Where subcommands carry different guards, the summary shows the strictest one and the command's own section lists the split. The guard is documentation of behavior, not the mechanism that enforces it. The real gates live in the CLI. Standard builds have no broker-write path compiled in at all. The separate trading build adds one, and it still requires a verified gateway session, a submit-eligible preview token where one applies, a local journal entry, daemon authorization, and trading.freeze set to false. Nothing on this page grants any of that.

The group column is the heading a command appears under in canary --help: Desk is the account, its positions, orders and risk; Markets is broad-market regime and named-symbol technical evidence; System is running Canary itself. It is a reading aid for a long command list and says nothing about what a command may do — that is the guard.

Command summary

canary status

Daemon + gateway health (run this first if anything fails).

Guard read-only. Also available as an MCP tool.

canary status [--json]

Flags

canary account

Account summary snapshot (NLV, BP, cash, margin, daily P&L).

Guard read-only. Also available as an MCP tool.

canary account [--watch --rate 1s] [--json]

Flags

canary positions

List open positions (stocks + options).

Guard read-only. Also available as an MCP tool.

canary positions [--symbol SYM] [--type stk|opt] [--sort alpha|pnl|value] [--quotes] [--by underlying] [--watch --rate 1s] [--json]

Flags

canary strategies

Group option legs and close or reduce them as one guaranteed combo.

Guard confirm. Also available as an MCP tool.

canary strategies list [--json]
canary strategies close ID REVISION [--limit PRICE] [--submit]
canary strategies reduce ID REVISION --units N [--limit PRICE] [--submit]

Subcommands

Flags

canary technical

Trend, relative strength, ATR, and liquidity from daily bars.

Guard read-only. Also available as an MCP tool.

canary technical SYM[,SYM...] [--benchmark SPY] [--market us|de] [--json]

Flags

canary calendar

Official exchange sessions, holidays, early closes, and coverage bounds.

Guard read-only. Also available as an MCP tool.

canary calendar [--market us|us-options|de] [--date YYYY-MM-DD] [--at RFC3339] [--days N] [--json]

Flags

canary macro

Public economic calendar, official publications and source coverage.

Guard read-only. Also available as an MCP tool.

canary macro [--json]

Flags

canary regime

Detailed broad-market regime across volatility, credit, funding, FX, gamma, and breadth.

Recorded readings from stale authority are explicit. --explain includes observation times, thresholds, calibration, and source diagnostics. JSON preserves detailed measurements; --profiles opts into large gamma arrays.

Guard read-only. Also available as an MCP tool.

canary regime [--explain] [--json [--view full|monitor] [--profiles]]

Flags

canary stress

Portfolio stress with margin, exposure, concentration, options, protection, and source evidence.

The default view separates findings from coverage gaps. --details includes quiet evidence and diagnostics. Required-input failures remain nonzero exits, with full error detail available explicitly.

Guard read-only. Also available as an MCP tool.

canary stress [--details] [--json]

Flags

canary brief

Combined post- and pre-trade operator brief with disclosed source degradation.

The default view prioritizes assessment completeness, findings, dated context, and coverage gaps. --details retains the full Review/Ready evidence and input diagnostics; JSON retains all typed rows and the daemon-authored overview.

Guard read-only. Also available as an MCP tool.

canary brief [--details] [--json]

Flags

canary edge

Automatic decision review with coverage, matched horizons, repeatability, and option position cycles.

Guard read-only. Also available as an MCP tool.

canary edge [--window 90d|365d] [--horizon 1|5|20] [--limit N] [--change ID] [--option ID] [--json]

Flags

canary rules

Advisory 14-rule daily trading checklist, hardest breach first.

Guard read-only. Also available as an MCP tool.

canary rules [--all] [--symbol SYM] [--json]
canary rules history [--since YYYY-MM-DD|RFC3339] [--until YYYY-MM-DD|RFC3339] [--rule ID] [--limit N] [--json]

Subcommands: history.

Flags

canary policy

Risk constitution: effective limits, capital/drawdown state, overrides (human-only writes).

Guard read-only, with confirm subcommands. CLI only, with no MCP tool: risk-constitution surface deferred from MCP in phase 1 (internal-docs/design/risk-policy.md): its writes are human-only governance acts the daemon rejects from agents, and the read view ships CLI-first; revisit after the phase-2 manual cadence.

canary policy show [--explain] [--json]
canary policy capital-event deposit|withdrawal [--amount F] [--effective-at TIME] [--note S]
canary policy capital-event reconcile [--report ID]
canary policy override --control KEY --reason S --hours N
canary policy reset-drawdown --reason S
canary policy correct-peak (--from-statements|--peak F) --reason S
canary policy default protection|opportunity

Subcommands

Flags

canary recon

Post-trade reconciliation: broker statement flows vs the declared capital ledger.

Guard read-only, with confirm subcommands. CLI only, with no MCP tool: post-trade reconciliation surface deferred from MCP in phase 3a (internal-docs/design/post-trade-truth.md): dismiss/sign-off are human-only governance acts and the read view ships CLI-first, same posture as policy; revisit together with it.

canary recon show [--refresh] [--json]
canary recon backtest [--refresh] [--json]
canary recon equity [--since YYYY-MM-DD|RFC3339] [--until YYYY-MM-DD|RFC3339] [--limit N] [--json]
canary recon dismiss --line ID --reason S

Subcommands

Flags

canary reporting

Shared IBKR statement reporting status for Recon and Edge.

Guard read-only. Also available as an MCP tool.

canary reporting status [--json]

Subcommands: status.

Flags

canary proposals

Daemon-owned close/reduce-only protection proposals.

Protection proposals are advisory. The daemon can propose a close or a reduce, and only submit and reduce reach the broker. Each needs an explicit human instruction for that exact order.

Guard confirm. Also available as an MCP tool.

canary proposals status|refresh|list|preview|submit|reduce|request-stop|ignore [--json]

Subcommands

Flags

canary opportunities

Daemon-owned option exercise opportunities.

Opportunity detection is advisory. Only exercise reaches the broker, and it needs an explicit human instruction for that exact action.

Guard confirm. Also available as an MCP tool.

canary opportunities status|refresh|list|preview|exercise|ignore [--json]

Subcommands

Flags

canary trading

Local trading gate status and configuration.

status reads the local trading gate and its blockers.

Guard read-only. Also available as an MCP tool.

canary trading status [--json]

Subcommands: status.

Flags

canary settings

Runtime platform preferences and observed read-only state.

show reads. set writes a runtime preference, and the write path has its own gate: trading.freeze and the trading-limit keys are accepted only from an interactive human terminal, and agent and paired-device origins are rejected. The keys are listed in the configuration reference.

Guard read-only, with confirm subcommands. Also available as an MCP tool.

canary settings show [--json]
canary settings set <supported-key>=true|false|null|number

Subcommands

Flags

canary orders

Read current-context local order lifecycle state without transmitting orders.

Guard read-only. Also available as an MCP tool.

canary orders open [--json]
canary orders history [--since YYYY-MM-DD|RFC3339] [--until YYYY-MM-DD|RFC3339] [--limit N] [--event-limit N] [--json]

Subcommands: open, history.

Flags

canary order

Preview, place, modify, cancel, or inspect gated orders.

status reads one journaled order and preview mints a tokenized draft: it runs the broker WhatIf and never transmits, and a minted token is not submit eligibility. place, modify, and cancel are broker writes: each requires an explicit human instruction for that exact order, and place/modify additionally consume a submit-eligible preview token through the daemon's ordinary admission gates (mode and account pins, caps, freeze, origin, journal). The constrained proposal and opportunity surfaces remain the daemon-authored candidate paths; this family is the operator's direct gated path.

Guard read-only, with confirm subcommands. Also available as an MCP tool.

canary order preview buy|sell SYMBOL QTY [--limit PRICE|--order-type TRAIL --trail-percent PCT] [--json]
canary order status ID [--json]
canary order place --preview-token TOKEN [--json]
canary order modify ID --preview-token TOKEN [--json]
canary order cancel ID [--json]

Subcommands

Flags

canary app

Run the paired mobile PWA application layer.

Guard local, with confirm subcommands. CLI only, with no MCP tool: local mobile/PWA service mode with browser pairing and Web Push state; not a broker-data MCP tool.

canary app [--addr HOST:PORT]
canary app pair

Subcommands

Flags

canary mcp

Run the stdio MCP server for local AI clients.

Guard local. CLI only, with no MCP tool: transport server mode; the MCP host starts this process, no LLM should call it as a tool.

canary mcp

Flags

canary daemon

Run the stateful gateway daemon (normally autospawned).

Guard local. CLI only, with no MCP tool: local background service mode; autospawned by CLI/MCP clients and not an agent operation.

canary daemon [--foreground] [--config PATH] [--socket PATH] [--log PATH|stderr]

Flags

canary setup

Configure a local client, app host, or shared broker reporting.

Guard local. CLI only, with no MCP tool: interactive local integration and credential configuration; not an LLM operation.

canary setup [claude-desktop|app|reporting]

Subcommands: claude-desktop, app, reporting.

Flags

canary update

Self-update the Canary binary from the latest GitHub release.

Guard confirm. CLI only, with no MCP tool: binary-management verb (replaces the canary binary from GitHub releases); not a daemon RPC, must stay user-triggered for trust-boundary reasons.

canary update [--check] [--force] [--restart|--no-restart]

Flags

canary restart

Gracefully restart the daemon and any running app process.

Guard confirm. CLI only, with no MCP tool: local process-management verb (signals daemon processes); useful for humans and scripts, but not a broker-data MCP tool.

canary restart [--app] [--force] [--timeout 15s] [--json]

Flags

canary stop

Stop the local daemon and app processes.

Stopping is local process management: it signals the daemon and the app on this machine and reaches no broker. Orders already working stay at the broker, but nothing local watches them until the daemon runs again — no fills or cancels in the journal, no protection proposals, no phone alerts. So stop asks before it stops a daemon that still has work in flight, the same work its own idle shutdown defers on, and --yes is how a script answers. --force only escalates a stuck process from SIGTERM to SIGKILL after --timeout; it never widens what is stopped. MCP servers belong to the AI client that started them and are reported, never signalled.

Guard confirm. CLI only, with no MCP tool: local process-management verb (stops the daemon and app the caller is talking through); a tool call that ends order tracking and phone alerts belongs to the human at the terminal.

canary stop [--app] [--daemon] [--force] [--timeout 15s] [--yes] [--json]

Flags

canary version

Print version, commit, build date.

Guard local. CLI only, with no MCP tool: info-only CLI verb; not useful as a tool call.

canary version

The catalog records no flags. Run canary version --help for what the command parses.