GitHub CLI: Manage Repositories, Issues, and Pull Requests

Switching between a terminal and a browser can slow down routine GitHub work. You may only need to create a pull request, check a workflow failure, or open an issue, but each task normally requires finding the right page and clicking through several screens.

GitHub CLI, available through the gh command, brings these operations into your terminal. It works with repositories, pull requests, issues, releases, GitHub Actions, and the GitHub API. This guide covers the commands you will use most often in a local Git workflow.

GitHub CLI Command Syntax #

The general syntax for gh commands is:

gh COMMAND SUBCOMMAND [FLAGS]

Most commands work against the repository in the current directory. To target another repository, use --repo OWNER/REPOSITORY with commands that support it.

Install GitHub CLI #

Ubuntu and Debian both carry a gh package in their own repositories, but those builds trail upstream by a long way. Ubuntu 24.04 ships 2.45.0, Ubuntu 26.04 and Debian 13 ship 2.46.0, and the current release is 2.101.0. Commands added after that point, gh attestation among them, are missing entirely. GitHub also warns that the 2.45.x and 2.46.x builds rely on deprecated APIs and no longer work reliably. For a current version, use the repository maintained by the GitHub CLI team.

Start by installing wget, which the key download needs:

sudo apt update
sudo apt install wget

Download the GitHub CLI signing key into the system keyring:

sudo mkdir -p -m 755 /etc/apt/keyrings
wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg

The key lands in /etc/apt/keyrings/, the standard location for third-party repository keys on current releases. Now add the repository:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

Update the package index again and install GitHub CLI:

sudo apt update
sudo apt install gh

With the repository registered, later sudo apt upgrade runs pull in new gh releases along with everything else.

On Fedora, the distribution package tracks upstream closely enough that dnf is all you need:

sudo dnf install gh

RHEL and its derivatives do not include gh in the default repositories. On systems that use DNF4, add the repository maintained by the GitHub CLI team and install the package:

sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh

GitHub CLI drives git for clone, checkout, and push operations, so make sure Git is installed as well. Confirm that the command is available:

gh --version

gh version 2.101.0 (2026-09-15)
https://github.com/cli/cli/releases/tag/v2.101.0

Your version may differ from the example. If the command prints a version number, the installation is ready.

Authenticate with GitHub #

Before gh can access your repositories, authenticate with your GitHub account:

gh auth login

The interactive prompt asks which GitHub host you use, whether Git should connect over HTTPS or SSH, and how you want to authenticate. For GitHub.com, the web browser method is usually the simplest option.

Check the active account and authentication scopes with:

gh auth status

github.com
  ✓ Logged in to github.com account octocat (keyring)
  - Active account: true
  - Git operations protocol: ssh
  - Token: gho_************************************
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

If you use GitHub Enterprise Server, pass its hostname:

gh auth login --hostname github.example.com

For GitHub.com CI jobs and other non-interactive environments, gh can read a token from the GH_TOKEN or GITHUB_TOKEN environment variable. GitHub Enterprise Server uses GH_ENTERPRISE_TOKEN or GITHUB_ENTERPRISE_TOKEN instead.

Work with Repositories #

To clone a repository, pass its OWNER/REPOSITORY name:

gh repo clone cli/cli

This runs the same Git clone operation you would run by hand, using the authentication and protocol configured for your account.

From inside a local repository, display its description, default branch, and README with:

gh repo view

Open the current repository in your browser by adding --web:

gh repo view --web

You can also create a GitHub repository from an existing local project. Run the following command from the project directory:

gh repo create my-project --private --source=. --remote=origin --push

The options perform the following actions:

• --private - Creates a private repository. Use --public when the repository should be public.
• --source=. - Uses the current directory as the repository source.
• --remote=origin - Adds the new GitHub repository as the origin remote .
• --push - Pushes the local commits after creating the repository.

Before using --push, check the files that are about to be published with git status and confirm that secrets, local configuration, and generated files are excluded through .gitignore .

Manage Pull Requests #

List open pull requests for the current repository with:

gh pr list

Showing 2 of 2 open pull requests in owner/project

ID   TITLE                     BRANCH             CREATED AT
#42  Add health check endpoint feature/health     about 2 hours ago
#38  Update deployment docs    docs/deployment    about 3 days ago

To create a pull request from the current branch, use:

gh pr create

GitHub CLI prompts for the title, body, base branch, and other details. If the branch commits already contain a useful title and description, use --fill:

gh pr create --fill

To create a draft pull request and request a reviewer in one command:

gh pr create --fill --draft --reviewer octocat

View the pull request associated with the current branch:

gh pr view

Add --web to open it in the browser, or specify a pull request number when it is not associated with your current branch:

gh pr view 42 --web

To check out a contributor’s pull request locally, gh creates a local branch for you and switches to it:

gh pr checkout 42

There is no need to add the fork as a remote or to create the branch yourself. Review its changes and status checks before merging:

gh pr diff 42
gh pr checks 42

The gh pr diff output is the same patch format git diff produces, so the + and - prefixes read exactly as you expect. The gh pr checks command lists each status check with its conclusion and a link to the run.

If the pull request is ready, merge it with a merge commit, squash commit, or rebase:

gh pr merge 42 --squash

The merge command changes the remote repository, so review the diff and checks first.

Manage Issues #

List open issues in the current repository:

gh issue list

You can filter by label, assignee, or search query. The following command shows open bug reports assigned to you:

gh issue list --label bug --assignee @me

Create an issue interactively with:

gh issue create

For a quick issue with a known title and body, provide both values directly:

gh issue create \
  --title "Deployment fails when the cache is empty" \
  --body "The deployment job exits during the cache restore step."

View an issue in the terminal:

gh issue view 27

When the issue has been resolved, close it with an optional comment:

gh issue close 27 --comment "Fixed in pull request #42."

Inspect GitHub Actions Runs #

GitHub CLI can list workflow runs without opening the Actions page:

gh run list

STATUS  TITLE                     WORKFLOW  BRANCH   EVENT         ID         ELAPSED  AGE
X       Add health check endpoint CI        feature  pull_request  123456789  1m12s    about 1 hour ago
✓       Update deployment docs    CI        main     push          123450001  47s      about 3 hours ago

Each row shows the conclusion, the workflow that produced the run, the branch and event that triggered it, how long the run took, and how long ago it finished. The ID column is the value the other gh run commands expect.

Inspect a specific run by passing its ID:

gh run view 123456789

For a failed run, show only the logs for failed steps:

gh run view 123456789 --log-failed

Watch a running workflow until it completes:

gh run watch 123456789

If a workflow supports the workflow_dispatch event, start it manually with:

gh workflow run build.yml

Use gh run rerun 123456789 --failed when you need to retry only the failed jobs from an existing run.

Manage Actions Secrets #

A workflow that deploys or publishes needs credentials, and those values belong in repository secrets rather than in the workflow file. GitHub CLI can set them without opening the repository settings page.

Create or update a secret by passing its name and reading the value from standard input:

gh secret set DEPLOY_TOKEN

The command prompts for the value and hides it as you type, so the secret never reaches your shell history. To set it non-interactively, pipe the value in:

cat token.txt | gh secret set DEPLOY_TOKEN

When several secrets change at once, load them from a dotenv-formatted file with --env-file:

gh secret set --env-file .env.production

List the secret names configured for the repository:

gh secret list

NAME            UPDATED
DEPLOY_TOKEN    about 2 minutes ago
NPM_TOKEN       about 21 days ago

Only the names and update times are shown. GitHub never returns a secret value after it is stored, which is why the list has no value column. Use --env production to target a deployment environment, or --org NAME for an organization secret. Values that are not sensitive, such as a region or a build flag, belong in gh variable set instead, where they remain readable.

Create and Download Releases #

To create a release from an existing Git tag and generate notes from merged pull requests:

gh release create v1.0.0 --generate-notes

If the tag does not exist, GitHub CLI creates it from the repository’s default branch unless you provide another target with --target.

