npm package: @filipnyquist/caidos
Description: CLI interface for Caido proxy — HTTP traffic analysis, request replay, and security testing with JSON output
Author: Filip Nyquist
Latest version: 0.1.0

# caidos

A command-line interface for [Caido](https://caido.io) proxy, built with [Bun](https://bun.sh) 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

```bash
# 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](https://code.claude.com):

```bash
# 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:

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

Or set environment variables:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

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

### Info

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

### Utilities

```bash
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](https://bun.sh) >= 1.0
- [Caido](https://caido.io) instance with a Personal Access Token