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 43 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; they still preview orders, which creates no order. The separate trading build adds that path, 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

Check Canary and the broker connection.

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

canary status [--json] [--gateway-diagnostics]

Flags

canary data

Check data availability and freshness.

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

canary data health [--offset N --limit N --revision ID] [--json]
canary data check [--json]

Subcommands: health, check.

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]
canary account --settlement-probe --json
canary account --currency-settlement-probe --json

Flags

canary positions

List open stock, option, bill and bond positions.

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 portfolio

Signed allocation by asset class and GICS sector, with coverage; plan reads the next portfolio action.

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

canary portfolio [plan] [--json]

Subcommands: plan.

Flags

canary market

Observed quotes, price history and a daily price/breadth/volume tape.

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

canary market [--symbol SYMBOL --range 1D] [--json]
canary market tape [--history] [--before YYYY-MM-DD] [--sessions 5] [--explain] [--json]

Subcommands: tape.

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|uk] [--json]

Flags

canary locks

Keep hedges and core holdings out of every bulk or automatic reduction; places no orders.

Guard local. CLI only, with no MCP tool: owner keep list for bulk and automatic reductions; owner CLI and console only, no model tool.

canary locks list [--json]
canary locks lock|unlock SYMBOL --con-id ID [--role hedge|core] [--expected-revision N] [--request-id ID] [--json]

Subcommands

Flags

canary watchlist

View and edit your saved watchlist; no orders or risk-limit changes.

Guard local. CLI only, with no MCP tool: owner-managed local preferences; typed read-only client and owner CLI, no model mutation tool.

canary watchlist list [--json]
canary watchlist add|remove SYMBOL [--con-id ID] [--expected-revision N] [--request-id ID] [--json]
canary watchlist replace --spec PATH|- [--json]

Subcommands

Flags

canary add

Plan a stock addition or opening and review it through existing order confirmation.

plan checks a stock addition or opening; preview creates an exact order review for separate owner confirmation through the existing order path. Neither places an order. Choose exactly one of --quantity or --max. An optional --stop-price applies only to added shares, uses GTC regular-session instructions, and stays held until the entry fills completely. Existing protection requires a separate review.

canary add plan SYNA --currency USD --limit 100 --quantity 3
canary add preview SYNA --currency USD --limit 100 --quantity 3 --stop-price 90 --json

market and call-plan read exactly one JSON object from standard input and always return JSON, even without --json. Unknown fields, extra objects, positional arguments and stock-only flags are rejected. These are read-only broker requests. The examples below use synthetic identities: replace the stock symbol and use the exact returned call contract, including its broker identity.

Stock quotes and call discovery

canary add market --json <<'JSON'
{
  "underlying": {
    "symbol": "SYNA",
    "sec_type": "STK",
    "currency": "USD",
    "exchange": "SMART"
  },
  "discover": true
}
JSON

Calls require USD. Each selected or refreshed contract must match the underlying symbol and carry its resolved con_id, sec_type: "OPT", currency: "USD", exchange: "SMART", expiry, positive strike, right: "C", multiplier: 100 and trading_class. Copy the returned contract rather than assembling a broker identity.

The response includes the resolved underlying, stock quote, price_increments, and optional calls or selected rows. Read option_mode (live, planning, or unavailable), options_session, and each row's planning or unavailable evidence. Closed-session planning prices are not executable quotes. Discovery grants no order authority or risk capacity.

Size a selected call

canary add call-plan --json <<'JSON'
{
  "contract": {
    "symbol": "SYNA",
    "con_id": 10001,
    "sec_type": "OPT",
    "currency": "USD",
    "exchange": "SMART",
    "expiry": "20300118",
    "strike": 100,
    "right": "C",
    "multiplier": 100,
    "trading_class": "SYNA"
  },
  "limit_price": 5.5,
  "budget": 5000,
  "round_size": false
}
JSON

The options session must be open. Read quantity, debit, fee_bound, and over_budget before using a result; debit includes the fee bound. Sizing returns no submission token and reserves no money. An exact order preview and separate owner confirmation are still required.

