Skip to content

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 finished cloudctl deploys a service to a region:

Terminal window
$ ./cloudctl --region eu-west-1 deploy web --image nginx:1.27
deploying web (nginx:1.27) to eu-west-1 with 2 replicas

We need Go 1.27 or later.

  1. Create a directory for the project and move into it:

    Terminal window
    mkdir cloudctl && cd cloudctl
  2. Initialize a Go module:

    Terminal window
    go mod init cloudctl
  3. Add CONGA to the module:

    Terminal window
    go get github.com/conga-sh/conga@latest

Create main.go:

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:

Terminal window
go build
Terminal window
$ ./cloudctl deploy web
deploying web

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

Terminal window
$ ./cloudctl
Error:cloudctl: error: subcommand required for "cloudctl"
Manage services in the cloud
Usage:
cloudctl <command>
Commands:
deploy Deploy a service
Flags:
--help Show help
--version Show version

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

Every deployment needs an image. Replace DeployCmd and its Run method:

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

Terminal window
go build
Terminal window
$ ./cloudctl deploy web
Error:cloudctl: error: missing required flag: --image
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:

Terminal window
$ ./cloudctl deploy web --image nginx:1.27
deploying 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.

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:

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

Terminal window
go build
Terminal window
$ ./cloudctl --region eu-west-1 deploy web --image nginx:1.27
deploying web (nginx:1.27) to eu-west-1 with 2 replicas

Now give it after the subcommand, with its short name:

Terminal window
$ ./cloudctl deploy web --image nginx:1.27 -r eu-west-1
deploying web (nginx:1.27) to eu-west-1 with 2 replicas

Notice 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 Status field to CLI, and a StatusCmd struct with its own Run method:

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

Terminal window
go build
Terminal window
$ ./cloudctl -r eu-west-1 status
all services healthy in eu-west-1

The help screen now lists both subcommands:

Terminal window
$ ./cloudctl --help
Manage 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 version

Let’s misspell one:

Terminal window
$ ./cloudctl stats
Error:cloudctl: error: unknown command: stats (did you mean "status"?)
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.

Each subcommand has its own help screen:

Terminal window
$ ./cloudctl deploy --help
Deploy 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 in

Notice that --region appears under Global Flags. deploy accepts it, though CLI declares it. The first line is the summary tag from the Deploy field.

We now have a cloudctl with two subcommands and a flag they share.