CLI Reference

Complete reference for all `keel` CLI verbs — strategy, backtest, live, components, accounts, sharing, audit.

The CLI and the MCP server bind to the same outcome-tool surface for research workflows: each outcome command has an MCP tool with the underscore-equivalent name (keel backtest run -> keel_backtest_run). Same args, same returns, same structured errors. A few commands are CLI-only helpers for auth, local projects, local context, and live arming.

For a generated registry-derived list of MCP tools, schemas, safety annotations, and CLI equivalents, see the MCP Tool Reference.

Local commands work without an API key (keel status, keel doctor, keel help, keel components search, keel components compose-help). Remote commands authenticate against KEEL_API_KEY or the cached OAuth login in ~/.keel/config.yaml.

Global Options

keel [OPTIONS] COMMAND
  --format [json|table|tsv|human]   Output format (auto-detected)
  --dry-run                         Preview without side effects
  --verbose                         Verbose output
  --version                         Show version
  --help                            Show help

Always-loaded outcomes

`keel status`

Report auth state, API URL, active toolsets, and the list of MCP tools visible under the current KEEL_TOOLSETS. Use as the first call when wiring up a new agent.

keel --format json status
# {
#   "share_url": null,
#   "hero_url": "https://app.usekeel.io/settings",
#   "authenticated": true,
#   "toolsets_loaded": ["always", "backtest", "read-only", "share"],
#   "tools_visible": [...]
# }

`keel doctor`

Diagnose auth, API reachability, and active toolsets. Call this when a command surfaces an unexpected error.

keel doctor

`keel help <topic>`

Fetch a Keel knowledge document by topic (phases, types, slots, composition, normalization, best_practices, dsl_syntax, ...). Same content as the keel://dsl/reference/{topic} MCP resource.

keel help dsl_syntax
keel help phases

`keel strategy` — strategy lifecycle

`keel strategy search`

List or filter strategies in your org. Replaces the old strategy list + strategy find-local commands.

keel strategy search --query "carry" --limit 10

`keel strategy get <strategy_id>`

Fetch one strategy by id — metadata, optionally source, optionally version list.

keel strategy get str_abc123
keel strategy get str_abc123 --include-source
keel strategy get str_abc123 --version v3 --include-source

`keel strategy compose`

Create or update a strategy. Dry-run validates without persisting.

keel strategy compose --source-file my_strat.py --dry-run        # validate only
keel strategy compose --source-file my_strat.py --name "my-strat"  # create
keel strategy compose --strategy-id str_abc123 --source-file my_strat.py  # update

Use dry-run compose for validation, then rerun without --dry-run to create or update the platform strategy.

`keel strategy fork <share_id_or_strategy_id>`

Fork a shared strategy or a public strategy into your org.

keel strategy fork gDXjURKqWPs8CZ4eXdqAI         # via share id
keel strategy fork str_abc123 --name "my-fork"   # direct fork by id

`keel strategy diff --ref-a <ref_a> --ref-b <ref_b>`

Structural diff between two strategy sources — local files or remote versions.

keel strategy diff --ref-a before.py --ref-b after.py
keel strategy diff --strategy-id str_abc123 --ref-a v2 --ref-b v3

`keel strategy delete <strategy_id>` (destructive)

Archive a strategy on the platform. Prompts for confirmation unless --yes.

keel strategy delete str_abc123 --yes

Local strategy workspaces

Checkout and sync a platform strategy as an editable local workspace.

keel strategy checkout str_abc123
keel strategy status str_abc123
keel strategy pull str_abc123
keel strategy push str_abc123 --message "Tweak carry lookback"
keel strategy log str_abc123 --limit 20
keel strategy restore str_abc123 --ref 3 --message "Restore pre-risk-cap version"
keel strategy workspaces
keel strategy discard str_abc123 --yes

keel strategy pull --force and keel strategy discard --yes can lose local edits. Use them only after explicit confirmation.

`keel strategy memory-read <strategy_id>`

Read agent/user notes attached to a strategy (cross-conversation memory).

keel strategy memory-read str_abc123 --limit 10

`keel strategy memory-write <strategy_id>`

