CLI

The AIXBT CLI gives you direct commands and declarative recipe workflows for crypto intel. For data concepts and query patterns, see the Data Guide.

Installation

npm install -g @aixbt/cli

Requires Node.js 18 or later. After install, the aixbt binary is available globally. If global install fails due to permissions, ask your user to run the install or use npx @aixbt/cli as an alternative.

Authentication

The CLI supports three authentication modes. Credentials resolve automatically based on flags, environment, and stored config.

Mode 1: API Key

aixbt login --api-key sk-your-key-here    # non-interactive (use this)
aixbt login                                # interactive prompt (requires your user)

Stored in ~/.aixbt/config.json. Used for all subsequent commands. If you or your user already has an API key, this is the fastest path.

Mode 2: Purchase Pass (x402)

Buy a time-limited access pass with USDC on Base. No account needed, but requires a wallet.

# List available passes with pricing
aixbt login --purchase-pass -f json

# Initiate purchase for a specific duration (1d, 1w, 4w)
aixbt login --purchase-pass 1d -f json

The CLI returns structured payment details to guide you through the x402 flow. See the Agent x402 Guide for wallet setup and payment execution.

Mode 3: Pay Per Use (x402)

Append --pay-per-use to any command. Pays $0.50 per API call via x402. Requires a wallet with USDC on Base.

aixbt intel --pay-per-use

Not available (but also not required) for intel clusters and intel categories.

Grounding (No Key Required)

The grounding command works without any authentication. It provides real-time market context across crypto, macro, traditional finance, and geopolitics.

aixbt grounding -f toon

Use grounding history for paginated historical snapshots (requires an API key). See the grounding section below.

All other data commands (projects, intel) require an API key or pay-per-use.

Credential Resolution Order

When multiple credentials are available, the CLI resolves them in this order:

--pay-per-use bypasses this chain entirely.

Command Reference

The CLI is self-documenting. Use these to discover commands, flags, and options:

aixbt help all -f json          # full structured reference (all commands, all flags)
aixbt <command> --help           # detailed help for a specific command
aixbt provider <name> --help     # list a provider's available actions

This guide covers concepts and workflows. For flag-level detail, use the commands above. The sections below highlight non-obvious behavior.

projects

# Filter and sort (toon for fewer tokens, json for jq piping)
aixbt projects --chain ethereum --min-momentum-score 0.5 --sort-by popularityScore -f toon
aixbt projects --tickers "BTC,ETH" -f json

# Date filters (ISO 8601 or relative: -7d, -24h, -30m)
aixbt projects --created-after -7d --has-token true -f toon

# Subcommands
aixbt projects chains -f toon
aixbt projects momentum <id> --start -7d --end -1d -f toon
aixbt projects rank <id> --start -7d --end -1d -f toon

intel

aixbt intel --tickers BTC --detected-after -24h -f toon
aixbt intel --categories "PARTNERSHIP,TECH_EVENT" --official -f json

# Subcommands
aixbt intel clusters -f toon         # list community clusters (-v for descriptions)
aixbt intel categories -f toon       # list intel categories (-v for descriptions)

grounding

Market grounding provides a high-level snapshot of current conditions across crypto, macro, traditional finance, and geopolitics. Useful as context for interpreting intel: a project's momentum means different things during a broad risk-on rally versus a sector rotation.

# Full snapshot
aixbt grounding -f toon

# Filter to specific sections (comma-separated)
aixbt grounding --sections crypto,macro -f toon

# Historical snapshot
aixbt grounding --at -24h -f toon

# Paginated history (requires API key)
aixbt grounding history -f toon
aixbt grounding history --from -7d --sections crypto -f toon
aixbt grounding history --from -7d --to -1d --page 2 -f toon

Available sections: crypto, tradfi, macro, geopolitics. Each contains a title and bullet-point items summarizing current conditions. The snapshot refreshes hourly with a 12-hour lookback window.

The history subcommand returns paginated historical snapshots sorted newest-first. It supports --from, --to, --at (anchor), --sections, --page, and --limit flags. See GET /v2/grounding/history for parameter details.

Grounding is also available as a recipe step via the grounding action, with an optional sections param:

- id: market_context
  type: api
  action: grounding

