The generated Go client and its cobra command tree are one package, so a Go program that wants only the typed client takes cobra with it

[jryannel]

Where

codegen/gocli.go — Options.CLIDir emits a single file. In the example that is example/tasks/cli/cli_gen.go: 1,917 lines, 101 references to cobra, with Client, Transport, Request and Do in the same package as the command tree. There is no option that emits one without the other.

What

A Go program that wants the typed client — the request encoder, the filter vocabulary, Do, the typed problem bodies — must import a package that brings spf13/cobra and a whole second command tree with it.

The consumer this bites is not hypothetical. An existing admin CLI already built on cobra + resty wants the generated encoder so its flags stop drifting from the API, and what it can take instead is a package that wants to be the CLI. Same for any server-to-server caller in Go: a sync job or an internal service consuming an sqlb API takes a command-line framework to make one typed request.

This is the split the TypeScript emitter already makes, and argues for. client.gen.ts imports nothing; queries.gen.ts imports @tanstack/react-query. The framework binding is a separate file precisely so a consumer that does not want the framework does not pay for it. docs/dart/README.md reaches the same conclusion from the other direction — one file that "imports nothing", explicitly because Dart has no framework layer to make optional.

Go is the one emitter where a dependency-free client is possible and is not offered. Nothing about Client/Do/Request needs cobra; the coupling is the file boundary, not the design.

Fix

Split the emission the way TSDir already splits it — a client.gen.go carrying Client, Transport, Request, Do and the typed row/param/problem types, importing only the standard library, and a cli_gen.go carrying the cobra tree and importing the first.

Two things worth settling with it:

• One knob or two. CLIDir could simply emit both files, which costs existing consumers nothing and makes the client importable on its own. A separate ClientDir would let a consumer take the client without generating a command tree at all — better for the server-to-server case, and the more honest shape if the two are really different artefacts.
• Where the runtime lives. codegen/gocli_runtime.go suggests some of this is already a distinct body of code; whichever file the shared runtime lands in is the one the eject story has to keep working, since docs/eject.md promises a generated layer that imports pgx and the standard library and nothing else — and today the Go client is the one generated artefact that cannot make that claim.

Not a docs problem

Worth recording, because it was the first hypothesis and it is wrong: the Go CLI is discoverable. It is in README.md:73, the docs/architecture.md fan-out diagram, docs/cli/README.md and docs/vision.md. An external evaluation on 2026-08-01 nonetheless concluded three separate times that sqlb "emits no Go client" and listed a Go client emitter as an outstanding upstream ask. Re-reading, the likely cause is that every one of those mentions describes it as a CLI — a command tree, a --help vocabulary, a cobra binary — and a reader looking for a client library to embed does not recognise their own use case in any of them. If the split above lands, naming the client half separately is most of the fix for that too.

Filed 2026-08-01, from an external adoption evaluation.

[jryannel]

Fixed in 641ac0d, on #99.

cli/client/client_gen.go   Client, Request, Transport, Do, Run, Problem
                           — the standard library, and nothing else
cli/cli_gen.go             the cobra tree, importing the above

go list -deps ./cli/client on the tasks example returns no spf13 anything.

The coupling was three functions, as you said. run took a *cobra.Command, and the two flag helpers. run became an exported Run(ctx, io.Writer, req, all) — that signature change is the fix, since it was the only thing in the runtime that knew what a command was — and the CLI keeps a four-line runRequest passing cmd.Context() and cmd.OutOrStdout() into it.

Both knobs, and they compose. ClientDir alone emits the client and no command tree (the server-to-server case). CLIDir emits both, defaulting the client to a client/ subdirectory, so an existing consumer keeps working without touching its project file. The CLI's import of the client is derived from the nearest go.mod plus Dir, with ClientImportPath as the override and an error naming it when derivation cannot work — an absolute Dir, or generating outside a module.

The old file's argument is answered rather than dropped. gocli.go argued for one file; it was reasoning about a different split (invariant runtime versus per-table commands, both needing cobra), but its actual point was sound and load-bearing here: an import set that depends on which operations a schema exposes fails at the consumer's build, because gofmt parses an unused import happily. So the CLI's imports are now derived from the rendered body rather than written down. A create-only schema no longer imports net/url, and there is a test that walks the emitted import block and fails on any import the body never refers to. That makes the failure class unrepresentable rather than avoided by care.

Two things that came out of doing it, both worth knowing:

• run had to be renamed runRequest. A generated unexported identifier shares a package with whatever the consumer writes beside it, and example/tasks/cli/cli_test.go has a hand-written run helper — so the first build after the split failed on a redeclaration, in the repo's own example. Any short generated name is a hazard here; this one is just the one that fired.
• The client needed os, for os.Stderr in Client.stderr, which the first invariant import list missed. Caught by building the example rather than by the generator — which is the argument for the derived-import approach in miniature.

On the naming half. You called it "most of the fix" for three external readers concluding sqlb emits no Go client, and it was cheap: docs/cli/README.md is now titled Go client and CLI and opens with a table of what lands where plus a Just the client section; the README bullet names Go as a client emitter beside TypeScript and Dart rather than only as a shell; the docs/architecture.md fan-out lists cli/client/ on its own line.

Not touched: docs/eject.md's promise. The generated Go client now does import only the standard library, so the claim that had an exception no longer has one — but I did not rewrite that page, since the eject story is about the server layer and whether it should now mention the client at all is your call.

Tests: codegen/goclient_test.go — the client imports no framework, the CLI imports the client rather than redeclaring it, ClientDir alone emits no command tree, the import set follows what is emitted, and the undeterminable-path error names its knob. Full suite green, and the tasks example regenerates and builds.