🦏 KIROO

Version Control for API Interactions

Record, Replay, Snapshot, Analyze, and Export your APIs — like Git for HTTP workflows.

Demo • Feature Grid • Use Cases • Install • Docs • Demo Walkthrough

📖 What is Kiroo?

Kiroo is version control for API interactions. It records real HTTP traffic, stores it locally in your repo, lets you replay history, compare snapshots, run semantic drift analysis, and export machine-readable artifacts like OpenAPI.

If your API changes frequently, Kiroo answers:

What changed?
What broke?
Which consumers are impacted?

🎬 Demo

[Demo @YT](https://youtu.be/OKY3gWdeg4k?si=aqTHUUdD-6BWGRLh)

🔥 Start Here (Developer Walkthrough)

If you test only one thing, test this:

Production Time-Travel Debugging (kiroo fetch + kiroo replay)
AI Blast Radius Analysis (--analyze --ai)
Git-native API snapshots (v1 vs v2)

Use the full walkthrough: DEMO.md

Quick launch:

cd examples/sdk-cli-walkthrough
npm install
npm start

Then from repo root:

kiroo get http://localhost:3311/api/fail
# copy X-Kiroo-Replay-ID from headers
kiroo fetch <replay-id>
kiroo replay <replay-id> --target http://localhost:3311

🌐 Product Landing Page

Landing page: docs/index.html
Documentation page: docs/docs.html
SDK + CLI walkthrough example: examples/sdk-cli-walkthrough

✨ Feature Grid

Capability	What it gives you
Request Recording	Store request/response history in `.kiroo/` for replay and auditability
Snapshot Versioning	Save versioned API states and compare contract drift
AI + Localized Blast Radius	Get severity, locale-aware risk boosts, field intent labels, and migration hints before deployment
Time-Travel Proxy	Auto-capture frontend traffic without manually typing requests
Zero-Code API Checks	CI-friendly assertions for status, fields, and exact matches
Load Benchmarking	Concurrency and throughput testing from CLI
OpenAPI/Postman Export	Generate shareable artifacts from observed traffic
Secret Redaction	Mask sensitive data so interaction files stay Git-safe
Dependency Graph + Stats	Understand variable flow and performance bottlenecks

🎯 Real-World Use Cases

Pre-release contract safety: Compare v1 vs v2 snapshots and fail CI on high-severity changes.
Frontend debugging: Capture browser flows with kiroo proxy and replay problematic requests instantly.
Regression protection: Convert critical endpoints into kiroo check assertions.
API docs bootstrap: Export real-world interactions as OpenAPI for partner teams.
Performance guardrails: Benchmark hot endpoints after backend changes.

🚀 Installation

1) Install globally

npm install -g kiroo

2) Initialize in your repo

kiroo init

3) Run a first request

kiroo get https://api.github.com/users/yash-pouranik

4) Snapshot + analyze

kiroo snapshot save v1
kiroo snapshot compare v1 current --analyze

📚 Full Command Documentation

`kiroo init`

Initialize Kiroo in your current project.

Description: Creates the .kiroo/ directory structure, a default env.json, and .kiroo/config.json with deterministic/redaction-safe defaults. During setup, you can configure environment name, baseUrl, GROQ_API_KEY, LINGODOTDEV_API_KEY, SUPABASE_URL, SUPABASE_KEY, SUPABASE_BUCKET, optional DEFAULT_LANG, and redaction preferences.
Prerequisites: None. Run once per project.
Example:
```
kiroo init
```

`kiroo get/post/put/delete/patch <url>`

Execute and record an API interaction.

Description: Performs an HTTP request, displays the response, and saves it to history.
Prerequisites: Access to the URL (or a baseUrl set in the environment).
Arguments:
- url: The endpoint (Absolute URL or relative path if baseUrl exists).
Options:
- -H, --header <key:value>: Add custom headers.
- -d, --data <data>: Request body (JSON or shorthand key=val).
- -s, --save <key=path>: Save response data to environment variables.

Example:

kiroo post /api/auth/login -d "email=user@test.com password=123" --save token=data.token
kiroo patch /api/profile -d "name=UpdatedName"

`kiroo list`

View your interaction history.

Description: Displays a paginated list of all recorded requests.
Arguments: None.
Options:
- -n, --limit <number>: How many records to show (Default: 10).
- -o, --offset <number>: How many records to skip (Default: 0).
Example:
```
kiroo list -n 20
```

`kiroo replay <id>`

Re-run a specific interaction.