- id: crypto_only
  type: api
  action: grounding
  params:
    sections: crypto

recipe

Recipes are the most powerful way to use AIXBT data. They are declarative YAML pipelines that chain API calls, iterate over results, sample and transform data, and yield back to you for inference, all with automatic pagination and rate limiting.

You can run recipes from the official registry, but the real leverage is that you can author custom pipelines on the fly. Generate a recipe dynamically, pipe it via --stdin, and get structured results back. When a pipeline proves useful, save it to ~/.aixbt/recipes/ so you (or your user) can invoke it by name later. Over time, you can build a library of reusable analysis pipelines tailored to your user's needs.

The instructions field in agent steps is a free-form prompt: you can write instructions that direct the executing agent to use specific tools (web search, code execution, file writes, etc.), not just pure inference. This means recipes can orchestrate rich multi-tool workflows, with the CLI handling data assembly and the agent step handling everything else.

See the Recipe Specification and Recipe Building Blocks for the full YAML reference.

# Browse the official registry
aixbt recipe list -f toon

# Show recipe details (registry name or file path)
aixbt recipe info <name> -f toon

# Clone a recipe from the registry to ~/.aixbt/recipes/
aixbt recipe clone <name>
aixbt recipe clone <name> --out ./my-recipe.yaml

# Validate a recipe without executing
aixbt recipe validate <name-or-file>

# Measure context token usage (runs data steps, skips agent steps)
aixbt recipe measure <name-or-file>

# Run a recipe
aixbt recipe run <name-or-file> -f toon
aixbt recipe run <name-or-file> --param1 value1 --param2 value2
aixbt recipe run --stdin < my-recipe.yaml

# Run with agent integration (spawns Claude Code or Codex for inference steps)
aixbt recipe run <name> --agent claude
aixbt recipe run <name> --agent codex

# Resume from an agent step (yield/resume protocol)
aixbt recipe run <name> --resume-from step:<id> --input '{"picks": [...]}'

# Write segment data to files instead of stdout
aixbt recipe run <name> --output-dir ./output/

Recipe resolution order: When given a name (not a file path), the CLI checks the registry first, then ~/.aixbt/recipes/. Registry takes precedence to prevent accidental or malicious shadowing.

provider

Manage data providers and run provider actions directly. Providers come in two flavors:

• Virtual providers (market, security, defi): provider-agnostic entry points that route to the best concrete backend. Use these in recipes for smart routing and portability.
• Concrete providers (coingecko, dexpaprika, goplus, defillama): direct access to specific backends. Use provider add/remove/test to manage API keys for these.

# List all providers and their configuration status
aixbt provider list -f toon

# Add a provider API key (auto-infers tier, verifies with a probe request)
aixbt provider add coingecko --api-key CG-xxxxx
aixbt provider add defillama --api-key xxxxx --tier pro
aixbt provider add goplus --api-key xxxxx --skip-verify

# Test a provider connection
aixbt provider test coingecko -f json

# Remove a provider key
aixbt provider remove coingecko

# Run a virtual provider action directly
aixbt provider market chart --geckoId bitcoin --limit 30 -f json
aixbt provider security security-check --chain ethereum --address 0x... -f json

Providers also expose direct data commands: aixbt provider <name> --help lists all available actions.

Global Flags

These flags are available on every command:

Output Formats

Control output format with -f or --format.

Always use -f json or -f toon. Human format includes ANSI escape codes and is not machine-parseable.

TOON (toonformat.dev) is a compact, lossless encoding of the JSON data model that combines YAML-like indentation with CSV-style tabular arrays. Benchmarks show 30-60% fewer tokens than JSON while achieving higher retrieval accuracy across tested models. It's a particularly good fit for AIXBT data, which is mostly uniform arrays of projects and intel, exactly the structure where TOON's tabular format excels. The CLI falls back to JSON automatically if TOON encoding fails for a particular payload.

When to use each format:

• -f toon: Default choice for agent consumption. 30-60% fewer tokens than JSON with equal comprehension accuracy. Use for all hot-path commands.
• -f json: Use when piping to jq, when the consumer expects JSON, or when debugging payloads.

Resolution order: --format flag > config.format > human. Structured data goes to stdout; spinners and progress go to stderr.

Verbosity

