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.
Declare required and optional arguments
Section titled “Declare required and optional arguments”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:
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) }}$ mirror src/copying src/ to backup/$ mirror src/ /mnt/backupcopying src/ to /mnt/backupThe argument names in help come from the field names:
$ mirror --helpUsage: mirror <source> [<target>]
Arguments: <source> Directory to copy [<target>] Destination directory
Flags: --help Show help --version Show versionA 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 directoryRequired 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:
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}$ mirror /mnt/backup src/ docs/ photos/copying [src/ docs/ photos/] to /mnt/backup$ mirror /mnt/backupError:mirror: error: missing required positional argument <sources>Error
Usage: mirror <target> <sources...>
Run 'mirror --help' for more information.Forward the words after -- with DashArgs
Section titled “Forward the words after -- with DashArgs”A conga.DashArgs field receives every word after --, unparsed, so the command can hand them to another program:
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}$ mirror /mnt/backup src/ docs/ -- --delete --dry-runcopying [src/ docs/] to /mnt/backuprsync options: [--delete --dry-run]Before the --, CONGA parses words as usual, so a forwarded option there is an unknown flag:
$ mirror /mnt/backup src/ --deleteError:mirror: error: unknown flag: --deleteError
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.
Complete the forwarded words
Section titled “Complete the forwarded words”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:
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-runPass everything through with RawArgs
Section titled “Pass everything through with RawArgs”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:
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}$ mirror /mnt/backup src/ --delete --dry-runtarget /mnt/backup, rsync arguments: [src/ --delete --dry-run]Help shows the collected words after the required arguments:
$ mirror --helpUsage: mirror <target> [args...]
Arguments: <target> Destination directory
Flags: --help Show help --version Show versionA help tag on the field describes the collected words. Help lists them under Arguments, by the name the usage line shows:
type Mirror struct { Target conga.RequiredArg[string] `help:"Destination directory"` Rsync conga.RawArgs `help:"Arguments passed to rsync"`}$ mirror --helpUsage: mirror <target> [args...]
Arguments: <target> Destination directory [args...] Arguments passed to rsync
Flags: --help Show help --version Show versionA 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.
Know what users see
Section titled “Know what users see”| 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 |
Where to go next
Section titled “Where to go next”- Positional arguments: every tag a positional argument takes.
- Trailing arguments: the
DashArgsandRawArgsrules and the tags they accept. - How to declare subcommands: split a program into commands, each with its own arguments.
- About flags and args: why positional arguments bind only from the command line.