Template syntax¶

A template is the command string with placeholders for the parts you fill in. The syntax is deliberately tiny — three tokens — so there's no bespoke grammar to learn.

Tokens¶

Token	Meaning
`<var>`	A required placeholder, prompted in the form.
`[ ... <var> ... ]`	An optional segment — if you skip the variable, the entire bracketed fragment is removed.
`\<` `\>` `\[` `\]` `\\`	Escaped literals — a real `<`, `>`, `[`, `]`, or `\`.

Required placeholders¶

<var> marks a value you must provide. The form prompts for it, and you can't finish until it's filled:

tmpl = "git branch -D <branch>"

The name inside the angle brackets links the placeholder to its [[cmd.var]] block (name = "branch").

Optional segments¶

This is Commando's signature move. Wrap a fragment and its variable in [...]. If you skip the variable, the whole fragment — flag and all — disappears:

tmpl = "git log [--author=<author>] [-n <count>] -- <file>"

You do	Result
author = skip, count = `20`, file = `README.md`	`git log -n 20 -- README.md`
author = `alice`, count = skip, file = `a.go b.go`	`git log --author=alice -- a.go b.go`
author + count skipped, file = `x`	`git log -- x`

Because the --author= text lives inside the bracket with its variable, skipping the variable removes the flag too. The dangling-flag problem simply doesn't exist.

Here it is in action — skipping an optional [--exclude=…] segment and multi-selecting the required files, with the command preview assembling as you go:

Skip an optional segment and multi-select values; the command assembles live and drops the skipped fragment

The optional [--exclude=…] is skipped (it vanishes from the command), while two files are multi-selected and quoted.

Optionality lives on the fragment, not the variable

A variable becomes optional by being inside [...]. The same variable outside brackets would be required. You can have multiple optional segments, and they can be nested.

Escaping literals¶

Need a literal <, >, [, or ] in your command? Escape it with a backslash:

# A literal redirection and a literal bracket:
tmpl = "echo hello \> out.txt"
tmpl = "grep '\[INFO\]' <file>"

Escape	Produces
`\<`	`<`
`\>`	`>`
`\[`	`[`
`\]`	`]`
`\\`	`\`

How resolution works¶

At fill-in time, Commando walks the template left to right:

For each segment, determine the variable's value (candidate, default, typed, or remembered).
If a segment is optional and the variable is skipped, omit the whole segment.
Otherwise substitute the value in place.
Multi-select values are formatted with each and joined with sep before substitution (see Variables).

The command preview shows this assembling in real time as you fill the form.

Next¶

Variables

Give each placeholder candidates, defaults, multi-select, and more.
Argument memory

How Commando remembers and ranks the values you enter.