Generate a CLI from an OpenAPI document

Speakeasy generates a fully functional command-line interface from an OpenAPI specification. The CLI is written in Go using Cobra and wraps a generated Go SDK, providing per-operation commands, built-in authentication, multiple output formats, shell completions, and cross-platform distribution tooling.

Prerequisites

Spec format Supported
OpenAPI 3.0 ✅
OpenAPI 3.1 ✅
JSON Schema ✅

Quickstart

1. Create a CLI

Run the Speakeasy quickstart command and select the CLI target:

speakeasy quickstart --target cli

The interactive flow prompts for three configuration values:

Field Description Example
packageName The Go module path for your CLI (for example, github.com/my-company/my-api-cli). github.com/acme/petstore-cli
cliName The binary name users will type to run the CLI. Also used for the config directory (~/.config/<cliName>/). Defaults to cli if not set. petstore
envVarPrefix Prefix for environment variables. The CLI will check for variables like <PREFIX>_API_KEY. Defaults to CLI if not set. PETSTORE

2. Review the generated output

After generation, the output is a complete Go project:

├── cmd/                            # CLI commands
│   ├── <cliName>/main.go           # Binary entrypoint
│   └── gendocs/main.go             # Cobra documentation generator
├── internal/                       # Internal modules
│   ├── cli/                        # Cobra command files (root, auth, configure, per-operation)
│   ├── client/                     # SDK client wrapper and diagnostics
│   ├── config/                     # Config file and OS keychain management
│   ├── flagutil/                   # Flag registration and request building
│   ├── output/                     # Output formatting and agent-mode behavior
│   ├── usage/                      # Grouped help and machine-readable usage schema
│   ├── explorer/                   # Interactive command explorer (when enabled)
│   └── sdk/                        # Auto-generated Go SDK
├── scripts/                        # Scripts for installation
│   ├── install.sh                  # Linux/macOS install script
│   └── install.ps1                 # Windows install script
├── .goreleaser.yaml                # Cross-platform binary builds
├── go.mod                          # Go module file
└── README.md                       # Project documentation

3. Build and run

go build -o petstore ./cmd/petstore
./petstore --help

4. Configure authentication

Run the interactive setup wizard to configure API credentials and global settings:

./petstore configure

How generated CLIs behave

Per-operation commands

Every API operation becomes a CLI command. Operations are grouped by tags, with smart stutter removal to keep command names clean:

# If the API has a "users" tag with a "list-users" operation:
petstore users list

# View all available commands:
petstore --help

Request input options

Generated CLIs support multiple request input styles with predictable precedence:

  • Individual flags (highest priority)
  • --body JSON
  • stdin JSON (lowest priority)
# Individual flags
petstore users create --name "Alice" --email "alice@example.com"

# Whole request body JSON
petstore users create --body '{"name":"Alice","email":"alice@example.com"}'

# Stdin piping
cat payload.json | petstore users create

Individual flags override values supplied through --body or stdin, which makes the CLI work well for both scripts and ad hoc usage.

Output formats

Control output format with the --output-format flag (or -o):

petstore users list -o pretty
petstore users list -o json
petstore users list -o yaml
petstore users list -o table
petstore users list -o toon
  • pretty is the default for human terminal use
  • toon is optimized for compact, line-oriented agent consumption
  • --jq applies a jq expression and produces JSON output
petstore users list --jq '.[] | {name: .name, email: .email}'

Pagination and streaming

When an operation is marked as paginated, the CLI adds --all and --max-pages:

petstore users list --all
petstore users list --all --max-pages 5

Streaming endpoints are also supported:

  • SSE (text/event-stream)
  • JSONL / NDJSON (application/jsonl, application/x-ndjson)

These are emitted incrementally rather than buffered.

Retries, timeout, and custom headers

Generated CLIs include runtime controls that map to the underlying SDK behavior. Retry flags are available when retry support is enabled for the generated target/spec:

petstore users list --timeout 30s
petstore users list --no-retries
petstore users list --retry-max-elapsed-time 10s
petstore users list --header "X-Request-ID: abc-123"

Diagnostics

The CLI includes built-in diagnostics that are safe for scripts and CI:

petstore users list --dry-run
petstore users list --debug
  • --dry-run shows the request that would be sent without making a network call
  • --debug logs request/response diagnostics to stderr

Interactive mode

Interactive mode is enabled by default in the generator and improves the human terminal experience:

  • auto-prompting for unresolved required fields
  • an explore TUI for browsing and launching commands
  • interactive configure flows
petstore explore
petstore users create