How-to › Ship a CLI or REPL

How to choose Restish, a generated CLI, or a hand-written one#

Pick the CLI for your API by who runs it and what runtime they have, then check the pick with three tasks and four measured checks per tool.

Audience
API producer
Level
beginner
Topic
Build a CLI over an API
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
cobraA Go CLI written by hand, where the command tree is the productEvery command, flag, and help line written by hand and kept in step with the APIThe API changes weekly and nobody owns the CLI
curl + jqScripts you own, on machines that already have both toolsThe longest commands measured here, with the header and the error flag repeated in eachOther people will type the commands
Fern CLI generatorCustomers, scripts, and agents who need one binary with JSON outputA hosted commercial generator: the default run sends your document to Fern, and a local run needs DockerThe document may not leave your network and Docker is not an option
Hey API client plus a CLI you writeTypeScript users who have Node, and command names you want to designThe CLI is yours to write, and every user needs Node unless you bundle a runtimeYour users have no Node
RestishYour team, scripts, and agents, when the document is reachable and its operationIds read wellEach user installs Restish and connects, and names change only through extensions in the documentCustomers need one binary under your name
sdkgen go-cli targetPeople at a terminal, in a project that already generates its SDKsThree fixed verbs, and output in a notation that jq and JSON parsers rejectScripts 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.

QuestionRestishGenerated CLIHand-written CLIcurl + jq
Who runs itYour team, scripts, agentsCustomers as wellWhoever you design it forYou, and scripts you own
Is the document reachable at run timeNeeded to connect and sync, or a local file with --specNot needed after generationNot neededNot needed
Must it ship as one static binaryNo: users install Restish, then connectYes: Go from sdkgen, Rust from Ferncobra yes, a Node CLI noNo: two tools to install
How much renaming do you needx-cli-name in the documentsdkgen fixes three verbs; Fern reads x-fern-sdk-method-nameEvery name is yoursNothing to name
Who maintains it in a yearIts maintainers, and you keep the document servedYou regenerateYou, for every operation the API gainsEvery 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.

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

  1. 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

  2. The number is assigned, not chosen by the script. The POSIX description of env gives 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

  3. Restish also follows a link. Its OpenAPI reference asks API authors to publish the document at a predictable location or expose a service-desc link 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

Read this page as markdown · All how-to guides

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.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.