Go Tool Base

The Intelligent Lifecycle Framework for Go Applications

Command-line tools, long-running bots and daemons, and binaries that serve their own UI all need more than basic flag parsing. GTB works as a "batteries-included" micro-framework, providing a standardized foundation for all three, with built-in agentic workflows, hardware-backed credentials vaults, OpenTelemetry observability, and zero-config service management.

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

Get Started Learn Concepts

Why GTB?¶

Before diving into code, we highly recommend reading our positioning guides to understand if GTB is the right fit for your next project:

• What is GTB?: Core philosophy, "IS / IS NOT" framing, and the 8 key advantages.
• Framework Comparison: Direct comparisons with Cobra, Viper, urfave/cli, and web frameworks.
• Coming from other Ecosystems?: A translation guide for developers migrating from PHP (Laravel), Ruby (Rails), or Python (Django).

Where the documentation lives¶

Four sections, each answering a different kind of question:

• Tutorials: start from nothing and end with something that runs. Begin with Build your first CLI.
• How-to guides: you know what you want to achieve; these are the steps.
• Reference: every command, flag and configuration key, with defaults and failure modes.
• Explanation: why the framework is shaped this way.

Overview¶

GTB is for three shapes of application, and a single binary can be all three:

• Command-line tools that run once and exit.
• Long-running processes, such as bots, workers and daemons, supervised 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, such as a browser studio or a desktop app's backend.

GTB accelerates development by providing a standardized Dependency Injection (Props) container pre-wired with essential features. It includes multi-source configuration, automatic version checking, structured logging, and an AI service layer: allowing you to focus entirely on your unique business logic.

Key Features¶

Built-in Commands¶

A tool generated with GTB carries these commands by default, whichever shape it takes:

• init - Initialize tool configuration and setup
• version - Display version information and check for updates
• update - Update the tool to the latest version
• doctor - Diagnose configuration, credentials and the environment
• docs - Interactive documentation browser with AI capabilities
• mcp - Expose your tool's capabilities via the Model Context Protocol

Quick Start¶

package main

import (
    "embed"
    "os"

    "gitlab.com/phpboyscout/go-tool-base/pkg/cmd/root"
    "gitlab.com/phpboyscout/go/errorhandling"
    "gitlab.com/phpboyscout/go-tool-base/pkg/logger"
    "gitlab.com/phpboyscout/go-tool-base/pkg/props"
    "gitlab.com/phpboyscout/go-tool-base/pkg/version"
    "github.com/spf13/afero"
)

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

func main() {
    l := logger.NewCharm(os.Stderr, logger.WithTimestamp(true))

    p := &props.Props{
        Tool: props.Tool{
            Name:        "mytool",
            Summary:     "My awesome CLI tool",
            Description: "A tool that does amazing things",
            ReleaseSource: props.ReleaseSource{
                Type:  "github",
                Owner: "myorg",
                Repo:  "mytool",
            },
        },
        Logger:  l,
        Assets:  props.NewAssets(props.AssetMap{"root": &assets}),
        FS:      afero.NewOsFs(),
        Version: version.NewInfo("1.0.0", "", ""),
    }
    p.ErrorHandler = errorhandling.New(logger.ToSlog(l), p.Tool.Help)

    rootCmd := root.NewCmdRoot(p)
    root.Execute(rootCmd, p)
}

CLI in Action¶

See how Go Tool Base builds and executes interactive lifecycle commands in real-time:

Further reading¶

The blog carries a curated route through this subject: Building a command-line tool in Go collects everything written about it, ordered so you can start at the beginning rather than newest-first.