Description: Fetches the original request from history and executes it again.
Arguments:
- id: The timestamp ID of the interaction (found via kiroo list).
Example:
```
kiroo replay 2026-03-10T14-30-05-123Z
```

`kiroo edit <id>`

Quick Refinement. Edit an interaction on the fly and replay it.

Description: Opens the stored interaction JSON in your default system editor (VS Code, Nano, Vim, etc.). Edit the headers, body, or URL, save, and close. Kiroo immediately replays the updated request.
Arguments:
- id: The timestamp ID of the interaction.
Example:
```
kiroo edit 2026-03-10T14-30-05-123Z
```

`kiroo proxy`

Start a time-travel proxy.

Description: Acts as a middleware between the frontend and backend, automatically capturing HTTP traffic and saving it as interactions without typing CLI commands.
Options:
- -t, --target <url>: Target URL of the backend.
- -p, --port <port>: Port for the proxy to listen on (Default: 8080).

Example:

kiroo proxy --target http://localhost:3000 --port 8080

`kiroo check <url>`

Zero-Code Testing engine.

Description: Executes a request and runs assertions on the response. Exits with code 1 on failure.
Prerequisites: Access to the URL.
Arguments:
- url: The endpoint.
Options:
- -m, --method <method>: HTTP method (GET, POST, etc. Default: GET).
- -H, --header <key:value>: Add custom headers.
- -d, --data <data>: Request body.
- --status <numbers>: Expected HTTP status code.
- --has <fields>: Comma-separated list of expected fields in JSON.
- --match <key=val>: Exact value matching for JSON fields.

Example:

# Check if login is successful
kiroo check /api/login -m POST -d "user=yash pass=123" --status 200 --has token

`kiroo bench <url>`

Local load testing and benchmarking.

Description: Sends multiple concurrent HTTP requests to measure endpoint performance (Latency, RPS, Error Rate).
Prerequisites: Access to the URL.
Arguments:
- url: The endpoint (supports Auto-BaseURL).
Options:
- -m, --method <method>: HTTP method (GET, POST, etc. Default: GET).
- -n, --number <number>: Total requests to send (Default: 10).
- -c, --concurrent <number>: Concurrent workers (Default: 1).
- -v, --verbose: Show the HTTP status, response time, and truncated response body for every individual request instead of a single progress spinner.
- -H, --header <key:value>: Add custom headers.
- -d, --data <data>: Request body.

Example:

# Send 100 requests in batches of 10
kiroo bench /api/projects -n 100 -c 10

`kiroo graph`

Visualize API dependencies.

Description: Generates a tree view showing how data flows between endpoints via saved/used variables.
Prerequisites: Recorded interactions that use --save and {{variable}}.
Example:
```
kiroo graph
```

`kiroo stats`

Analytics dashboard.

Description: Shows performance metrics, success rates, and identify slow endpoints.
Options:
- --json: Output machine-readable JSON stats for dashboards/CI.
Example:
```
kiroo stats
kiroo stats --json
```

`kiroo import`

Import from cURL.

Description: Converts a cURL command into a Kiroo interaction. Opens an interactive editor if no argument is provided.
Arguments:
- curl: (Optional) The raw cURL string in quotes.

Example:

kiroo import "curl https://api.exa.com -H 'Auth: 123'"

`kiroo snapshot`

Snapshot management.

Commands:
- save <tag>: Save current history as a versioned state.
- list: List all saved snapshots.
- compare <tag1> <tag2>: Detect structural changes between two states.
- compare <tag1> <tag2> --analyze: Structural compare + semantic severity in one run.
- run <tag>: Execute all interactions in a snapshot sequentially (supports auth token chaining).
Options for run:
- -v, --verbose: Show response preview for each request.
- --fail-fast: Stop immediately on first failed interaction.
- --timeout <ms>: Request timeout in milliseconds (Default: 30000).

Example:

kiroo snapshot compare v1.stable current
kiroo snapshot run v1.stable --fail-fast

`kiroo analyze <tag1> <tag2>`

Semantic blast-radius analysis between snapshots.

Description: Generates endpoint-wise severity report for contract drift (low|medium|high|critical) and can optionally generate AI impact summary via Groq.
Options:
- --json: Output machine-readable JSON report.
- --fail-on <severity>: Exit non-zero if max severity meets threshold.
- --ai: Add Groq-powered impact summary.
- --model <model>: Override default model priority.
- --max-tokens <number>: Max completion tokens for AI summary.
Environment:
- GROQ_API_KEY in .kiroo/env.json: Required when --ai is used.

Example:

