Your users ask for commands named after branches and totals, and the CLI tools you tried give
them one command per operationId, list-branches beside get-stats. A generator that reads
entities out of the paths prints list branch instead. Its commands are then only as right as its
reading of your document, and the built binary does not show that reading.
What you get
You will end up with a Go binary generated beside a Go SDK, whose commands are the entities of the
semantic model, with its verbs and entity names fixed in .sdk/. This is for you if you own an
API and want one static CLI per release without writing it.
Short answer
Scaffold an sdkgen project with a go target, add the CLI with npx voxgig-sdkgen target add go-cli, run npm run generate, and build the go-cli folder with go build. Its commands are
words over the model’s entities, such as list branch. The stock build offers list, load and
update only, so add create and remove in the target’s fragments under .sdk/, and correct a
misread entity in the guide file.
You will need
Node 22 or later, Go 1.24 or later, and an OpenAPI 3 document. Verified 2026-11-21 against Node
22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef
8.32.4, and Swagger Codegen 3.0.85 on OpenJDK 21. The document here, api.json, describes six
operations on library branches and one totals endpoint, /stats. A stand-in server on
127.0.0.1 answers them. Which CLI to build at all is the subject of
choose Restish, a generated CLI, or a hand-written one.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Restish | Your team and scripts, with the document reachable at run time | Each user installs Restish and connects, and commands are the document’s operationIds | Customers need one binary under your name |
| sdkgen go-cli target | A project that already generates a Go SDK and wants entity-shaped words | Three verbs until you edit its fragments, output in boru notation, and names only as good as the model | Scripts or agents parse the output |
| Speakeasy CLI target | Customers and agents who need JSON output, auth commands and release tooling | A commercial generator that needs an account and a browser login, for a target its matrix grades Beta | Your build cannot depend on a vendor account |
| Swagger Codegen Go client plus a CLI you write | You want every command name designed, over a free open source client | Every command written and kept by hand, over a client that drops false fields and splices ids into paths | The API changes faster than anyone will maintain the CLI |
Voxgig maintains sdkgen. It is the subject of this page and one of four options here, with its cost in its own row.
Restish names its commands after the document’s operationIds, and Speakeasy makes a command of
every operation, grouped by tag, so in both a name changes where the document changes. sdkgen
guesses entities from paths and puts the verb first, as in list branch. Swagger Codegen gives you
a typed client and leaves the command tree to you, which is the most code and the most control.
Kiota used to generate CLIs and has dropped the language.1
Scaffold and add the target
The go-cli target wraps the Go SDK, so the project needs go first. These four lines start
generate.sh, which holds the rest of the run:
npx --yes @voxgig/create-sdkgen@0.31.9 libraries --def api.json --target go
cd libraries-sdk/.sdk
npx voxgig-sdkgen target add go-cli
npm run generate
go-cli/ now sits beside go/, with a go.mod that points at the SDK through a replace
directive, and go build in go-cli/ builds the binary.
Read which commands the model produced
The commands come from two places: the entities in .sdk/model, and a fixed verb list in the
target. commands.mjs sets one against the other, from the files the stock run wrote:
node commands.mjs recorded/stock-words.go.txt recorded/stock-sdk.json
recorded/stock-words.go.txt: words list load update, entities branch stat
branch.create POST /branches no command
branch.list GET /branches list branch
branch.load GET /branches/{branchId} load branch
branch.remove DELETE /branches/{branchId} no command
branch.update PATCH /branches/{branchId} update branch
stat.load GET /stats load stat
6 model operations, 4 reachable from the CLI
apidef classified every path, and the model holds all five branch operations. The stock CLI
registers list, load and update only, so creating or removing a branch has no command. It
also read /stats as an entity called stat, so the totals are load stat. The Go SDK has
Create, Remove and Direct, but this release of the target registers no word for them.
Fix the model and the words in .sdk
Each fix goes where generation reads it. The entity name is a fact about the API, so it goes in
the guide, .sdk/model/guide/guide.aontu, which regeneration never rewrites:
# apidef read /stats as an entity called stat. Give the path to an entity
# called stats, and switch the guessed name off.
guide: entity: stats: path: "/stats": { op: load: method: GET }
guide: entity: stat: active: false
The verbs are a decision about this CLI, so they go in the target’s fragment,
.sdk/src/cmp/go-cli/fragment/words.fragment.go. Two words join the verb list, and the switch
gains a case for each:
case "load":
result, err = ent.Load(arg, nil)
case "create":
result, err = ent.Create(arg, nil)
case "update":
result, err = ent.Update(arg, nil)
case "remove":
result, err = ent.Remove(arg, nil)
main.fragment.go carries the help text, and it gets the same two words. The generated
go-cli/README.md still tabulates three words, because its component writes that table from a
fixed list of its own. After npm run generate, every model operation has a command:
node commands.mjs generated/go-cli/words.go
generated/go-cli/words.go: words list load create update remove, entities branch stats
branch.create POST /branches create branch
branch.list GET /branches list branch
branch.load GET /branches/{branchId} load branch
branch.remove DELETE /branches/{branchId} remove branch
branch.update PATCH /branches/{branchId} update branch
stats.load GET /stats load stats
6 model operations, 6 reachable from the CLI
Build the binary and run it
demo.mjs builds generated/go-cli, points it at the stand-in through LIBRARIES_BASE and
LIBRARIES_APIKEY, and runs six commands. The binary prints records in the notation of
boru,2 from a Go map, so the key order changes between runs;
the demo sorts the keys before printing.
node demo.mjs
libraries-cli list branch
exit 0 [{city:'Dublin' id:'b1' name:'Central' open:true} {city:'Dublin' id:'b2' name:'Pearse Street' open:false}]
libraries-cli create {name:"Ranelagh",city:"Dublin",open:true} branch
exit 0 {city:'Dublin' id:'b3' name:'Ranelagh' open:true}
libraries-cli update {id:"b2",open:true} branch
exit 0 {city:'Dublin' id:'b2' name:'Pearse Street' open:true}
libraries-cli remove {id:"b1"} branch
exit 0 {}
libraries-cli load {id:"b1"} branch
exit 1 error: LibrariesSDK: load: request: 404: Not Found
libraries-cli load stats
exit 0 {branches:2 loans:412}
requests the stand-in received:
GET /v1/branches 200
POST /v1/branches 201
PATCH /v1/branches/b2 200
DELETE /v1/branches/b1 204
GET /v1/branches/b1 404
GET /v1/stats 200
The two added words went out as POST and DELETE on the paths the model holds. The binary has
no switch for the SDK’s test mode. A Go test in the go-cli package reaches it, handing the CLI’s
own words a client from sdk.TestSDK, and regeneration leaves that file in place:
go test -C generated/go-cli -run TestWordsInTestMode -v .
=== RUN TestWordsInTestMode
words_testmode_test.go:48: client mode: test
words_testmode_test.go:58: list branch exit 0, ids [b1 b2]
words_testmode_test.go:58: remove {id:"b2"} branch exit 0, ids []
words_testmode_test.go:58: list branch exit 0, ids [b1]
words_testmode_test.go:58: update {id:"b1",open:false} branch exit 0, ids [b1]
words_testmode_test.go:65: load {id:"b2"} branch exit 1, error: LibrariesSDK: load: request: 404: Not found
Get the same commands from Swagger Codegen or Speakeasy
Swagger Codegen 3.x has no CLI target: its client list
holds SDKs only. The 2.x line adds a Bash client, but that line
reads Swagger 2.0 only. The substitute is -l go
for the client and a command tree you write.
swagger/main.go is 60 lines for three commands, and the generated client set two traps for it:
node demo.mjs swagger
libraries-swagger branch list
exit 0 [{"id":"b1","name":"Central","city":"Dublin","open":true},{"id":"b2","name":"Pearse Street","city":"Dublin"}]
libraries-swagger branch get b2
exit 0 {"id":"b2","name":"Pearse Street","city":"Dublin"}
libraries-swagger branch get b9
exit 1 error: 404 Not Found
libraries-swagger stats
exit 0 {"branches":2,"loans":412}
The output is JSON, which a script can parse. Branch b2 has no open field, because
api.json leaves open optional, the generated struct tags it json:"open,omitempty", and
encoding/json omits a false. A test shows the same tag drops
open from an update body, and that marking the field required removes the tag. The client also
splices the id into the path as written, so GetBranch(ctx, "../stats") asked for
/v1/branches/../stats, which dot-segment removal in
RFC 3986 turns into /v1/stats.3
main.go escapes the id as one segment.
Speakeasy’s CLI target generates a
Go program on Cobra over a generated Go SDK, from speakeasy quickstart --target cli. Every
operation becomes a command, grouped by tag, and removeStutter turns users list-users into
users list (customize a CLI). It
documents -o json, a --jq flag and an agent mode. Its
maturity matrix grades the CLI target
Beta. The Speakeasy CLI opens a browser to log in
to an account, so it was not run here.
Check it worked
Fourteen tests build both binaries, drive them against the stand-in, run the two Go suites, and read the recorded runs.
node --test cli.test.mjs
1..14
# tests 14
# suites 0
# pass 14
# fail 0
# cancelled 0
# skipped 0
# todo 0
The first two read the stock and the corrected words, so rerunning generate.sh on a release
that changes the verbs turns the suite red.
When it goes wrong
The added words vanish after the next generate. They were typed into go-cli/, which is output,
as the hand edit to go-cli/main.go below shows. doctor compares only the copies under .sdk/, so it passes the edit;
npm run check-drift regenerates everything and names the file. pitfall.mjs prints what the
recorded run showed:
node pitfall.mjs
a hand edit to go-cli/main.go, then:
voxgig-sdkgen doctor exit 0 .sdk matches the scaffold (0 additive, 0 customized)
npm run check-drift exit 1 M go-cli/main.go
npm run generate the edit is gone from main.go
the guide and fragment corrections, then:
voxgig-sdkgen doctor exit 1 ORPHAN MODEL FILE (on disk, included by nothing, read by nobody): flow/BasicStatFlow.aontu
after deleting it exit 0 .sdk matches the scaffold (0 additive, 2 customized)
doctor fails after a correct guide fix. The rename left the flow file of the old entity behind,
and doctor refuses an orphaned model file. Its summary line meanwhile counts the two customized
fragments as 2 forked. Delete .sdk/model/flow/BasicStatFlow.aontu, and the fragments then read
as customized with exit 0. @voxgig/sdkgen 4.45.0 with @voxgig/apidef 8.33.1 shipped the same
three verbs, left the same file, and printed the same summary.
A script piping the CLI into jq fails to parse. The output is boru notation, not JSON. Use a
client that prints JSON for scripts.
When not to do this
Do not hand this binary to scripts or agents at this version. Its records are boru notation with
keys in an order that changes between runs, and every failure exits 1. Speakeasy’s CLI target is the
better fit when agents read the output and a hosted vendor is acceptable, because it documents JSON
and an agent mode.
Do not adopt sdkgen to get a CLI for one API you will never generate an SDK for. The model, the
guide, the fragments and a Go SDK are four things to keep for one binary. Swagger Codegen with
your own Cobra or flag layer suits a team that wants every command designed and has no use for a
model.
Do not ship the first generated tree before reading what the model made of each path. A path the heuristics misread becomes a command your users type, and renaming it later breaks their scripts.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4 and Swagger Codegen 3.0.85. Every output block is
what the command preceding it printed. Scaffolding, generation, doctor and check-drift ran once, in
generate.sh, which also repeated the stock and guide tests on sdkgen 4.45.0. Their output is
committed under generated/ and recorded/, and the commands here read it or build from it. Both
Go binaries are built on every check. Speakeasy was not run, for want of an account, and its
paragraph and table row come from its CLI generation and maturity pages read that day. Kiota was
not run; its footnote rests on its changelog.
Footnotes
-
Kiota’s changelog records the whole career. Version 1.5.1, on 2023-08-08, renamed the Shell language to CLI. Version 1.28.0, on 2025-07-11, carries the line “Removed CLI generation ability.” The language spent just under two years under its second name. ↩︎ Back to text
-
The
boruREADME calls it a typed, word-based query language. Its reference binary, the README says, includes a REPL, a type checker, a formatter, an LSP server, a registry client, a secrets vault and a multi-service supervisor. The generated CLI imports two packages of it, the engine and the parser, which is whylist branchreads as a sentence in that language. ↩︎ Back to text -
RFC 3986 calls its routine “a simple method using two string buffers” and sets it out in five lettered cases. It then walks two merged paths through it one step at a time, the first being
/a/b/c/./../../g. The routine removes extra dot segments rather than treating them as an error, the courtesy that lets a branch id of../statsleave its segment. ↩︎ Back to text