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 35 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 in an interactive terminal opens the full-screen terminal app, which reads the same registry.

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 state such as the watchlist or a config file, 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.

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 quote

Snapshot or stream quotes for symbols / option contracts.

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

canary quote SYM[,SYM…] [--market us|de] [--watch --rate 250ms]
canary quote SYM YYMMDD C|P STRIKE [--json]

Flags

canary watch

Local watchlist symbols; add/remove/clear offline or quote the list live.

Guard local. Also available as an MCP tool.

canary watch [--quotes] [--timeout 5s] [--json]
canary watch --list [--json]
canary watch --watch --rate 1s
canary watch SYM[,SYM…] --add|--remove
canary watch --clear

Subcommands

Flags

canary calendar

Official market sessions for US equities, US options, and Xetra.

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

canary calendar [--market us|us-options|de] [--date YYYY-MM-DD] [--next 14] [--json]

Flags

canary chain

Option chain table or expiry list.

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

canary chain SYM [--expiry YYYY-MM-DD [--width 5] [--side calls|puts|both] [--class SPX|SPXW]] [--no-iv] [--all-expiries] [--require-live-iv] [--min-dte N] [--max-dte N] [--target-dte N] [--json]

Flags

canary history

Daily OHLCV bars for a symbol.

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

canary history SYM [--days 90] [--json]

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 market-events

Held-symbol market-event flags: borrow inventory, Reg SHO, LULD, and halts.

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

canary market-events [SYM[,SYM...]] [--symbol SYM] [--json]

Flags

canary breadth

S&P 500 breadth — % above 50/200-DMA + new-highs/new-lows, computed locally from constituent fan-out (~74 min cold).

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

canary breadth [--days 30] [--json]

Flags

canary gamma

SPX-canonical dealer zero-gamma estimate with SPY context (daemon-prewarmed; refreshes behind the served value after 15m in RTH; off-hours refresh not due).

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

canary gamma [--no-wait] [--force] [--only spy|spx] [--explain] [--diagnostics] [--json]

Flags

canary regime

Broad-market stress lifecycle across vol, credit, funding, FX, gamma, and breadth.

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

canary regime [--explain [--diagnostics]] [--watch --rate 5m] [--log PATH] [--json]
canary regime history [--since YYYY-MM-DD|RFC3339] [--until YYYY-MM-DD|RFC3339] [--stage STAGE] [--limit N] [--json]

Subcommands: history.

Flags

canary stress

Stateless market-regime × portfolio-shape stress read with action, evidence, and source health.

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

canary stress [--details] [--view full|alert] [--json]
canary stress history [--since YYYY-MM-DD|RFC3339] [--until YYYY-MM-DD|RFC3339] [--severity SEV] [--action ACTION] [--limit N] [--json]

Subcommands: history.

Flags

canary brief

Typed morning/EOD operator brief with disclosed source degradation.

Guard read-only. CLI only, with no MCP tool: daily brief MCP exposure is explicitly deferred until after phase 2; agent CLI renders are read-only and never stamp.

canary brief [--json] [--kind morning|eod]

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 artefact morning|eod|weekly [--note S]

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 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|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 purge

Emergency fast-path close for current stock/ETF and single-leg option positions.

canary purge SYMBOL, canary purge --all, and purge execute close live positions through the broker. They carry the same gate as canary order: an explicit human instruction for that exact action, in that moment. dry-run, status, and monitor only read.

Guard confirm. CLI only, with no MCP tool: emergency local-terminal purge-book workflow; deliberately withheld from MCP until execution/review safety is proven.

canary purge SYMBOL|'*' [--wait 2s] [--json]
canary purge --all [--wait 2s] [--json]
canary purge restore SYMBOL|'*' [--scale 0.5] [--execute] [--json]
canary purge status [PURGE_ID] [--json]
canary purge monitor [PURGE_ID] [--watch --rate 1s]
canary purge dry-run [--json]

Subcommands

Flags

