go-tool-base

Go Tool Base (GTB)

The Intelligent Application Lifecycle Framework for Go.

Flag parsing is the easy part. What costs you is everything after it: configuration that layers properly, a self-update path you trust, errors a user can act on, and the same six commands written again in every tool. GTB is a batteries-included micro-framework (think Rails or Laravel) for Go applications, and it ships those already built.

Those applications come in three shapes, and one binary can be all of them:

• Command-line tools that run once and exit, with the built-in commands (init, update, doctor, docs, mcp) already wired.
• Long-running processes, such as bots, workers and daemons, supervised by go/controls for ordered start-up, health checks and graceful shutdown. A run without a terminal (systemd, a container, cron) starts without prompting anyone.
• Binaries that serve their own local UI, a web studio or a desktop app's backend, on the same hardened HTTP server and the same Props as the rest of the tool.

✅ What GTB IS / IS NOT

• IS a full-lifecycle framework. Configuration, versioning, auto-updates, embedded TUI docs, error handling and structured logging, out of the box.
• IS a dependency injection container. Services are passed explicitly through the Props container to every command constructor. Nothing reaches for a global.
• IS an AI-ready foundation. Agentic loop orchestration and MCP exposure are built in.
• NOT a web framework (like Gin/Fiber) or a microservice generator (like Sponge). GTB gives an application its lifecycle: configuration, updates, supervision, errors and logging. It brings no router opinions, no templating and no service mesh. A serve or studio command boots whatever HTTP handler you choose, inside that lifecycle.

[!IMPORTANT] Full Documentation: For detailed guides, component deep-dives, framework comparisons, and API references, please visit our documentation site: https://gtb.phpboyscout.uk

📦 CLI Installation

To install the gtb automation CLI, use the recommended installation script for your platform:

macOS/Linux (bash/zsh):

curl -sSL https://gtb.phpboyscout.uk/install.sh | bash

Windows (PowerShell):

irm https://gtb.phpboyscout.uk/install.ps1 | iex

Homebrew (macOS)

Every release publishes a cask to the GitLab-hosted tap at phpboyscout/homebrew, so Homebrew handles upgrades for you:

brew tap phpboyscout/homebrew https://gitlab.com/phpboyscout/homebrew.git
brew install --cask gtb

Upgrade later with brew upgrade --cask gtb.

[!NOTE] Pass the tap URL. The shorthand brew tap phpboyscout/homebrew resolves to github.com/phpboyscout/homebrew-homebrew, which does not exist. The tap is on GitLab, so the URL is required.

If you tapped the pre-migration GitHub tap before it was withdrawn, remove it with brew untap phpboyscout/homebrew, or brew update will fail against it.

[!NOTE] To build from source, clone the repository and run just install, which builds the CLI and the framework from the same commit through the repository's Go workspace. Do not use go install .../cli/cmd/gtb@<version>: it builds the CLI against the framework release named in cli/go.mod, which lags the CLI, and can fail to compile. A source build carries no pre-built documentation assets, so the docs command falls back to a limited source-build mode.

🚀 Key Advantages & Features

• 🤖 AI Agentic Workflows: Integrated support for Claude, Gemini, and OpenAI to power autonomous ReAct-style loops and built-in Q&A against your embedded docs.
• 🔌 Model Context Protocol (MCP): Expose your CLI commands automatically as MCP tools for use by IDEs and external AI agents.
• 📦 Auto Updates & Lifecycle: Zero-config version checking and self-update, straight from GitHub/GitLab releases, via the built-in update command.
• 📕 TUI Documentation: A built-in, interactive terminal browser for your markdown documentation. Forget generic man pages.
• 🧱 Scaffold: Generate production-ready, interface-driven CLI tool skeletons in seconds.
• ⚙️ Robust Configuration: Configuration merged from files, environment variables and embedded assets, in a precedence you can inspect.
• 🏢 Enterprise VCS: Deep integration with GitHub Enterprise and GitLab (including nested group paths) for auth, PR management, and assets.
• 🩹 Error Handling: Structured, testable error management with logging, stack traces, and integrated help context routing to user-facing output.

🏗️ Core Architecture

The framework is built around a centralized Props container that provides type-safe access to all system dependencies.

Much of what GTB once implemented now lives in the standalone phpboyscout Go toolkit, small framework-free modules under gitlab.com/phpboyscout/go/, so a tool can take one without taking all of GTB. Where that happened, the pkg/ package that remains is a thin config adapter that wires the module from Props.

🛠️ Built-in Commands

Every tool built on GTB inherits these essential capabilities:

• init: Bootstraps local environments, configures GitHub/GitLab auth, and manages SSH keys.
• version: Reports the current version and checks for available updates.
• update: Downloads and installs the latest release binary from the project's forge (GitHub, GitLab, Gitea, Codeberg or Bitbucket).
• mcp: Exposes CLI commands as Model Context Protocol (MCP) tools for use in IDEs.
• docs: Interactive terminal browser for documentation with built-in AI Q&A.
• doctor: Runs diagnostic checks to validate configuration, connectivity, and runtime environment.
• changelog: Shows the tool's version history.
• telemetry (opt-in): Manages pseudonymous usage telemetry.
• config (opt-in): Reads and writes the tool's configuration.
• man (opt-in): Generates roff man pages for the command tree.

Commands can be selectively enabled or disabled at bootstrap time via feature flags. See Feature Flags below.

🤖 AI Providers

GTB reaches every provider the go/chat module family registers, through a unified pkg/chat adapter. A provider is a module a tool blank-imports from its main; gtb itself links all of them.

Set the active provider with the AI_PROVIDER environment variable or in your tool's configuration. GTB's own init wizard sets up credentials for the API-key providers; the local CLIs need none, and Vertex, Bedrock and Azure are configured through go/chat's own settings.

🏁 Quick Start

The fastest way to create a new GTB-based tool is with the scaffold command:

gtb generate project

This launches an interactive wizard to configure your project. For automation:

gtb generate project --name mytool --repo myorg/mytool --description "My CLI tool" --path ./mytool

For a GitLab-hosted project with nested groups:

gtb generate project --name mytool --repo myorg/mygroup/mytool --forge-backend gitlab --host gitlab.mycompany.com --path ./mytool

Generated Project Structure

The scaffold produces a fully wired project. The key entry points are:

cmd/mytool/main.go. The entry point, reading version from internal/version. Execute runs the tree with a signal-aware context: SIGINT/SIGTERM cancel cmd.Context() for graceful shutdown, a second signal force-exits, and a signal-terminated run exits 128+signum:

func main() {
    rootCmd, p, err := root.NewCmdRoot(version.Get())
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(errorhandling.ExitCodeUsage)
    }

    gtbRoot.Execute(rootCmd, p)
}

pkg/cmd/root/cmd.go. Wires the Props container and the root command:

//go:embed assets/*
var assets embed.FS

func NewCmdRoot(v version.Info) (*setup.Command, *props.Props) {
    l := logger.NewCharm(os.Stderr, logger.WithTimestamp(true))

    p := &props.Props{
        Tool: props.Tool{
            Name:        "mytool",
            Description: "My CLI tool",
            EnvPrefix:   "MYTOOL",
            ReleaseSource: props.ReleaseSource{
                Type:  "gitlab",
                Host:  "gitlab.com",
                Owner: "myorg",
                Repo:  "mytool",
            },
        },
        Logger:  l,
        FS:      afero.NewOsFs(),
        Version: v,
        Assets:  props.NewAssets(props.AssetMap{"root": &assets}),
    }
    p.ErrorHandler = errorhandling.New(logger.ToSlog(l), p.Tool.Help)

    return gtbRoot.NewCmdRoot(p, NewCmdServe(p)), p
}

[!NOTE] Command constructors return *setup.Command, not *cobra.Command. It embeds *cobra.Command and carries the feature the command belongs to, so it behaves as a cobra command everywhere; .Command exposes the raw pointer when a cobra API needs one. Register child commands with parent.Register(child) rather than AddCommand, so the feature middleware chain is applied.

internal/version/version.go. Populated from GoReleaser ldflags at release, or from runtime/debug VCS info in development:

var (
    version = "dev"
    commit  = "none"
    date    = "unknown"
)

🏳️ Feature Flags

Commands can be selectively disabled or opt-in features enabled via the Tool configuration:

version is always present and is not gated. Only builtin features may be default-enabled; a plugin feature that declares itself default-on is rejected with ErrPluginDefaultOn.

p := &props.Props{
    Tool: props.Tool{
        // ...
        Features: props.SetFeatures(
            props.Disable(props.UpdateCmd), // disable self-update
            props.Enable(props.AiCmd),      // opt-in to AI features
        ),
    },
}

📂 Project Layout

Standard layout for GTB projects:

.
├── cmd/
│   └── mytool/
│       └── main.go              # Entry point
├── pkg/
│   └── cmd/
│       └── root/
│           ├── cmd.go           # Root command and Props setup
│           └── assets/
│               └── init/
│                   └── config.yaml  # Default configuration
├── internal/
│   └── version/
│       └── version.go           # Version info (ldflags + runtime/debug)
├── go.mod
└── README.md