How to declare subcommands
This guide builds a cloudctl program with deploy, list, debug, and push subcommands. If you’re new to CONGA, Build a multi-command CLI builds a program with subcommands step by step.
Add a subcommand
Section titled “Add a subcommand”A subcommand is a field of its parent command’s struct, and its type is the container conga.Command[...]. The type in the brackets is the subcommand’s own struct, which declares the subcommand’s flags and arguments. A pointer to it implements conga.Runner:
type Runner interface { Run(ctx context.Context, session *Session) error}The field name in kebab case becomes the command name, so Deploy is deploy, and summary is its line in the parent’s help:
type CLI struct { Verbose conga.OptionalFlag[bool] `help:"Print each step" short:"v"`
Deploy conga.Command[DeployCmd] `summary:"Deploy a manifest"`}
type DeployCmd struct { Replicas conga.OptionalFlag[int] `default:"3" help:"Number of replicas" short:"r"` 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.Replicas.Get())
return nil}
func main() { app := conga.New[CLI]().Name("cloudctl")
if err := app.Run(); err != nil { app.Exit(err) }}$ cloudctl --helpUsage: cloudctl <command> [flags]
Commands: deploy Deploy a manifest
Flags: -v, --verbose Print each step --help Show help --version Show version$ cloudctl deploy web.yamldeploying web.yaml with 3 replicasCLI has no Run method, so cloudctl alone is a usage error:
$ cloudctlError:cloudctl: error: subcommand required for "cloudctl"Error
Usage: cloudctl <command> [flags]
Commands: deploy Deploy a manifest
Flags: -v, --verbose Print each step --help Show help --version Show versionTo run code when the user names no subcommand, implement Runner on the parent too. Its Run handles cloudctl alone, and cloudctl deploy web.yaml still runs deploy. Help then shows the subcommand as optional, as in cloudctl [<command>] [flags].
A command declares subcommands or positional arguments, not both. How to accept positional arguments covers positional arguments.
Group, alias, hide, and deprecate subcommands
Section titled “Group, alias, hide, and deprecate subcommands”Tags on the conga.Command[...] field control how a subcommand is reached and listed:
type CLI struct { Verbose conga.OptionalFlag[bool] `help:"Print each step" short:"v"`
Deploy conga.Command[DeployCmd] `summary:"Deploy a manifest"` List conga.Command[ListCmd] `aliases:"ls,ps" section:"Inspection" summary:"List running services"` Debug conga.Command[DebugCmd] `hidden:"true" summary:"Dump internal state"` Push conga.Command[DeployCmd] `deprecated:"use deploy" summary:"Deploy a manifest (old name)"`}section puts list under its own heading, hidden leaves debug out of help and completion, and deprecated labels push:
$ cloudctl --helpUsage: cloudctl <command> [flags]
Commands: deploy Deploy a manifest push Deploy a manifest (old name) [deprecated: use deploy]
Inspection: list List running services
Flags: -v, --verbose Print each step --help Show help --version Show versionaliases routes ls and ps to list, and cloudctl debug still runs. A deprecated command still runs, after a warning on stderr, and completion stops offering it:
$ cloudctl lsapi worker$ cloudctl push web.yamlWARNING: command 'cloudctl push' is deprecated: use deploydeploying web.yaml with 3 replicasShell completion offers the aliases, and --help lists each command once, by name. name:"..." replaces the kebab-case name. How to deprecate flags and commands also deprecates flags and whole applications.
Read root flags from a subcommand
Section titled “Read root flags from a subcommand”Flags on a parent apply to all its descendants, and the user can give them before or after the subcommand name. A subcommand reads them through session.Root[CLI](), which returns the root struct:
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { root := session.Root[CLI]() if root.Verbose.Get() { fmt.Fprintf(session.Stdout(), "running %s\n", session.Path()) }
fmt.Fprintf(session.Stdout(), "deploying %s with %d replicas\n", d.Manifest.Get(), d.Replicas.Get())
return nil}$ cloudctl -v deploy web.yamlrunning cloudctl deploydeploying web.yaml with 3 replicasThe subcommand’s help lists the parent’s flags under Global Flags:. A descendant can’t redeclare a parent’s flag name, alias, or short letter, but sibling subcommands can share names. session.Path() and the other accessors are in package conga.
Make one subcommand the default
Section titled “Make one subcommand the default”Tag a subcommand implicit:"true" to run it when the user names none:
type CLI struct { Verbose conga.OptionalFlag[bool] `help:"Print each step" short:"v"`
Deploy conga.Command[DeployCmd] `implicit:"true" summary:"Deploy a manifest"` // ...}cloudctl web.yaml now deploys, and so does cloudctl -r 5 web.yaml, since -r belongs to deploy. A subcommand named on the command line still wins:
$ cloudctl web.yamldeploying web.yaml with 3 replicas$ cloudctl listapi workerHelp marks the default and shows the command as optional:
$ cloudctl --helpUsage: cloudctl [<command>] [flags]
Commands: deploy Deploy a manifest (default) push Deploy a manifest (old name) [deprecated: use deploy]
Inspection: list List running services
Flags: -v, --verbose Print each step --help Show help --version Show versionAn operand that starts with - goes after --, so cloudctl -- -web.yaml deploys -web.yaml. Implicit subcommands gives the full routing rules, including a parent that also implements Run.
Know what users see
Section titled “Know what users see”| What happens | When | Result |
|---|---|---|
The user mistypes a subcommand (cloudctl lst) |
Run | unknown command: lst (did you mean "list"?), exit 2 |
The user runs a subcommand whose type has no Run method |
Run | struct ListCmd: schema error: runner not implemented: implement conga.Runner: Run(context.Context, *conga.Session) error, ErrSchema, exit 1 |
| A subcommand declares a flag its parent already declares | Startup | struct DeployCmd field Verbose: schema error: duplicate flag: --verbose (already declared by struct CLI field Verbose on an ancestor command), exit 1 |
Two subcommands of one parent are tagged implicit:"true" |
Startup | schema error: only one implicit command is allowed per command, exit 1 |
With deploy implicit, a flag only list declares comes before list (cloudctl --format json list) |
Run | unknown flag: --format, exit 2; the line routes to deploy |
With deploy implicit, the user runs cloudctl alone |
Run | missing required positional argument <manifest>, exit 2 |
A missing Run passes startup and fails only when a user invokes that subcommand. conga-lint reports it before you build, and How to lint schemas sets it up.
Where to go next
Section titled “Where to go next”- Subcommands (
Command[T]): every subcommand tag and the implicit routing rules. - About subcommands and hierarchy: why flags are reserved down a branch and how routing works.
- How to accept positional arguments: give a leaf command its arguments.
- How to read resolved values after Run: read resolved values after
Runreturns.