@cli4ai/openapi

Turn any OpenAPI spec into a dynamic CLI tool.

Installation

cli4ai add -g openapi

Usage

Load and inspect a spec

# From URL
cli4ai run openapi load https://petstore3.swagger.io/api/v3/openapi.json

# From file
cli4ai run openapi load ./api-spec.json

List all operations

# List all operations
cli4ai run openapi list https://petstore3.swagger.io/api/v3/openapi.json

# Filter by tag
cli4ai run openapi list ./spec.json --tag pets

# Filter by method
cli4ai run openapi list ./spec.json --method POST

Call an endpoint

# By operationId
cli4ai run openapi call ./spec.json getPetById id=123

# By method and path
cli4ai run openapi call ./spec.json "GET /pet/{petId}" petId=123

# With query parameters
cli4ai run openapi call ./spec.json findPetsByStatus status=available

# With request body
cli4ai run openapi call ./spec.json addPet body='{"name":"Fluffy","status":"available"}'

# Dry run (show request without executing)
cli4ai run openapi call ./spec.json getPetById id=123 --dry-run

View schemas

# List all schemas
cli4ai run openapi schema ./spec.json

# View specific schema
cli4ai run openapi schema ./spec.json Pet

Authentication

Set environment variables for authentication:

# Bearer token
export OPENAPI_BEARER_TOKEN="your-token"

# API key (uses X-API-Key header or spec-defined header)
export OPENAPI_API_KEY="your-api-key"

# Override base URL
export OPENAPI_BASE_URL="https://api.example.com/v2"

Examples

Petstore API

# Load the spec
cli4ai run openapi load https://petstore3.swagger.io/api/v3/openapi.json

# List pets
cli4ai run openapi call https://petstore3.swagger.io/api/v3/openapi.json findPetsByStatus status=available

# Get a specific pet
cli4ai run openapi call https://petstore3.swagger.io/api/v3/openapi.json getPetById petId=1

GitHub API

export OPENAPI_BEARER_TOKEN="ghp_your_token"

# Get user info
cli4ai run openapi call https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json "GET /user"

Parameter Passing

Parameters can be passed in several ways:

# key=value format
cli4ai run openapi call ./spec.json operation param1=value1 param2=value2

# --key=value format
cli4ai run openapi call ./spec.json operation --param1=value1

# Request body as JSON
cli4ai run openapi call ./spec.json operation body='{"key":"value"}'

Output

All output is JSON for easy parsing:

{
  "status": 200,
  "statusText": "OK",
  "headers": { ... },
  "data": { ... }
}

Limitations

• Only JSON specs are supported (no YAML)
• OAuth2 flows require manual token acquisition
• File uploads not yet supported