How-to Guides¶

Practical, step-by-step instructions for common tasks and workflows in GTB. These guides focus on the "How" – providing actionable steps to build and extend your CLI tools.

Getting Oriented¶

Migrating from Other Ecosystems ¶

A conceptual translation guide if you're coming to Go from Laravel, Rails, or Django.

Development Workflows¶

Scaffolding a New CLI ¶

Get up and running in seconds using the gtb CLI generator.

Using Command Middleware ¶

Add cross-cutting concerns like logging and auth checks to your command tree.

Implementing Custom Middleware ¶

A hands-on guide to creating and registering your own domain-specific middleware.

Configuring Built-in Features ¶

How to toggle and tune framework features like Self-Updates, MCP, and AI documentation.

Adding Custom Commands ¶

A hands-on guide to implementing domain-specific logic and registering it with the command tree.

Adding Nested Subcommands ¶

Build multi-level command trees (e.g. tool deploy canary) via the generator or by hand using setup.Command.Register.

Advanced Guides¶

Testing & Mocking ¶

Strategies for unit testing your commands using the framework's built-in mocking capabilities.

AI Provider Setup ¶

Choosing an AI provider (Claude, OpenAI, Gemini) and securely configuring your environment.

Adding an Initialiser ¶

Learn how to create and register a custom Initialiser for your feature.

Adding a Doctor Check ¶

Register custom diagnostic checks so the doctor command validates your feature's health.

Output & Observability¶

Add Scriptable JSON Output to a Command ¶

Use pkg/output to give any command a --output json flag for CI/CD and scripting integration.

Switch to Structured JSON Logging for Containers ¶

Replace the charmbracelet terminal logger with a slog JSON backend for daemon and container deployments.

Configuration¶

React to Configuration Changes at Runtime ¶

Use config.Observable and AddObserver to reconfigure long-running services without restarting.

Define and Validate Config for a Component ¶

Define config defaults via embedded assets and validate them at runtime using per-package schema validation.

Error Handling¶

Write User-Facing Errors with Hints ¶

Use cockroachdb/errors and ErrorHandler to produce actionable error messages with recovery suggestions.

AI Integration¶

Build a Command with Structured AI Responses ¶

Use chat.Ask with a typed struct to receive deterministic, schema-validated responses from an AI provider.

Add Tool Calling to an AI Command ¶

Expose Go functions as tools the AI can call, with the built-in ReAct loop managing the back-and-forth.

Persist Chat Conversations ¶

Save and restore AI chat conversations across CLI invocations using snapshots and the FileStore.

Version Control & Releases¶

Configure Self-Updating ¶

Wire up UpdateCmd with GitHub, GitLab, Bitbucket, Gitea, Codeberg, or a direct HTTP server as the release source for automatic binary updates.

Add a Custom Release Source ¶

Implement and register a custom release.Provider so your tool can self-update from any backend — S3, Artifactory, Nexus, or a proprietary store.

Secure Releases — Checksum Verification ¶

Publish checksums.txt alongside release binaries so Update() rejects tampered or truncated downloads. Covers the fail-open library default, the setup.DefaultRequireChecksum opt-in for fail-closed tools, and per-provider manifest retrieval (Bitbucket downloads, Direct's checksum_url_template).

Telemetry¶

Create a Custom Telemetry Backend ¶

Implement the telemetry.Backend interface to send usage analytics to any platform.

Create a Custom Deletion Requestor ¶

Implement the telemetry.DeletionRequestor interface for GDPR-compliant data deletion from custom backends.

Code Generation¶

Configure Generator Ignore Rules ¶

Use .gtb/ignore to prevent the generator from overwriting customised files during regeneration.

Automate GitHub Workflows ¶

Create pull requests, download release assets, and read file contents using GHClient.

Assets¶

Embed and Register Custom Assets ¶

Ship default configs, templates, and data files with your tool using Go's embed package and props.Assets.

Services¶

Add a gRPC Management Service ¶

Register a gRPC server with the controller, wire the standard health protocol, and configure the port.

Expose a gRPC Service as REST ¶

Put a JSON/REST surface over an existing gRPC service with the grpc-gateway — annotate the proto, mount gateway.New, and let DialLocal handle the connection.

Serve Interactive API Docs ¶

Generate an OpenAPI v3 spec and serve it with an embedded Stoplight Elements "try it" console using pkg/openapi.

Security¶

Add HTTP Security Headers ¶

Implement HSTS, CSP, and other security headers for your tool using the pkg/http middleware chain.