On this page
Components
Syntax
We show meaning or objects through syntax such as angled brackets, square brackets, curly brackets, parenthesis, and color.
Branches
Display branch names in brackets and/or cyan
![A branch name in brackets and cyan](https://user-images.githubusercontent.com/980622/215497467-7cf94a73-4b35-4352-81a4-a6c00d1f3486.png)
Labels
Display labels in parenthesis and/or gray
![A label name in parenthesis and gray](https://user-images.githubusercontent.com/980622/215497505-182904ee-019e-41c9-825f-cf21ecbabdfb.png)
Repository
Display repository names in bold where appropriate
![A repository name in bold](https://user-images.githubusercontent.com/980622/215497508-3d5f1879-54f0-4c8f-9156-9143e35eec3a.png)
Help
Use consistent syntax in help pages to explain command usage.
Literal text
Use plain text for parts of the command that cannot be changed
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.
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.
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.
gh pr {view | create}
Repeatable arguments
Ellipsis represent arguments that can appear multiple times
gh pr close <pr-number>...
Variable naming
For multi-word variables use dash-case (all lower case with words separated by dashes)
gh pr checkout <issue-number>
Additional examples
Optional argument with placeholder:
<command> <subcommand> [<arg>]
Required argument with mutually exclusive options:
<command> <subcommand> {<path> | <string> | literal}
Optional argument with mutually exclusive options:
<command> <subcommand> [<path> | <string>]
Prompts
Generally speaking, prompts are the CLI’s version of forms.
- Use prompts for entering information
- Use a prompt when user intent is unclear
- Make sure to provide flags for all prompts
Yes/No
Use for yes/no questions, usually a confirmation. The default (what will happen if you enter nothing and hit enter) is in caps.
![An example of a yes/no prompt.](https://user-images.githubusercontent.com/980622/215497458-36deca06-477d-47e6-8656-d83b71edbe82.png)
Short text
Use to enter short strings of text. Enter will accept the auto fill if available
![An example of a short text prompt.](https://user-images.githubusercontent.com/980622/215497453-0d3fc9a0-96e7-4285-8a28-464abad66ad6.png)
Long text
Use to enter large bodies of text. E key will open the user’s preferred editor, and Enter will skip.
![An example of a long text prompt.](https://user-images.githubusercontent.com/980622/215497445-4397c8e2-5900-4863-b5f7-bb6ceaba34d8.png)
Radio select
Use to select one option
![An example of a radio select prompt](https://user-images.githubusercontent.com/980622/215497450-589acfd9-f1a4-45da-a9e3-146cc48452a4.png)
Multi select
Use to select multiple options
![An example of a multi select prompt](https://user-images.githubusercontent.com/980622/215497447-5a6628d8-339a-479a-8a72-fea5ac78df2a.png)
State
The CLI reflects how GitHub.com displays state through color and iconographhy.
![A collection of examples of state from various command outputs](https://user-images.githubusercontent.com/980622/215497462-02b78963-a977-4801-aef1-c693787aca62.png)
Progress indicators
For processes that might take a while, include a progress indicator with context on what’s happening.
![An example of a loading spinner when forking a repository](https://user-images.githubusercontent.com/980622/215497460-92b83be7-829a-4b78-adeb-f2d369f95a8a.png)
Headers
When viewing output that could be unclear, headers can quickly set context for what the user is seeing and where they are.
Examples
![An example of the header of the gh pr create command](https://user-images.githubusercontent.com/980622/215497394-b2ec59b2-5082-41ee-9ccb-2bbe80f21fe5.png)
The header of the "gh pr create" command reassures the user that they're creating the correct pull request
![An example of the header of the gh pr list command](https://user-images.githubusercontent.com/980622/215497378-70bbe5b1-74dc-4b95-a329-c8f7e2908bae.png)
The header of the "gh pr list" command sets context for what list the user is seeing
Lists
Lists use tables to show information.
- State is shown in color.
- A header is used for context.
- Information shown may be branch names, dates, or what is most relevant in context.
![An example of gh pr list](https://user-images.githubusercontent.com/980622/215497378-70bbe5b1-74dc-4b95-a329-c8f7e2908bae.png)
Detail views
Single item views show more detail than list views. The body of the item is rendered indented. The item’s URL is shown at the bottom.
![An example of gh issue view](https://user-images.githubusercontent.com/980622/215497374-4410111c-b2c9-4f04-8bab-1acd7bcd4135.png)
Empty states
Make sure to include empty messages in command outputs when appropriate.
![The empty state of the gh pr status command](https://user-images.githubusercontent.com/980622/215497357-142ef375-ea50-4156-b00a-82f511935b11.png)
The empty state of "gh pr status"
![The empty state of the gh issue list command](https://user-images.githubusercontent.com/980622/215497363-b43175f4-9b3a-4ad8-8a1e-b9c3bf31e042.png)
The empty state of "gh issue list"
Help pages
Help commands can exist at any level:
- Top level (
gh
) - Second level (
gh [command]
) - Third level (
gh [command] [subcommand]
)
Each can be accessed using the --help
flag, or using gh help [command]
.
Each help page includes a combination of different sections.
Required sections
- Usage
- Core commands
- Flags
- Learn more
- Inherited flags
Other available sections
- Additional commands
- Examples
- Arguments
- Feedback
Example
![The output of gh help](https://user-images.githubusercontent.com/980622/215497399-8a13ace4-d795-4014-ac23-5ecfd5eac237.png)