Your team writes Python, so the CLI for your API ships as a Python package. The first customer to install it has a locked-down laptop with no Python, and support spends the week on interpreter versions. The two people who asked for a CLI already script the API with curl, so a package was never what they needed.
What you get
You will end up with a choice between four ways to put a CLI over your API, made on five questions and checked with three measured tasks. This is for you if you own an API and somebody has asked for a command line.
Short answer
Choose by who runs the CLI and what runtime they have, not by your team’s language. Restish
reads your OpenAPI document at run time and needs no code. A generated CLI, such as the sdkgen
go-cli target, ships as one binary whose commands follow the model. A hand-written CLI gives
you every name and a codebase to keep. Drive one interactive task, one script task, and one
agent task through each candidate, counting keystrokes, owned lines, and failed checks.
You will need
Node 22.18 or later, bash, curl 7.76 or later, jq, and an OpenAPI 3 document. Verified 2026-11-19
against Node 22.23.5, curl 8.5.0, jq 1.7, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@hey-api/openapi-ts 0.99.0, and Restish v2.3.0. The document here, openapi.json, describes
three operations on allotment plots behind a bearer token, and a stand-in server on the loopback
interface answers them. Restish and the sdkgen CLI are compiled Go programs, and the page’s checks
install no Go. Each ran once against that server and its transcript is committed under recorded/.
Every command below that shows Restish or sdkgen output replays that transcript and starts neither
binary. The other tools run live.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| cobra | A Go CLI written by hand, where the command tree is the product | Every command, flag, and help line written by hand and kept in step with the API | The API changes weekly and nobody owns the CLI |
| curl + jq | Scripts you own, on machines that already have both tools | The longest commands measured here, with the header and the error flag repeated in each | Other people will type the commands |
| Fern CLI generator | Customers, scripts, and agents who need one binary with JSON output | A hosted commercial generator: the default run sends your document to Fern, and a local run needs Docker | The document may not leave your network and Docker is not an option |
| Hey API client plus a CLI you write | TypeScript users who have Node, and command names you want to design | The CLI is yours to write, and every user needs Node unless you bundle a runtime | Your users have no Node |
| Restish | Your team, scripts, and agents, when the document is reachable and its operationIds read well | Each user installs Restish and connects, and names change only through extensions in the document | Customers need one binary under your name |
| sdkgen go-cli target | People at a terminal, in a project that already generates its SDKs | Three fixed verbs, and output in a notation that jq and JSON parsers reject | Scripts or agents will read the output |
Voxgig maintains sdkgen. It is one of six options here, not the recommendation.
The rows differ in who owns the command names. Restish and the two generators take them from the document or the model, so a rename happens there. cobra and the Node CLI put every name in your code, and the price is keeping that code. curl and jq own nothing and repeat everything. Of the generated options, Fern alone documents JSON output and typed exit codes, and it is a hosted product.
Answer five questions before you compare tools
Five questions decide most of the choice. The language your team writes is not one of them.
| Question | Restish | Generated CLI | Hand-written CLI | curl + jq |
|---|---|---|---|---|
| Who runs it | Your team, scripts, agents | Customers as well | Whoever you design it for | You, and scripts you own |
| Is the document reachable at run time | Needed to connect and sync, or a local file with --spec | Not needed after generation | Not needed | Not needed |
| Must it ship as one static binary | No: users install Restish, then connect | Yes: Go from sdkgen, Rust from Fern | cobra yes, a Node CLI no | No: two tools to install |
| How much renaming do you need | x-cli-name in the document | sdkgen fixes three verbs; Fern reads x-fern-sdk-method-name | Every name is yours | Nothing to name |
| Who maintains it in a year | Its maintainers, and you keep the document served | You regenerate | You, for every operation the API gains | Every script author |
Read the binary row first. A CLI your users cannot start has no features.
Generate the sdkgen CLI and read its transcript
The sdkgen go-cli target is a Go program generated beside the Go SDK it wraps. Two commands
produce the source, and go build turns it into a binary.
npx --yes @voxgig/create-sdkgen@0.31.9 allot --def openapi.json --target go --target go-cli
(cd allot-sdk/.sdk && npm run generate)
The generator fixes the vocabulary: three verbs over the entities the model extracted, here
plot.
func registerSDKWords(r *eng.Registry, client *sdk.AllotSDK) {
for _, op := range []string{"list", "load", "update"} {
The binary ran the three tasks once, with ALLOT_BASE and ALLOT_APIKEY pointing it at the
stand-in, and record.sh saved what it printed. transcript.mjs replays that recording from
recorded/sdkgen-go-cli.json and does not start the binary:
node transcript.mjs sdkgen-go-cli
sdkgen go-cli, recorded 2026-11-19
$ allot-cli list plot
[{id:'plot_11' state:'let' tenant:'Grace' bed:'A1'} {id:'plot_12' state:'vacant' bed:'A2'} {state:'vacant' bed:'B1' id:'plot_13'}]
[exit 0]
$ allot-cli load '{id:"plot_12"}' plot
{state:'vacant' bed:'A2' id:'plot_12'}
[exit 0]
$ allot-cli list plot | jq -r '.[] | select(.state=="vacant") | .id'
jq: parse error: Invalid numeric literal at line 1, column 5
[exit 5]
$ allot-cli update '{id:"plot_12",state:"let",tenant:"Ada"}' plot
{state:'let' tenant:'Ada' bed:'A2' id:'plot_12'}
[exit 0]
$ allot-cli update '{id:"plot_99",state:"let",tenant:"Ada"}' plot
error: AllotSDK: update: request: 404: Not Found
[exit 1]
A person can read every line of that, but a program cannot parse it. The records come out in the
notation of boru, the word-based query language the CLI is
built on, and jq rejects it.1 The key order changes from run to run: recorded again, in
recorded/sdkgen-go-cli-rerun.json, the same binary put bed first in the record it loaded, and
jq reported a different column. The missing plot exits 1, which is also the code
for every other failure. One more fact for the binary row: plain
go build linked this binary against the system C library, and CGO_ENABLED=0 go build produced a
statically linked one.
Drive the same three tasks through each candidate
tasks.mjs holds each tool’s commands as its user would type them, and four checks that are the
same for every tool:
return [
{ name: 'a person lists the plots and looks at one', ok: list.exit === 0 && one.exit === 0 && list.stdout.includes('plot_12') && one.stdout.includes('plot_12') },
{ name: 'a script gets the vacant plot ids out of jq', ok: pipeline.exit === 0 && pipeline.stdout === 'plot_12\nplot_13\n' },
{ name: 'an agent reads the update back as JSON', ok: update.exit === 0 && parsesTo(update.stdout, { state: 'let', tenant: 'Ada' }) },
{ name: 'an agent sees a missing plot as a non-zero exit', ok: missing.exit !== 0 },
]
The agent task is run by a script that holds an agent’s constraints: no terminal, stdin closed,
output parsed as JSON, success read from the exit code. No model is involved. The source column
says which rows ran: live rows run on every check, and recorded rows replay recorded/.
node drive.mjs
three tasks, four tools, one stand-in API on the loopback interface
tool source setup own code keystrokes checks passed
curl + jq live 0 0 612 4 of 4
hand-written CLI on a Hey API client live 1 79 180 4 of 4
restish recorded 1 0 243 4 of 4
sdkgen go-cli recorded 3 0 247 2 of 4
keystrokes by task: a person looking, a script, an agent
curl + jq 146 116 350
hand-written CLI on a Hey API client 39 55 86
restish 54 71 118
sdkgen go-cli 55 66 126
checks that failed
sdkgen go-cli: a script gets the vacant plot ids out of jq
sdkgen go-cli: an agent reads the update back as JSON
Restish needed one line of setup, restish api connect, and passed every check with two fifths
of curl’s typing. Its commands are the document’s operationIds in kebab case. The hand-written CLI
has the shortest commands because somebody designed them, and it has 79 lines of code that somebody
keeps. The sdkgen CLI cost no owned code but failed both checks that parse its output. curl and jq
passed all four at 612 keystrokes, which is the price of having no CLI.
Get a CLI from Fern, or write one on a Hey API client
Fern is a hosted commercial product, and its CLI generator is the closest counterpart to the
sdkgen target. Its quickstart
configures it in generators.yml, the format Fern’s
SDK reference calls legacy:
add fern-cli-generator, run fern generate --group cli, and cargo build compiles the Rust
project it writes. The
features page describes JSON
output whenever stdout is a pipe, a --schema flag that prints each command’s contract, and exit
codes from 0 to 5. Command names come from
x-fern-sdk-method-name,
falling back to the operationId. The default run sends the document to Fern’s cloud and needs a
token or a login, and --local
needs Docker. Fern was not run for this page.
Hey API generates a TypeScript client and no CLI: its
documentation index lists no CLI plugin. @hey-api/openapi-ts
turned the three operations into listPlots, getPlot, and updatePlot. With
output.module.extension set
to .ts, Node runs the generated files as written. allot.mjs is the hand-written layer over
them:
let call
if (verb === 'list' && id === undefined) call = () => listPlots()
else if (verb === 'get' && id) call = () => getPlot({ path: { plotId: id } })
else if (verb === 'let' && id) {
if (!values.tenant) return usage('let needs --tenant <name>')
call = () => updatePlot({ path: { plotId: id }, body: { state: 'let', tenant: values.tenant } })
plots let is a verb the document never implied, which is what hand-writing buys.
Check it worked
Run the suite:
node --test choose.test.mjs
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
# pass 16 is the line to read. One test holds the sdkgen recording to exactly two failed checks,
so a release that prints JSON turns the suite red and the table gets rewritten.
When it goes wrong
The CLI will not start on a user’s machine. It was written in the team’s language, and the user
has no runtime for it. allot.mjs starts through #!/usr/bin/env node:
node runtime.mjs
allot.mjs --help, started through its #!/usr/bin/env node line
node on the PATH: exit 0, usage printed: true
no node on the PATH: exit 127, usage printed: false
Exit 127 is env reporting that it found no node.2 Ship a binary, or bundle the runtime:
oclif’s standalone tarballs include a Node binary for this
reason.
restish api connect fails with spec discovery failed. Restish asked the API root, /openapi.json,
and /openapi.yaml on the API’s host,3 and the runner could not reach the host. Pass --spec
with a file from the repository.
A script that pipes a CLI into jq exits 5. The CLI printed something other than JSON, as the
sdkgen transcript shows. Test the pipe before you promise it.
When not to do this
Do not build or generate anything for three people who script the API. curl and jq passed every check here. Their cost is typing, and a shell function is cheaper than a CLI project.
Do not pick the sdkgen go-cli target for scripts or agents at this version. It failed both
checks that read its output. Fern’s generator is the better choice when agents and customers are
the audience and a hosted vendor is acceptable. Its documentation describes JSON on a pipe, a
schema flag, and typed exit codes.
Do not hand a Node CLI to users without Node. A Hey API client under your own commands is the better choice when the users are TypeScript developers and you need verbs the document does not imply.
Do not choose Restish when the command names are part of your product. They are the document’s names, and each user’s copy depends on reaching it.
Related how-tos
Last verified
Verified 2026-11-19 against Node 22.23.5, curl 8.5.0, jq 1.7, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @hey-api/openapi-ts 0.99.0, and Restish v2.3.0. Every output block is
what the command preceding it printed. The curl, jq, and hand-written rows are run on every check.
Restish and the sdkgen binary ran the same tasks once, on that day, against the same stand-in, and
record.sh holds the commands. node transcript.mjs and the Restish and sdkgen rows of
node drive.mjs replay those recordings and run neither binary. The sdkgen binary was built with
Go 1.24.7. go install built Restish with Go 1.26.11, because v2.3.0 requires Go 1.25.3, and the
binary reports itself as 2.0.0-dev. On 2026-11-20 a second record.sh run reproduced both
recordings, apart from the order of the sdkgen record keys, and that run is committed as
recorded/sdkgen-go-cli-rerun.json. Fern and cobra were not run; their rows and paragraphs describe their
documentation. No request left the loopback interface.
Footnotes
-
The 5 is jq’s own, and its manual mentions it only in passing. The jq 1.7 manual says jq normally exits with 2 for a usage problem or system error, 3 for a program that does not compile, and 0 if the program ran. The number 5 appears there as the default of
halt_error. Input that fails to parse, the case in the transcript, is on neither list. ↩︎ Back to text -
The number is assigned, not chosen by the script. The POSIX description of
envgives 127 to a utility that could not be found and 126 to one that was found but could not be invoked. A CLI that never started therefore reports through somebody else’s exit code, and a caller that expects the CLI’s own table has no row for it. ↩︎ Back to text -
Restish also follows a link. Its OpenAPI reference asks API authors to publish the document at a predictable location or expose a
service-desclink from the API root. RFC 8631 registered that relation in July 2019 for a description primarily intended for machine consumption, and gives an OpenAPI description as its example. ↩︎ Back to text