How to Use the Command 'gh help' (with examples)

The gh help command is a comprehensive and accessible resource for users of the GitHub CLI. It is designed to assist users by providing detailed descriptions and information regarding the numerous commands available within the CLI. This command is an essential tool for both beginners trying to get acquainted with GitHub’s command-line functionalities and seasoned developers looking for quick and detailed command references.

Use Case 1: Display General Help

Code:

gh help

Motivation:
This command is often the first port of call for users who are new to the GitHub CLI or those who need a quick overview of the available commands. It provides a general description and a list of top-level commands.

Explanation:
The command gh help contains only one word, which is the command itself. It does not require any additional arguments, allowing users to easily access a summary of the CLI’s capabilities, facilitating an understanding of where to find more detailed help if needed.

Example Output:

A command-line interface for GitHub.

Usage
  gh [command] [flags]

Available commands:
  alias        Manage command aliases
  api          Make an authenticated GitHub API request
  auth         Authenticate gh and manage GitHub credentials
  browse       Open the repository in the web browser
  ...

Use Case 2: Display Help for the gh help Subcommand

Code:

gh help --help

Motivation:
This command is useful when users need assistance on how to utilize the help subcommand specifically. Even though gh help might seem straightforward, users might want additional context or options available with this command.

Explanation:
The --help argument is appended to the gh help command. This flag tells the system to provide detailed information specifically about the gh help command, including its usage and all possible options.

Example Output:

Help about any command

Usage
  gh help [command] [flags]

Available flags:
  -h, --help       Show help for the 'help' command

Use Case 3: Display Help About Environment Variables

Code:

gh help environment

Motivation:
Users who wish to customize their GitHub CLI experience often turn to environment variables. This command provides all the information required to understand and implement these variables effectively.

Explanation:
By specifying environment as the argument to gh help, this command directs the help system to focus on environment-related configurations. It explains various environment variables that can modify the behavior of the GitHub CLI.

Example Output:

GH_* environment variables can change the behavior of GitHub CLI.

Reference for environment variables:
  GH_HOST
      The hostname of the GitHub instance to communicate with.

Use Case 4: Display a Markdown Reference of All gh Commands

Code:

gh help reference

Motivation:
Developers often look for consolidated references that they can consult offline or integrate into documentation. This command generates a comprehensive markdown-formatted list of all GitHub CLI commands.

Explanation:
Here, reference is used as the argument for the gh help command. It instructs the CLI to produce a formatted document that outlines each available command and their respective roles and functionalities, thus serving as an all-in-one guide.

Example Output:

# GitHub CLI manual

## Commands

### alias
### api
### auth
### browse
...

Use Case 5: Display Help About Formatting JSON Output Using jq

Code:

gh help formatting

Motivation:
For users who need to process and manipulate JSON outputs for their workflows or integrations, understanding how to format data using jq in conjunction with GitHub CLI outputs is crucial. This command provides necessary formatting guidelines.

Explanation:
The command gh help formatting provides a tutorial or help guide on formatting the response data received from various gh commands, often using jq—a lightweight and flexible command-line JSON processor.

Example Output:

Formatting with 'jq'

...
Using 'jq', you can parse JSON outputs: 

  $ gh api /repos/:owner/:repo/pulls --jq '.[] | {title}'

Use Case 6: Display Help About Using gh with MinTTY

Code:

gh help mintty

Motivation:
MinTTY is a terminal emulator for Cygwin and MSYS. If users are on Windows and encounter issues using gh with MinTTY, this specific help section offers guidance tailored to their environment.

Explanation:
The argument mintty targets information pertinent to using the GitHub CLI within the MinTTY terminal. This helps in identifying compatibility issues or setting adjustments needed for smooth operation.

Example Output:

Using GitHub CLI with MinTTY

If you experience issues, try using 'winpty' or modify your startup command, e.g.,:

  $ winpty gh auth login

Use Case 7: Display Help for a Subcommand

Code:

gh help subcommand

Motivation:
When users need information about specific subcommands but aren’t sure of the exact syntax or functionality, using gh help followed by the name of the subcommand provides detailed guidance.

Explanation:
The [subcommand] placeholder is where users can specify a particular subcommand they are interested in exploring. By replacing subcommand with actual commands such as gh auth, users get tailored documentation on that subcommand only.

Example Output:

GitHub CLI's 'subcommand'
Usage:  
  gh subcommand [options]

Available options:
  -o, --option   Description of what this option does

Use Case 8: Display Help for a Subcommand Action

Code:

gh help pr create

Motivation:
Advanced use cases often involve performing specific actions using subcommands; for instance, creating pull requests is a frequent activity in GitHub workflows. This command provides a rundown of parameters and examples for performing such tasks.

Explanation:
Here, pr create is specified after gh help, where pr is the subcommand and create is the action tied to pull requests. The CLI returns documentation on how to properly execute this action, including options and examples.

Example Output:

Create a pull request

Usage:
  gh pr create <options>

Flags:
  -a, --assignee   Assign people to this pull request
  -B, --base       The base branch
  -t, --title      Title for the pull request
  ...

Conclusion:

The gh help command is a powerful utility to aid in mastering the GitHub CLI. It offers both a broad overview and detailed guidance across various use cases, making it an indispensable part of any developer’s toolkit. Whether you’re looking for general command references or specific documentation for actions like creating pull requests, gh help proves invaluable in navigating and leveraging the full scope of capabilities embedded in the GitHub CLI.