Quickstart
In this tutorial, we will build hello, a command-line tool that greets someone by name. We will give it two flags, run it with good and bad input, and read the help screen CONGA generates for it.
The command we will build
Section titled “The command we will build”The finished command takes a --name flag and a --loud flag:
$ ./hello --name conga --loudHELLO, CONGA!Set 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 hello && cd hello -
Initialize a Go module:
Terminal window go mod init hello -
Add CONGA to the module:
Terminal window go get github.com/conga-sh/conga@latest
Write the program
Section titled “Write the program”Create main.go:
package main
import ( "context" "fmt"
"github.com/conga-sh/conga")
The command. CONGA reads its fields to find its flags.type CLI struct {A container: it makes Name an optional flag whose value is a string. Name conga.OptionalFlag[string] `default:"World" help:"Name of the person to greet" short:"n"`}
func (c *CLI) Run(ctx context.Context, session *conga.Session) error {Reads the flag's value. fmt.Printf("Hello, %s!\n", c.Name.Get())
return nil}
func main() { app := conga.New[CLI](). Name("hello"). Description("A greeting command"). Version("1.0.0")
if err := app.Run(); err != nil { app.Exit(err) }}CONGA names the flag after the field, so Name becomes --name. The Run method is what the command does. main names the application, describes it, gives it a version, and runs it.
Build and run it
Section titled “Build and run it”Build the program:
go buildRun it without flags:
$ ./helloHello, World!Notice that --name took its value from the field’s default tag:
Used when the user leaves out --name.Name conga.OptionalFlag[string] `default:"World" help:"Name of the person to greet" short:"n"`Now give it a name:
$ ./hello --name congaHello, conga!The short tag gives the flag a one-letter name:
Adds -n beside --name.Name conga.OptionalFlag[string] `default:"World" help:"Name of the person to greet" short:"n"`Run it with the short name:
$ ./hello -n BobHello, Bob!Make a mistake
Section titled “Make a mistake”Let’s misspell the flag:
$ ./hello --nme congaError:hello: error: unknown flag: --nme (did you mean "--name"?)Error
Usage: hello [flags]
Run 'hello --help' for more information.Notice that Run never ran. CONGA rejected the unknown --nme before calling it, and suggested the closest flag name. The program exits with status 2, which marks a usage error:
$ echo $?2Add a second flag
Section titled “Add a second flag”Add a Loud field to the struct, and use it in Run:
package main
import ( "context" "fmt" "strings"
"github.com/conga-sh/conga")
type CLI struct { Name conga.OptionalFlag[string] `default:"World" help:"Name of the person to greet" short:"n"` Loud conga.OptionalFlag[bool] `help:"Print the greeting in capitals"`}
func (c *CLI) Run(ctx context.Context, session *conga.Session) error { greeting := fmt.Sprintf("Hello, %s!", c.Name.Get()) if c.Loud.Get() { greeting = strings.ToUpper(greeting) }
fmt.Println(greeting)
return nil}
func main() { app := conga.New[CLI](). Name("hello"). Description("A greeting command"). Version("1.0.0")
if err := app.Run(); err != nil { app.Exit(err) }}Notice that Loud is a bool flag with no default tag, so it stays false until the user gives --loud.
Build the program again, and run it with the new flag:
go build$ ./hello --loudHELLO, WORLD!$ ./hello -n Bob --loudHELLO, BOB!Read the generated help
Section titled “Read the generated help”Ask the program for help:
$ ./hello --helpA greeting command
Usage: hello [flags]
Flags: -n, --name="World" Name of the person to greet --loud Print the greeting in capitals --help Show help --version Show versionNotice where each part comes from. The first line is the Description(...) text, and the usage line uses the name from Name(...). Each flag line shows the flag’s short name, its default, and the text from its help tag:
Becomes the description beside --name.Name conga.OptionalFlag[string] `default:"World" help:"Name of the person to greet" short:"n"`CONGA added --help and --version itself.
Check the version
Section titled “Check the version”Ask for the version:
$ ./hello --versionhello has version 1.0.0 built with go1.27.3The number comes from Version(...). The line ends with the Go version that built the program, so yours may differ.
Where to go next
Section titled “Where to go next”We now have a working command with two flags.
- Build a multi-command CLI: the next tutorial, a
cloudctlwith subcommands, a positional argument, and a shared flag. - How to declare flags: give flags other types, aliases, counters, lists, and key=value pairs.
- How to declare subcommands: split a program into several commands.
- About flags and args: why CONGA reads values through containers.
- Examples: a runnable program for each feature.