@lucianfialho/tocli

tocli

Turn any OpenAPI spec into a CLI. No code generation, no build step.

npx tocli --spec ./api.yaml pets list --status available
npx tocli --spec ./api.yaml pets create --name Rex --token sk-123

tocli reads an OpenAPI 3.x spec at runtime and dynamically generates a fully functional CLI with commands, flags, auth, and formatted output.

Quick start

# Try it with any OpenAPI spec
npx @lucianfialho/tocli --spec https://petstore3.swagger.io/api/v3/openapi.json pets --help

# Or install globally
npm install -g @lucianfialho/tocli

How it works

OpenAPI 3.x spec (YAML or JSON)
         │
         ▼
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Parser          │────▶│  Commander   │────▶│  Output         │
│  (reads spec,    │     │  (dynamic    │     │  (json, pretty, │
│   extracts ops)  │     │   commands)  │     │   table, quiet) │
└─────────────────┘     └──────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │  HTTP        │
                        │  Executor    │
                        └──────────────┘

• Each tag in the spec becomes a command group (pets, store)
• Each operation becomes a subcommand (list, create, get)
• Path params become required flags (--petId 123)
• Query params become optional flags (--limit 10)
• Request body fields become flags (--name Rex --tag dog)
• Auth is detected from securitySchemes

Usage

Commands from spec

# List
tocli --spec api.yaml pets list
tocli --spec api.yaml pets list --status available --limit 5

# Create
tocli --spec api.yaml --token sk-123 pets create --name Rex --tag dog

# Get by ID
tocli --spec api.yaml pets get --petId 1

# Update
tocli --spec api.yaml --token sk-123 pets update --petId 1 --status sold

# Delete
tocli --spec api.yaml --token sk-123 pets delete --petId 1

Output formats

tocli --spec api.yaml --output json pets list      # compact JSON (pipe-friendly)
tocli --spec api.yaml --output pretty pets list     # colorized JSON (default in TTY)
tocli --spec api.yaml --output table pets list      # aligned columns
tocli --spec api.yaml --quiet pets create --name X  # no output, just exit code
tocli --spec api.yaml --max-items 3 pets list       # limit results

Authentication

# Inline flags (auto-detected from spec securitySchemes)
tocli --spec api.yaml --token sk-123 pets create --name Rex
tocli --spec api.yaml --api-key my-key store inventory

# Persistent profiles
tocli auth login --token sk-prod-key
tocli auth login --api-key staging-key --profile staging
tocli auth status
tocli auth logout

Project config

# Initialize config in your project
tocli init --spec ./openapi.yaml --base-url https://api.example.com

Creates a .toclirc file:

spec: ./openapi.yaml
baseUrl: https://api.example.com
auth:
  type: bearer
  envVar: API_TOKEN
environments:
  staging:
    baseUrl: https://staging.example.com
    auth:
      envVar: STAGING_API_TOKEN

Now you can skip --spec:

tocli pets list
tocli --env staging pets list

Dynamic help

tocli generates help automatically from the spec:

tocli --spec api.yaml --help           # shows all command groups
tocli --spec api.yaml pets --help      # shows subcommands
tocli --spec api.yaml pets create --help  # shows flags with types

Debug

tocli --spec api.yaml --verbose pets get --petId 1
# → GET https://api.example.com/pets/1
#   Accept: application/json
# ← 200 OK

Features

• Reads OpenAPI 3.x (YAML or JSON) from local files or URLs
• Dynamic CLI generation at runtime (no code-gen, no build step)
• All output formats: json, pretty (colorized), table, quiet
• Auth: Bearer token, API key, with persistent profiles
• Project config (.toclirc) with multiple environments
• Verbose mode for debugging requests
• Works with npx (zero install)

Development

git clone https://github.com/lucianfialho/tocli
cd tocli
npm install
npm run build
npm test

License

MIT