# 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](https://cobra.dev/) and wraps a generated Go SDK, providing per-operation commands, built-in authentication, multiple output formats, shell completions, and cross-platform distribution tooling.

## Prerequisites

- The [Speakeasy CLI](/content/docs/speakeasy-reference/cli/getting-started/index.html)
- An API spec in a supported format:

| 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
```