Skip to content

Tutorials

Learning-oriented lessons. Each one starts from nothing and ends with something that runs, and each is verified against a named GTB release.

If you already know what you want to achieve and just need the steps, the how-to guides are the shorter route. To look something up, try the reference.

Start here

Build your first CLI

Scaffold a project with the gtb generator, build and run it, give it a configuration, add a command of your own, and regenerate without losing your changes. About twenty minutes.

The CLI series

Each part builds on the mytool project from Build your first CLI.

  • Configure your CLI: settings with shipped defaults, overrides from the environment and from layered files, validation, and a setup step that asks the user. About twenty-five minutes.
  • Expose your CLI to AI agents: serve your commands over MCP and see exactly what an agent can reach. About fifteen minutes.
  • Build an AI-backed command: a command that calls a model, with the rules, mechanics and state kept in your code. About thirty minutes, and it needs an API key.
  • Ship self-updates: watch the tool replace itself, and make it refuse an update it cannot verify. About fifteen minutes.

The web-service series

Turns the same mytool project into a long-running service, one part at a time.

  • Run a long-lived service: a serve command that runs a service until it's stopped, shuts down cleanly on a signal, and exits non-zero when the service fails for good. About twenty minutes.
  • Serve gRPC over TLS: a protobuf contract, code generated with buf, a gRPC service with health and reflection on the same controller, then TLS from config alone. About forty minutes.
  • Add a REST API: JSON over HTTPS beside the gRPC service, by hand on net/http and then from an OpenAPI spec, with health endpoints for both. About thirty-five minutes.
  • Serve a web page: escaped HTML and static files from the same server, embedded in the binary. About fifteen minutes.
  • Put a gateway in front of gRPC: REST routes in the proto, a generated grpc-gateway, and the hand-written REST layer deleted. About thirty minutes.
  • Serve live API docs: an OpenAPI document generated from the proto, and an interactive docs site whose console calls the running API. About twenty minutes.
  • Trace a request end to end: OpenTelemetry on both transports and in your own code, and one REST request followed through the gateway, gRPC and the store in Jaeger. About thirty minutes.

The signing series

Signs your releases with a key the release host can't reach, so a tool can refuse an update it can't verify. The first part needs nothing but gtb; the rest need an AWS account, and from the fifth part a gtb-generated tool.

  • Sign and verify on your laptop: make a key, mint the public key you'll publish, sign a checksums file, and verify it with plain gpg. About fifteen minutes, with no cloud account.
  • Put the signing key in AWS KMS: a key that can never leave KMS, a signer role, and a key policy that keeps managing the key apart from signing with it. About twenty minutes.
  • Sign from CI without stored keys: a GitLab or GitHub release job assumes the signer role over OIDC, with no AWS key stored anywhere. About twenty minutes.
  • Publish your public key: mint the public key out of KMS, make an offline rotation authority, and publish both on WKD away from your release host. About thirty minutes.
  • Require signed updates: embed the key in a generated tool, cross-check it against WKD, and turn on enforcement without locking out existing installs. About twenty minutes.
  • Sign every release with GoReleaser: one command wires KMS signing into the release config, so every tag ships a signature. About twenty minutes.
  • Rotate your signing key: move to a new key without breaking a single installed copy, and what to do when the old key is gone. An afternoon, then weeks of overlap.