Skip to content

Go Tool Base (GTB)

The Intelligent Application Lifecycle Framework for Go.

Modern CLI tools and DevOps workflows demand more than basic flag parsing. GTB works as a "batteries-included" micro-framework, providing a standardized foundation for building mission-critical tools with built-in agentic workflows, embedded documentation, and zero-config service management.

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).

Overview

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

  • 🤖 AI Agentic Workflows: Integrated support for Claude, Gemini, and OpenAI to power autonomous ReAct-style loops against your code.
  • 🔌 Model Context Protocol (MCP): Expose your CLI commands automatically as MCP tools for external AI agents.
  • 📕 Integrated TUI Docs: An interactive documentation browser with AI Q&A (docs ask) embedded directly in your tool.
  • 📦 Auto Updates & Lifecycle: Zero-config version syncing and self-update capabilities via GitHub/GitLab releases.
  • 🚀 Scaffold & Generate: Get a CLI tool running in seconds with the skeleton generator.
  • ⚙️ Configuration Management: Seamless config merging from embedded assets, YAML, and Env vars.
  • 📝 Structured Logging & Errors: Unified logger abstraction (with charmbracelet as the default backend) with stack-traced, context-aware error handling.

Built-in Commands

Every CLI tool built with GTB automatically includes the following commands with a cli tool:

  • init - Initialize tool configuration and setup
  • version - Display version information and check for updates
  • update - Update the tool to the latest version
  • 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-tool-base/pkg/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(l, p.Tool.Help)

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

Architecture

Learn about the high-level system design, command registry, and execution flow in our Concepts section.

Getting Started

Ready to build your own CLI tool? We provide two clear paths:

  • The Fast Track: Use the Generator CLI to scaffold a project in seconds.
  • Manual Integration: Follow the Step-by-Step Guide to integrate the library manually.

Check out our How-to Guides for more practical instructions.