What does it cost when a Go CLI's subcommands register themselves into a package-level map from init?

## The pattern A CLI grows subcommands. Someone notices that if each subcommand package writes itself into a shared map from an `init` function, the top-level package never has to know their names — it just needs to import them. The result is a `main` file whose only content is a block of blank imports, and a `cli` package holding `var registry = map[string]*Command{}` plus a `Register` function that everyone calls at startup. It is genuinely attractive: adding a command touches one new package and one import line, and no central file grows forever. It is also the pattern reviewers most often push back on, for reasons worth being able to state precisely. ## 1. The import graph is now the specification What the binary can do is decided by which packages happen to be linked in. Nothing in the source says "this tool has fourteen commands"; you learn it by reading an import block whose entries have no visible use, and whose identifiers do not appear anywhere else in the file. Delete one by accident and you have shipped a build that is missing a feature with no compile error and no test failure — the registry simply has one fewer entry. The same property means you cannot build a variant of the tool with a subset of commands without editing that import block, and a reader tracing "where does this command come from?" has to search for a string literal rather than follow a reference. ## 2. Registration cannot report an error `init` returns nothing. If two packages claim the same command name, the only things `Register` can do are overwrite silently, or panic. Overwriting is worse: whichever package initialized last wins, and initialization order between independent packages is not something you should be encoding intent in. Panicking is honest but happens during startup, before flags are parsed, before logging is set up, and before your usage text can be printed — the user sees a runtime stack trace. The standard library does exactly this in `database/sql`: `sql.Register` panics on a duplicate driver name. That is a deliberate trade for a case where the driver package and the consumer must not import each other and the plugin set is genuinely open-ended. It is a poor trade for a fixed set of subcommands inside one binary you own. ## 3. Ordering is unspecified beyond dependencies Initialization is ordered by dependency, and independent packages have no ordering relationship you should rely on. A map absorbs that fine. Anything order-sensitive — help output, a first-match dispatch chain, a list of middleware — does not, and will produce a stable-looking result until someone adds an import or renames a package. If ordered output matters, sort explicitly rather than depending on registration order. ## 4. Tests inherit one process-wide registry All tests of a package compile into one binary and run in one process, so there is one registry for the whole test run, already fully populated before the first test function starts. That produces three separate problems. A test cannot construct an empty registry to assert against — it always sees every command the test binary happened to link. A test that registers a fake command leaves it behind for every later test, so behaviour depends on the order tests run in. And a test cannot easily assert the error path for a duplicate name, because the only way to trigger it is to panic the test binary. ## 5. Nothing can be dropped Because `init` has side effects, an unused subcommand is still linked and still initialized. If a command's package dials a service or reads a file to prepare itself, every binary and every test that imports it pays that cost even when the command is never invoked. ## The shape that keeps the good part The useful property is decoupling: the top-level package should not have to know each subcommand's internals. You keep that without a global. Make the registry a type with methods instead of a package-level map, so any number of them can exist. Have each subcommand package export a constructor — `func New() *Command` — or a `Register(r *Registry) error` that takes the registry as a parameter. Then assembling the tool is ordinary code: a short function that adds each command in a visible order, returning an error on a duplicate instead of panicking. What you gain: the command list is readable, the duplicate check returns an error you can print properly, an ordered listing is deterministic, and every test builds its own registry with exactly the commands it cares about and leaves nothing behind. What you give up: one line per command in one file. That is the whole cost, and it is the reason this rewrite is usually an easy sell in review.