Append an agent or user note to a strategy's memory.

keel strategy memory-write str_abc123 \
    --note "Tried lookback=20 — Sharpe 0.6, deep DD in Q4 2025. Try lookback=40 next."

`keel backtest` — run + summarize

`keel backtest run <strategy_id>`

Submit a backtest. By default blocks up to 90s polling; pass --no-wait to return immediately with a status_url. Omit --end-date to run through today's UTC date.

keel backtest run str_abc123 \
    --start-date 2025-06-01
keel backtest run str_abc123 \
    --start-date 2025-06-01 --end-date 2026-02-01 \
    --commit-id cmt_xxx                  # pin to a specific version
keel backtest run str_abc123 \
    --start-date 2025-06-01 --no-wait

`keel backtest watch <backtest_id>`

Poll an existing backtest until terminal or timeout. Use this after a --no-wait run or when keel backtest run returns a still-running status.

keel backtest watch btr_xyz789
keel backtest watch btr_xyz789 --timeout-s 300 --interval-s 10

`keel backtest summarize <backtest_id>`

Read terminal-state metrics + attribution for a completed backtest.

keel backtest summarize btr_xyz789

`keel live` — deploy, monitor, control

keel live CLI commands are always available, but actual live deployment is gated by OAuth live scope and local machine arming. KEEL_TOOLSETS controls MCP exposure only: keel_live_monitor is visible by default under live-read; set export KEEL_TOOLSETS=always,read-only,backtest,share,live-read,paper,live-write before keel mcp serve to expose deploy/control MCP tools.

`keel live deploy <strategy_id>` — hand off to the web app

Going live is completed by you in the Keel web app. This command places no orders and enumerates no accounts: it returns code=handoff_required with an action_url into the web deploy flow — pick or connect the Hyperliquid account, review the server-computed sizing, accept the risk, go live — plus a resume block whose token polls the handoff.

keel live deploy str_abc123                                   # prints the deploy link
keel live deploy str_abc123 --intent-token <resume-token>     # poll: pending|completed|expired
keel live deploy str_abc123 \
    --schedule "0 */4 * * *"                                  # custom cron on the handoff

The --no-preview / confirmation_token ceremony is not the way to go live. It belongs to the --direct operator escape hatch, which is inert unless the operator has set KEEL_ALLOW_DIRECT_DEPLOY=1 in the environment (and is refused outright on hosted surfaces). Only that path requires keel auth login --scope live and keel arm live set --account <account_id> on the local machine.

`keel live monitor <deployment_id>` — unified observability

One command, 12 read-only views via --view.

keel live monitor dep_123                                  # overview (default)
keel live monitor dep_123 --view positions
keel live monitor dep_123 --view equity
keel live monitor dep_123 --view pnl
keel live monitor dep_123 --view trades --symbol BTC --limit 50
keel live monitor dep_123 --view weights-history --limit 100
keel live monitor dep_123 --view funding
keel live monitor all --view portfolio                      # aggregate across deployments

Available views: overview, positions, equity, pnl, stats, weights, weights-history, executions, orders, trades, funding, portfolio.

JSON output includes freshness metadata. Treat positions as an on-demand Hyperliquid snapshot; portfolio and history views are Keel backend records and may lag the web dashboard live stream.

`keel deployments list` — every deployment in the org

keel deployments list                    # active deployments
keel deployments list --include-stopped  # include stopped and archived
keel deployments list --limit 50
keel deployments list --capital-class practice  # paper runs only

With no --capital-class the list asks for every run and labels each Live or Paper; --capital-class practice lists paper runs only and real live runs only.

Rows carry deployment_id, strategy_id, status, schedule, account_id, deployed_version_string, realized P&L, and open position count. This is the id-lookup step: deployment_id goes into keel live monitor / keel live receipt / keel live quality, and account_id into keel accounts safety. For aggregate performance across deployments use keel live monitor all --view portfolio instead.

Execution outcomes — what a bar did, and what it cost

Execution style. Live execution defaults to market (a marketable IOC limit), which needs no capability and is on for every account on the execution engine. Maker is an org grant: deny-by-default, armed only by adding maker to the org's execution_grants. A deployment executes maker only if its org has been granted it — nothing in a strategy's own configuration turns it on.

