Agent Integration

The CLI is designed as a data and analysis tool for AI agents. Agents bring their own LLM; the CLI provides structured data and analytical framing.

Output Formats

Agents should use -f json or -f toon. To avoid passing the flag on every command, set the default format in ~/.aixbt/config.json:

{ "format": "toon" }

About TOON

TOON is a compact, lossless encoding of the JSON data model that combines YAML-like indentation with CSV-style tabular arrays. Benchmarks show ~40% 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 signals, exactly the structure where TOON's tabular format excels. The CLI falls back to JSON automatically if TOON encoding fails for a particular payload. All examples in this guide use JSON for clarity, but everything works the same with -f toon.

The Yield/Resume Protocol

Recipes that include agent steps use a yield/resume pattern. The CLI runs data-fetching steps, then yields control to the agent for analysis, then optionally resumes for further steps.

Yield

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

{
  "status": "awaiting_agent",
  "recipe": "momentum-scan",
  "version": "1.0",
  "step": "analyze",
  "task": "Identify the strongest momentum shift and explain why it matters.",
  "instructions": "Focus on rate of change, not absolute score.",
  "returns": { "summary": "string", "topProject": "string" },
  "data": { "projects": ["..."] },
  "tokenCount": 12450,
  "resumeCommand": "aixbt recipe run momentum-scan --resume-from step:analyze --input '<json>'"
}

Key fields:

• task and instructions: what the agent should do with the data
• returns: the JSON schema the agent must produce
• data: the fetched data to analyze
• tokenCount: approximate token count of the data field, for context window budgeting
• resumeCommand: the exact command to resume the recipe

See the Recipe Specification for the full RecipeAwaitingAgent interface.

Resume

Pass the agent's output back to the CLI to continue the recipe:

aixbt recipe run momentum-scan --resume-from step:analyze --input '{"summary":"...","topProject":"..."}' --params key=value

Resume is a stateless re-invocation. All --params must be re-provided. The --input value must conform to the returns schema from the yield payload.

You can also pipe input via stdin:

echo '{"summary":"..."}' | aixbt recipe run momentum-scan --resume-from step:analyze --params key=value

Error Handling

In -f json and -f toon modes, all errors are structured:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "rateLimit": {
    "limit": 30,
    "remaining": 0,
    "resetAt": "2026-03-12T12:01:00Z"
  }
}

Error Codes

The no_api_key error includes an options array listing all four authentication modes with costs and commands. Agents can use this to self-resolve authentication without hardcoded knowledge of auth flows.

Delayed Data

Add --delayed to any command to use the free tier without authentication. Responses include a meta field describing the data staleness:

{
  "meta": {
    "tier": "free",
    "dataDelayHours": 24,
    "dataAsOf": "2026-03-11T00:00:00.000Z",
    "upgrade": {
      "description": "This response contains data delayed by 24 hours. Purchase an API key for real-time access — no account needed.",
      "protocol": "x402",
      "payment": "USDC on Base",
      "options": [
        { "period": "1 day", "price": "$0.1", "method": "POST", "url": "https://api.aixbt.tech/x402/v2/api-keys/1d" },
        { "period": "1 week", "price": "$50", "method": "POST", "url": "https://api.aixbt.tech/x402/v2/api-keys/1w" },
        { "period": "4 weeks", "price": "$100", "method": "POST", "url": "https://api.aixbt.tech/x402/v2/api-keys/4w" }
      ]
    }
  }
}

In human format, the CLI displays a warning after the output. In json and toon formats, the meta field is included in the response for the agent to interpret. Agents should surface the delay to users or decide whether the data is fresh enough for the task.

Workflow Patterns

Single-Pass Recipes

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

aixbt recipe run my-recipe -f json
# Returns: { "status": "complete", "data": { ... } }

Multi-Segment Recipes

Recipes with one or more agent steps yield once per agent step. The agent processes each yield, resumes, and repeats until the recipe completes.

CLI (fetch) -> yield -> Agent (analyze) -> resume -> CLI (fetch) -> yield -> Agent (summarize) -> resume -> complete

Combining CLI with Other Tools

Pipe CLI output to other tools or use it as context for further processing:

# Feed signals into another tool
aixbt signals -f json | jq '.data[:5]' | my-analysis-tool

# Use recipe output as context
RESULT=$(aixbt recipe run scan -f json)
echo "$RESULT" | my-agent --context

Next Steps

• CLI Overview - Installation, authentication, and commands
• Recipe Specification - Full recipe YAML reference