Help output

Help is generated from the command tree and the tags. A command gets useful help from its help: tags and its one-line Help() alone, and richer help by overriding the other providers.

The help providers

BaseCommand supplies no-op defaults for Description, Examples, Args, and Flags, so you override only the ones you want. Help has no default, so every command implements it.

func (c *DeployCommand) Help() string { return "Deploy the app to an environment" }

func (c *DeployCommand) Description() string {
	return "Deploy builds the current revision and rolls it out to the target environment."
}

func (c *DeployCommand) Examples() [][]string {
	return [][]string{
		{"deploy --env prod", "rolling out to prod..."},
		{"deploy --env staging --region us"},
	}
}

The single-line help: tag on a field and these providers combine, so a flag's short help comes from its tag and its long help from Flags().

Registering the help command

The help renderer lives in the commands/help sub-package, so the core stays dependency-light. Register it with App.Help, which wires it under the reserved help name.

import "github.com/toaweme/cli/commands/help"

app.Help(help.NewHelpCommand(app.Config, app.Commands, app.OutputFormats, app.DefaultCommand))

Output formats

--help-format selects the help format. The built-ins are plain, plain-flags, pretty, md, json, and jsonschema. Register more with App.HelpOutputs, passing any OutputCodec. Each codec's name comes from its extension (.yml becomes yml) and becomes a valid --help-format value.

mytool deploy --help --help-format md    # markdown help for the deploy command
mytool deploy --help --help-format json  # machine-readable help

Resolved-value help

--help-values annotates each flag with the value it would resolve to, the merge of defaults, config, environment, and flags for the invoked command. Values marked secret:"true" are prefix-masked so they never leak into pasted help. Passing --help-values implies --help.

mytool deploy --help-values

Docs and completion sub-packages

Two more opt-in sub-packages build on the same renderers.

• commands/completion provides completion.NewCompletionCommand(appName) for bash, zsh, and fish completion scripts.
• commands/gendocs provides gendocs.NewGenDocsCommand(...) to render the app's own command tree to files in every help format, so generated docs never go stale.