How-to › Ship a CLI or REPL

How to generate a Go CLI from a semantic model with sdkgen#

Add the sdkgen go-cli target, build a binary whose commands follow the model's entities, and fix its words and entity names under .sdk/, not in the output.

Audience
API producer
Level
intermediate
Topic
Build a CLI over an API
Languages
Go
Verified

Read first: Choose Restish, a generated CLI, or a hand-written one

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
RestishYour team and scripts, with the document reachable at run timeEach user installs Restish and connects, and commands are the document’s operationIdsCustomers need one binary under your name
sdkgen go-cli targetA project that already generates a Go SDK and wants entity-shaped wordsThree verbs until you edit its fragments, output in boru notation, and names only as good as the modelScripts or agents parse the output
Speakeasy CLI targetCustomers and agents who need JSON output, auth commands and release toolingA commercial generator that needs an account and a browser login, for a target its matrix grades BetaYour build cannot depend on a vendor account
Swagger Codegen Go client plus a CLI you writeYou want every command name designed, over a free open source clientEvery command written and kept by hand, over a client that drops false fields and splices ids into pathsThe 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.

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

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

  2. The boru README 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 why list branch reads as a sentence in that language. ↩︎ Back to text

  3. 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 ../stats leave its segment. ↩︎ 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.