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

Source: https://voxgig.com/howto/choose-restish-generated-or-hand-written-cli

- Audience: api-producer
- Level: beginner
- Verified: 2026-11-19
- Published: 2026-11-19

## 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](https://cobra.dev/docs/) | 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](https://curl.se/docs/manpage.html) | 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](https://buildwithfern.com/learn/cli-generator/get-started/overview) | 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](https://heyapi.dev/docs/openapi/typescript/plugins/sdk) | 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](https://rest.sh/docs/getting-started/connect-to-an-api/) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/add-a-target.md) | 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.

```bash title="generate.sh"
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`.

```go title="generated/go-cli/words.go"
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:

```bash
node transcript.mjs sdkgen-go-cli
```

```text output
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`](https://github.com/boru-lang/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:

```js title="tasks.mjs"
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/`.

```bash
node drive.mjs
```

```text output
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](https://buildwithfern.com/learn/cli-generator/get-started/quickstart)
configures it in `generators.yml`, the format Fern's
[SDK reference](https://buildwithfern.com/learn/sdks/current/reference/sdk-config) calls legacy:
add `fern-cli-generator`, run `fern generate --group cli`, and `cargo build` compiles the Rust
project it writes. The
[features page](https://buildwithfern.com/learn/cli-generator/get-started/features) 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`](https://buildwithfern.com/learn/cli-generator/get-started/openapi-extensions),
falling back to the operationId. The default run sends the document to Fern's cloud and needs a
token or a login, and [`--local`](https://buildwithfern.com/learn/cli-generator/get-started/local-generation)
needs Docker. Fern was not run for this page.

Hey API generates a TypeScript client and no CLI: its
[documentation index](https://heyapi.dev/llms.txt) lists no CLI plugin. `@hey-api/openapi-ts`
turned the three operations into `listPlots`, `getPlot`, and `updatePlot`. With
[`output.module.extension`](https://heyapi.dev/docs/openapi/typescript/configuration/output) set
to `.ts`, Node runs the generated files as written. `allot.mjs` is the hand-written layer over
them:

```js title="allot.mjs"
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:

```bash
node --test choose.test.mjs
```

```text output
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`:

```bash
node runtime.mjs
```

```text output
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](https://oclif.io/docs/releasing/) 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

- [Generate a REPL from an OpenAPI description](/howto/generated-repl-from-an-openapi-description)

- [Derive a noun-verb command tree from an OpenAPI document](/howto/derive-a-command-tree-from-operation-ids)

- [Design a CLI a coding agent can drive](/howto/design-a-cli-a-coding-agent-can-drive)

- [Add a --json flag and stable exit codes to a CLI](/howto/json-flag-and-stable-exit-codes)

- [Map API parameters to CLI arguments and flags](/howto/map-api-parameters-to-cli-flags-and-arguments)

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

[^1]: The 5 is jq's own, and its manual mentions it only in passing. The
[jq 1.7 manual](https://jqlang.org/manual/v1.7/) 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.

[^2]: The number is assigned, not chosen by the script. The
[POSIX description of `env`](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/env.html)
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.

[^3]: Restish also follows a link. Its [OpenAPI reference](https://rest.sh/docs/reference/openapi-cli-integration/)
asks API authors to publish the document at a predictable location or expose a `service-desc`
link from the API root. [RFC 8631](https://www.rfc-editor.org/rfc/rfc8631.html) registered that
relation in July 2019 for a description primarily intended for machine consumption, and gives an
OpenAPI description as its example.