Code-Memo

Project layout and CLI structure

There isn’t a single “official” Go project layout, but there are strong conventions that help DevOps tooling stay maintainable.

Minimal layout (small tool)

mytool/
  go.mod
  main.go
  internal/
    ...

Common layout (service or multi-command CLI)

myrepo/
  go.mod
  cmd/
    mytool/        # main package for CLI/service
      main.go
    mytool-agent/  # optional second binary
      main.go
  internal/        # private packages used by cmd/*
    config/
    run/
    version/
  pkg/             # optional: public packages intended for reuse
  scripts/
  Makefile

cmd/ convention

• Each subdirectory under cmd/ typically builds one binary.
• Keep main.go thin: parse flags, load config, call internal packages.

internal/ convention

• Code under internal/ can only be imported by sibling directories “inside” the parent module tree.
• Great for keeping app-only packages private while still well-structured.

CLI frameworks

• Stdlib: flag is enough for many internal tools.
• For larger CLIs: spf13/cobra is common (subcommands, completion, docs).

Version information

Expose a --version flag and inject version at build time (see builds/release pages).