Broker CLIWIP
BlogReference

Command Reference

Complete reference for every broker-cli command. Every response uses a stable JSON envelope:{ok,data,error,meta}with request IDs for tracing and audit correlation. Use supported flags where available and note command-specific behavior in each section.

Setup

Install-time onboarding and cleanup. E*Trade OAuth is handled inside `broker setup`.

broker setup

Interactive setup wizard: choose provider, configure credentials, and complete E*Trade OAuth.

broker setup

Use this command for all provider onboarding.

broker update

Sync broker-cli source checkout to the latest commit on origin/main.

broker update [OPTIONS]
--forceDiscard tracked local changes before syncing
--reinstall / --no-reinstallReinstall editable packages after syncing
$ broker update
{"ok":true,"data":{"updated":true,"branch":"main","from":"...","to":"..."},"error":null,"meta":{"schema_version":"v1","command":"update.sync","request_id":"...","timestamp":"..."}}
broker schema

Return machine-readable JSON Schema for command params/results.

broker schema [COMMAND]
$ broker schema quote.snapshot
{"ok":true,"data":{"schema_version":"v1","command":"quote.snapshot","schema":{"params":{...},"result":{...}},"envelope":{...}},"error":null,"meta":{"schema_version":"v1","command":"schema.get","request_id":"...","timestamp":"..."}}

Use this in agent bootstrapping to validate payloads before command execution.

broker uninstall

Remove broker-cli install/setup artifacts (config, state, data, runtime, wrappers, completions).

broker uninstall [OPTIONS]
--yesSkip interactive confirmation
--keep-ib-appKeep installed IB Gateway app
--keep-sourceKeep source checkout under ~/.local/share/broker/source

Daemon

Manage the broker daemon process. The daemon maintains the broker connection and handles all API communication.

broker daemon start

Start the trading daemon and wait for socket readiness.

broker daemon start [OPTIONS]
--paperUse paper trading port (4002)
--gateway HOST:PORTOverride gateway endpoint
--client-id INTOverride IB client ID
$ broker daemon start
{"ok":true,"data":{"socket":"~/.local/state/broker/broker.sock"},"error":null,"meta":{"schema_version":"v1","command":"daemon.start","request_id":"...","timestamp":"..."}}

$ broker daemon start --paper
{"ok":true,"data":{"socket":"~/.local/state/broker/broker.sock"},"error":null,"meta":{"schema_version":"v1","command":"daemon.start","request_id":"...","timestamp":"..."}}
broker daemon stop

Request graceful daemon shutdown.

broker daemon stop
$ broker daemon stop
{"ok":true,"data":{"stopping":true},"error":null,"meta":{"schema_version":"v1","command":"daemon.stop","request_id":"...","timestamp":"..."}}
broker daemon status

Show daemon uptime and broker connection state.

broker daemon status
$ broker daemon status
{"ok":true,"data":{"uptime_seconds":3421.4,"connection":{"connected":true,"account_id":"..."},"socket":"~/.local/state/broker/broker.sock"},"error":null,"meta":{"schema_version":"v1","command":"daemon.status","request_id":"...","timestamp":"..."}}
broker daemon restart

Stop then start the daemon.

broker daemon restart [OPTIONS]
--paperRestart using paper trading port

Market Data

Real-time quotes, streaming, option chains, and historical bars.

broker quote

Snapshot quote for one or more symbols.

broker quote SYMBOL [SYMBOL...]
$ broker quote AAPL MSFT
{"ok":true,"data":[{"symbol":"AAPL","bid":185.2,"ask":185.25,"last":185.22,"volume":48291033},{"symbol":"MSFT","bid":412.1,"ask":412.15,"last":412.12,"volume":22104891}],"error":null,"meta":{"schema_version":"v1","command":"quote.snapshot","request_id":"...","timestamp":"..."}}
broker watch

Continuously refresh quote fields in the terminal. Ctrl+C to stop.

