Complete Guide to GoBrain CLI (gob): Managing Go Projects Without Global Tools

Have you ever switched between Go projects and found different versions of golangci-lint or goimports clashing in GOPATH/bin? This problem arises because Go tooling is generally installed globally, rather than being tied to a project. GoBrain CLI (gob) is here to solve that: a project-scoped CLI that keeps binaries, generator modules, and configuration inside the project's .gob/ folder, so each repository can choose its own tool and toolchain versions without interfering with one another.

This article will guide you through understanding what GoBrain solves, setting up the installation, running the init through verify flow with concrete examples, explaining the key concepts behind the scenes, and closing with troubleshooting and opportunities for further development.

1. Repository Overview and the Problem It Solves

GoBrain is a CLI for the Go ecosystem with a focus on project-scoped tooling. It keeps the build and tooling environment consistent within the project folder, with the following main features:

• Project initialization (gob init): creates gob.yaml, selects the template source (none/preset/url), fills in placeholders, sets up go.mod and toolchain, and prepares a managed .gitignore.

• Template generator (gob make): renders files from templates using built-in functions such as snake_case, pascal_case, and camel_case, with generator dependencies fetched via go get into a local cache.

• Command execution (gob exec): runs commands with an injected environment (.gob/bin, .gob/mod, GOTOOLCHAIN=auto).

• Project scripts (gob scripts run|list): runs a sequence of commands from gob.yaml with support for && chaining, cd, and pwd.

• Tool management (gob tools install|run|list): installs tools into .gob/bin and runs them with the injected PATH.

• Verification (gob verify): a check/test pipeline based on the steps in gob.yaml, supporting the fail_fast option.

• Project root detection: searches for gob.yaml from the current directory upward.

• Debug mode: the --debug flag or debug: true in gob.yaml for detailed logs.

The core problem is clear: without GoBrain, developers have to rely on global tools that are hard to reproduce. With GoBrain, all tooling becomes part of the repository and can be replicated on another machine simply by cloning the project and running gob tools install.

2. Prerequisites and Installation Preparation

2.1 Prerequisites

• Go >= 1.21.x — required for toolchain directive support.

• Git — for cloning templates via URL.

• Windows, Linux, or macOS.

2.2 Installing the Binary from a Release

Download the package for your platform from the Release Page:

• Windows: gob_windows_amd64.zip (Intel/AMD) or gob_windows_arm64.zip (ARM). Extract it, then add it to PATH, for example C:\gobrain\bin.

• macOS: gob_darwin_amd64.tar.gz (Intel) or gob_darwin_arm64.tar.gz (Apple Silicon). Extract it, then move the binary to /usr/local/bin or another PATH folder.

• Linux: gob_linux_amd64.tar.gz or gob_linux_arm64.tar.gz. Extract and move the binary to a PATH folder.

2.3 Installing via go install

bashCopygo install github.com/sch39/gobrain-cli/cmd/gob@latest

Make sure GOBIN or $GOPATH/bin is in your PATH, so that the gob command can be invoked from anywhere.

2.4 Local Build

If you want to modify GoBrain itself, build it from source:

bashCopy# macOS / Linux
go build -trimpath -o bin/gob ./cmd/gob

powershellCopy# Windows (PowerShell)
go build -trimpath -o bin\gob.exe .\cmd\gob

If the project provides a Makefile, simply run:

bashCopymake build

2.5 Verifying the Installation

bashCopygob --help

If the help appears, the installation was successful and you are ready to continue to the next step.

3. Step-by-Step Guide

3.1 Initializing a New Project: gob init

Create a project folder, then run:

bashCopymkdir my-app && cd my-app
gob init

During the process, you will be asked to specify:

1. source-type: none (no template), preset (use the embedded list), or url (git repo).

2. toolchain: GoBrain automatically detects the local Go version and offers a more recent stable version.

You can also provide a custom preset via the GOB_PRESET_FILE environment variable. If this variable is empty, GoBrain will still try to detect a preset file from the current working directory.

3.2 Understanding gob.yaml

The result of gob init is a gob.yaml file at the project root. Here is a complete example you can use as a starting point:

yamlCopyversion: "1.0.0"
debug: false
project:
  name: my-app
  module: github.com/user/my-app
  toolchain: 1.24.2
meta:
  template_origin: https://github.com/Sch39/gobrain-presets.git
  author: ""
  path: minimal
tools:
  - name: golangci-lint
    pkg: github.com/golangci/golangci-lint/cmd/golangci-lint@latest
scripts:
  build:
    - go build ./...
  test:
    - go test ./...
generators:
  requires:
    - github.com/Masterminds/sprig@latest
  commands:
    handler:
      desc: "Generate HTTP handler"
      args: ["name"]
      templates:
        - src: .template/handler.tmpl
          dest: internal/handlers/{{ pascal_case .Name }}.go
verify:
  fail_fast: true
  pipeline:
    - name: fmt
      run: go fmt ./...
    - name: vet
      run: go vet ./...
layout:
  dirs:
    - internal/handlers
    - internal/services

A brief explanation of each section:

• project: the name, module, and expected Go toolchain version. The toolchain will be aligned with go.mod.

• meta: the template origin, author, and template subdirectory path (if any).

• tools: the list of tools to be installed into .gob/bin.

• scripts: a map of name → sequence of shell commands; supports &&, cd, and pwd.

• generators: generator commands with templates to be rendered; requires will be go get-ed into the local .gob/mod cache.