List existing releases with:

gh release list

Download all assets attached to a release:

gh release download v1.0.0

To publish build files when creating the release, list them after the tag:

gh release create v1.0.0 dist/app-linux-amd64 dist/checksums.txt

Format Output for Scripts #

Many gh commands support --json for structured output. For example, list pull request numbers, titles, and authors:

gh pr list --json number,title,author

Use --jq to select and format fields without piping the result to a separate jq process:

gh pr list \
  --json number,title \
  --jq '.[] | "#\(.number) \(.title)"'

#42 Add health check endpoint
#38 Update deployment docs

Structured output is more reliable in scripts than parsing the default table, which is intended for people and can change with terminal width.

Call the GitHub API #

The gh api command sends authenticated requests to GitHub’s REST or GraphQL API. From inside a repository, list release tag names with:

gh api repos/{owner}/{repo}/releases --jq '.[].tag_name'

The {owner} and {repo} placeholders are filled from the current repository. To request a specific API version or media type, pass additional headers with -H.

For a POST request, use -f for string fields or -F for typed fields:

gh api repos/{owner}/{repo}/issues \
  -f title="API-created issue" \
  -f body="Created with gh api."

This command creates a real issue. Use a test repository while learning write operations.

Create Command Aliases #

Aliases shorten commands you use repeatedly. The following alias opens the current pull request in a browser:

gh alias set pv 'pr view --web'

You can then run:

gh pv

List all configured aliases with:

gh alias list

Install Extensions #

Extensions add new top-level commands to gh. They are ordinary GitHub repositories whose name starts with gh-, and they run through the same authentication your other commands use.

Browse what is available with a keyword search:

gh extension search dashboard

Install one by repository name:

gh extension install dlvhdr/gh-dash

The extension then runs as a subcommand, in this case gh dash. List what you have installed and update everything at once with:

gh extension list
gh extension upgrade --all

Remove one you no longer use with gh extension remove dash.

Quick Reference #

For a printable quick reference, see the GitHub CLI cheatsheet .

Troubleshooting #

GitHub CLI reports that authentication is required
Run gh auth status to inspect the active account. If the credentials are missing or expired, authenticate again with gh auth login. In CI, confirm that GH_TOKEN or GITHUB_TOKEN is available to the step that runs the command.

The command targets the wrong repository
Run the command from inside the intended Git repository, pass --repo OWNER/REPOSITORY, or set a default with gh repo set-default. This is especially important in scripts that run outside a working tree.

A command returns an insufficient scopes error
The stored token does not have permission for the requested operation. Run gh auth refresh and select the additional scope requested by the error. Organization policies may also restrict token access.

gh pr create cannot find commits between branches
Push the current branch and confirm that it contains commits not present in the base branch. Use git status, git log, and git diff BASE...HEAD to check the local state before retrying.

FAQ #

What is the difference between Git and GitHub CLI?
Git manages commits, branches, tags, and repository history. GitHub CLI manages GitHub features such as pull requests, issues, releases, and Actions runs. You will often use git for local history and gh for the remote collaboration workflow.

Can GitHub CLI work with private repositories?
Yes. The authenticated account must have access to the repository, and the token used by gh must include the required permissions.

How do I use a different repository without changing directories?
Add --repo OWNER/REPOSITORY to supported commands. For example, gh issue list --repo cli/cli lists issues from that repository regardless of your current directory.

Can GitHub CLI produce machine-readable output?
Yes. Commands that expose --json can return selected fields, and --jq can filter or format the result. The gh api command also supports --jq and --template.

Does GitHub CLI support GitHub Enterprise Server?
Yes. Authenticate with gh auth login --hostname HOSTNAME, then use that host for repository and API operations.

Conclusion #

GitHub CLI keeps repository administration and collaboration close to your existing Git workflow. Start with gh auth login, gh repo, gh pr, and gh issue, then add Actions, releases, and gh api as your terminal workflow grows, and keep the GitHub CLI cheatsheet open while the subcommands are still new.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 1000+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page