broker watch SYMBOL [OPTIONS]
--fields FIELDSComma-separated: bid, ask, last, volume, timestamp, exchange, currency, symbol(default: bid,ask,last,volume)
--interval INTERVALRefresh rate (e.g. 250ms, 1s, 2m)(default: 1s)
$ broker watch AAPL --fields bid,ask,last --interval 500ms
{"ok":true,"data":{"bid":185.2,"ask":185.25,"last":185.22},"error":null,"meta":{"schema_version":"v1","command":"quote.watch","request_id":"...","timestamp":"..."}}
broker chain

Fetch an option chain with paging and field selection controls for agent-efficient payloads.

broker chain SYMBOL [OPTIONS]
--expiry YYYY-MMFilter by expiration month
--strike-range LOW:HIGHRelative range around current price(default: 0.9:1.1)
--type call|putFilter by option type
--limit INTMax entries returned after filtering(default: 200)
--offset INTOffset into filtered entries(default: 0)
--fields LISTComma-separated entry fields (e.g. strike,expiry,bid,ask)
$ broker chain AAPL --type call --strike-range 0.95:1.05 --limit 5 --fields strike,expiry,bid,ask
{"ok":true,"data":{"symbol":"AAPL","underlying_price":263.3,"entries":[{"strike":252.5,"expiry":"2026-02-20","bid":null,"ask":null}],"pagination":{"total_entries":80,"offset":0,"limit":5,"returned_entries":5},"fields":["strike","expiry","bid","ask"]},"error":null,"meta":{"schema_version":"v1","command":"market.chain","request_id":"...","timestamp":"..."}}
broker history

Fetch historical price bars for a symbol.

broker history SYMBOL --period PERIOD --bar SIZE [OPTIONS]
--period 1d|5d|30d|90d|1yLookback period
--bar 1m|5m|15m|1h|1dBar size
--rth-onlyRestrict to regular trading hours
$ broker history AAPL --period 5d --bar 1h
{"ok":true,"data":[{"symbol":"AAPL","time":"2026-02-18T00:00:00","open":265.1,"close":263.29}],"error":null,"meta":{"schema_version":"v1","command":"market.history","request_id":"...","timestamp":"..."}}

Available on Interactive Brokers only.

Orders

Place, monitor, and cancel orders. Supports market, limit, stop, and bracket orders.

broker order buy

Place a buy order. Market by default unless --limit or --stop is set.

broker order buy SYMBOL QTY [OPTIONS]
--limit PRICELimit price (creates limit order)
--stop PRICEStop trigger price (creates stop order)
--tif DAY|GTC|IOCTime in force(default: DAY)
--dry-runPreview order without submitting
--idempotency-key KEYStable retry key mapped to client_order_id
$ broker order buy AAPL 100 --limit 185.00 --idempotency-key rebalance-aapl-1
{"ok":true,"data":{"order":{"client_order_id":"rebalance-aapl-1","status":"Submitted"},"dry_run":false,"submit_allowed":true},"error":null,"meta":{"schema_version":"v1","command":"order.place","request_id":"...","timestamp":"..."}}

$ broker order buy AAPL 10 --limit 185 --dry-run
{"ok":true,"data":{"order":{"client_order_id":"dryrun-...","status":"DryRunAccepted"},"dry_run":true,"submit_allowed":true},"error":null,"meta":{"schema_version":"v1","command":"order.place","request_id":"...","timestamp":"..."}}
broker order sell

Place a sell order. Market by default unless --limit or --stop is set.

broker order sell SYMBOL QTY [OPTIONS]
--limit PRICELimit price
--stop PRICEStop trigger price
--tif DAY|GTC|IOCTime in force(default: DAY)
--dry-runPreview order without submitting
--idempotency-key KEYStable retry key mapped to client_order_id
$ broker order sell AAPL 50 --limit 190.00 --tif GTC
broker order bracket

Place a bracket order: entry + take profit + stop loss.

