Advanced on Go Subcommand

Generator design principles

Mon, 01 Jan 0001 00:00:00 +0000

Generator design principles#

go-subcommand owns command execution and process policy. User functions supply actions, initialization and dependencies. Templates remain an optional escape hatch.

The preferred workflow is deliberately small: write a Go function, document it with a Go comment, generate, and run. A user should not need to understand the generated entry point, implement dispatch, manually register callbacks, or customize templates to get a usable CLI.

For example, the ordinary current workflow begins with:

Project generation configuration

Mon, 01 Jan 0001 00:00:00 +0000

gosubc generate --config gosubc.mdc reads optional generator settings. Both .mdc and .mdconf are supported candidates; neither filename is required. Generated applications do not read this file or depend on go-subcommand at runtime.

format-version: 1
cli-parser: gnu
recursive: true
emit-go-generate: false
paths:
- commands

Explicit flags override file values, including --recursive=false and --prov-version=. File settings override built-in defaults. Settings belong at the top, without a # Configuration heading. Generator settings are dir, man-dir, parser-name, cli-parser, paths, recursive, force, clean, replace-templates, project-provenance (alias project), timestamp, emit-go-generate, prov-version, prov-commit, and prov-date. Keys ignore case, hyphens and underscores. version is an alias for format-version, and one version declaration is required.

Functionless command metadata

Mon, 01 Jan 0001 00:00:00 +0000

Use a package or standalone comment to describe a root or child without registering an executable action:

// App is a command `app` -- Manage jobs.
// More application help.
package commands

// Generate is a subcommand `app generate` -- Generate jobs.
func Generate() { fmt.Println("generate") }

app prints described help on stderr and exits 0. app generate prints generate on stdout. app unknown returns an unknown-command error and status 1. app help, app usage, app --help, recursive help and version keep normal dispatch behaviour and do not acquire business providers.

Generated errors and process boundary

Mon, 01 Jan 0001 00:00:00 +0000

Generated cmd packages expose ErrUsage and *UsageError. These are generated application types; applications do not import go-subcommand at runtime.

var usage *cmd.UsageError
if errors.Is(err, cmd.ErrUsage) && errors.As(err, &usage) {
 fmt.Printf("%s: kind=%s flag=%s\n", usage.CommandPath, usage.Kind, usage.Flag)
}

The stable kinds are UsageUnknownCommand, UsageUnknownFlag, UsageMissingFlagValue, UsageInvalidValue, UsageInvalidArguments, and UsageMissingRequiredFlag. The error holds a canonical command path, a flag name without leading dashes where applicable, an optional underlying cause, and a presentation message. Classification never depends on matching that message. Causes remain available through errors.Is and errors.As. Application-provided usage errors and explicit exit errors retain their wrappers when returned from dispatch.

No-command policy

Mon, 01 Jan 0001 00:00:00 +0000

Use functionless root metadata to require a selected command:

// App is a command `app` -- Run jobs.
// No command: error
package commands

// Run is a subcommand `app run` -- Run a job.
func Run() { fmt.Println("run") }

Or place the same directive in native configuration:

format-version: 1
# Commands
```command: app
Description: Run jobs.
No command: error
```

Invocation	stdout	stderr	Status
`app`	empty	`Error: no command provided`	1
`app --`	empty	`Error: no command provided`	1
`app run`	`run`	empty	0
`app help`, `app usage`, `app --help`	empty	normal help	0
`app version`	normal version	empty	0
`app missing`	empty	usage and unknown-command error	1
`app -- run`	empty	usage and unknown-command error	1

The directive is an execution policy, independent of executable routing. When omitted, bare invocation preserves existing help and status 0. Only error is accepted. Empty/unknown values, duplicate declarations and policies on children are generation errors with source filename and line diagnostics. A real root action or any default route, including a help route or a child marked default, conflicts with the policy. Put it in root metadata rather than an action comment.