caidos

A command-line interface for Caido proxy, built with Bun and the official @caido/sdk-client SDK. Designed for terminal-based HTTP traffic analysis, request replay, and security testing — with machine-readable JSON output suitable for AI agent consumption.

Install

# Run without installing (bunx)
bunx caidos setup <your-pat>
bunx caidos recent

# Or clone and run locally
git clone https://github.com/filipnyquist/caidos.git
cd caidos && bun install
bun run src/cli.ts setup <your-pat>

Claude Code Skill

Install the /caido skill for Claude Code:

# Personal (available in all projects)
bunx caidos install-skill

# Project-scoped (version-controlled with repo)
bunx caidos install-skill --project

After installing, use /caido in any Claude Code session to interact with Caido proxy.

Setup

Authenticate

Configure your Caido Personal Access Token:

bunx caidos setup <your-pat>
bunx caidos setup <your-pat> --url https://caido.example.com

Or set environment variables:

export CAIDO_URL=http://localhost:8080  # default
export CAIDO_PAT=<your-pat>

Tokens are cached to ~/.caido-cli/ for fast subsequent invocations (~70ms auth).

Commands

All commands output JSON to stdout, diagnostics to stderr.

Request History

# Search with HTTPQL filter
caidos search 'req.host.eq:"example.com"'
caidos search 'resp.code.eq:"403"' --limit 10

# List recent requests
caidos recent --limit 20

# Get full request/response by ID
caidos get 42 --max-body 5000

# Export as curl
caidos export-curl 42

Replay

# Replay a request from history (~0.5s response time)
caidos send 42
caidos send 42 --keep              # persist in Caido Replay UI
caidos send 42 --max-body 10000

# Send a raw HTTP request
caidos send-raw "GET /api/users HTTP/1.1\r\nHost: example.com\r\n\r\n" example.com 443 true
caidos send-raw "POST /login HTTP/1.1\r\nHost: example.com\r\nContent-Length: 28\r\n\r\nusername=admin&password=x" example.com 443 true --keep

# List replay sessions
caidos replay-sessions

# View entries in a session
caidos replay-entries 1 --max-body 2000

# Delete sessions
caidos delete-sessions 1 2 3

Findings

# List security findings
caidos findings --limit 20

# Get finding details
caidos get-finding 1

# Create a finding
caidos create-finding 42 --title "XSS in search parameter" --desc "Reflected input in /search?q="

Management

caidos scopes          # List scopes
caidos filters         # List filter presets
caidos projects        # List projects
caidos envs            # List environments
caidos workflows       # List workflows
caidos select-project 2  # Switch active project

Intercept

caidos intercept-status    # RUNNING or PAUSED
caidos intercept-enable    # Resume intercept
caidos intercept-disable   # Pause intercept

Info

caidos health     # Instance health check
caidos instance   # Instance settings
caidos viewer     # Current user
caidos plugins    # List installed plugins

Utilities

caidos encode url "hello world"
caidos encode base64 "secret"
caidos decode hex "48656c6c6f"

HTTPQL Syntax

Caido uses HTTPQL for filtering request history. Values must be quoted:

| Filter | Example | |--------|---------| | Method | req.method.eq:"POST" | | Host | req.host.eq:"api.example.com" | | Path | req.path.contain:"/api/" | | Status code | resp.code.eq:"200" | | Combined | req.method.eq:"POST" AND resp.code.eq:"403" |

Common Flags

| Flag | Default | Description | |------|---------|-------------| | --limit N | 50 | Max results to return | | --max-body N | 2000 | Max response body bytes to include | | --keep | off | Persist replay session in Caido UI | | --url U | - | Override Caido instance URL | | --help | - | Show usage |

Architecture

src/
  cli.ts              Entry point, arg parsing, command dispatch
  client.ts           SDK client singleton, PAT auth, token caching
  output.ts           HTTP message decoding, truncation, curl export
  commands/
    requests.ts       search, recent, get, export-curl
    replay.ts         send, send-raw, replay-sessions, replay-entries, delete-sessions
    findings.ts       findings, get-finding, create-finding
    management.ts     scopes, filters, projects, envs, workflows
    intercept.ts      intercept-status, intercept-enable, intercept-disable
    info.ts           health, instance, viewer, plugins, setup
    encode.ts         encode, decode utilities
    skill.ts          install-skill command

Requirements

• Bun >= 1.0
• Caido instance with a Personal Access Token