• verify: a pipeline of verification steps; with fail_fast: true, the process stops at the first failure.

• layout: directories to be created during init from a template/preset.

3.3 Running a Generator: gob make

List the available commands, then run one of them:

bashCopygob make list
gob make handler User
gob make handler --name=User

The command above will render .template/handler.tmpl to internal/handlers/User.go. The built-in functions pascal_case, camel_case, and snake_case can be used inside the template, for example:

goCopypackage handlers

type {{ pascal_case .Name }}Handler struct {
    // dependencies
}

func (h *{{ pascal_case .Name }}Handler) Serve() error {
    return nil
}

3.4 Executing Commands with the Project ENV: gob exec

Any command run via gob exec will get the project environment:

bashCopygob exec go test ./...
gob exec --debug go build ./...

The injected ENV includes GOBIN=.gob/bin, GOMODCACHE=.gob/mod, the addition of .gob/bin to PATH, and GOTOOLCHAIN=auto.

3.5 Project Scripts: gob scripts

Reads scripts from gob.yaml and then runs them in sequence:

bashCopygob scripts list
gob scripts run build

Scripts support chaining and directory navigation, for example:

yamlCopyscripts:
  docs:
    - cd docs
    - pwd
    - go run ./cmd/gen && echo "done"

3.6 Local Tool Management: gob tools

Install all tools listed in gob.yaml and then run them with the injected PATH:

bashCopygob tools install
gob tools list
gob tools run golangci-lint --version

All binaries are stored in .gob/bin, so they won't interfere with global installations on other developers' machines.

3.7 Verification Pipeline: gob verify

Run all verification steps from gob.yaml:

bashCopygob verify

Because of fail_fast: true, the pipeline will stop at the first failing step, so feedback is faster.

3.8 Running the Entire Flow from Scratch

A summary of the end-to-end flow for a new project:

bashCopygob init                 # 1. create gob.yaml + structure
# edit gob.yaml if needed
gob tools install        # 2. install golangci-lint into .gob/bin
gob make handler User    # 3. render the handler template
gob exec go test ./...   # 4. test with the project ENV
gob scripts run build    # 5. build via script
gob verify               # 6. run the verification pipeline

4. Key Concepts Behind the Code

4.1 Project Root Detection

Like Git, GoBrain searches for gob.yaml starting from the current directory and then going upward. This means you can run gob from any subdirectory and the command will still be executed with the correct project root.

4.2 ENV Injection and Tool Isolation

The essence of isolation is this: every command is run with GOBIN, GOMODCACHE, and PATH pointed at .gob/. That way, go install or go get does not write to the global $GOPATH. Adding GOTOOLCHAIN=auto makes Go automatically download the toolchain requested by the project.

4.3 Synchronizing toolchain with go.mod

go.mod can contain a toolchain goX.Y.Z line. GoBrain validates that the toolchain version written in gob.yaml is not lower than the go directive in go.mod, keeping the build environment consistent across contributors.

4.4 The Template System and Built-in Functions

Templates are rendered using project data and helpers such as pascal_case, camel_case, and snake_case. Additional dependencies for generators (for example sprig) are declared in generators.requires and will be go get-ed into .gob/mod without leaving a trace in the project module.

4.5 Built-in and Custom Presets

Built-in presets are embedded from internal/presets/presets.yaml, which comes from the gobrain-presets repo. You can override them with a custom preset via GOB_PRESET_FILE, or provide a local preset file in the working directory.

5. Troubleshooting Tips

5.1 gob: command not found

Make sure the binary directory ($GOPATH/bin, GOBIN, or the folder where you extracted the release) is in your PATH. On Windows, close and reopen the terminal after changing PATH.

5.2 gob.yaml not found

You are outside the project structure. Move to the project root or run gob init first in the correct directory.

5.3 Tool not found during gob tools run

Run gob tools install first. If it still fails, check whether the pkg in tools is correct (for example github.com/golangci/golangci-lint/cmd/golangci-lint@latest). Enable debug with gob --debug tools run golangci-lint --version.

5.4 Toolchain mismatch

If an error appears saying the toolchain is lower than the go directive, align the version in gob.yaml with the one in go.mod, or let GOTOOLCHAIN=auto download the requested version.

5.5 Template fails due to an unknown function

Make sure the sprig or other helper dependency is included in generators.requires, then run gob make list to trigger fetching the dependency into .gob/mod.

5.6 General Debugging

Add --debug to the command or set debug: true in gob.yaml to see detailed logs, including the injected ENV and the commands executed.

6. Conclusion and Further Development

GoBrain CLI answers the problem of non-reproducible tooling in the Go ecosystem with a project-scoped approach: gob.yaml as the source of truth, .gob/ as the place for isolating binaries and modules, and a consistent command flow of init → make → exec → scripts → tools → verify. Once you have mastered it, switching between projects only requires gob tools install.

For further development, here are some interesting directions:

• Organization presets: create an internal preset repo with your team's standard structure, then distribute it via GOB_PRESET_FILE or a URL.

• Custom generators: add templates for DTOs, database migrations, or API clients to drastically reduce boilerplate.

• CI integration: run gob tools install && gob verify in the pipeline to ensure the build is validated with the project's tool versions.

• Contributing to the repository: since this project is open source, you can add new template helpers or improvements to project root detection.

By adopting GoBrain early in the project cycle, teams will experience higher reproducibility and much faster onboarding.