The -v flag controls how much data is included in responses. Each level adds more fields.

The default page limit is 25 for human format, 50 for structured formats (json, toon). Override with --limit.

Historical Queries

The --at flag returns data as it existed at a past point in time. Supported on projects, intel, projects momentum, projects rank, and grounding.

# What was surging 24 hours ago?
aixbt projects --at -24h -f toon

# Intel as of a specific timestamp
aixbt intel --tickers BTC --at 2026-03-28T12:00:00Z -f toon

# Market context from yesterday
aixbt grounding --at -1d -f toon

Accepts ISO 8601 timestamps or relative expressions (-30m, -24h, -7d).

In Recipes

When --at is passed to recipe run, the CLI auto-injects the timestamp into all API steps that support it. Steps that already set their own at param are not overridden. External provider steps receive the equivalent before_timestamp parameter, and OHLC data is capped to the specified time window.

This enables backtesting: run the same recipe against historical data without modifying the YAML.

# Run a recipe as if it were 7 days ago
aixbt recipe run momentum-scan --at -7d --agent claude

Environment Variables

Error Handling

All errors are structured. In json/toon format, errors produce a JSON object with error (code) and message fields. In human format, errors are printed to stderr.

Error Codes

Errors include contextual details. For example, NO_API_KEY includes an options array with all access modes, and RATE_LIMIT_EXCEEDED includes retryAfterSeconds.

Rate Limiting

The CLI handles rate limiting automatically, both for the AIXBT API and external providers. During recipe execution, rate limit waits happen transparently within pagination and for: loops.

If a command fails with RATE_LIMIT_EXCEEDED, wait the indicated retryAfterSeconds and retry. You do not need to implement retry logic for recipe execution; it handles this internally.

Agent Execution

The --agent flag on recipe run spawns a local LLM agent for inference steps. The CLI handles all data fetching, pagination, and assembly, then delegates analysis to you (or another agent).

Supported Agents

How It Works

1. The CLI executes recipe data steps (API calls, for: loops, transforms)
2. When an agent step is reached, the recipe yields with status: "awaiting_agent"
3. The CLI assembles the recipe data and spawns the agent with instructions and a return schema
4. The agent follows the instructions and returns JSON
5. The CLI resumes recipe execution with the agent's response
6. For final analysis steps, the agent streams output to stdout

Configuration

# Per-command
aixbt recipe run daily_digest --agent claude

# Environment variable
export AIXBT_AGENT=claude

# Config file (~/.aixbt/config.json)
{ "agent": "claude", "agentAllowedTools": ["Read"] }

Resolution order: --agent flag > AIXBT_AGENT env > config.agent.

The agentAllowedTools config limits which tools the agent can use during inference. This is a safety measure; by default, agents have access to all tools.

No-Agent Mode (Yield/Resume)

Without --agent, recipe run outputs the raw recipe result as JSON/TOON. You are responsible for handling agent steps via the yield/resume protocol. This is the more flexible mode: when the recipe yields, you can use any tools available to you (web search, code execution, file I/O, other APIs) to fulfill the instructions, not just LLM inference. The --agent flag constrains execution to a single spawned agent; yield/resume lets you bring your full capabilities to bear.

When a recipe reaches an agent step, the CLI returns a RecipeAwaitingAgent payload:

{
  "status": "awaiting_agent",
  "recipe": "momentum-scan",
  "version": "1.0",
  "step": "analyze",
  "instructions": "Identify the strongest momentum shift and explain why it matters.",
  "returns": { "summary": "string", "topProject": "string" },
  "data": { "projects": ["..."], "details": ["..."] },
  "tokenCount": 12450,
  "progress": { "stepsCompleted": 2, "stepsTotal": 5, "segmentIndex": 0, "segmentsTotal": 2 },
  "remaining": "After your response: 2 data steps, then final analysis.",
  "resumeCommand": "aixbt recipe run momentum-scan --resume-from step:analyze --input '<json>'",
  "carryForward": { "projects": ["..."] }
}

Key fields:

