Skip to content

Configure a CLI from a file and the environment

In this tutorial, we will make cloudctl remember its settings. In Build a multi-command CLI we typed --image nginx:1.27 on every deployment. Now a config file will supply it, an environment variable will override the file, and a flag will override both. We continue in the cloudctl directory from that tutorial.

With the settings in a file, a deployment needs no flags:

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

CONGA reads config files through a decoder for each file format. Add the YAML decoder to the imports, and register it and the place to look for the file on the builder:

main.go
import (
"context"
"fmt"
"github.com/conga-sh/conga"
"github.com/conga-sh/conga/decoder/yaml"
)
// ...
func main() {
app := conga.New[CLI]().
Name("cloudctl").
Description("Manage services in the cloud").
Version("0.1.0").
Reads files ending in .yaml with the YAML decoder.
RegisterDecoder(".yaml", yaml.Decode).
Looks for the file in the current directory.
ConfigOptions(conga.ConfigPaths("."))
if err := app.Run(); err != nil {
app.Exit(err)
}
}

The decoder brings a new dependency into the module. Add it, and build the program:

Terminal window
go mod tidy
go build

Now create cloudctl.yaml next to main.go:

cloudctl.yaml
region: eu-west-1
deploy:
image: nginx:1.27
replicas: 3

Deploy without any flags:

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

Notice that each key in the file is a flag name. region sits at the top because --region belongs to CLI, and image and replicas sit under deploy because they belong to the deploy subcommand. --image is still a required flag, but the file gives it a value, so we no longer have to.

status reads the region from the same file:

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

Suppose we want one deployment in another region without editing the file. Give the builder an environment prefix:

main.go
func main() {
app := conga.New[CLI]().
Name("cloudctl").
Description("Manage services in the cloud").
Version("0.1.0").
Lets each flag read a variable named CLOUDCTL_ and the flag name.
EnvPrefix("CLOUDCTL").
RegisterDecoder(".yaml", yaml.Decode).
ConfigOptions(conga.ConfigPaths("."))
// ...
}

Build the program, and set the region in the environment for one run:

Terminal window
go build
Terminal window
$ CLOUDCTL_REGION=ap-south-1 ./cloudctl deploy web
deploying web (nginx:1.27) to ap-south-1 with 3 replicas

Notice that only the region changed. The image and replicas still came from the file. The help screen now names the variable each flag reads:

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 [env: CLOUDCTL_IMAGE]
--replicas=2 Number of copies to run [env: CLOUDCTL_REPLICAS]
--help Show help
Global Flags:
-r, --region="us-east-1" Region to work in [env: CLOUDCTL_REGION]

The variables for deploy’s flags are CLOUDCTL_IMAGE and CLOUDCTL_REPLICAS, without the command name.

Keep the variable set, and give the region as a flag too:

Terminal window
$ CLOUDCTL_REGION=ap-south-1 ./cloudctl deploy web -r us-west-2
deploying web (nginx:1.27) to us-west-2 with 3 replicas

The flag won. We have now set --region in four places, and each run took the value from the first of these that had one:

  1. The command line.
  2. The environment variable.
  3. The config file.
  4. The default tag.

About value precedence explains why CONGA uses this order.

Misspell replicas in cloudctl.yaml:

cloudctl.yaml
region: eu-west-1
deploy:
image: nginx:1.27
replcas: 3

Run a deployment:

Terminal window
$ ./cloudctl deploy web
Error:cloudctl: error: config file "cloudctl.yaml": unknown field "replcas" in command "deploy" (did you mean "replicas"?)

CONGA checks every key in the file against the flags, and stops before any command runs. This time the program exits with status 1, not the 2 of a mistyped flag:

Terminal window
$ echo $?
1

Exit status 2 marks a mistake on the command line, and 1 marks a run that failed for another reason, here a broken file. Put replicas back before going on.

We now have a cloudctl that reads its settings from a file and the environment, and lets the command line override both.