1.5 KiB
How we document our command line syntax
Literal text
Use plain text for parts of the command that cannot be changed.
example:
gh help
The argument help is required in this command.
Placeholder values
Use angled brackets to represent a value the user must replace. No other expressions can be contained within the angled brackets.
example:
gh pr view <issue-number>
Replace <issue-number> with an issue number.
Optional arguments
Place optional arguments in square brackets. Mutually exclusive arguments can be included inside square brackets if they are separated with vertical bars.
example:
gh pr checkout [--web]
The argument --web is optional.
gh pr view [<number> | <url>]
The <number> and <url> arguments are optional.
Required mutually exclusive arguments
Place required mutually exclusive arguments inside braces, separate arguments with vertical bars.
example:
gh pr {view | create}
Repeatable arguments
Ellipsis represent arguments that can appear multiple times.
example:
gh pr close <pr-number>...
Variable naming
For multi-word variables use dash-case (all lower case with words separated by dashes)
example:
gh pr checkout <issue-number>
Additional examples
optional argument with placeholder:
command sub-command [<arg>]
required argument with mutually exclusive options:
command sub-command {<path> | <string> | literal}
optional argument with mutually exclusive options:
command sub-command [<path> | <string>]