• instructions: what you should do with the data
• returns: the JSON schema you must produce
• data: object mapping context step IDs to their collected data. May include _fallbackNotes if any provider steps were skipped due to missing keys
• tokenCount: approximate token count of data (JSON.stringify(data).length / 4), for your context window budgeting
• progress: step and segment counters so you know where you are in the pipeline
• remaining: prose description of what happens after you respond
• resumeCommand: pre-built CLI command to resume the recipe
• carryForward: pre-yield step data needed by downstream agent steps or analysis.context. Restored automatically when using --agent; in yield/resume mode, the orchestrating agent already has this data in its conversation context

To resume, pass the agent's output back:

aixbt recipe run momentum-scan \
  --resume-from step:analyze \
  --input '{"summary": "...", "topProject": "..."}' \
  -f json

Resume is a stateless re-invocation. All original --params must be re-provided. The --input value must conform to the returns schema from the yield payload. The CLI re-parses the entire YAML from scratch on resume.

Parallel Agent Steps

Recipes with agent steps that include a for: field create fan-out patterns. The CLI spawns up to 3 agent invocations in parallel, each processing one item. Results are collected and merged back into the recipe flow.

The yield payload for parallel steps includes additional fields:

• parallel: { items, itemKey, concurrency, perItemContext, sharedContext }, which describes the fan-out
• parallelExecution: instructions for you on how to process items

You must return results wrapped as { "_results": [...] } with one entry per item.

Workflow Patterns

Single-Pass Recipes

Recipes with no agent steps return status: "complete" immediately. No yield/resume cycle needed.

aixbt recipe run data-only-recipe -f json
# Returns: { status, recipe, version, timestamp, data, tokenCount, hints?, analysis? }

Multi-Segment Recipes

Recipes with one or more agent steps yield once per agent step.

CLI (fetch) → yield → Agent (analyze) → resume → CLI (fetch more) → yield → Agent (summarize) → resume → complete

With --agent, this loop is handled automatically. Without --agent, you must drive each yield/resume cycle manually.

Provider Configuration

None of the external providers require an API key to start. CoinGecko, DeFiLlama, and GoPlus all have free tiers that work without configuration. That said, CoinGecko in particular benefits from registering for their free demo API key, which unlocks additional actions and higher rate limits. Run aixbt provider list -f json to see current configuration and tier details. Keys are resolved with the same 3-layer pattern as the AIXBT API key (flag > env var > config file).

In Recipes

Providers are used in recipe steps via the source field. Use virtual providers (market, security, defi) for smart routing, or concrete providers for direct access:

steps:
  - id: price_data
    type: api
    action: chart
    source: market
    params:
      geckoId: bitcoin
      limit: 30

When a recipe step requires a provider key that isn't configured, behavior depends on the fallback field:

• With fallback: The step is skipped and produces { _fallback: true, message: "..." } instead of failing. The fallback value (a string) is included in the message shown to you. The recipe continues.
• Without fallback: The step fails with an error.

Config File

The CLI stores configuration in ~/.aixbt/config.json (0600 permissions). The full schema:

{
  "apiKey": "sk-...",
  "apiUrl": "https://api.aixbt.tech",
  "keyType": "full",
  "expiresAt": "2026-04-19T00:00:00Z",
  "scopes": ["read"],
  "format": "toon",
  "limit": 50,
  "agent": "claude",
  "agentAllowedTools": ["Read"],
  "providers": {
    "coingecko": { "apiKey": "CG-xxx", "tier": "demo" },
    "defillama": { "apiKey": "xxx", "tier": "pro" }
  }
}

All fields are optional. The file is created by aixbt login and updated by provider add.

Update Notifications

When a newer CLI version is available, structured output includes a meta.update object with current, latest, type, and a human-readable message. In human format, a notification box appears on the next run.

Quick Start

1. Discover commands: aixbt help all -f toon returns a complete structured reference of every command, flag, and option. Use aixbt <command> --help for details on any specific command.

2. Check auth: aixbt whoami -f toon. If not authenticated, ask your user to run aixbt login. The grounding command works without auth.

3. Use -f toon to save tokens. TOON saves 30-60% vs JSON with equal comprehension accuracy. Use -f json when piping to jq or when the consumer expects JSON.

4. Use recipes for complex analysis: Browse aixbt recipe list -f toon, then run with --agent for automated inference or pipe a recipe via --stdin.

5. Handle errors structurally. Errors in -f json mode include an error code and message. The Error Codes table lists every code with recovery actions.