Skip to content


Language is the most important tool at our disposal for creating a clear, understandable product. Having clear language helps us create memorable commands that are clear in what they will do.

We generally follow this structure:


Command: The object you want to interact with

Subcommand: The action you want to take on that object. Most gh commands contain a command and subcommand. These may take arguments, such as issue/PR numbers, URLs, file names, OWNER/REPO, etc.

Flag: A way to modify the command, also may be called “options”. You can use multiple flags. Flags can take values, but don’t always. Flags always have a long version with two dashes (--state) but often also have a shortcut with one dash and one letter (-s). It’s possible to chain shorthand flags: -sfv is the same as -s -f -v

Values: Are passed to the commands or flags

  • The most common command values are:
    • Issue or PR number
    • The “owner/repo” pair
    • URLs
    • Branch names
    • File names
  • The possible flag values depend on the flag:
    • --state takes {closed | open | merged}
    • --clone is a boolean flag
    • --title takes a string
    • --limit takes an integer

Tip: To get a better sense of what feels right, try writing out the commands in the CLI a few different ways.


Use a flag for modifiers of actions


Avoid making modifiers their own commands

When designing your command’s language system:

  • Use GitHub language
  • Use unambiguous language that can’t be confused for something else
  • Use shorter phrases if possible and appropriate

Use language that can't be misconstrued


Avoid language that can be interpreted in multiple ways ("open in browser" or "open a pull request" here)


Use understood shorthands to save characters to type


Avoid long words in commands if there's a reasonable alternative

Edit this page on GitHub
2 contributorscolebemisampinsk
Last edited by colebemis on October 5, 2020