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 are
gh auth statusShows the logged-in account, host, and token scopes for each GitHub host.Open a PR
gh pr create --fillCreates a PR from the current branch, taking title and body from your commits.Check out a PR
gh pr checkout NUMBERFetches PR #NUMBER into a local branch so you can test or review it.Watch a CI run
gh run watchLive-tails the most recent Actions run until it finishes, then exits with its status.Merge a PR
gh pr merge --squash --delete-branchSquash-merges the PR and deletes the head branch. Changes the remote — see tasks.The pull request lifecycle through gh
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
| Task | Command | What to check |
|---|---|---|
| Log in interactively | gh auth login | gh auth status prints 'Logged in to github.com as USER' |
| Confirm identity and scopes | gh auth status | Correct account and host shown; token scopes include 'repo' |
| Clone a repo | gh repo clone OWNER/REPO | Directory REPO exists with a configured origin remote |
| Inspect a repo in the terminal | gh repo view OWNER/REPO | README and metadata render in the pager |
| Create a repo from the current folder | gh repo create REPO --private --source=. --push | gh repo view shows the new private repo with your commits |
| Open a PR from the current branch | gh pr create --fill --base main | Command prints the new PR URL |
| List open PRs | gh pr list | Table of open PRs with numbers, titles, and branches |
| Read a PR and its diff | gh pr view NUMBER && gh pr diff NUMBER | PR body, checks, and unified diff are shown |
| Check out someone's PR to test it | gh pr checkout NUMBER | git branch shows you on the PR's head branch |
| Review a PR | gh pr review NUMBER --approve -b "LGTM" | gh pr view NUMBER lists your approval under Reviews |
| Watch CI for a PR's checks | gh pr checks NUMBER --watch | All required checks resolve to pass before the command exits |
| [REMOTE] Merge the PR | gh pr merge NUMBER --squash --delete-branch | gh pr view NUMBER shows state MERGED |
| List and watch Actions runs | gh run list && gh run watch | Latest run streams to completion with a conclusion |
| Re-run a failed workflow | gh run rerun RUN_ID --failed | gh 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/423
Wait for required checks to go green
gh pr checks 42 --watch
# All checks were successful
# 3 successful, 0 failing4
Optionally self-review the diff before merging
gh pr diff 42
# unified diff of the PR's changes5
Squash-merge and delete the head branch
gh pr merge 42 --squash --delete-branch
# Merged pull request #42
# Deleted branch feat/add-search6
Verify the PR is merged
gh pr view 42
# state: MERGED base: mainTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| 'gh: To get started with GitHub CLI, please run gh auth login' | gh auth status | Whether any credentials exist for the target host | Run gh auth login and complete the browser or token flow |
| Commands hit the wrong account or GitHub Enterprise host | gh auth status (shows every host and active account) | Which account/host is active for API calls | gh 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 base | gh pr checkout NUMBER, rebase or merge base, resolve, push; then retry merge |
| Merge blocked: required status checks have not passed | gh pr checks NUMBER | Which required checks are failing or pending | Fix the failing job (gh run view --log-failed), push, wait for green, then merge |
| 'HTTP 403' or 'Resource not accessible' on repo/PR writes | gh auth status (inspect token scopes) | Whether the token lacks the 'repo'/'workflow' scope or repo access | gh 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-current | Whether you are on main/detached HEAD with nothing to compare | Create a feature branch, commit, git push -u origin BRANCH, then gh pr create |
References
- GitHub CLI manual (gh)cli.github.com
- gh pr command referencecli.github.com
- gh run command referencecli.github.com
- gh auth command referencecli.github.com
- Using GitHub CLI (GitHub Docs)docs.github.com