broker order bracket SYMBOL QTY --entry PRICE --tp PRICE --sl PRICE [OPTIONS]
--entry PRICEEntry limit price (required)
--tp PRICETake-profit price (required)
--sl PRICEStop-loss price (required)
--side buy|sellOrder side(default: buy)
--tif DAY|GTC|IOCTime in force(default: DAY)
$ broker order bracket AAPL 100 --entry 185 --tp 195 --sl 180

Available on Interactive Brokers only.

broker order status

Show status for a single order by client order ID.

broker order status ORDER_ID
$ broker order status a1b2c3
{"ok":true,"data":{"client_order_id":"a1b2c3","status":"Filled","fill_qty":100,"fill_price":185.02},"error":null,"meta":{"schema_version":"v1","command":"order.status","request_id":"...","timestamp":"..."}}
broker orders

List orders with optional status and date filters.

broker orders [OPTIONS]
--status active|filled|cancelled|allFilter by status(default: all)
--since YYYY-MM-DDFilter by date
$ broker orders --status active
{"ok":true,"data":[{"client_order_id":"...","status":"Submitted","symbol":"AAPL"}],"error":null,"meta":{"schema_version":"v1","command":"orders.list","request_id":"...","timestamp":"..."}}
broker cancel

Cancel a single order by ID, or all open orders with --all.

broker cancel [ORDER_ID] [OPTIONS]
--allCancel all open orders
--confirmRequired with --all in interactive mode
$ broker cancel a1b2c3
{"ok":true,"data":{"client_order_id":"a1b2c3","cancelled":true},"error":null,"meta":{"schema_version":"v1","command":"order.cancel","request_id":"...","timestamp":"..."}}

$ broker cancel --all
{"ok":true,"data":{"cancelled":true},"error":null,"meta":{"schema_version":"v1","command":"orders.cancel_all","request_id":"...","timestamp":"..."}}
broker fills

List fill/execution history.

broker fills [OPTIONS]
--since YYYY-MM-DDFilter by date
--symbol SYMBOLFilter by symbol
$ broker fills --since 2026-02-01 --symbol AAPL
{"ok":true,"data":[{"fill_id":"...","symbol":"AAPL","qty":100,"price":185.02}],"error":null,"meta":{"schema_version":"v1","command":"fills.list","request_id":"...","timestamp":"..."}}

Portfolio

Positions, P&L, balances, and exposure analysis.

broker positions

Show current positions with unrealized P&L.

broker positions [OPTIONS]
--symbol SYMBOLFilter to a single symbol
$ broker positions
{"ok":true,"data":[{"symbol":"AAPL","qty":200,"avg_cost":178.5,"market_value":37044.0,"unrealized_pnl":344.0},{"symbol":"MSFT","qty":100,"avg_cost":405.2,"market_value":41212.0,"unrealized_pnl":692.0}],"error":null,"meta":{"schema_version":"v1","command":"portfolio.positions","request_id":"...","timestamp":"..."}}
broker pnl

Show P&L summary for today, a named period, or since a specific date.

broker pnl [OPTIONS]
--todayToday's P&L window
--period PERIODNamed period (e.g. 7d)
--since YYYY-MM-DDCustom start date
$ broker pnl --today
{"ok":true,"data":{"date":"2026-02-19","realized":1250.0,"unrealized":1036.0,"total":2286.0},"error":null,"meta":{"schema_version":"v1","command":"portfolio.pnl","request_id":"...","timestamp":"..."}}

Only one of --today, --period, or --since can be used. Defaults to --today.

broker balance

Show account balances and margin metrics.

broker balance
$ broker balance
{"ok":true,"data":{"net_liquidation":125000.0,"cash":42000.0,"buying_power":84000.0,"margin_used":41000.0},"error":null,"meta":{"schema_version":"v1","command":"portfolio.balance","request_id":"...","timestamp":"..."}}
broker exposure

Show portfolio exposure grouped by dimension. Returns percentage of net liquidation value.

