Build a multi-command CLI
In this tutorial, we will build cloudctl, a command-line tool that deploys services and reports their status. It has two subcommands, deploy and status, and a --region flag that both of them read. If you haven’t built a CONGA program before, start with the quickstart.
The command we will build
Section titled “The command we will build”The finished cloudctl deploys a service to a region:
$ ./cloudctl --region eu-west-1 deploy web --image nginx:1.27deploying web (nginx:1.27) to eu-west-1 with 2 replicasSet up the project
Section titled “Set up the project”We need Go 1.27 or later.
-
Create a directory for the project and move into it:
Terminal window mkdir cloudctl && cd cloudctl -
Initialize a Go module:
Terminal window go mod init cloudctl -
Add CONGA to the module:
Terminal window go get github.com/conga-sh/conga@latest
Write a command with one subcommand
Section titled “Write a command with one subcommand”Create main.go:
package main
import ( "context" "fmt"
"github.com/conga-sh/conga")
type CLI struct {A container: it makes Deploy a subcommand, defined by the DeployCmd struct. Deploy conga.Command[DeployCmd] `summary:"Deploy a service"`}
type DeployCmd struct {A positional argument the user must give. Service conga.RequiredArg[string] `help:"Service to deploy"`}
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { fmt.Printf("deploying %s\n", d.Service.Get())
return nil}
func main() { app := conga.New[CLI](). Name("cloudctl"). Description("Manage services in the cloud"). Version("0.1.0")
if err := app.Run(); err != nil { app.Exit(err) }}CLI is the command the program starts from, and DeployCmd is a command of its own, with its own fields and its own Run method. CONGA names the subcommand after the field, so Deploy becomes deploy.
Build the program, and deploy a service:
go build$ ./cloudctl deploy webdeploying webNotice that web went to the Service field. A positional argument takes a word from the command line, with no flag name in front of it.
Now run cloudctl on its own:
$ ./cloudctlError:cloudctl: error: subcommand required for "cloudctl"Error
Manage services in the cloud
Usage: cloudctl <command>
Commands: deploy Deploy a service
Flags: --help Show help --version Show versionCLI has no Run method, so cloudctl needs a subcommand to do anything. CONGA lists the subcommands it has, with each one’s summary tag, and exits with status 2.
Require a flag
Section titled “Require a flag”Every deployment needs an image. Replace DeployCmd and its Run method:
type DeployCmd struct { Service conga.RequiredArg[string] `help:"Service to deploy"`A flag the user must give. Image conga.RequiredFlag[string] `help:"Container image to run"` Replicas conga.OptionalFlag[int] `default:"2" help:"Number of copies to run"`}
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { fmt.Printf("deploying %s (%s) with %d replicas\n", d.Service.Get(), d.Image.Get(), d.Replicas.Get())
return nil}Build the program again, and leave out the image:
go build$ ./cloudctl deploy webError:cloudctl: error: missing required flag: --imageError
Usage: cloudctl deploy --image=STRING [flags] <service>
Run 'cloudctl deploy --help' for more information.Notice that the usage line shows --image=STRING outside [flags], because a user can’t leave it out. Now give it:
$ ./cloudctl deploy web --image nginx:1.27deploying web (nginx:1.27) with 2 replicas--replicas took its value from its default tag. A required flag can’t have a default tag, since the user must give a value.
Add a flag every subcommand shares
Section titled “Add a flag every subcommand shares”The region applies to everything cloudctl does, so its flag goes on CLI. Add Region to CLI, and read it in DeployCmd’s Run method:
type CLI struct { Region conga.OptionalFlag[string] `default:"us-east-1" help:"Region to work in" short:"r"` Deploy conga.Command[DeployCmd] `summary:"Deploy a service"`}
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error {Returns the CLI struct, with its flags filled in. root := session.Root[CLI]() fmt.Printf("deploying %s (%s) to %s with %d replicas\n", d.Service.Get(), d.Image.Get(), root.Region.Get(), d.Replicas.Get())
return nil}DeployCmd has no Region field of its own. session.Root[CLI]() gives it the struct the program started from, so it reads --region there.
Build the program, and give the region before the subcommand:
go build$ ./cloudctl --region eu-west-1 deploy web --image nginx:1.27deploying web (nginx:1.27) to eu-west-1 with 2 replicasNow give it after the subcommand, with its short name:
$ ./cloudctl deploy web --image nginx:1.27 -r eu-west-1deploying web (nginx:1.27) to eu-west-1 with 2 replicasNotice that both runs give the same result. A flag on CLI belongs to every subcommand below it, so the user can put it on either side of the subcommand name.
Add a second subcommand
Section titled “Add a second subcommand”Add a Status field to CLI, and a StatusCmd struct with its own Run method:
type CLI struct { Region conga.OptionalFlag[string] `default:"us-east-1" help:"Region to work in" short:"r"` Deploy conga.Command[DeployCmd] `summary:"Deploy a service"` Status conga.Command[StatusCmd] `summary:"Show service status"`}
type StatusCmd struct{}
func (s *StatusCmd) Run(ctx context.Context, session *conga.Session) error { root := session.Root[CLI]() fmt.Printf("all services healthy in %s\n", root.Region.Get())
return nil}StatusCmd has no fields. status takes no arguments or flags of its own, and reads the region from CLI as deploy does.
Build the program, and ask for the status of a region:
go build$ ./cloudctl -r eu-west-1 statusall services healthy in eu-west-1The help screen now lists both subcommands:
$ ./cloudctl --helpManage services in the cloud
Usage: cloudctl <command> [flags]
Commands: deploy Deploy a service status Show service status
Flags: -r, --region="us-east-1" Region to work in --help Show help --version Show versionLet’s misspell one:
$ ./cloudctl statsError:cloudctl: error: unknown command: stats (did you mean "status"?)Error
Usage: cloudctl <command> [flags]
Run 'cloudctl --help' for more information.As with a misspelled flag, CONGA suggests the closest name and exits with status 2.
Read a subcommand’s help
Section titled “Read a subcommand’s help”Each subcommand has its own help screen:
$ ./cloudctl deploy --helpDeploy a service
Usage: cloudctl deploy --image=STRING [flags] <service>
Arguments: <service> Service to deploy
Flags: --image=STRING Container image to run --replicas=2 Number of copies to run --help Show help
Global Flags: -r, --region="us-east-1" Region to work inNotice that --region appears under Global Flags. deploy accepts it, though CLI declares it. The first line is the summary tag from the Deploy field.
Where to go next
Section titled “Where to go next”We now have a cloudctl with two subcommands and a flag they share.
- Configure a CLI from a file and the environment: the next tutorial, which gives this
cloudctla config file. - How to declare subcommands: aliases, sections, hidden commands, and a default subcommand.
- How to accept positional arguments: optional arguments, lists of arguments, and the words after
--. - How to declare flags: give flags other types, aliases, counters, lists, and key=value pairs.
- About subcommands: why a flag on a parent can’t be declared again on a subcommand.