You own a Go CLI other teams call from CI. How do you decide what becomes a subcommand, a flag, or a positional?

## The command line is an API without a compiler A Go CLI's argument surface has every property of a published interface and none of the protections. When you rename a method, every caller fails to build. When you rename a flag, a shell script fails at 3am with a message about an unknown flag — or worse, keeps running and does something else. There is no deprecation period baked into `flag`, no alias mechanism, no warning channel. The design question is therefore not "what reads best today" but "what can I add later without breaking anyone". ## What is safe to change, and what is not Ranked from harmless to dangerous: 1. **Adding a new subcommand.** Safe. Nothing that exists changes meaning. 2. **Adding a new flag with a default that preserves current behaviour.** Safe, and it is the mechanism you should design toward. 3. **Adding output or extending help text.** Usually safe, unless somebody parses your output — which is why machine-readable output belongs behind an explicit flag. 4. **Renaming a flag or a subcommand.** Breaking, but loudly: unknown flags are reported. 5. **Changing an existing flag's default.** The most dangerous change available to you, because every invocation already in existence keeps working and quietly does something new. If a default must change, do it by adding a new flag or a new subcommand, not by editing the old one. 6. **Changing the meaning or order of positional arguments.** Also silent, and worse, because there is no name to key on. ## Choosing the form **Subcommand** when the action is genuinely a different verb with a different set of options. A `*flag.FlagSet` per verb is the concrete payoff: each command's flags and help are scoped to it, two commands can use the same short name for different things, and adding a seventh command touches nothing the other six do. The alternative — one mode flag plus a pile of options that are only meaningful in some modes — has no way to express that scoping, and its help text degrades into a list of caveats. **Flag** for anything optional, anything with a sensible default, and anything you can imagine wanting to vary. Flags are named, so they are self-documenting at the call site and order-independent among themselves. The cost of one extra flag is nearly zero; the cost of having made something positional that should have been a flag is permanent. **Positional** for the single obvious operand — the file, the path, the identifier the command is *about* — and for variadic lists of the same kind of thing. Two positionals of different meaning is a smell: `tool copy src dst` is defensible because the order is a universal convention, `tool report 30 prod` is not. ## Mechanical constraints to publish on day one Go's parser imposes rules that become part of your contract whether or not you write them down: - **Flags must come before operands.** Parsing stops at the first non-flag token, so `tool sync out.txt -v` silently ignores `-v`. Publish the synopsis as `tool [flags] <operands>`. - **Boolean flags need the equals form** to be turned off: `-q=false`, never `-q false`. - **One dash and two dashes are identical**, and there is no bundling. If people expect a short alias, register it explicitly. - **`--` ends flag parsing.** If your tool will ever forward arguments to something else, define that boundary in the first release; adding it later changes the meaning of commands already written. ## The alias you do have When a name really must change, `flag` gives you exactly one affordance: register both names bound to the same variable using the `Var` forms, with the same default. ```go var out string fs.StringVar(&out, "output", "", "write results here") fs.StringVar(&out, "o", "", "short form of -output") ``` Both write into `out`, so whichever appears later on the command line wins. Give them the same default or the second registration will overwrite the first at definition time. This is how you keep an old spelling alive while the new one becomes the documented form — and you keep it alive for a long time, because you cannot see who is still using it. ## Who actually decides The maintainer proposes the surface; the teams whose pipelines invoke the tool can overrule it, and they should be able to, because they carry the migration cost of every rename. Practically that means: circulate flag names before the first release rather than after, treat any change in category 4-6 above as requiring their agreement, and keep a `version` subcommand from day one so a script can assert what it is talking to. The thing you are optimising is not elegance; it is the number of shell scripts that never have to be edited again.