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

Source: https://voxgig.com/howto/generate-a-go-cli-from-a-semantic-model

- Audience: api-producer
- Level: intermediate
- Languages: go
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](/howto/choose-restish-generated-or-hand-written-cli).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Restish](https://rest.sh/docs/reference/openapi-cli-integration/) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/add-a-target.md) | 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](https://www.speakeasy.com/docs/cli-generation/create-cli) | 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](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/) | 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:

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

```bash
node commands.mjs recorded/stock-words.go.txt recorded/stock-sdk.json
```

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

```aontu title="sdk/guide.aontu"
# 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:

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

```bash
node commands.mjs generated/go-cli/words.go
```

```text output
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`](https://github.com/boru-lang/boru),[^2] from a Go map, so the key order changes between runs;
the demo sorts the keys before printing.

```bash
node demo.mjs
```

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

```bash
go test -C generated/go-cli -run TestWordsInTestMode -v .
```

```text output
=== 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](https://generator3.swagger.io/api/client/V3)
holds SDKs only. The 2.x line adds a Bash client, but that line
[reads Swagger 2.0 only](https://github.com/swagger-api/swagger-codegen). 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:

```bash
node demo.mjs swagger
```

```text output
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](https://pkg.go.dev/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](https://www.rfc-editor.org/rfc/rfc3986.html#section-5.2.4) turns into `/v1/stats`.[^3]
`main.go` escapes the id as one segment.

Speakeasy's [CLI target](https://www.speakeasy.com/docs/cli-generation/create-cli) 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](https://www.speakeasy.com/docs/cli-generation/customize-cli)). It
documents `-o json`, a `--jq` flag and an agent mode. Its
[maturity matrix](https://www.speakeasy.com/docs/sdks/languages/maturity) grades the CLI target
Beta. The Speakeasy CLI [opens a browser to log in](https://www.speakeasy.com/docs/speakeasy-reference/cli/getting-started)
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.

```bash
node --test cli.test.mjs
```

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

```bash
node pitfall.mjs
```

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

- [Choose Restish, a generated CLI, or a hand-written one](/howto/choose-restish-generated-or-hand-written-cli)

- [End-to-end test a CLI against a mock API](/howto/e2e-test-a-cli-against-a-mock-api)

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

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Block a release when generated SDK files have drifted](/howto/block-a-release-when-generated-sdk-files-drift)

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

[^1]: Kiota's [changelog](https://github.com/microsoft/kiota/blob/main/CHANGELOG.md) 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.

[^2]: The `boru` [README](https://github.com/boru-lang/boru) 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.

[^3]: [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html#section-5.2.4) 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.