CLI

The krawl CLI wraps the REST API so you can run research, manage async tasks, and configure lookouts from a terminal or shell script.

Status: documented contract. This page is the specification for the CLI's commands and behavior. The published package is rolling out; until it lands on the public registries, this is the canonical contract the CLI implements. (Actual package publishing is tracked separately and out of scope here.)

InstallCopy Anchor Link

The CLI is distributed as a Python package (primary) with a Node wrapper:

# Python (recommended — isolated install)
pipx install krawl-cli
# or
pip install krawl-cli

# Node
npm install -g @krawl/cli

Verify:

krawl --version

AuthenticationCopy Anchor Link

The CLI reads your API key from the KRAWL_API_KEY environment variable:

export KRAWL_API_KEY="krawl_live_xxxxxxxxxxxxxxxxxxxxxxxx"

You can override the base URL (e.g. to point at a staging or proxied Krawl deployment) with KRAWL_BASE_URL (default https://api.krawl.sh). A --api-key flag overrides the env var per command. The CLI sends the key in the X-API-Key header on every request, just like the REST API. See Authentication.

Common commandsCopy Anchor Link

Run researchCopy Anchor Link

# Stream a deep research run (SSE) to your terminal
krawl research "What is EIP-4844 and who benefits?"

# Pick a mode and tune intensity
krawl research "State of L2 rollups" --mode deep --depth 80 --breadth 5

# Quick mode for fast answers
krawl research "Latest Solana TPS" --mode quick

Output defaults to rendered markdown. Use --json for the raw result object or --output report.md to write the report to a file.

Async tasksCopy Anchor Link

# Submit a background job; prints the task id
krawl research "Long multi-source report" --async

# List your tasks
krawl tasks list

# Check / wait on a task
krawl tasks get <task_id>
krawl tasks wait <task_id>        # blocks until done|error, then prints result

Compare resultsCopy Anchor Link

krawl compare "AI agents" --result-ids 9f1c... 7b3e...

Maps to POST /research/compare.

LookoutsCopy Anchor Link

krawl lookouts create "Watch AI agent funding" --schedule daily \
  --webhook-url https://example.com/notify
krawl lookouts list
krawl lookouts run <lookout_id>
krawl lookouts delete <lookout_id>

See Lookouts and Webhooks.

Global flagsCopy Anchor Link

Exit codesCopy Anchor Link

The CLI maps API failures to non-zero exit codes so scripts can branch on them:

On 429/5xx the CLI retries with exponential backoff + jitter, honoring Retry-After. See Rate Limits & Retries.