Skip to content

Commit 72ed332

Browse files
beezythebotbeezythebot
committed
Sync open source content 🐝 (from 6531c5eaaa87447c167d99eea73eae54edb0f8b0)
1 parent b992573 commit 72ed332

File tree

10 files changed

+2675
-743
lines changed

10 files changed

+2675
-743
lines changed

‎_meta.global.tsx‎

Lines changed: 549 additions & 521 deletions
Large diffs are not rendered by default.

‎docs/cli-generation/create-cli.mdx‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
title: "Generate a CLI from an OpenAPI Document"
3+
description: "Generate a production-ready command-line interface from an OpenAPI document using Speakeasy."
4+
---
5+
6+
import { Callout, Table } from "@/mdx/components";
7+
8+
# Generate a CLI from an OpenAPI document
9+
10+
<Callout type="warning" title="Alpha · Enterprise Only">
11+
CLI generation is currently in **alpha** and available exclusively to
12+
**Enterprise** customers. Features and configuration may change. [Contact
13+
us](https://www.speakeasy.com/pricing) for access.
14+
</Callout>
15+
16+
Speakeasy generates a fully functional command-line interface from your OpenAPI specification. The CLI is written in Go using [Cobra](https://cobra.dev/) and wraps a generated Go SDK, providing a per-operation command structure with built-in authentication, multiple output formats, and cross-platform distribution tooling.
17+
18+
## Prerequisites
19+
20+
- The [Speakeasy CLI](/docs/speakeasy-reference/cli/getting-started)
21+
- An [Enterprise plan](https://www.speakeasy.com/pricing)
22+
- An API spec in a supported format:
23+
24+
<Table
25+
data={[
26+
{ format: "OpenAPI 3.0", supported: "✅" },
27+
{ format: "OpenAPI 3.1", supported: "✅" },
28+
{ format: "JSON Schema", supported: "✅" },
29+
]}
30+
columns={[
31+
{ key: "format", header: "Spec format" },
32+
{ key: "supported", header: "Supported" },
33+
]}
34+
/>
35+
36+
## Quickstart
37+
38+
### 1. Create a CLI
39+
40+
Run the Speakeasy quickstart command and select the CLI target:
41+
42+
```bash
43+
speakeasy quickstart --target cli
44+
```
45+
46+
The interactive flow prompts for three configuration values:
47+
48+
49+
<Table
50+
data={[
51+
{
52+
field: "`packageName`",
53+
description:
54+
"The Go module path for your CLI (e.g., `github.com/my-company/my-api-cli`).",
55+
example: "`github.com/acme/petstore-cli`",
56+
},
57+
{
58+
field: "`cliName`",
59+
description:
60+
"The binary name users will type to run the CLI. Also used for the config directory (`~/.config/<cliName>/`).",
61+
example: "`petstore`",
62+
},
63+
{
64+
field: "`envVarPrefix`",
65+
description:
66+
"Prefix for environment variables. The CLI will check for variables like `<PREFIX>_API_KEY`.",
67+
example: "`PETSTORE`",
68+
},
69+
]}
70+
columns={[
71+
{ key: "field", header: "Field" },
72+
{ key: "description", header: "Description" },
73+
{ key: "example", header: "Example" },
74+
]}
75+
/>
76+
77+
### 2. Review the generated output
78+
79+
After generation, you'll have a complete Go project:
80+
81+
```
82+
├── cmd/
83+
│ ├── <cliName>/main.go # Binary entrypoint
84+
│ └── gendocs/main.go # Cobra documentation generator
85+
├── internal/
86+
│ ├── cli/ # Cobra command files (one per operation)
87+
│ │ ├── root.go # Root command with global flags
88+
│ │ ├── configure.go # Interactive setup wizard
89+
│ │ ├── whoami.go # Auth status checker
90+
│ │ ├── version.go # Version info
91+
│ │ └── ... # Per-operation commands
92+
│ ├── client/ # SDK client wrapper and diagnostics
93+
│ ├── config/ # Config file and OS keychain management
94+
│ ├── flagutil/ # Flag registration and request building
95+
│ ├── output/ # Output formatting (pretty, JSON, YAML, table, TOON)
96+
│ └── sdk/ # Auto-generated Go SDK
97+
├── scripts/
98+
│ ├── install.sh # Linux/macOS install script
99+
│ └── install.ps1 # Windows install script
100+
├── .goreleaser.yaml # Cross-platform binary builds
101+
├── go.mod
102+
└── README.md
103+
```
104+
105+
### 3. Build and run
106+
107+
```bash
108+
go build -o petstore ./cmd/petstore
109+
./petstore --help
110+
```
111+
112+
### 4. Configure authentication
113+
114+
Run the interactive setup wizard to configure API credentials:
115+
116+
```bash
117+
./my-cli configure
118+
```
119+
120+
This stores credentials securely in the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) and generates a config file at `~/.config/<cliName>/config.yaml`.
121+
122+
## Key features
123+
124+
### Per-operation commands
125+
126+
Every API operation becomes a CLI command. Operations are grouped by tags, with smart stutter removal to keep command names clean:
127+
128+
```bash
129+
# If your API has a "users" tag with a "list-users" operation:
130+
my-cli users list # "-users" suffix is removed from "list-users"
131+
132+
# View all available commands:
133+
my-cli --help
134+
```
135+
136+
### Multiple output formats
137+
138+
Control output format with the `--output-format` flag (or `-o` for short):
139+
140+
```bash
141+
my-cli users list -o json # JSON output
142+
my-cli users list -o yaml # YAML output
143+
my-cli users list -o table # Tabular output
144+
my-cli users list -o pretty # Colored key-value output (default)
145+
my-cli users list -o toon # Token-oriented output (for LLM consumption)
146+
```
147+
148+
### jq filtering
149+
150+
Filter and transform output with built-in jq support:
151+
152+
```bash
153+
my-cli users list --jq '.[] | {name: .name, email: .email}'
154+
```
155+
156+
### Flexible request input
157+
158+
Provide request data through individual flags, a JSON body, or stdin:
159+
160+
```bash
161+
# Individual flags
162+
my-cli users create --name "Alice" --email "alice@example.com"
163+
164+
# JSON body
165+
my-cli users create --body '{"name": "Alice", "email": "alice@example.com"}'
166+
167+
# Stdin piping
168+
echo '{"name": "Alice"}' | my-cli users create
169+
```
170+
171+
### Authentication
172+
173+
The CLI resolves credentials with a 4-tier priority:
174+
175+
- **Flags** — `--api-key`, `--bearer-token`, etc.
176+
- **Environment variables** — `<PREFIX>_API_KEY`, `<PREFIX>_BEARER_TOKEN`, etc.
177+
- **OS keychain** — stored via `my-cli configure`
178+
- **Config file** — `~/.config/<cliName>/config.yaml`
179+
180+
### Pagination
181+
182+
Automatically page through paginated endpoints:
183+
184+
```bash
185+
my-cli users list --all # Fetch all pages
186+
my-cli users list --all --max-pages 5 # Limit to 5 pages
187+
```
188+
189+
### Diagnostics
190+
191+
Debug API calls without making real requests:
192+
193+
```bash
194+
my-cli users list --dry-run # Show the request without sending it
195+
my-cli users list --debug # Show full request/response with secret redaction
196+
```
197+
198+
### Shell completions
199+
200+
Generate shell completions for your CLI:
201+
202+
```bash
203+
my-cli completion bash # Bash
204+
my-cli completion zsh # Zsh
205+
my-cli completion fish # Fish
206+
my-cli completion powershell # PowerShell
207+
```
208+
209+
## Next steps
210+
211+
- [**Customize your CLI**](/docs/cli-generation/customize-cli) — Configure command naming, environment variables, and custom code
212+
- [**Distribute your CLI**](/docs/cli-generation/distribute-cli) — Set up GoReleaser, install scripts, and release automation
213+
- [**Configuration reference**](/docs/speakeasy-reference/generation/cli-config) — Full `gen.yaml` reference for the `cli` target

‎docs/cli-generation/customize-cli.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: "Customize a CLI"
3+
description: "Customize command naming, authentication, output, and behavior of your generated CLI."
4+
---
5+
6+
import { Callout } from "@/mdx/components";
7+
8+
# Customize a CLI
9+
10+
<Callout type="warning" title="Alpha · Enterprise Only">
11+
CLI generation is currently in **alpha** and available exclusively to
12+
**Enterprise** customers. Features and configuration may change. [Contact
13+
us](https://www.speakeasy.com/pricing) for access.
14+
</Callout>
15+
16+
The generated CLI can be customized through `gen.yaml` configuration options and OpenAPI extensions. This page covers CLI-specific customization. For the full configuration reference, see the [CLI configuration options](/docs/speakeasy-reference/generation/cli-config).
17+
18+
## Command stutter removal
19+
20+
By default, the CLI applies smart stutter removal to keep command names clean. When an operation name shares a prefix or suffix with its tag (group), the redundant part is removed.
21+
22+
**Prefix stutter** — an operation name like `users-list` under a `users` tag becomes `list`:
23+
24+
```bash
25+
# With removeStutter: true (default)
26+
my-cli users list # "users-" prefix removed from "users-list"
27+
my-cli users get # "users-" prefix removed from "users-get"
28+
29+
# With removeStutter: false
30+
my-cli users users-list
31+
my-cli users users-get
32+
```
33+
34+
**Suffix stutter** — an operation name like `list-users` under a `users` tag becomes `list`:
35+
36+
```bash
37+
# With removeStutter: true (default)
38+
my-cli users list # "-users" suffix removed from "list-users"
39+
my-cli users create # "-user" suffix removed from "create-user" (singular match)
40+
41+
# With removeStutter: false
42+
my-cli users list-users
43+
my-cli users create-user
44+
```
45+
46+
**Exact matches** are promoted to the parent group command (the group itself becomes runnable). Both prefix and suffix matching also handle singular/plural variations (e.g., `create-user` under a `users` group). Configure this behavior in `gen.yaml`:
47+
48+
```yaml
49+
cli:
50+
removeStutter: true # default
51+
```
52+
53+
## Environment variable prefix
54+
55+
The `envVarPrefix` setting controls the prefix for all environment variables the CLI reads. This affects authentication, server selection, and global parameters.
56+
57+
```yaml
58+
cli:
59+
envVarPrefix: "PETSTORE"
60+
```
61+
62+
With this configuration, the CLI will check for variables like:
63+
64+
- `PETSTORE_API_KEY` — API key authentication
65+
- `PETSTORE_BEARER_TOKEN` — Bearer token authentication
66+
- `PETSTORE_SERVER_URL` — Server URL override
67+
68+
## Custom code regions
69+
70+
Enable custom code regions to insert hand-written code into specific locations in the generated CLI. When enabled, marked regions in the generated code are preserved across regenerations.
71+
72+
```yaml
73+
cli:
74+
enableCustomCodeRegions: true
75+
```
76+
77+
Custom code regions use Go comments to mark boundaries:
78+
79+
```go
80+
// #region custom-imports
81+
import "my-custom-package"
82+
// #endregion custom-imports
83+
```
84+
85+
For more details on custom code regions, see the [custom code regions documentation](/docs/customize-sdks/code/code-regions/overview).
86+
87+
## Release artifact generation
88+
89+
By default, the CLI target generates GoReleaser configuration, GitHub Actions workflows, and install scripts. Disable this if you manage releases separately:
90+
91+
```yaml
92+
cli:
93+
generateRelease: false # default: true
94+
```
95+
96+
When enabled, the following files are generated:
97+
98+
- `.goreleaser.yaml` — Cross-platform binary build configuration
99+
- `.github/workflows/release.yaml` — GitHub Actions release workflow
100+
- `scripts/install.sh` — Linux/macOS install script
101+
- `scripts/install.ps1` — Windows PowerShell install script
102+
103+
For more information on distributing your CLI, see [Distribute a CLI](/docs/cli-generation/distribute-cli).
104+
105+
## CLI name and binary
106+
107+
The `cliName` setting controls:
108+
109+
- The binary name (what users type to run the CLI)
110+
- The config directory path (`~/.config/<cliName>/config.yaml`)
111+
- Shell completion command names
112+
- References in generated documentation
113+
114+
```yaml
115+
cli:
116+
cliName: "petstore"
117+
```
118+
119+
## Go SDK customization
120+
121+
The CLI target generates a Go SDK internally (in the `internal/sdk/` directory) that powers the CLI commands. Many standard SDK customization options apply to the underlying SDK, including:
122+
123+
- [Server configuration](/docs/customize-sdks/servers)
124+
- [Authentication and security](/docs/customize-sdks/authentication/overview)
125+
- [Retries](/docs/customize-sdks/runtime/retries)
126+
- [Pagination](/docs/customize-sdks/runtime/pagination)
127+
- [Error handling](/docs/customize-sdks/responses/errors)
128+
- [Global parameters](/docs/customize-sdks/globals)
129+
130+
For Go-specific SDK configuration, see the [Go configuration reference](/docs/speakeasy-reference/generation/go-config).

0 commit comments

Comments
 (0)