← All cheatsheets

Git

GitHub & the gh CLI — PRs, issues, and runs from the terminal

Drive GitHub from the terminal with gh: authenticate, clone and create repos, open and merge pull requests, triage issues, and watch Actions runs — without leaving the shell.

Docs-checkedgithubghclipull-requestactions

Quick reference — reach for these first

Check who you aregh auth statusShows the logged-in account, host, and token scopes for each GitHub host.
Open a PRgh pr create --fillCreates a PR from the current branch, taking title and body from your commits.
Check out a PRgh pr checkout NUMBERFetches PR #NUMBER into a local branch so you can test or review it.
Watch a CI rungh run watchLive-tails the most recent Actions run until it finishes, then exits with its status.
Merge a PRgh pr merge --squash --delete-branchSquash-merges the PR and deletes the head branch. Changes the remote — see tasks.

The pull request lifecycle through gh

The pull request lifecycle through ghA pipeline from a local branch through push, pr create, pr checks, pr review, to a squash merge into main on the remote.git push-u origingh pr create--fillgh pr checks--watchgh pr review--approvegh prmergelocalCI gatemain (remote)gh auth status / gh auth login establishes the account for every step

Text equivalent: A left-to-right pipeline: git push sends a local branch to GitHub; gh pr create opens a pull request; gh pr checks waits for CI to pass; gh pr review approves it; gh pr merge squash-merges into the main branch on the remote.

Common tasks

Task · Command · What to check

TaskCommandWhat to check
Log in interactivelygh auth logingh auth status prints 'Logged in to github.com as USER'
Confirm identity and scopesgh auth statusCorrect account and host shown; token scopes include 'repo'
Clone a repogh repo clone OWNER/REPODirectory REPO exists with a configured origin remote
Inspect a repo in the terminalgh repo view OWNER/REPOREADME and metadata render in the pager
Create a repo from the current foldergh repo create REPO --private --source=. --pushgh repo view shows the new private repo with your commits
Open a PR from the current branchgh pr create --fill --base mainCommand prints the new PR URL
List open PRsgh pr listTable of open PRs with numbers, titles, and branches
Read a PR and its diffgh pr view NUMBER && gh pr diff NUMBERPR body, checks, and unified diff are shown
Check out someone's PR to test itgh pr checkout NUMBERgit branch shows you on the PR's head branch
Review a PRgh pr review NUMBER --approve -b "LGTM"gh pr view NUMBER lists your approval under Reviews
Watch CI for a PR's checksgh pr checks NUMBER --watchAll required checks resolve to pass before the command exits
[REMOTE] Merge the PRgh pr merge NUMBER --squash --delete-branchgh pr view NUMBER shows state MERGED
List and watch Actions runsgh run list && gh run watchLatest run streams to completion with a conclusion
Re-run a failed workflowgh run rerun RUN_ID --failedgh run view RUN_ID shows a fresh attempt in progress

Open a PR and get it merged, start to finish

[REMOTE] final step changes the remote repository

1
Push your feature branch and set upstream
git push -u origin feat/add-search
# branch 'feat/add-search' set up to track 'origin/feat/add-search'
2
Open the PR, filling title/body from commits
gh pr create --fill --base main
# https://github.com/OWNER/REPO/pull/42
3
Wait for required checks to go green
gh pr checks 42 --watch
# All checks were successful
# 3 successful, 0 failing
4
Optionally self-review the diff before merging
gh pr diff 42
# unified diff of the PR's changes
5
Squash-merge and delete the head branch
gh pr merge 42 --squash --delete-branch
# Merged pull request #42
# Deleted branch feat/add-search
6
Verify the PR is merged
gh pr view 42
# state: MERGED  base: main

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
'gh: To get started with GitHub CLI, please run gh auth login'gh auth statusWhether any credentials exist for the target hostRun gh auth login and complete the browser or token flow
Commands hit the wrong account or GitHub Enterprise hostgh auth status (shows every host and active account)Which account/host is active for API callsgh auth switch --hostname HOST --user USER, or gh auth login --hostname HOST
gh pr merge refuses: PR is not mergeable (conflicts)gh pr view NUMBER (look for 'MERGEABLE' / 'CONFLICTING')Whether the head branch conflicts with the basegh pr checkout NUMBER, rebase or merge base, resolve, push; then retry merge
Merge blocked: required status checks have not passedgh pr checks NUMBERWhich required checks are failing or pendingFix the failing job (gh run view --log-failed), push, wait for green, then merge
'HTTP 403' or 'Resource not accessible' on repo/PR writesgh auth status (inspect token scopes)Whether the token lacks the 'repo'/'workflow' scope or repo accessgh auth refresh -s repo,workflow to add scopes, or get write access to the repo
gh pr create says 'must be on a branch to create a pull request'git branch --show-currentWhether you are on main/detached HEAD with nothing to compareCreate a feature branch, commit, git push -u origin BRANCH, then gh pr create