MCP exposes stock planning through canary_stock_add; market, call-plan and preview are CLI surfaces, not MCP tools.

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

canary add plan|preview SYMBOL --currency CCY --limit PRICE (--quantity N|--max) [--con-id ID] [--stop-price PRICE] [--json]
canary add market [--json] < request.json
canary add call-plan [--json] < request.json

Subcommands: plan, preview, market, call-plan.

Flags

canary setups

Review volume signals, find standard call options and check prices after entry; no orders or risk-limit changes.

options reads in three steps: listed expiries; with --expiry, up to 21 listed call strikes around the underlying price, which carry no prices (status: not_requested); with --strike, the exact call. Only that exact call carries a quote, read once within 5 seconds on a market-data line opened for this request: status: quoted with bid, ask, as_of and data_type when both sides are finite and positive, the bid is at most the ask, as_of is no more than 60 seconds old, and the broker labelled the data live, delayed, frozen or delayed-frozen. Anything else is status: missing with no prices. A missing quote never fails the selection, and the order preview still prices any order.

Guard read-only. CLI only, with no MCP tool: owner-configured entry observations ship through CLI and the typed host client first; no model tool or automatic playbook activation.

canary setups evaluate --spec PATH|- --symbol SYMBOL [--con-id ID] [--at RFC3339] [--json]
canary setups options --symbol SYMBOL --con-id ID [--expiry YYYYMMDD] [--strike N] [--json]
canary setups coverage [--session YYYY-MM-DD] [--symbol SYMBOL] [--json]
canary setups markouts [--order-ref REF] [--since YYYY-MM-DD] [--symbol SYMBOL] [--json]

Subcommands: evaluate, options, coverage, markouts.

Flags

canary chains

Daily option-chain snapshots the recorder kept: coverage per run and a CSV export of quotes, IV, greeks and open interest.

Guard read-only. CLI only, with no MCP tool: research panel of recorded option chains: bulk CSV export and run coverage for the owner, not a decision input; read-only CLI and RPC only.

canary chains recorded [--symbol SYM] [--date YYYY-MM-DD] [--limit N] [--json|--csv]

