Skip to content

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 finished command takes a --name flag and a --loud flag:

Terminal window
$ ./hello --name conga --loud
HELLO, CONGA!

We need Go 1.27 or later.

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

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

    Terminal window
    go mod init hello
  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"
)
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 the program:

Terminal window
go build

Run it without flags:

Terminal window
$ ./hello
Hello, 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:

Terminal window
$ ./hello --name conga
Hello, 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:

Terminal window
$ ./hello -n Bob
Hello, Bob!

Let’s misspell the flag:

Terminal window
$ ./hello --nme conga
Error:hello: error: unknown flag: --nme (did you mean "--name"?)
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:

Terminal window
$ echo $?
2

Add a Loud field to the struct, and use it in Run:

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

Terminal window
go build
Terminal window
$ ./hello --loud
HELLO, WORLD!
Terminal window
$ ./hello -n Bob --loud
HELLO, BOB!

Ask the program for help:

Terminal window
$ ./hello --help
A 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 version

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

Ask for the version:

Terminal window
$ ./hello --version
hello has version 1.0.0 built with go1.27.3

The number comes from Version(...). The line ends with the Go version that built the program, so yours may differ.

We now have a working command with two flags.