Kiroo Docs — Command Reference

Prerequisites

Before you begin your time-travel journey, you need a private storage vault to store your API traces. Kiroo uses Supabase for secure, encrypted storage.

What you need

Supabase Project: A standard Supabase project URL (e.g., https://xyz.supabase.co).
Service Role Key: Required for backend SDK to upload traces. Do not use the Anon key.
Bucket Name: A storage bucket named kiroo-captures (optional, defaults to this).

Production SDK

The @kiroo/sdk is our heart. It captures production API traffic with zero overhead and syncs it securely to your storage (Supabase).

npm install @kiroo/sdk

1. Integration

Add the capture middleware early in your application stack. It handles sanitization, buffering, and batch-upload in the background.

const { capture } = require('@kiroo/sdk');

app.use(capture({
  supabaseUrl: 'your-project.supabase.co',
  supabaseKey: 'production-service-role-key',
  sampleRate: 0.1 // 100% of errors are always captured
}));

Non-Blocking

The SDK uses in-memory buffering and uploads batches every 30 seconds. It will never block your primary API response.

2. Exposing Replay IDs

The SDK injects a unique X-Kiroo-Replay-ID into every response. Expose this in your error responses so developers can fetch the exact trace.

app.use((err, req, res, next) => {
  const id = res.get('X-Kiroo-Replay-ID');
  res.status(500).json({ error: 'Failed', replayId: id });
});

The Magic Loop (Time-Travel)

Once your SDK is capturing data, the CLI becomes your time-machine to debug production bugs locally.

Step A: Fetch - Pull the production interaction using the Replay ID.

kiroo fetch kiroo-177359-9f3eb9

Step B: Replay - Re-run that exact production payload against your local server.

kiroo replay kiroo-177359-9f3eb9 --target localhost:3000

Local Debugging

Since the CLI is hitting your localhost, you can set breakpoints in your IDE and stop the "production" traffic in its tracks.

CLI Installation

Install the Kiroo CLI globally to manage interactions, snapshots, and replay traffic.

npm install -g @kiroo/cli

Pro Tip

You can also use npx @kiroo/cli for a zero-installation experience.

kiroo init

Initialize Kiroo in your local project to create the .kiroo/ directory for snapshots and logs.

kiroo init

Creates .kiroo/config.json and .kiroo/env.json.
You can set baseUrl, GROQ_API_KEY, and LINGODOTDEV_API_KEY.

HTTP methods

Run requests and store complete request/response artifacts for replay and analysis.

kiroo get <url>
kiroo post <url> [options]
kiroo put <url> [options]
kiroo delete <url> [options]

Flag	Purpose
`-H, --header <key:value>`	Add request headers
`-d, --data <data>`	JSON or shorthand body payload
`-s, --save <key=path>`	Store a response value into env vars

kiroo post /api/login -d "email=dev@site.com password=123" --save jwt=data.token
kiroo get /api/users -H "Authorization: Bearer {{jwt}}"

kiroo list

List recorded interactions in a paginated format.

kiroo list [options]

Flag	Purpose	Default
`-n, --limit <number>`	Rows to print	10
`-o, --offset <number>`	Rows to skip	0

kiroo fetch

Download a production capture from Supabase using its Replay ID.

kiroo fetch <replay-id>

This command uses Kiroo's internal environment variables for Supabase credentials. Ensure you have set SUPABASE_URL and SUPABASE_KEY using kiroo env set.

kiroo replay

Re-execute a saved interaction. Use --target to redirect production traffic to a local server.

kiroo replay <interaction-id> [options]

Flag	Purpose
`-t, --target <url>`	Override target host (e.g., `localhost:3000`)

kiroo edit

Open a saved interaction in your editor, modify it, then immediately replay.

kiroo edit <interaction-id>

kiroo import

Convert cURL commands into Kiroo interactions.

kiroo import "curl https://api.example.com/users -H 'Authorization: Bearer token'"

kiroo proxy

Run a traffic-capturing proxy between frontend and backend.

kiroo proxy --target <backend-url> [options]

Flag	Purpose	Default
`-t, --target <url>`	Backend target URL (required)	—
`-p, --port <port>`	Proxy listen port	8080

kiroo snapshot

Create and compare API state snapshots.

kiroo snapshot save <tag>
kiroo snapshot list
kiroo snapshot compare <tag1> <tag2> [--analyze] [--ai]

kiroo analyze

Run semantic blast-radius analysis between snapshots.

kiroo analyze <tag1> <tag2> [options]

Flag	Purpose
`--json`	Machine-readable output for CI
`--fail-on <severity>`	Exit non-zero from threshold: low\|medium\|high\|critical
`--ai`	Add AI impact summary
`--model <model>`	Override AI model
`--max-tokens <n>`	Limit AI completion length

kiroo check

Run a request with assertions; exits with code 1 on failure.

kiroo check <url> [options]

Flag	Purpose	Default
`-m, --method <method>`	HTTP method	`GET`
`-H, --header <header...>`	Add request headers (repeatable)	—
`-d, --data <data>`	Request body (JSON or shorthand)	—
`--status <code...>`	Expected status code(s)	—
`--has <fields...>`	Expected JSON fields (comma-separated or repeated)	—
`--match <matches...>`	Expected field values (for example: `state=active`)	—

kiroo check /api/login -m POST -d "email=dev@site.com password=123" --status 200 --has token,userId
kiroo check /api/user/42 --status 200 204 --match active=true

kiroo bench

Load test endpoints using configurable concurrency and request volume.

kiroo bench <url> [options]

Flag	Purpose	Default
`-m, --method <method>`	HTTP method	`GET`
`-n, --number <number>`	Total number of requests	`10`
`-c, --concurrent <number>`	Number of concurrent workers	`1`
`-H, --header <header...>`	Add request headers (repeatable)	—
`-d, --data <data>`	Request body payload	—
`-v, --verbose`	Print detailed output for every request	`false`

kiroo bench /api/projects -n 100 -c 10
kiroo bench /api/orders -m POST -H "Authorization: Bearer {{jwt}}" -d '{"type":"bulk"}' -n 50 -c 5 -v

kiroo export

Export captured interactions to Postman or OpenAPI formats.

kiroo export --format postman --out collection.json
kiroo export --format openapi --out openapi.json --title "My API" --api-version 1.0.0

kiroo graph

Show API dependency flow based on saved and reused variables.

kiroo graph

kiroo stats

View request counts, status distributions, latency averages, and slowest endpoints.

kiroo stats

kiroo scrub

Redact sensitive values from historical interactions and snapshots.

kiroo scrub --dry-run
kiroo scrub

kiroo env

Manage project environments and variables.

kiroo env list
kiroo env use production
kiroo env set baseUrl https://api.myapp.com
kiroo env rm baseUrl

kiroo clear

Delete recorded interactions when you need a clean slate.

kiroo clear --force

Capture once. Replay anywhere.