keel-trade 0.4.0

Keel — CLI and MCP server for AI-driven crypto strategy development

Keel Agent SDK

Keel is a quantitative crypto trading platform. This SDK provides CLI and MCP tools for AI agents to create, validate, backtest, and deploy trading strategies.

Quick Start

pipx install keel-trade                             # or: uv tool install keel-trade
keel auth login                                     # Opens a browser; --key <token> for CI/SSH
claude mcp add keel --command "keel mcp serve"      # Register local stdio MCP for Claude Code
keel components search "momentum"                   # Search 160+ components (local)
keel strategy checkout str_abc123                   # Pull strategy for editing
keel strategy validate                              # Local 9-pass validation
keel strategy push -m "tuned parameters"            # Push changes to platform
keel backtest run str_abc123 --start-date 2024-01-01 --end-date 2025-01-01

Authentication

keel auth login opens your browser and runs the OAuth 2.1 + PKCE loopback flow against app.usekeel.io/oauth/connect. The CLI captures the redirect on a temporary 127.0.0.1:<random> listener, exchanges the code for access + refresh tokens, and stores them in ~/.keel/config.yaml. Access tokens refresh transparently before each request.

For headless environments where CLI and browser are not on the same machine (CI, SSH, GitHub Codespaces, WSL without port forwarding), use keel auth login --key <token> with a token from app.usekeel.io/settings?tab=api-keys. For the live-trading scope tier add --scope live to pre-check the "Include live trading" consent.

Strategy Workspace

Agents use a checkout/push/pull model to iterate on strategies:

# Start from existing strategy
keel strategy checkout str_abc123    # Pull to ~/.keel/workspace/

# Or create new (auto-checks out)
keel strategy create strategy.py     # Creates on platform + local checkout

# Edit locally — commands auto-detect the workspace
keel strategy validate               # No file arg needed
keel strategy explain                # Structure walkthrough
keel universe set --mode top_volume --top-n 30   # Edits file in place

# Push to platform (creates version, enables backtesting)
keel strategy push -m "added universe"

# Check sync state
keel strategy status                 # current / ahead / behind / conflict

# If someone edited in the web editor
keel strategy pull                   # Pull their changes

Available Tools

Local (no API key)

Command	Description
keel components search <query>	Search components by keyword
keel components detail <name>	Full component spec
keel components after <name>	Type-compatible successors
keel components before <name>	Type-compatible predecessors
keel components list	List all 160+ components
keel components reference [topic]	DSL reference docs
keel strategy new <name>	Create from template
keel strategy validate [file]	Validate strategy (auto-detects workspace)
keel strategy explain [file]	Explain structure
keel strategy diff <a> <b>	Structural diff
keel strategy stage [file]	Pipeline completeness check
keel strategy examples	Browse examples
keel strategy patterns <query>	Composition patterns
keel strategy lock-status [file]	Component version drift
keel strategy lock-upgrade [file]	Upgrade component versions
keel universe get [file]	Read universe config
keel universe set [file] --mode ...	Set universe (writes back to workspace)
keel universe add-group [file] <name>	Add asset group
keel universe modify-group [file] <name>	Modify asset group
keel universe remove-group [file] <name>	Remove asset group

Workspace (requires API key)

Command	Description
keel strategy checkout <id>	Pull strategy to local workspace
keel strategy push [-m "msg"]	Push local changes to platform
keel strategy pull [--force]	Pull remote changes
keel strategy status	Compare local vs remote
keel strategy workspaces	List checked-out strategies
keel strategy discard	Remove local workspace

Remote (requires API key)

Command	Description
keel auth login	Store API key
keel auth whoami	Current identity
keel strategy create <file>	Create on platform + auto-checkout
keel strategy compile [file]	Compile (needs live components)
keel strategy list	List platform strategies
keel strategy show <id>	Strategy details
keel strategy update <id> <file>	Update strategy
keel backtest run <id> --start-date --end-date	Start backtest
keel backtest status <id>	Check progress
keel backtest results <id>	Get results
keel backtest list	List backtests
keel live deploy <id>	Deploy strategy
keel live list	List deployments
keel live positions <id>	View positions
keel live stop <id>	Stop deployment
keel sharing create-link <id>	Share a strategy
keel sharing fork <share_id>	Fork shared strategy
keel audit list	View action history

Authentication

export KEEL_API_KEY=sk_org_xxx    # Env var (preferred for agents)
keel auth login                    # Interactive (stores in ~/.keel/config.yaml)

Output Formats

All commands support --format (json | table | tsv | human). Default: json in agent mode, human in terminal.

Agent mode is auto-detected via CLAUDE_CODE, CURSOR_AGENT, AIDER, GITHUB_COPILOT, or KEEL_AGENT_MODE env vars.

Exit Codes

Code	Meaning
0	Success
1	General failure
2	Usage error
3	Not found
4	Auth failed
5	Conflict (push rejected — pull first)
6	Insufficient entitlements
7	Validation failed

MCP Server

{"keel": {"command": "keel", "args": ["mcp", "serve"], "env": {"KEEL_API_KEY": "sk_org_xxx"}}}

The MCP server exposes each CLI command directly as a named tool (~70 total) — there is no meta-tool layer. Tools are grouped by domain (strategy_components_*, strategy_*, universe_*, backtest_*, live_*, accounts_*, sharing_*, audit_*, market_data_*) plus the SDK helpers keel_status and strategy_find_local. Live-trading mutation tools (live_deploy, live_pause, live_resume, live_stop) are gated by API-key runner.* scope and removed from tools/list when the key cannot create deployments. Resources: keel://components/catalog and keel://dsl/reference/{topic}.

Strategy Workflow

1. Discover: keel components search "momentum" → find components
2. Compose: keel strategy new my_strat → create from template
3. Validate: keel strategy validate → check for errors
4. Stage: keel strategy stage → verify backtest-ready
5. Create: keel strategy create my_strat.py → upload to platform
6. Backtest: keel backtest run str_xxx --start-date ... --end-date ...
7. Iterate: edit → keel strategy push → backtest → repeat
8. Deploy: keel live deploy str_xxx → go live