canary backtest

Offline stress/regime/opportunity backtest harness from JSONL snapshots.

Guard local. CLI only, with no MCP tool: offline research harness over local JSONL fixtures; not a live broker/MCP operation.

canary backtest stress|regime|opportunity|build-regime|build-opportunity --input PATH [--json]
canary backtest build-opportunity-pit --bars BARS.jsonl --bars-manifest MANIFEST.json [--symbols SYM[,SYM...]] [--sample-step-bars 21] [--holdout-start-date YYYY-MM-DD --holdout-plan ID]
canary backtest opportunity --input PATH [--max-slots N] [--bars BARS.jsonl] [--bars-manifest MANIFEST.json]
canary backtest research-opportunity --input SCORED_PIT.jsonl [--plan all|ID[,ID...]] [--max-slots N] [--bars BARS.jsonl] [--bars-manifest MANIFEST.json] [--json]
canary backtest score-opportunity --input PIT.jsonl --bars BARS.jsonl [--bars-manifest MANIFEST.json] [--target-policy net-excess-positive]
canary backtest capture-opportunity [--preset top-movers
--symbols SYM[,SYM...]] [--include-regime] [--split tuning|holdout] [--holdout-plan ID] [--append PATH] [--json]
canary backtest export-opportunity-bars --symbols SYM[,SYM...] --bars BARS.jsonl --bars-manifest MANIFEST.json [--benchmark QQQ] [--lookback-days 420] [--json]

Subcommands: stress, regime, opportunity, research-opportunity, build-regime, build-opportunity, build-opportunity-pit, score-opportunity, capture-opportunity, export-opportunity-bars.

Flags

canary scan

Run a scanner preset or an ad-hoc scan; dump the gateway catalog with scan params.

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

canary scan <preset>
canary scan list
canary scan params [--instrument STK] [--raw]
canary scan --type SCANCODE --exchange LOCATIONCODE [--instrument STK|STOCK.EU] [--limit N] [--min-price 5] [--require-live] [--json]

Subcommands: list, params.

Flags

canary size

Fixed-fractional position sizing pegged to live NLV.

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

canary size --symbol SYM --entry F --stop F [--risk-pct 1.0] [--side long|short] [--lot 1] [--fx 1.0] [--json]

Flags

canary trading

Local trading gate status and configuration.

status reads the local gate. paper-smoke is a release check that places one far-off-market paper order and cancels it, so it needs a paper account and an explicit human instruction.

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

canary trading status [--json]
canary trading paper-smoke [--timeout 30s] [--json]

Subcommands

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.

Broker writes are gated. place, modify, and cancel reach the broker, and each one needs an explicit instruction from the human at the terminal, in that moment, for that exact transaction. preview and status only read: a preview drafts an order and can mint a local token, but it never transmits. A plan, a proposal, or a preview is evidence, never authority to submit.

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 --trigger-method 2] [--json]
canary order preview buy|sell SYMBOL YYYYMMDD C|P STRIKE QTY [--order-type TRAIL-LIMIT --trail-percent PCT --limit-offset PRICE] [--json]
canary order place --preview-token TOKEN [--json]
canary order modify ID --preview-token TOKEN [--json]
canary order cancel ID [--json]
canary order status 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.

Run this from a plain shell rather than the full-screen terminal app: it owns a long-lived process or an installer lifecycle.

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.

Run this from a plain shell rather than the full-screen terminal app: it owns a long-lived process or an installer lifecycle.

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.

Run this from a plain shell rather than the full-screen terminal app: it owns a long-lived process or an installer lifecycle.

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

Flags

canary setup

Wire Canary into a local AI client (default: claude-desktop).

Guard local. CLI only, with no MCP tool: local configuration verb (writes claude_desktop_config.json); not a daemon RPC, no LLM should ever call it.

Run this from a plain shell rather than the full-screen terminal app: it owns a long-lived process or an installer lifecycle.

canary setup [claude-desktop]

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

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