Bar-level outcomes. --view executions is the attempt timeline. Add --expand-orders for the child orders behind each attempt's counts, and --execution-run-id to narrow to one bar:

keel live monitor dep_123 --view executions --expand-orders
keel live monitor dep_123 --view executions --execution-run-id ern_abc123 --expand-orders

In --format human the fields that carry meaning are rendered rather than dumped as JSON. The slippage number always prints its lane and how many sessions it was measured over — a bps figure without both is not interpretable — and a halted bar prints the account's halt instead of an internal session id.

Receipts are per episode, not per run. An execution run covers every symbol in the universe, and each symbol's execution is its own episode with its own sealed receipt. A run with 11 episodes has 11 receipts and no single run-level receipt; the timeline row says so, and its quality_summary carries the session_id and intent_rev that address one.

keel live receipt dep_123 --session-id exs_abc123 --intent-rev 1
keel live receipt dep_123 --session-id exs_abc123 --version 1   # a superseded version

A receipt is the per-symbol record of what an execution cost: filled and residual quantity, decision- and arrival-benchmark shortfall in basis points, fee components, completeness and its missing reasons, and the terminal reason.

`keel live quality <deployment_id>` — the cost rollup

keel live quality dep_123
keel live quality dep_123 --start-date 2026-08-25 --end-date 2026-09-02
keel live quality dep_123 --style maker

The deployment-level rollup of sealed receipts — a projection of them, never a recomputation. --start-date is inclusive and --end-date exclusive. Narrow with --style / --style-version so maker and market bars are not pooled into one number.

`keel live control <deployment_id> --action <verb>` (destructive)

Pause, resume, stop, or trigger a manual rebalance on a live deployment.

keel live control dep_123 --action pause
keel live control dep_123 --action resume
keel live control dep_123 --action stop --yes
keel live control dep_123 --action trigger     # one-off rebalance

`keel paper` — paper (simulated) runs

A paper run trades a saved strategy forward with simulated fills at live Hyperliquid prices under Keel's published fill model. No real orders are placed and no funds are at risk. See Paper trading for the lifecycle, plan slots and the auto-pause rules.

`keel paper deploy <strategy_id>` — start a paper run

keel paper deploy str_abc123
keel paper deploy str_abc123 --capital 100000

Unlike keel live deploy, it completes here, in band: there is no web handoff, no exchange account, no --scope live login and no arming. The run uses the access that lets you run a backtest. --capital is the simulated starting capital, one of 1000, 10000 (the default) or 100000 US dollars. Each plan runs a set number of paper runs at once; keel plan status shows this plan's paper slots.

`keel paper control <deployment_id> --action <verb>` (destructive)

keel paper control dep_123 --action pause
keel paper control dep_123 --action resume
keel paper control dep_123 --action update
keel paper control dep_123 --action restart
keel paper control dep_123 --action stop --yes

stop is permanent for that record and frees its slot; restart starts a fresh record of the same version; update moves the run onto the strategy's newest saved version. It asks for confirmation unless --yes is passed, and it refuses a live deployment (keel live control controls those).

Monitoring a paper run

keel live monitor dep_123 --view overview
keel deployments list --capital-class practice

keel live monitor reads a paper run with the same views as a live run.

`keel components` — discovery + composition help

`keel components search`

Search the component catalog by keyword, category, type, or compatibility.

keel components search momentum
keel components search --category indicator
keel components search --after PriceDataLoader        # type-compatible successors
keel components search --before ForecastScaler        # type-compatible predecessors
keel components search --query "oscillator for mean reversion"
keel components search --limit 5

Collapses the old search / list / after / before / dump commands.

`keel components compose-help <name>`

Full schema + parameters + pitfalls + examples for a single component.

keel components compose-help ROC
keel components compose-help ForecastWeightNormalizer

`keel components describe-batch <names...>`

Fetch multiple component specs in one call. This is usually better for agents than calling single-component detail commands repeatedly.

keel components describe-batch ROC FundingRate ForecastWeightNormalizer

`keel accounts list` — Hyperliquid accounts

