| name | go-cli-builder |
| description | Use when building, scaffolding, or substantially expanding Go CLIs for APIs, SaaS products, SOAP/OpenAPI/Postman/HAR-backed integrations, Homebrew-distributed tools, or Kong-based command surfaces, following a phased research-to-ship quality loop. |
Go CLI Builder
Build production-grade Go CLIs in Peter's house style: useful vertical slices first, agent-friendly command contracts, strong auth/config/output boundaries, and shippable Homebrew distribution.
Start Here
- Read local context before design:
- Existing repo:
go.mod, Makefile, .goreleaser.yaml, README.md, cmd/, internal/, tests, docs, current command grammar.
- New repo: inspect
~/Development/Personal/go-cli-development-guide.md, then sample the closest existing CLIs: nimbu-go-cli, frontapp-cli, harvest-cli, raindrop-cli.
- If the target API facts may have changed, verify current primary docs before designing auth, rate limits, endpoint scope, or dependency versions.
- Make docs parity a gate: before implementation, create a command-to-doc matrix that traces each planned command to the primary operation, method/path or SOAP action, auth/session rule, required fields, response fields, pagination/rate limits, and documented errors.
- Read
references/cli-quality-loop.md when shaping scope, phases, artifacts, or verification gates.
- Read
references/local-go-cli-patterns.md before scaffolding, changing command grammar, auth/config/output, release setup, or tests.
Default Shape
Prefer a hand-shaped Go CLI over generated breadth. Start with one valuable vertical slice that proves auth, transport, output, errors, tests, and release shape.
Use this package layout unless the repo already has stronger conventions:
cmd/<binary>/main.go
internal/api/ # clients, transport, typed API errors, resource methods
internal/auth/ # login/token/session/keyring/env handling
internal/config/ # config files, profiles/accounts, paths
internal/cmd/ # Kong commands and command wiring
internal/output/ # table/json/plain, colors, terminal helpers
internal/errfmt/ # actionable user-facing errors
internal/ui/ # optional TUI/wizards/spinners only when useful
Use Kong for new CLIs, matching nimbu, frontcli, harvest, and raindrop. Use Cobra only when the existing repo already uses Cobra or interoperability demands it.
Fast Path
| Phase | Purpose | Output |
|---|
| 0 Resolve + Reuse | Existing repo, docs/spec/HAR/Postman/WSDL, tokens, prior CLIs | source map + constraints |
| 1 Research Brief | API identity, user jobs, auth, rate limits, product thesis | short brief |
| 2 Ecosystem Scan | Existing CLIs/MCPs/SDKs, Nimbu/frontcli/harvest patterns | ecosystem notes |
| 3 Discovery Gate | API quirks, sampled responses, SOAP/XML/HAR provenance | discovery notes |
| 4 Docs Parity Gate | planned commands checked against primary docs/spec/WSDL/Postman/HAR evidence | command-to-doc matrix |
| 5 Scaffold Slice | Small working CLI slice | buildable repo |
| 6 Build Useful CLI | workflow commands, safe mutations, output contracts | real commands |
| 7 Shipcheck | fmt/lint/test, help/version, doctor, read-only smoke | proof block |
| 8 Distribution | GoReleaser, Homebrew tap, install docs | releasable binary |
Build one excellent CLI; add catalog or marketplace machinery only if the user explicitly asks for a family of CLIs.
Command Contract
- Keep identity in flags, payload last:
tool invoices get --invoice 123 --json, not hidden positional ID chains.
- Prefer explicit resource words over generic wrappers. Add raw API escape hatches only after core workflows are stable.
- For create/update, support
--file or clear inline assignments; make them mutually exclusive.
- Default to human table output; always support structured
--json. Add --plain/TSV when shell pipelines matter.
- Add
--no-input, --readonly or env equivalent, --dry-run for mutating previews, and --force for destructive actions.
- Errors must name the failed command/flag/resource and the next corrective command when possible.
Verification Bar
Before handoff, run the repo gate: usually make ci or make fmt-check lint test. Also smoke:
make build
./bin/<binary> --help
./bin/<binary> version 2>/dev/null || ./bin/<binary> --version
./bin/<binary> auth doctor 2>/dev/null || true
For bug fixes or durable behavior, add regression tests. For API integrations, prefer read-only live smoke when credentials are available; otherwise use fixture servers, golden SOAP/XML payloads, or recorded responses.
Docs parity is a release gate, not a research note:
- Every shipped command must link to a primary source section, WSDL operation, OpenAPI path, Postman request, HAR finding, or documented example.
- Verify method/path/SOAP action, auth/session placement, required and optional params, request body/XML, response fields used by output, pagination/rate limits, and error cases.
- Cover request builders and output mappers with fixtures or goldens based on documented examples when practical.
- Commands based only on observed behavior must be marked provisional with provenance and warnings.
Common Mistakes
- Starting with every endpoint instead of a useful slice.
- Putting secrets in config files instead of OS keyring/env.
- Making JSON a separate afterthought instead of a first-class output contract.
- Treating docs parity as optional research instead of a release gate.
- Letting command grammar drift between examples, README, tests, completion, and GoReleaser binary name.
