api-spec-cli

api-spec-cli

CLI for AI agents to explore and call OpenAPI and GraphQL APIs. Output is JSON by default — compact, parseable, token-efficient.

Install

npm install -g api-spec-cli

Works with Node.js 18+ or Bun. No other dependencies.

# Or run without installing
npx api-spec-cli <command>

How It Works

The CLI follows a progressive discovery pattern. You never dump an entire API spec at once — instead you narrow down to what you need.

Step 1: Load the spec

spec load https://petstore3.swagger.io/api/v3/openapi.json   # OpenAPI
spec load ./openapi.yaml                                       # Local file
spec load https://gql.hashnode.com                             # GraphQL (introspection)

Output tells you what was loaded:

{ "ok": true, "type": "graphql", "operationCount": 114, "source": "https://gql.hashnode.com" }

Step 2: Find what you need

list is compact by default — just operation IDs, no schemas. Use --filter, --tag, --limit to narrow down.

spec list                          # All operations (compact IDs only)
spec list --filter publish         # Search by keyword
spec list --tag pets               # OpenAPI: filter by tag
spec list --tag mutation           # GraphQL: filter by kind (query/mutation/subscription)
spec list --limit 10               # First 10 only
spec list --limit 10 --offset 10   # Next 10

Compact output (token-efficient):

{
  "type": "graphql",
  "total": 5,
  "showing": 5,
  "operations": [
    { "id": "publishPost", "kind": "mutation" },
    { "id": "publishDraft", "kind": "mutation" }
  ]
}

Use --compact false for full details (summary, tags, args).

Step 3: Inspect one operation

show gives you everything you need to call an operation — params, body schema, response, and related types — in one call.

spec show publishPost              # GraphQL: by operation name
spec show getPetById               # OpenAPI: by operationId
spec show /pet/{petId}             # OpenAPI: by path
spec show "GET /pet/{petId}"       # OpenAPI: by method + path

Schemas are compact. Nested $ref references show as type names (not exploded), so the output stays small. If you need details on a referenced type, use spec types <name>.

Step 4: Drill into types (if needed)

spec types                         # List all schema/type names
spec types Pet                     # Inspect one schema
spec types PublishPostInput        # Inspect a GraphQL input type

This is optional — show already includes related types inline. Use types only when you need a type that wasn't included in the show output.

Step 5: Call the API

# Set base URL and auth first (persisted across calls)
spec config set baseUrl https://petstore3.swagger.io/api/v3
spec config set auth YOUR_TOKEN

# OpenAPI calls
spec call getPetById --var petId=1
spec call findPetsByStatus --query status=available
spec call addPet --data '{"name":"Rex","photoUrls":[]}'

# GraphQL calls (auto-generates query from schema)
spec call me
spec call publication --var host=blog.hashnode.dev

Config

Persistent config stored in .spec-cli/config.json. Set once, used for all calls.

spec config set baseUrl https://api.example.com
spec config set auth my-token                        # Auto-adds "Bearer " prefix
spec config set auth "Basic dXNlcjpwYXNz"            # Or explicit auth header
spec config set headers.X-API-Key abc123              # Custom headers (dot notation)
spec config get                                       # Show all config
spec config unset auth                                # Remove a key

Validate

Check an OpenAPI spec for errors before using it:

spec validate https://api.example.com/openapi.json

Reports broken $ref references, missing required fields, duplicate operationIds, invalid schema types, and more.

Output Format

JSON by default. Use --format text or --format yaml for alternatives:

spec list --format text
spec show getPetById --format yaml

Errors always go to stderr as JSON: {"error": "message"} with non-zero exit code.

Token Efficiency

The CLI is designed to minimize context window usage for AI agents:

• list returns only IDs by default (not full schemas)
• show resolves schemas compactly — nested refs show as names, not deep explosions
• types lets you inspect one type at a time instead of loading all schemas
• --limit and --offset paginate large APIs
• --filter and --tag narrow results before output

Storage

All state lives in .spec-cli/ in the working directory:

• spec.json — loaded spec cache
• config.json — base URL, auth, headers

Add .spec-cli/ to your .gitignore.