Skip to content

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.

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:

main.go
package main
import (
"context"
"fmt"
"github.com/conga-sh/conga"
)
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)
}
}
Terminal window
$ cloudctl --help
Usage:
cloudctl <command> [flags]
Commands:
deploy Deploy a manifest
Flags:
-v, --verbose Print each step
--help Show help
--version Show version
Terminal window
$ cloudctl deploy web.yaml
deploying web.yaml with 3 replicas

CLI has no Run method, so cloudctl alone is a usage error:

Terminal window
$ cloudctl
Error:cloudctl: error: subcommand required for "cloudctl"
Usage:
cloudctl <command> [flags]
Commands:
deploy Deploy a manifest
Flags:
-v, --verbose Print each step
--help Show help
--version Show version

To 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:

main.go
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:

Terminal window
$ cloudctl --help
Usage:
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 version

aliases 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:

Terminal window
$ cloudctl ls
api worker
Terminal window
$ cloudctl push web.yaml
WARNING: command 'cloudctl push' is deprecated: use deploy
deploying web.yaml with 3 replicas

Shell 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.

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:

main.go
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
}
Terminal window
$ cloudctl -v deploy web.yaml
running cloudctl deploy
deploying web.yaml with 3 replicas

The 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.

Tag a subcommand implicit:"true" to run it when the user names none:

main.go
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:

Terminal window
$ cloudctl web.yaml
deploying web.yaml with 3 replicas
Terminal window
$ cloudctl list
api worker

Help marks the default and shows the command as optional:

Terminal window
$ cloudctl --help
Usage:
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 version

An 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.

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.