GitHub CLI is an open source tool for using GitHub from your computer's command line. When you're working from the command line, you can use the GitHub CLI to save time and avoid switching context.
Install GitHub CLI on macOS, Windows, or Linux. For more information, see Installation in the GitHub CLI repository.
Authenticate with GitHub by running this command from your terminal.
gh auth login
Follow the on-screen prompts.
GitHub CLI automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your GitHub credentials. This can be useful as it allows you to use
git pull, and so on, without needing to set up a separate credential manager or use SSH.
Note: When you use some commands for the first time - for example,
gh codespace SUBCOMMAND - you'll be prompted to add extra scopes to your authentication token. Follow the onscreen instructions.
gh status to see details of your current work on GitHub across all the repositories you're subscribed to.
gh repo view OWNER/REPO to see the repository description and
README.md for the repository. Enter
gh repo view OWNER/REPO --web to view the repository in your default browser.
If you run the
repo subcommand from within the directory of a local Git repository that has a remote on GitHub you can omit
gh repo clone OWNER/REPO. For example,
gh repo clone octo-org/octo-repo clones the
octo-org/octo-repo repository to the directory from which you ran this command on your local computer.
gh repo create and follow the on-screen instructions. You can create a new, empty repository on GitHub and then, optionally, clone it locally. Alternatively, you can push an existing local repository to GitHub, and optionally set it as the remote for your local repository. For information on setting a local directory as a Git repository, see "Adding locally hosted code to GitHub."
gh issue list --repo OWNER/REPO to list the most recently created issues that are currently open for the specified repository. If you run the
issue subcommand from within the directory of a local Git repository that has a remote on GitHub you can omit
--repo OWNER/REPO. For example, enter
gh issue list --assignee "@me" to list issues assigned to you in this repository, or
gh issue list --author monalisa to list issues created by the user "monalisa."
gh pr list --repo OWNER/REPO to list the most recently created pull requests that are currently open for the specified repository. If you run the
pr subcommand from within the directory of a local Git repository that has a remote on GitHub you can omit
--repo OWNER/REPO. For example, enter
gh pr list --author "@me" to list open pull requests that you created in this repository.
gh pr list --label LABEL-NAME to list open pull requests with a specific label. Enter
gh search prs --review-requested=@me --state=open to list pull requests that you've been asked to review.
To create a pull request, enter
gh pr create and follow the on-screen instructions. For more information, see "Creating a pull request."
To create a new codespace, enter
gh codespace create and follow the on-screen instructions.
To display your existing codespaces, enter
gh codespace list. To open a codespace in the web version of VS Code enter
gh codespace code -w and choose a codespace .
In all of these commands you can substitute
gh for a reminder of the top-level GitHub CLI commands that you can use. For example,
repo, and so on.
For each command, and each subsidiary subcommand, you can append the
--help flag to find out how it's used. For example,
gh issue --help or
gh issue create --help.
You can change configuration settings and add aliases or extensions, to make GitHub CLI work the way that suits you best.
gh config set SUBCOMMANDSto configure GitHub CLI's settings, replacing
SUBCOMMANDSwith the setting you want to adjust.
For example, you can specify the text editor that's used when a GitHub CLI command requires you to edit text - such as when you add the body text for a new issue you're creating. To set your preferred text editor to Visual Studio Code enter
gh config set editor "code -w". The
--wait) flag in this example causes the command to wait for the file to be closed in Visual Studio Code before proceeding with the next step in your terminal.
For more information, see
gh config set.
Define aliases for commands that you commonly run. For example, if you run
gh alias set prd "pr create --draft", you will then be able to run
gh prdto quickly open a draft pull request. For more information, see