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

CLI Reference

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 search --tag baseline
keel strategy search --share-id gDXjURKqWPs8CZ4eXdqAI

`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,live-write before keel mcp serve to expose deploy/control MCP tools.

`keel live deploy <strategy_id>` (destructive)

Deploy a strategy to a live Hyperliquid account. Defaults to preview mode and returns planned actions without firing real orders. Pass --no-preview only after the user explicitly asks to deploy live.

keel live deploy str_abc123 --account-id acct_xyz789                # preview first
keel live deploy str_abc123 --account-id acct_xyz789 --no-preview   # actually deploy
keel live deploy str_abc123 --account-id acct_xyz789 \
    --schedule "0 */4 * * *"                                        # custom cron

Actual deploys require both 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 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 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/settings/accounts.

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-trading mutations (deploy, pause, resume, stop) 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.

`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 an actual live deploy can fire.

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

CLI Reference

On this page