Skip to content

How to accept positional arguments

This guide builds a mirror command that copies directories to a target and forwards options to rsync. If you’re new to CONGA, Build a multi-command CLI builds a command with a positional argument step by step.

CONGA builds a command’s positional arguments from the fields of its struct, as it does flags. The type of each argument field is a container, conga.RequiredArg[...] for a required argument or conga.OptionalArg[...] for an optional one, with the type of the argument’s value in the brackets. CONGA binds the words on the command line to the fields in declaration order, and GetOr gives an optional argument’s fallback:

main.go
package main
import (
"context"
"fmt"
"github.com/conga-sh/conga"
)
type Mirror struct {
Source conga.RequiredArg[string] `help:"Directory to copy"`
Target conga.OptionalArg[string] `help:"Destination directory"`
}
func (m *Mirror) Run(ctx context.Context, session *conga.Session) error {
fmt.Fprintf(session.Stdout(), "copying %s to %s\n", m.Source.Get(), m.Target.GetOr("backup/"))
return nil
}
func main() {
app := conga.New[Mirror]().Name("mirror")
if err := app.Run(); err != nil {
app.Exit(err)
}
}
Terminal window
$ mirror src/
copying src/ to backup/
Terminal window
$ mirror src/ /mnt/backup
copying src/ to /mnt/backup

The argument names in help come from the field names:

Terminal window
$ mirror --help
Usage:
mirror <source> [<target>]
Arguments:
<source> Directory to copy
[<target>] Destination directory
Flags:
--help Show help
--version Show version

A name tag replaces a placeholder exactly as written, so include the angle brackets to keep the usual form. With name:"<dest>" on Target:

Usage:
mirror <source> [<dest>]
Arguments:
<source> Directory to copy
[<dest>] Destination directory

Required arguments come before optional ones (Positional arguments). Positional arguments bind from the command line only.

Collect any number of arguments in a slice

Section titled “Collect any number of arguments in a slice”

Declare a slice as the last positional argument, and CONGA collects every remaining word into it. A RequiredArg[[]T] needs at least one word, and an OptionalArg[[]T] can be empty:

main.go
type Mirror struct {
Target conga.RequiredArg[string] `help:"Destination directory"`
Sources conga.RequiredArg[[]string] `help:"Directories to copy"`
}
func (m *Mirror) Run(ctx context.Context, session *conga.Session) error {
fmt.Fprintf(session.Stdout(), "copying %v to %s\n", m.Sources.Get(), m.Target.Get())
return nil
}
Terminal window
$ mirror /mnt/backup src/ docs/ photos/
copying [src/ docs/ photos/] to /mnt/backup
Terminal window
$ mirror /mnt/backup
Error:mirror: error: missing required positional argument <sources>
Usage:
mirror <target> <sources...>
Run 'mirror --help' for more information.

A conga.DashArgs field receives every word after --, unparsed, so the command can hand them to another program:

main.go
type Mirror struct {
Target conga.RequiredArg[string] `help:"Destination directory"`
Sources conga.RequiredArg[[]string] `help:"Directories to copy"`
Rsync conga.DashArgs
}
func (m *Mirror) Run(ctx context.Context, session *conga.Session) error {
fmt.Fprintf(session.Stdout(), "copying %v to %s\n", m.Sources.Get(), m.Target.Get())
fmt.Fprintf(session.Stdout(), "rsync options: %v\n", m.Rsync.Get())
return nil
}
Terminal window
$ mirror /mnt/backup src/ docs/ -- --delete --dry-run
copying [src/ docs/] to /mnt/backup
rsync options: [--delete --dry-run]

Before the --, CONGA parses words as usual, so a forwarded option there is an unknown flag:

Terminal window
$ mirror /mnt/backup src/ --delete
Error:mirror: error: unknown flag: --delete
Usage:
mirror <target> <sources...> [-- <args...>]
Run 'mirror --help' for more information.

DashArgs also works on a command with subcommands, because the -- marks where forwarding starts.

To complete the words after --, give the DashArgs field a predictor tag. It takes the same values as on a flag, a built-in such as file or dir or a name registered with app.Predictor:

main.go
type Mirror struct {
Target conga.RequiredArg[string] `help:"Destination directory"`
Sources conga.RequiredArg[[]string] `help:"Directories to copy"`
Rsync conga.DashArgs `predictor:"rsync-options"`
}
// ...
func main() {
app := conga.New[Mirror]().Name("mirror").
EnableCompletion().
Predictor("rsync-options", predict.Values("--checksum", "--delete", "--dry-run"))
// ...
}
$ mirror /mnt/backup src/ -- --<Tab>
--checksum --delete --dry-run

A conga.RawArgs field collects every word after the required positional arguments, flags included, without a --. It suits a wrapper whose own arguments end early, such as one target followed by the other program’s arguments:

main.go
type Mirror struct {
Target conga.RequiredArg[string] `help:"Destination directory"`
Rsync conga.RawArgs
}
func (m *Mirror) Run(ctx context.Context, session *conga.Session) error {
fmt.Fprintf(session.Stdout(), "target %s, rsync arguments: %v\n", m.Target.Get(), m.Rsync.Get())
return nil
}
Terminal window
$ mirror /mnt/backup src/ --delete --dry-run
target /mnt/backup, rsync arguments: [src/ --delete --dry-run]

Help shows the collected words after the required arguments:

Terminal window
$ mirror --help
Usage:
mirror <target> [args...]
Arguments:
<target> Destination directory
Flags:
--help Show help
--version Show version

A help tag on the field describes the collected words. Help lists them under Arguments, by the name the usage line shows:

main.go
type Mirror struct {
Target conga.RequiredArg[string] `help:"Destination directory"`
Rsync conga.RawArgs `help:"Arguments passed to rsync"`
}
Terminal window
$ mirror --help
Usage:
mirror <target> [args...]
Arguments:
<target> Destination directory
[args...] Arguments passed to rsync
Flags:
--help Show help
--version Show version

A DashArgs field takes the same tag.

Collection starts after the last required positional, so words up to that point are still parsed. mirror /mnt/backup --help prints help, and mirror /mnt/backup src/ --help forwards --help. Only required scalar arguments can come before RawArgs, and the command can’t have subcommands. Use DashArgs when you need either.

What happens When Result
The user leaves out a required argument Run missing required positional argument <source>, exit 2
The user gives more words than the arguments take Run unexpected argument "c", exit 2
The user puts a forwarded option before -- Run unknown flag: --delete, exit 2
An OptionalArg is declared before a RequiredArg Startup schema error: invalid positional argument order: optional positional argument cannot precede required positional argument <source>, exit 1
A slice argument is followed by another positional argument Startup schema error: invalid positional argument order: slice argument <sources> must be the last positional argument, exit 1
A slice or optional argument comes before RawArgs Startup schema error: raw args requires a deterministic positional prefix, exit 1
A command declares both positional arguments and subcommands Startup schema error: positional argument Target cannot be combined with subcommand Check, exit 1
A DashArgs or RawArgs help tag uses a variable such as {{enum}} Startup schema error: invalid struct tag: tag "help" references {{enum}}, but the field provides no value for that variable, exit 1