keel accounts list
keel accounts list acct_xyz789                    # one account detail

The full account-management flow (create / authorize / refresh-mode) is web-only — sign in at app.usekeel.io/accounts.

`keel accounts safety <account_id>` — execution HALT state

keel accounts safety acct_xyz789

A halted account executes nothing, so a deployment can look idle with no failure anywhere in its timeline. This read answers that: whether the account is halted, which halt event is current, how many frozen sessions and unresolved cancels a release still waits on, the halt's authority tier, and the block reasons.

Operator-gated. Allowlisted platform and on-call operators only — org role, plan tier and OAuth scope grant no access. Everyone else gets an operator_only refusal, and no re-login can fix it; report it as operator-only, never as an authentication problem. Clearing a halt is an operator ceremony and is deliberately not on this surface. keel arm live is a local file and is unrelated to this server-side halt.

Publish a strategy or backtest result at a public usekeel.io/share/<id> URL. Prompts for confirmation unless --yes.

keel share create str_abc123                          # share strategy (no source by default)
keel share create str_abc123 --include-source --permission fork
keel share create btr_xyz789                          # share backtest (source not applicable)
keel share create str_abc123 --expires-at 2026-12-31

Target type is inferred from the id prefix (str_* -> strategy, btr_* -> backtest). Override with --target-type strategy|backtest.

`keel audit`

`keel audit list-last`

Most recent audit events for your org.

keel audit list-last --n 20

Audit rows include tool/action name and decision. args and result_ref are best-effort fields and may be empty when the API event lacks sanitized metadata.

CLI-only escape-hatch verbs

These are not MCP tools — they exist for CLI-specific workflows.

Authentication. By default keel auth login opens your browser, runs OAuth 2.1 + PKCE against app.usekeel.io, and captures the redirect on a temporary 127.0.0.1:<random> listener. Access tokens (1h TTL) refresh transparently before each request; refresh tokens (30d TTL) rotate on every use per OAuth 2.1 §6.1. Tokens persist in ~/.keel/config.yaml.

# Default — opens browser
keel auth login

# Headless — paste a token from app.usekeel.io/settings?tab=api-keys
keel auth login --key <token>

# Live-trading scope tier (pre-checks the "Include live trading" box)
keel auth login --scope live

# Override Keel API URL (rarely needed — only for self-hosted Keel or
# internal preview environments). Defaults to https://api.usekeel.io
keel auth login --api-url <url>

# Verify
keel auth whoami
keel auth status

# Clear all credentials (api_key, refresh_token, token_expires_at,
# client_name); preserves api_url
keel auth logout

Live-control mutations (pause, resume, stop, trigger) need both the OAuth live scope tier AND keel arm live set --account <id> on the local machine — defense in depth. The CLI never auto-arms. deploy is not in that list: it hands off to the web app and places no orders itself.

`keel mcp serve`

Run the stdio MCP command for local IDE integration.

keel mcp serve                                    # stdio (Claude Code, Cursor, …)

Register this command in the agent host config. The host starts it as a child process and communicates over stdin/stdout; users do not need to run a daemon, open a port, or start a separate service.

`keel universe …`

Hand-edit universe.yaml in a local workspace.

`keel skills …`

Inspect bundled agent skills.

keel skills list
keel skills show strategy-creation

`keel project …`

Create local project scaffolding and agent instruction files.

keel project init
keel project hooks

`keel context …`

Manage user and project context read by the MCP server on session start.

keel context init
keel context add "Prefer simple carry baselines before multi-signal mixes."
keel context show

`keel arm live …`

Local live-trading arming. Required, in addition to OAuth live scope, before keel live control can fire (and by the --direct deploy escape hatch). The normal deploy path is the web handoff and needs no arming.

keel arm live set --account acct_xyz789

Stdin support

Commands that accept a file also accept - for stdin:

echo 'Pipeline([ROC(period=8)], name="test")' | keel strategy compose --source - --dry-run

Exit codes

Code	Meaning
0	Success
1	General failure
2	Usage error (bad args)
3	Not found
4	Auth failed
5	Conflict (already exists)
6	Insufficient entitlements
7	Validation failed

On this page