Derive a noun-verb command tree from an OpenAPI document
Turn operationIds, tags and paths into a committed map of noun, verb and operationId that any CLI framework can implement, with collisions resolved in the map.
How-to › Section 7
Ship a CLI or REPL#
Command-line and interactive surfaces over an API, for humans, scripts and agents: building, making usable, distributing, and exploring an API before writing code.
15 guides in 4 topics. Every guide compares its approaches and shows the output its commands printed.
- Build a CLI over an API 3
- Make a CLI usable by people, scripts and agents 3
- Test, package and distribute a CLI 3
- Explore an API interactively 6
Build a CLI over an API 3 guides
Generating or hand-writing a CLI: restish over any OpenAPI document, the go-cli target generated from a semantic model, oclif and commander, cobra, click and typer, clap, Thor, Symfony Console, and a gh-style resource-shaped command tree; mapping operationIds to commands, flags and auth, and curl plus jq or HTTPie as the do-nothing baseline.
Map API parameters to CLI arguments and flags
Extend the command map with a parameter map: path parameters as positional arguments, query and header parameters as flags, and one input style for request bodies.
Wire OpenAPI security schemes into CLI auth flags
Turn each OpenAPI security scheme into a CLI flag backed by an environment variable, place the value where the scheme says, and prove it with a 401 and a 200.
Make a CLI usable by people, scripts and agents 3 guides
Output formats (table, JSON, YAML, --jq), stable exit codes, TTY detection and color, paging, progress, shell completion, help text, config files and profiles, environment variable precedence, keychain token storage after a device-flow login, and designing a CLI that a coding agent can drive.
Add a --json flag and stable exit codes to a CLI
Print one JSON document on stdout, every message on stderr, and a four-line exit code table in the help, then prove a script can branch on it.
Design a CLI a coding agent can drive
Give a CLI machine-readable output, exit codes that mean one thing each, and a confirmation rule that never depends on a terminal being attached.
Write CLI help that people and agents can both use
Describe the command surface once, render it as text and as data, and lint the result so a command cannot ship with an example that does not run.
Test, package and distribute a CLI 3 guides
Golden-file and snapshot tests across operating systems, end-to-end tests against a mock API, then distribution with goreleaser, Homebrew taps, Scoop, npm, pipx, Docker images, code signing and notarization, and update checks.
Cross-compile CLI release archives with goreleaser
Turn one tag into per-OS archives and a checksums file with goreleaser, a build script you own, or dist for Rust, and stamp the version so no binary says `dev`.
Snapshot-test CLI output across operating systems
Run the built CLI as a child process, normalize line endings, paths, and color, and compare with committed golden files on Linux, macOS, and Windows in one matrix.
Test interactive prompts and terminal behavior in a CLI
Test a confirmation prompt without a real terminal, by passing the streams and the terminal flag in rather than reading them from the process.
Explore an API interactively 6 guides
Trying calls before writing code: language REPLs with an SDK loaded and tab completion from the model, generated REPL surfaces (the sdkgen REPL, seneca-repl), prompt_toolkit and IPython shells, Postman, Bruno, Insomnia and Hoppscotch collections generated from OpenAPI and kept in git, GraphiQL, Swagger UI try-it, HTTPie sessions, and a keyboard-first command bar over an API's operations (cmdk, kbar, voxgig-ui as options).
Add a keyboard command bar over your API operations
Build a command palette over every operation in an OpenAPI document, opening in the sandbox and refusing a delete until its operationId is typed back.
Build a REPL for your API in Node.js
Wrap an API client in its own Node REPL: environment in the prompt, dot commands for state, one-line API errors, and a session that survives a background failure.
Generate a REPL from an OpenAPI description
Generate a shell from an OpenAPI document with the sdkgen Go CLI target, read what the model gave it words for, and point it at a sandbox before the first call.
Generate an API client collection from an OpenAPI document
Turn an OpenAPI document into a Bruno or Postman collection with one command, commit the output beside the document, and fail the build when the two stop agreeing.
Preload a generated client into a Node REPL
Start a REPL with the client already built and its entities named, so exploring an API is one command rather than six lines of setup typed from memory.
Turn an exploratory REPL session into a script
Convert a REPL history into a script that runs, by dropping the lines that threw, the expressions typed to look at a value, and the REPL's own commands.
Generate the client instead of writing it#
Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.