broker exposure [OPTIONS]
--by symbol|sector|asset_class|currencyGrouping dimension(default: symbol)
$ broker exposure --by symbol
{"ok":true,"data":[{"key":"AAPL","exposure_pct":29.6},{"key":"MSFT","exposure_pct":33.0},{"key":"cash","exposure_pct":37.4}],"error":null,"meta":{"schema_version":"v1","command":"portfolio.exposure","request_id":"...","timestamp":"..."}}

$ broker exposure --by sector
{"ok":true,"data":[{"key":"Technology","exposure_pct":62.6},{"key":"cash","exposure_pct":37.4}],"error":null,"meta":{"schema_version":"v1","command":"portfolio.exposure","request_id":"...","timestamp":"..."}}
broker snapshot

Single-call state snapshot for agent loops: quotes, positions, balance, pnl, exposure, and connection.

broker snapshot [OPTIONS]
--symbols SYMBOLSComma-separated symbol list for quote snapshot
--exposure-by symbol|sector|asset_class|currencyExposure grouping(default: symbol)
$ broker snapshot --symbols AAPL,MSFT
{"ok":true,"data":{"symbols":["AAPL","MSFT"],"quotes":[...],"positions":[...],"balance":{...},"pnl":{...},"exposure":[...],"connection":{"connected":true}},"error":null,"meta":{"schema_version":"v1","command":"portfolio.snapshot","request_id":"...","timestamp":"..."}}

Audit

Query order history and command invocations. Export to CSV.

broker audit orders

Query order lifecycle records from audit storage.

broker audit orders [OPTIONS]
--since YYYY-MM-DDFilter by date
--status active|filled|cancelled|allFilter by status
broker audit commands

Query command invocation audit records.

broker audit commands [OPTIONS]
--source cli|sdk|ts_sdkFilter by source
--since YYYY-MM-DDFilter by date
--request-id IDFilter to a single command execution trace
$ broker audit commands --request-id 647a8306-...
{"ok":true,"data":[{"timestamp":"...","source":"cli","command":"order.place","result_code":0,"request_id":"647a8306-..."}],"error":null,"meta":{"schema_version":"v1","command":"audit.commands","request_id":"...","timestamp":"..."}}
broker audit export

Export audit rows to CSV.

broker audit export --table TABLE [OPTIONS]
--table orders|commandsWhich audit table to export
--format csvOutput format(default: csv)
--request-id IDWhen table=commands, filter export by request_id

Configuration

broker-cli uses a JSON config file and supports environment variable overrides.

Config file

Default location: ~/.config/broker/config.json

{
  "broker": {
    "provider": "ib",
    "etrade": {
      "consumer_key": "...",
      "consumer_secret": "...",
      "persistent_auth": true,
      "username": "...",
      "password": "...",
      "sandbox": false
    },
    "gateway": {
      "host": "127.0.0.1",
      "port": 4002,
      "client_id": 1
    },
    "runtime": {
      "request_timeout_seconds": 15
    }
  }
}

Environment variables

Environment variables override config file values.

BROKER_PROVIDERProvider name (etrade, ib)
BROKER_ETRADE_CONSUMER_KEYE*Trade consumer key
BROKER_ETRADE_CONSUMER_SECRETE*Trade consumer secret
BROKER_ETRADE_USERNAMEE*Trade username (persistent auth)
BROKER_ETRADE_PASSWORDE*Trade password (persistent auth)
BROKER_ETRADE_PERSISTENT_AUTHEnable persistent auth (true/false)
BROKER_GATEWAY_HOSTIB gateway host
BROKER_GATEWAY_PORTIB gateway port (4001=live, 4002=paper)
BROKER_GATEWAY_CLIENT_IDIB client ID

File locations

Config~/.config/broker/config.json
Skill file~/.local/share/broker/source/skills/broker/SKILL.md
E*Trade tokens~/.config/broker/etrade_tokens.json
Daemon socket~/.local/state/broker/broker.sock
Daemon log~/.local/state/broker/broker.log
Audit data~/.local/share/broker/