Subcommands: recorded.

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|uk|jp|hk] [--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 [--window-start DATE --window-end DATE] [--details] [--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 mandate

Mandate risk budget: the book's ex-ante volatility against the owner's budget, what drives it, gap and index stresses, and whether additions are open.

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

canary mandate [--refresh] [--json]

Flags

canary core

Core sleeve target: the month's trend and volatility decision, the target shares, the holding, the band and what the rule would trade; live, the month's row waiting for your confirmation and the last decision. Reads only.

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

canary core [--refresh] [--json]
canary core resolve [--isin ISIN] [--currency CCY] [--json]

Subcommands: resolve.

Flags

canary strategy

A registered strategy's target by its id in the strategy register: its month's decision, target, paper position and what its rule would trade, in the core's shape; with --replay, its rule run over the month-ends FROM TO on the daemon's own history, the table the lab's replay-compare reads; read-only, no orders.

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

canary strategy ID [--refresh] [--json]
canary strategy ID --replay FROM TO [--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

Review past trading decisions using broker records; replay long-option exit rules over your own option trades.

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

canary edge [--window 90d|365d] [--horizon 1|5|20] [--limit N] [--change ID] [--option ID] [--option-offset N] [--option-limit N] [--all-options] [--json]
canary edge replay [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--rules A,B,C,D,loss_exit,...] [--json]

Subcommands: replay.

Flags

canary scorecard

Score past decisions per strategy against the underlying's own history, with sequential evidence and gates.

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

canary scorecard [--sleeve S] [--horizon 5|10|21] [--limit N] [--json]

Flags

canary short-interest

Screen FINRA short positions across US equities.

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

canary short-interest screen [--listed-only] [--min-average-volume SHARES] [--min-days-to-cover N] [--min-price USD] [--min-avg-dollar-volume-20d USD] [--sort-by FIELD] [--sort-dir asc|desc] [--limit N] [--exclude SYMBOL,...] [--json]

Subcommands: screen.

Flags

canary lending

Read lending income, borrowing fees and stock market context.

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

canary lending screen [--min-rate PERCENT] [--min-price USD] [--min-avg-dollar-volume-20d USD] [--min-high-dates N] [--sort-by FIELD] [--sort-dir asc|desc] [--limit N] [--exclude SYMBOL,...] [--json]
canary lending market --symbols SYMBOL,... [--json]
canary lending rates --symbols SYMBOL,... [--json]
canary lending fees [--window 90d|365d] [--from YYYY-MM-DD --to YYYY-MM-DD] [--con-id ID] [--limit N] [--cursor CURSOR] [--fingerprint ID] [--json]

Subcommands: fees, rates, screen, market.

Flags

canary rules

Advisory daily trading rule checklist, hardest breach first, against limits you can set.

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]
canary rules policy [--json]
canary rules policy set KEY=VALUE… [--file PATH]
canary rules policy reset KEY…|--all [--file PATH]

Subcommands: history, policy.

Flags

canary policy

Every policy and setting in force, capital/drawdown state, plausibility check, 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. The read-only plausibility check (policy check) is exposed as canary_policy_check.

canary policy show [SECTION] [--explain] [--json]
canary policy check [--offline] [--config PATH] [--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 rulebook|protection|opportunity|constitution
canary policy ensure [--dry-run|--apply-plan FILE] [--config PATH] [--json]

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

IBKR statement reporting status, performance series and execution costs for Recon and Edge.

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

canary reporting status|performance|fx|costs [--json]

Subcommands: status, performance, fx, costs.

Flags

canary proposals

Review proposals to close or reduce positions.

Proposals are advisory. Only submit, submit-bundle and reduce reach the broker; each needs an explicit human instruction for that exact order, and the standard build refuses them.

Guard confirm. Also available as an MCP tool.

canary proposals status|refresh|list|preview|prepare|prepared-status|prepare-bundle|submit-bundle|bundle-status|submit|reduce|request-stop|ignore|veto|queue [--json]

Subcommands

Flags

canary opportunities

Review option exercise opportunities.

Opportunity detection is advisory. Only exercise reaches the broker; it needs an explicit human instruction for that exact action, and the standard build refuses it. exercises reads pending requests, revisions and available IBKR evidence. reconcile-exercise REQUEST_REF REVISION --evidence EVIDENCE_ID --confirm-complete records a human confirmation backed by matching broker records and sends no broker instruction. It requires an interactive human terminal; agents and MCP cannot confirm completion. Uncertain or partial requests stay blocked. See Exercise reconciliation.

Guard confirm. MCP exposes advisory opportunity snapshots and discovery refresh only; exercise reconciliation is CLI only.

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

Subcommands

Flags

canary trading

Check trading permissions and what blocks orders.

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

View settings and change supported preferences.

show reads. set writes a runtime preference, and the write path has its own gate: trading.freeze is accepted only from an interactive human terminal (the order limits live in risk-policy.toml [order_limits], not in settings), 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>=<value> [--json]

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, change, cancel or check 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. Every build serves preview; the standard build refuses place, modify, cancel, tws-cancel and tws-modify with trading_disabled before anything is sent.

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 preview buy|sell SYMBOL YYYYMMDD C|P STRIKE QTY [flags]
canary order preview buy|sell ISIN|CUSIP FACE --type BOND|BILL --currency CCY [--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]
canary order tws-cancel PERM_ID [--terms JSON] [--request-id ID] [--json]
canary order tws-modify PERM_ID --quantity N --limit PRICE [--terms JSON] [--request-id ID] [--json]

Subcommands

Flags

canary app

Run the paired mobile app.

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 Canary’s connection for AI assistants (MCP).

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 background broker connection (usually starts automatically).

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

Set up an AI assistant, the mobile app or broker statements.

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

Install the latest Canary 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

Restart Canary and any running mobile app server.

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 Canary and the mobile app server.

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. Stopping the daemon records a persistent stop intent for its socket. Ordinary CLI, MCP and app requests cannot start it again until canary restart clears that intent. 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.