respec

Generate agent-first CLIs from OpenAPI specs.

respec takes an OpenAPI 3.0/3.1 spec and produces a Python CLI package that AI agents (Claude Code, Codex CLI, etc.) can use safely via bash. The generated CLI includes JSON I/O, Pydantic validation, input hardening, dry-run mode, schema introspection, and auto-generated SKILL.md files — all the things agents need to interact with APIs without breaking things.

Quick Start

# Install
pip install respec-cli
# or run directly
uvx respec-cli generate --spec petstore.yaml --name petstore-cli --output ./out

# Use the generated CLI
cd out && uv run petstore-cli --help

Usage

Single API

respec generate --spec petstore.yaml --name petstore-cli --output ./out

Multiple APIs (microservices)

Each spec becomes a top-level subcommand group:

respec generate \
  --spec api:api.yaml \
  --spec workflow-api:workflow.yaml \
  --name myapp-cli --output ./out

myapp-cli api pets list
myapp-cli workflow-api runs create --json '{"name":"nightly"}'
myapp-cli schema list          # aggregated across all services

Options

--spec TEXT        Spec as 'name:path' or just 'path' (repeatable)
--name TEXT        CLI package name (e.g. petstore-cli)
--output PATH     Output directory (default: ./out)
--env-prefix TEXT  Env var prefix for auth (default: derived from --name)

What Gets Generated

out/
├── src/petstore_cli/
│   ├── main.py           # typer app entry point
│   ├── models.py         # Pydantic v2 models (via datamodel-code-generator)
│   ├── commands/
│   │   ├── pets.py       # pets list / create / get
│   │   └── schema.py     # schema introspection
│   ├── client.py         # httpx HTTP client
│   └── validation.py     # input hardening
├── skills/
│   ├── SKILL.md          # agent skill definition
│   └── CONTEXT.md        # usage guide for agents
└── pyproject.toml        # uvx-runnable package

Agent-first Design

The generated CLI follows agent-first principles:

JSON in, JSON out. Agents pass --json payloads and parse JSON responses. No interactive prompts, no color codes in output.

petstore-cli pets create --json '{"name":"Fido","tag":"dog"}'
# → {"id": 1, "name": "Fido", "tag": "dog"}

Dry-run before mutating. Every command supports --dry-run to preview the HTTP request without sending it.

petstore-cli pets create --json '{"name":"Fido"}' --dry-run
# → {"method": "POST", "url": "http://petstore.swagger.io/v1/pets", "body": {"name": "Fido"}, "params": null}

Schema introspection. Agents can discover API schemas at runtime instead of relying on documentation in the context window.

petstore-cli schema list
# → ["createpetrequest", "error", "pet", "pets", "pets.create"]

petstore-cli schema show pet
# → { "properties": { "id": { "type": "integer" }, ... } }

Two-layer validation. Layer 1: Pydantic validates types, required fields, and constraints. Layer 2: security hardening rejects path traversal, control characters, double-encoding, and query injection.

petstore-cli pets create --json '{"tag":"dog"}'
# → {"error": "1 validation error for CreatePetRequest\nname\n  Field required"}

SKILL.md distribution. The generated skills/SKILL.md and skills/CONTEXT.md follow the convention used by Claude Code, Cursor, and similar tools, giving agents structured knowledge about the CLI's capabilities.

Authentication

Auth is passed via flags or environment variables:

# Via flags
petstore-cli pets list --api-key sk-xxx
petstore-cli pets list --auth-token eyJ...

# Via environment variables (prefix derived from --name, or set with --env-prefix)
export PETSTORE_CLI_API_KEY=sk-xxx
export PETSTORE_CLI_AUTH_TOKEN=eyJ...
petstore-cli pets list

Use --env-prefix at generation time to customize:

respec generate --spec api.yaml --name myapp-cli --env-prefix MYAPP --output ./out
# → MYAPP_API_KEY, MYAPP_AUTH_TOKEN

Development

git clone https://github.com/user/respec.git
cd respec
uv sync --dev
uv run pytest

License

MIT

chezou/respec