Agent Ready

Generate agent-first CLIs from any OpenAPI spec — with built-in safety rails, schema introspection, and MCP server generation.

Copy-Paste Prompt for AI Agents

Drop this into Claude Code, Codex, or any coding agent. Replace the placeholder with your OpenAPI spec path or URL. The agent will do everything — no docs needed.

Generate a CLI from my OpenAPI spec using agent-ready-cli.

Steps:
1. npx agent-ready-cli generate --spec <PATH_TO_MY_OPENAPI_SPEC> --name my-cli --out generated/my-cli.js
2. Run: node generated/my-cli.js --help-json   (to see all available operations)
3. Test every API group using: node generated/my-cli.js <group> <command> --base-url <MY_API_URL> --output json
4. Use --dry-run on mutating operations (POST/PUT/PATCH/DELETE) before executing
5. Use schema <group.command> to inspect parameters and body schema for any operation
6. Use --fields to limit response size and --sanitize for safety

Auth options: --token <bearer>, --api-key <key>, --basic <user:pass>
Or set env vars: AGENT_READY_TOKEN, AGENT_READY_API_KEY, AGENT_READY_BASE_URL

Test at least 10-15 operations across different groups. Report which ones work and which fail.

Install

npm install -g agent-ready-cli

One command turns your API spec into a fully-featured CLI that both humans and AI agents can use:

npx agent-ready-cli generate --spec openapi.yaml --name my-cli --out my-cli.js

Why Agent-First?

AI agents are increasingly the primary consumers of CLIs. They don't need GUIs — they need deterministic output, runtime-queryable schemas, and safety rails against hallucinations.

Agent Ready generates CLIs with all of this built in:

Battle-Tested

Generated CLIs have been validated against 11 real-world open-source SaaS platforms with 2,012 operations:

OpenAPI specs for all 11 are included in examples/ so you can reproduce these results.

Quick Start

npx agent-ready-cli generate --spec openapi.yaml --name my-api --out my-api.js

Try the included Petstore spec:

npx agent-ready-cli generate --spec examples/petstore/openapi.yaml --name pet-cli --out generated/pet-cli.js

Generate from Any OpenAPI Spec

# From a local file
npx agent-ready-cli generate --spec path/to/openapi.yaml --name my-api --out generated/my-api.js

# From any of the included real-world specs
npx agent-ready-cli generate --spec examples/gitea/openapi.json --name gitea --out generated/gitea.js
npx agent-ready-cli generate --spec examples/mattermost/openapi.yaml --name mattermost --out generated/mattermost.js
npx agent-ready-cli generate --spec examples/killbill/swagger.json --name killbill --out generated/killbill.js
npx agent-ready-cli generate --spec examples/chatwoot/openapi.json --name chatwoot --out generated/chatwoot.js
npx agent-ready-cli generate --spec examples/coolify/openapi.yaml --name coolify --out generated/coolify.js
npx agent-ready-cli generate --spec examples/growthbook/openapi.yaml --name growthbook --out generated/growthbook.js

Supports OpenAPI 3.0/3.1 and Swagger 2.0 specs in YAML or JSON.

What Gets Generated

For each spec, the generator produces:

generated/
  my-api.js          # Executable CLI (Commander.js, ESM)
  my-api-CONTEXT.md  # Agent context file for LLM system prompts
  my-api-SKILL.md    # Structured skill file with YAML frontmatter

The CLI automatically:

• Groups commands by OpenAPI tags (or path prefix fallback)
• Maps path/query/header/cookie parameters to --kebab-case flags
• Handles auth (Bearer, API key, Basic) via flags or env vars
• Validates inputs against hallucination patterns (path traversal, control chars, embedded query params)

Agent-First Features

Schema Introspection

Agents can self-serve API documentation at runtime — no need to stuff docs into system prompts:

my-api schema users.list-users
# Returns: method, path, parameters, bodySchema, responseSchema as JSON

Raw JSON Payloads

Instead of translating nested structures into dozens of flags, agents pass the full API payload:

my-api users create-user --json '{
  "path": {"org": "my-org"},
  "body": {"login": "agent-user", "email": "agent@example.com"}
}'

Context Window Protection

# Only return the fields you need
my-api repos list-repos --fields "id,name,description" --output json

# Stream pages as NDJSON instead of buffering
my-api repos list-repos --page-all

Safety Rails

# Preview before mutating
my-api repos delete-repo --owner me --repo important-data --dry-run

# Strip prompt injection from API responses
my-api messages list --sanitize

Input Hardening

Every generated CLI rejects:

• Path traversal: ../../.ssh in resource IDs
• Control characters: invisible chars below ASCII 0x20
• Embedded query params: fileId?fields=name in IDs
• Pre-encoded strings: %2e%2e that would double-encode

MCP Server Generation

Generate a Model Context Protocol server for use with Claude, Cursor, and other MCP-compatible agents:

npx agent-ready-cli generate --spec openapi.yaml --name my-api --out generated/my-api.js --mcp generated/my-api-mcp.js

The MCP server exposes every operation as a typed JSON-RPC tool over stdio — no shell escaping, no argument parsing ambiguity.

Auth

Generated CLIs support multiple auth mechanisms with runtime precedence:

CLI flags > env vars > profile config > spec default

# Bearer token
my-api users list --token "ghp_xxxx"

# API key (placed in header, query, or cookie per spec)
my-api users list --api-key "sk-xxxx"

# Basic auth
my-api users list --basic "user:pass"

# Environment variables
export AGENT_READY_TOKEN="ghp_xxxx"
export AGENT_READY_API_KEY="sk-xxxx"
export AGENT_READY_BASE_URL="https://api.example.com"

# Config profiles
my-api users list --config ./config.json --profile staging

Config file format:

{
  "profiles": {
    "default": { "baseUrl": "http://localhost:3000", "output": "json" },
    "staging": { "baseUrl": "https://staging.api.example.com", "token": "ghp_xxxx" }
  }
}

Spec Compatibility

Development

npm install
npm run build
npm test          # 42 tests

License

MIT