Canary
DocumentationStart

Your first session

Updated: 2026-08-09

This walkthrough uses only read-only commands. It assumes Canary is installed and a local IB Gateway or TWS session is available. Install and first run covers setup.

1. Prove the authority

canary status

Start with the connected account mode and gateway endpoint, then read storage, subsystem, data-farm, and background-task health. An idle daemon is neutral; a normal command starts it on demand. Missing or stale source evidence remains a warning or unavailable state rather than becoming a clean result.

A ready Gateway does not configure IBKR statements. Before relying on Recon, statement-derived equity, or Canary Edge, complete Set up broker reporting. It creates one shared Activity Flex Query for all three consumers. Then verify the independent reporting lane:

canary reporting status

This distinguishes local credentials, broker reachability, report freshness, observed fields, sections not returned, and returned-empty sections that cannot yet prove their field choices.

2. Read the account and book

canary account
canary positions --by underlying

Both reads identify one selected account and mode. A missing value stays missing, and an unresolved multi-account login is refused rather than combined. Check positions freshness and Greeks coverage before relying on aggregate exposure.

3. Read the desk brief

canary brief

The default view leads with assessment completeness, then findings needing review, dated context, and grouped coverage gaps. A missing observation time is explicit; a retained finding does not become current merely because the brief was generated now.

Use canary brief --details for the full Review and Ready evidence and source diagnostics. The app offers the same overview with expandable details. canary regime --explain opens all eight market indicators, their observation times, thresholds, and independent source failures. canary stress --details opens portfolio-risk evidence and diagnostics. JSON and MCP retain the complete typed evidence; the compact human view does not change risk decisions.

4. Inspect the rulebook

canary rules
canary policy show
canary recon show

rules reports the hardest advisory finding and every unknown input. policy show identifies the approved risk constitution. recon show compares retained broker statements with the declared capital ledger. The read commands do not acknowledge, override, dismiss, or change any state.

5. Inspect current work

canary proposals list
canary opportunities list
canary orders open

Proposals are close/reduce-only protection candidates. Opportunities are option-exercise candidates. Order reads inspect the local lifecycle journal. These records are evidence, not broker-write authority; any action requires the separate trading build, a fresh exact review contract, daemon revalidation, and an explicit instruction for that transaction.

6. Analyze an explicitly named symbol

canary technical SPY,QQQ

The technical read batches daily trend, relative strength, ATR, and liquidity evidence for named stocks or ETFs. It reports degraded history rather than silently ranking an incomplete row.

7. Ask through an MCP host

The bundled MCP server is read-only. Ask the question rather than naming a tool:

Ask Typical tool
“What needs attention today?” canary_brief
“How does my account look?” canary_account, then canary_positions
“Is broker reporting ready for Recon and Edge?” canary_reporting
“What did my past stock, ETF, and option activity actually deliver?” canary_edge
“Which rulebook inputs are unknown?” canary_rules
“Are there protection or exercise candidates?” canary_proposals or canary_opportunities
“Why is a local order still open?” canary_orders_open, then canary_order_status

MCP has no resource subscriptions, preview tools, settings writes, governance writes, or broker-write tools. Working with agents has the host setup and evidence rules.

Where to go next