How to customize help screens
CONGA builds every help screen from your command structs. This guide adds the text around them, marks a deprecated command, assigns short flags to the built-ins, groups flags and commands into sections, and controls the hints that follow each flag.
This guide builds a small cloudctl program with deploy and rollout subcommands. The built-ins example is a fuller program with custom help, usage, and version commands.
Describe the application
Section titled “Describe the application”Set the root command’s description, examples, and footer on the builder:
type CLI struct { Token conga.OptionalFlag[string] `help:"API access token"` Profile conga.OptionalFlag[string] `help:"Credentials profile"` Verbose conga.OptionalFlag[bool] `help:"Print each step" short:"v"`
Deploy conga.Command[DeployCmd] `summary:"Deploy workloads to clusters"` Rollout conga.Command[RolloutCmd] `summary:"Roll out a release"`}
func main() { app := conga.New[CLI](). Name("cloudctl"). Description("Manage cloud infrastructure and deployments."). Examples("cloudctl deploy --replicas 5\ncloudctl rollout v1.4"). HelpFooter("Documentation: https://example.com/docs")
if err := app.Run(); err != nil { app.Exit(err) }}The description opens the help screen, the examples follow the usage line, and the footer closes it:
$ cloudctl --helpManage cloud infrastructure and deployments.
Usage: cloudctl <command> [flags]
Examples: cloudctl deploy --replicas 5 cloudctl rollout v1.4
Commands: deploy Deploy workloads to clusters rollout Roll out a release
Flags: --token=STRING API access token --profile=STRING Credentials profile -v, --verbose Print each step --help Show help --version Show version
Documentation: https://example.com/docsThe footer appears on every help screen, including each subcommand’s. When the root declares feature toggles, the root screen also lists them under Features:.
Describe a subcommand
Section titled “Describe a subcommand”A subcommand’s summary tag is its line in the parent’s Commands: list. Its own screen opens with the same text:
$ cloudctl deploy --helpDeploy workloads to clusters
Usage: cloudctl deploy [flags]For a longer description and examples, implement Description() and Examples() on the subcommand struct. Unlike the summary tag, they’re Go code, so they can build the text when the program starts. Examples() can check runtime.GOOS and show Windows paths on Windows, for instance. CONGA calls them once, before it reads flags, so the text can’t use the command’s own flag values:
type DeployCmd struct { Replicas conga.OptionalFlag[int] `default:"3" help:"Number of replicas"` Port conga.OptionalFlag[int] `default:"8080" help:"Listen port" range:"1..65535"` Region conga.OptionalFlag[string] `enum:"us-east-1,us-west-1,us-west-2,eu-west-1,eu-central-1" help:"Target region"`}
func (d *DeployCmd) Description() string { return "Deploy application workloads to target clusters.\n\nEach replica runs on its own node."}
func (d *DeployCmd) Examples() string { return "cloudctl deploy --replicas 5\ncloudctl deploy --region eu-west-1"}The description replaces the summary on the subcommand’s screen, and the parent keeps showing the summary. Line breaks in the description are kept:
$ cloudctl deploy --helpDeploy application workloads to target clusters.
Each replica runs on its own node.
Usage: cloudctl deploy [flags]
Examples: cloudctl deploy --replicas 5 cloudctl deploy --region eu-west-1
Flags: --replicas=3 Number of replicas --port=8080 Listen port [1..65535] --region=STRING Target region [enum: us-east-1, us-west-1, us-west-2, eu-west-1, eu-central-1] --help Show help
Global Flags: --token=STRING API access token --profile=STRING Credentials profile -v, --verbose Print each step
Documentation: https://example.com/docsMark a subcommand deprecated
Section titled “Mark a subcommand deprecated”Add a deprecated tag with the reason, and the parent’s list marks the command. Here a push command gives way to rollout:
type CLI struct { // ... Rollout conga.Command[RolloutCmd] `summary:"Roll out a release"` Push conga.Command[PushCmd] `deprecated:"use rollout" summary:"Push a release"`}Commands: deploy Deploy workloads to clusters rollout Roll out a release push Push a release [deprecated: use rollout]How to deprecate flags and commands shows the warnings users see, and deprecates flags and whole applications.
Give help and version short flags
Section titled “Give help and version short flags”--help and --version are long-only, so they leave every short rune to your own flags. To give them short flags, call HelpShortFlag and VersionShortFlag:
app := conga.New[CLI](). // ... HelpShortFlag('h'). VersionShortFlag('V')-h and -V then work like the long flags, and help shows them:
Flags: --token=STRING API access token --profile=STRING Credentials profile -v, --verbose Print each step -h, --help Show help -V, --version Show version-h appears on every command and -V on the root, as --version does. A rune that one of your flags already uses fails at startup (see Know what users see). When you disable a built-in with app.DisableHelpFlag() or app.DisableVersionFlag(), its rune stays free for your own flags.
Group flags and commands into sections
Section titled “Group flags and commands into sections”Give flags or commands a section tag. Each section gets its own heading, with the tag’s text as written:
type CLI struct { Token conga.OptionalFlag[string] `help:"API access token" section:"Authentication Flags"` Profile conga.OptionalFlag[string] `help:"Credentials profile" section:"Authentication Flags"` Verbose conga.OptionalFlag[bool] `help:"Print each step" short:"v"`
Deploy conga.Command[DeployCmd] `section:"Workload Commands" summary:"Deploy workloads to clusters"` Rollout conga.Command[RolloutCmd] `section:"Workload Commands" summary:"Roll out a release"` Push conga.Command[PushCmd] `deprecated:"use rollout" section:"Workload Commands" summary:"Push a release"`}Untagged flags stay under Flags:, and each section follows in the order its first field is declared:
$ cloudctl --helpManage cloud infrastructure and deployments.
Usage: cloudctl <command> [flags]
Examples: cloudctl deploy --replicas 5 cloudctl rollout v1.4
Workload Commands: deploy Deploy workloads to clusters rollout Roll out a release push Push a release [deprecated: use rollout]
Flags: -v, --verbose Print each step -h, --help Show help -V, --version Show version
Authentication Flags: --token=STRING API access token --profile=STRING Credentials profile
Documentation: https://example.com/docsWrite constraints into the help text
Section titled “Write constraints into the help text”CONGA appends each flag’s constraints to its help. --port above shows 8080 in its value slot and [1..65535] after the text. To phrase them yourself, put help variables in the help tag:
type DeployCmd struct { Port conga.OptionalFlag[int] `default:"8080" help:"Listen port (default {{default}}, allowed {{range}})" range:"1..65535"` // ...}Each variable you use replaces the matching hint, and the rest stay:
Flags: --replicas=3 Number of replicas --port=INT Listen port (default 8080, allowed 1..65535) --region=STRING Target region [enum: us-east-1, us-west-1, us-west-2, eu-west-1, eu-central-1] -h, --help Show help| Variable | Replaces |
|---|---|
{{default}} |
The [default: …] hint, and the default in the value slot (--port=8080 becomes --port=INT) |
{{range}} |
The [min..max] hint |
{{enum}} |
The [enum: …] hint |
{{len}}, {{items}} |
The [len: …] and [items: …] hints |
{{env}} |
The [env: …] hint |
A variable needs the matching tag, so {{range}} on a field without range fails at startup. Write {{{{ for a literal {{. Help variables lists where each variable is available.
Hide a long list of allowed values
Section titled “Hide a long list of allowed values”A long enum crowds the screen, as --region does above. Add enumhint:"-" to leave the list out of help:
type DeployCmd struct { Region conga.OptionalFlag[string] `enum:"us-east-1,us-west-1,us-west-2,eu-west-1,eu-central-1" enumhint:"-" help:"Target region"` // ...}Flags: --replicas=3 Number of replicas --port=INT Listen port (default 8080, allowed 1..65535) --region=STRING Target region -h, --help Show helpThe flag still accepts only the listed values, and shell completion still offers them:
$ cloudctl deploy --region marsError:cloudctl: error: invalid value "mars" (must be one of: us-east-1, us-west-1, us-west-2, eu-west-1, eu-central-1) for flag --regionErrorenumhint accepts only -. Feature toggles hide the list for you, because the Features: section already shows every toggle.
Check help at a narrow width
Section titled “Check help at a narrow width”Help wraps to the terminal’s width. Set COLUMNS to see a screen as a narrow terminal shows it:
$ COLUMNS=60 cloudctl deploy --helpDeploy application workloads to target clusters.
Each replica runs on its own node.
Usage: cloudctl deploy [flags]
Examples: cloudctl deploy --replicas 5 cloudctl deploy --region eu-west-1
Flags: --replicas=3 Number of replicas --port=INT Listen port (default 8080, allowed 1..65535) --region=STRING Target region -h, --help Show help
Global Flags: -v, --verbose Print each step
Authentication Flags: --token=STRING API access token --profile=STRING Credentials profile
Documentation: https://example.com/docsLong help text folds at spaces, under the help column. Wrap width gives the full rules, including the width used when output is piped.
Know what users see
Section titled “Know what users see”Each of these mistakes stops the program at startup, before it reads any input, with exit status 1:
| Mistake | Message |
|---|---|
A short flag uses the rune given to HelpShortFlag or VersionShortFlag |
built-in --help short flag -h collides with --verbose; assign a different rune to one of them |
A help variable CONGA doesn’t define, such as {{min}} |
tag "help" references unknown variable {{min}}; supported variables are … |
| A help variable without its matching tag | tag "help" references {{range}}, but the field provides no value for that variable |
enumhint:"-" on a field without enum |
tag "enumhint" suppresses the enum hint, but the field declares no enum values |
Each full message names the struct and field:
Error:cloudctl: error: struct CLI field Verbose: schema error: duplicate flag: built-in --help short flag -h collides with --verbose; assign a different rune to one of themErrorError:cloudctl: error: struct DeployCmd field Port: schema error: invalid struct tag: tag "help" references unknown variable {{min}}; supported variables are {{range}}, {{len}}, {{items}}, {{enum}}, {{default}}, {{env}}conga-lint reports the same mistakes before you build, and How to lint schemas sets it up.
Print help from your own command
Section titled “Print help from your own command”session.Help() returns the active command’s help screen, and session.Usage() its usage line, as strings. Neither writes anything, so a command can page, reformat, or route them. This guide command prints its own usage string, quoted to show its exact content:
type GuideCmd struct{}
func (g *GuideCmd) Run(_ context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "%q\n", session.Usage())
return nil}$ cloudctl guide"Usage:\n cloudctl guide [flags]"The usage string includes its Usage: heading, as on the help screen.
Where to go next
Section titled “Where to go next”- Built-ins and deprecation: every help section, the usage line, and wrapping rules.
- Help variables: the full variable catalog.
- How to gate features: the
Features:section. - How to deprecate flags and commands: the deprecation markers and warnings.
- Built-ins example: custom help, usage, and version commands.