kiroo analyze before-refactor after-refactor --fail-on high
kiroo analyze before-refactor after-refactor --ai --model qwen/qwen3-32b
kiroo snapshot compare before-refactor after-refactor --analyze --ai

`kiroo export`

Team Compatibility. Export to Postman or OpenAPI.

Description: Converts stored Kiroo interactions into Postman Collection or OpenAPI/Swagger JSON for team sharing and docs.
Options:
- -f, --format <format>: postman or openapi (Default: postman).
- -o, --out <filename>: Output file name (Default: kiroo-collection.json for postman, openapi.json for openapi).
- --title <title>: OpenAPI title override.
- --api-version <version>: OpenAPI version override.
- --server <url>: OpenAPI server URL override.
- --path-prefix <prefix>: Include only matching API paths (e.g. /api).
- --min-samples <number>: Include only operations observed at least N times.

Example:

kiroo export --format postman --out my_api_collection.json
kiroo export --format openapi --out openapi.json --title "My API" --api-version 1.0.0
kiroo export --format openapi --path-prefix /api --min-samples 2 --out openapi.json

`kiroo scrub`

Redact sensitive values in already stored data.

Description: Scans .kiroo/interactions and .kiroo/snapshots, then masks secrets like auth headers, cookies, tokens, passwords, and API keys.
Options:
- --dry-run: Show what would change without modifying files.
Example:
```
kiroo scrub --dry-run
kiroo scrub
```

`kiroo env`

Environment & Variable management.

Commands:
- list: View all environments and their variables.
- use <name>: Switch active environment (e.g., prod, local).
- set <key> <value>: Set a variable in the active environment.
- rm <key>: Remove a variable.
Note:
- Sensitive keys (tokens/passwords/API keys) are masked in kiroo env list.
- Set DEFAULT_LANG to auto-apply language when --lang is not passed.

Example:

kiroo env set baseUrl https://api.myapp.com
kiroo env set GROQ_API_KEY your_key
kiroo env set LINGODOTDEV_API_KEY your_key
kiroo env set SUPABASE_URL https://your-project.supabase.co
kiroo env set DEFAULT_LANG de

`kiroo clear`

Wipe history.

Description: Deletes all recorded interactions to start fresh.
Options:
- -f, --force: Clear without a confirmation prompt.
Example:
```
kiroo clear --force
```

`kiroo help [command]`

Get command-level help directly in CLI.

Description: Shows global help or detailed help for a specific command.
Arguments:
- command: (Optional) Command name to inspect.
Example:
```
kiroo help
kiroo help bench
```

📜 License

Distributed under the MIT License. See LICENSE for more information.

Built with ❤️ for Developers

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
bin		bin
docs		docs
examples		examples
packages		packages
src		src
.gitignore		.gitignore
DEMO.md		DEMO.md
LICENSE		LICENSE
README.md		README.md
hld-cli.png		hld-cli.png
hld-sdk.png		hld-sdk.png
kiroo_banner.png		kiroo_banner.png
lingo.dev.docs.md		lingo.dev.docs.md
openapi.json		openapi.json
package-lock.json		package-lock.json
package.json		package.json
sequence_diagram.png		sequence_diagram.png
test.js		test.js

Folders and files

Latest commit

History

Repository files navigation

🦏 KIROO

Version Control for API Interactions

📖 What is Kiroo?

🎬 Demo

🔥 Start Here (Developer Walkthrough)

🌐 Product Landing Page

✨ Feature Grid

🎯 Real-World Use Cases

🚀 Installation

1) Install globally

2) Initialize in your repo

3) Run a first request

4) Snapshot + analyze

📚 Full Command Documentation

kiroo init

kiroo get/post/put/delete/patch <url>

kiroo list

kiroo replay <id>

kiroo edit <id>

kiroo proxy

kiroo check <url>

kiroo bench <url>

kiroo graph

kiroo stats

kiroo import

kiroo snapshot

kiroo analyze <tag1> <tag2>

kiroo export

kiroo scrub

kiroo env

kiroo clear

kiroo help [command]

📜 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`kiroo init`

`kiroo get/post/put/delete/patch <url>`

`kiroo list`

`kiroo replay <id>`

`kiroo edit <id>`

`kiroo proxy`

`kiroo check <url>`

`kiroo bench <url>`

`kiroo graph`

`kiroo stats`

`kiroo import`

`kiroo snapshot`

`kiroo analyze <tag1> <tag2>`

`kiroo export`

`kiroo scrub`

`kiroo env`

`kiroo clear`

`kiroo help [command]`

Packages