How to deprecate flags and commands
A deprecated tag marks a flag or a subcommand for removal. The old name keeps working, help marks it with the reason, every run that uses it prints a warning to stderr, and shell completion stops offering it. This guide renames a flag and a subcommand of a cloudctl program, then deprecates the whole application.
The program starts with one deploy subcommand, whose --count flag sets the number of replicas:
type CLI struct { Deploy conga.Command[DeployCmd] `summary:"Deploy a manifest"`}
type DeployCmd struct { Count conga.OptionalFlag[int] `default:"3" help:"Number of replicas"` Manifest conga.RequiredArg[string] `help:"Manifest file"`}
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "deploying %s with %d replicas\n", d.Manifest.Get(), d.Count.Get())
return nil}
func main() { app := conga.New[CLI]().Name("cloudctl").EnvPrefix("CLOUDCTL")
if err := app.Run(); err != nil { app.Exit(err) }}$ cloudctl deploy --count 2 app.yamldeploying app.yaml with 2 replicasRename a flag
Section titled “Rename a flag”Add the new flag, and give the old one a deprecated tag with the reason. Move the default to the new flag, so the old one holds a value only when a user sets it:
type DeployCmd struct { Replicas conga.OptionalFlag[int] `default:"3" help:"Number of replicas"` Count conga.OptionalFlag[int] `deprecated:"use --replicas" help:"Number of replicas"` Manifest conga.RequiredArg[string] `help:"Manifest file"`}The two flags are separate fields, and a value given to --count stays in Count. Read the old flag in Run when the user set it. Changed reports whether a value came from the command line, the environment, or a config file rather than from a default:
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { replicas := d.Replicas.Get() if d.Count.Changed() { replicas = d.Count.Get() }
fmt.Fprintf(session.Stdout(), "deploying %s with %d replicas\n", d.Manifest.Get(), replicas)
return nil}Old invocations still work, after a warning on stderr:
$ cloudctl deploy --count 2 app.yamlWARNING: flag '--count' is deprecated: use --replicasdeploying app.yaml with 2 replicasHelp marks the old flag with the reason:
$ cloudctl deploy --helpDeploy a manifest
Usage: cloudctl deploy [flags] <manifest>
Arguments: <manifest> Manifest file
Flags: --replicas=3 Number of replicas [env: CLOUDCTL_REPLICAS] --count=INT Number of replicas [env: CLOUDCTL_COUNT] [deprecated: use --replicas] --help Show helpShell completion offers --replicas and leaves out --count, even when the user has typed --co.
The warning names the source that set the old flag. A user who exports CLOUDCTL_COUNT sees the variable:
$ CLOUDCTL_COUNT=2 cloudctl deploy app.yamlWARNING: environment variable 'CLOUDCTL_COUNT' is deprecated: use --replicasdeploying app.yaml with 2 replicasA config file that sets count under deploy: gives WARNING: config key 'count' is deprecated: use --replicas. The key appears without its section.
Reject the old and new flags together
Section titled “Reject the old and new flags together”As written, --replicas 4 --count 2 deploys 2 replicas, because Run prefers the old flag whenever it is set. To make that an error, put both flags in one xor group:
type DeployCmd struct { Replicas conga.OptionalFlag[int] `default:"3" help:"Number of replicas" xor:"replicas"` Count conga.OptionalFlag[int] `deprecated:"use --replicas" help:"Number of replicas" xor:"replicas"` Manifest conga.RequiredArg[string] `help:"Manifest file"`}$ cloudctl deploy --replicas 4 --count 2 app.yamlError:cloudctl: error: flags --replicas and --count are mutually exclusiveError
Usage: cloudctl deploy [flags] <manifest>
Run 'cloudctl deploy --help' for more information.The default on --replicas doesn’t count as given, so --count alone still works. A value from the environment or a config file does count. A user who exports CLOUDCTL_REPLICAS=4 and runs an old script that passes --count 2 gets the same error.
Rename a subcommand
Section titled “Rename a subcommand”Keep the old subcommand as a second field of the same type, so both names run the same code, and give it a deprecated tag. Here push was the old name for deploy:
type CLI struct { Deploy conga.Command[DeployCmd] `summary:"Deploy a manifest"` Push conga.Command[DeployCmd] `deprecated:"use deploy" summary:"Deploy a manifest (old name)"`}The parent’s help marks the old name:
$ cloudctl --helpUsage: cloudctl <command>
Commands: deploy Deploy a manifest push Deploy a manifest (old name) [deprecated: use deploy]
Flags: --help Show help --version Show versionThe old command’s own help screen opens with the warning:
$ cloudctl push --helpWARNING: command 'cloudctl push' is deprecated: use deploy
Deploy a manifest (old name)
Usage: cloudctl push [flags] <manifest>
Arguments: <manifest> Manifest file
Flags: --replicas=3 Number of replicas [env: CLOUDCTL_REPLICAS] --count=INT Number of replicas [env: CLOUDCTL_COUNT] [deprecated: use --replicas] --help Show helpThe command still runs, and prints one warning for each deprecated name it uses:
$ cloudctl push --count 2 app.yamlWARNING: command 'cloudctl push' is deprecated: use deployWARNING: flag '--count' is deprecated: use --replicasdeploying app.yaml with 2 replicasShell completion offers deploy and leaves out push. How to declare subcommands compares deprecated with hidden, which leaves a command out of help as well.
Deprecate the whole application
Section titled “Deprecate the whole application”Call Deprecated on the app with the reason. A Deprecated method on the root struct fails at startup:
func main() { app := conga.New[CLI]().Name("cloudctl").EnvPrefix("CLOUDCTL").Deprecated("install cloudctl2")
if err := app.Run(); err != nil { app.Exit(err) }}Every command prints the warning to stderr first:
$ cloudctl deploy app.yamlWARNING: cloudctl is deprecated: install cloudctl2deploying app.yaml with 3 replicas--help prints it to stdout, above the help screen:
$ cloudctl --helpWARNING: cloudctl is deprecated: install cloudctl2
Usage: cloudctl <command>
Commands: deploy Deploy a manifest push Deploy a manifest (old name) [deprecated: use deploy]
Flags: --help Show help --version Show version--version prints the version line alone.
Rename a required flag
Section titled “Rename a required flag”Suppose --count had been a conga.RequiredFlag[...]. A deprecated tag on it fails at startup, because users can’t stop passing a flag the program requires:
$ cloudctl deploy app.yamlError:cloudctl: error: struct DeployCmd field Count: schema error: invalid struct tag: tag "deprecated" cannot be used on required flags (make the flag optional before deprecating it so callers can migrate without error)ErrorMake both flags optional and put them in one oneof group, so the user must give exactly one of them. A oneof member can’t have a default:
type DeployCmd struct { Replicas conga.OptionalFlag[int] `help:"Number of replicas" oneof:"replicas"` Count conga.OptionalFlag[int] `deprecated:"use --replicas" help:"Number of replicas" oneof:"replicas"` Manifest conga.RequiredArg[string] `help:"Manifest file"`}Leaving out both is a usage error. The error and the usage line name only --replicas, and help still lists --count, marked deprecated:
$ cloudctl deploy app.yamlError:cloudctl: error: missing required flag: --replicasError
Usage: cloudctl deploy --replicas=INT <manifest>
Run 'cloudctl deploy --help' for more information.--count 2 alone deploys 2 replicas after the warning, as before.
A deprecated tag on a positional argument fails at startup with tag "deprecated" is invalid on positional argument.
Know what users see
Section titled “Know what users see”Here the app also registered a YAML config decoder, so cloudctl reads ~/.config/cloudctl/config.yaml.
| What the user does | Result |
|---|---|
Gives --count 2 |
WARNING: flag '--count' is deprecated: use --replicas on stderr, then deploys 2 replicas |
Sets CLOUDCTL_COUNT=2 |
WARNING: environment variable 'CLOUDCTL_COUNT' is deprecated: use --replicas, then deploys 2 replicas |
Sets count: 2 under deploy: in the config file |
WARNING: config key 'count' is deprecated: use --replicas, then deploys 2 replicas |
Gives --replicas 4 --count 2 |
flags --replicas and --count are mutually exclusive, then usage, exit 2 |
Sets CLOUDCTL_REPLICAS=4 and gives --count 2 |
The same error, exit 2 |
| Gives neither flag | Deploys 3 replicas, no warning |
Runs push |
WARNING: command 'cloudctl push' is deprecated: use deploy on stderr, then runs |
Runs push --help |
The warning above the help screen, on stdout |
| Runs any command of a deprecated app | WARNING: cloudctl is deprecated: install cloudctl2 on stderr, then runs |
Runs --help on a deprecated app |
The warning above the help screen, on stdout |
Runs --version on a deprecated app |
The version line, no warning |
Where to go next
Section titled “Where to go next”- Flags: the
deprecatedandxortags with every other flag tag. - Subcommands: the
deprecatedtag on a subcommand field. - Built-ins and deprecation: where the deprecation banner sits on a help screen.
- Example 22 and example 23: runnable programs that deprecate an app, a flag, and a subcommand.