A Safe First Workflow with gh, the GitHub CLI

gh can authenticate, inspect a repository, clone it and review pull requests, all from one binary. The credential it stores deserves the same care as any other login, so this walkthrough covers all four in order. The local command is gh version 2.87.3, from the installed Ubuntu package.

Allow about fifteen minutes. You need a shell, the gh package, a GitHub account for private work, and network access for commands that contact GitHub. None of the examples needs sudo. Commands that only print help or status are read-only; cloning creates files locally.

1. Confirm Which gh You Are Running

Start with the version and the top-level command list. This catches an unexpected binary before it handles credentials or repository data:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh --help

The manual uses the general shape gh <command> <subcommand> [flags]. Available commands depend on the installed release, so read the help for the command you are about to use rather than relying on a remembered flag.

Checkpoint: If command -v gh points into an unexpected virtual environment or home directory, stop and inspect your PATH. Do not enter a token until you know which executable will receive it.

2. Authenticate Without Printing a Token

For an interactive machine, use the browser flow:

$ gh auth login --hostname github.com --web

Follow the prompts and choose the Git protocol that matches how you want Git operations to work; the default host is github.com. A successful login stores an authentication token in the system credential store when one is available. If no suitable store exists, gh can fall back to a plain-text file, so check the result and the host's local permissions before using the machine for shared work.

Headless automation is a different case. The installed help recommends supplying a fine-grained token through the GH_TOKEN environment variable. Keep it out of shell history, process listings and logs.

Warning: Do not paste a real token into a command shown in documentation, and do not run gh auth status --show-token on a shared terminal: that option deliberately prints the token.

Verify the account without revealing the token:

$ gh auth status --active --hostname github.com
github.com
  ✓ Logged in to github.com account ACCOUNT_NAME
  - Active account: true
  - Git operations protocol: https

Your account name and protocol will differ. A non-zero status means authentication needs attention. With several hosts or accounts, use --hostname and --active so you do not end up checking the wrong one.

3. Inspect a Repository Before Cloning

Use a repository's full owner and name when the target matters:

$ gh repo view OWNER/REPOSITORY
$ gh repo view OWNER/REPOSITORY --json nameWithOwner,description,defaultBranchRef,isPrivate

The first command shows a human-readable description and README. The second asks for selected fields, easier to review in a script than a long formatted page. Replace both uppercase placeholders with a real repository. A private repository still needs an account with access; a successful login is not permission to every repository.

Check the protocol before making a clone:

$ gh config get git_protocol
https

If the setting is empty or different, an explicit URL also selects the protocol. Do not change a shared account's configuration casually: gh config set git_protocol ssh affects every later Git operation for that host.

4. Clone into a Deliberate Directory

Cloning is the first example here that changes local state. Choose a destination you have checked, then run:

$ gh repo clone OWNER/REPOSITORY WORKSPACE/REPOSITORY
Cloning into 'WORKSPACE/REPOSITORY'...
$ cd WORKSPACE/REPOSITORY
$ git remote -v
$ git status --short

The destination must not be a directory holding work you want to preserve. A fork can pick up an additional upstream remote, so inspect git remote -v before pushing or fetching. The clone uses the configured Git protocol unless the repository argument includes an explicit https:// or SSH URL.

Recovery: If this was only a test, leave the repository directory alone until you have checked it. To remove a disposable clone, move outside it, verify the printed path, then remove that exact directory with your normal file-management tool. Deleting a directory is irreversible and is not a job for sudo.

5. Review Open Pull Requests Without Changing Branches

From the cloned repository, list the open pull requests. This reads remote data and does not check anything out:

$ gh pr list --limit 10
$ gh pr view 123 --json number,title,state,author,reviewDecision,statusCheckRollup

gh pr list shows open pull requests by default and fetches up to 30 unless you change --limit. Use --state all for closed or merged items, and --repo OWNER/REPOSITORY when the current directory is not the repository you mean.

Before treating a pull request as ready, read its title and body, review the changed files, and check the status fields gh pr view returns. A green-looking summary is not a substitute for understanding what will change.

Warning: Do not run gh pr merge, gh pr close or gh pr checkout as a casual follow-up. Those commands change remote or local state and need a separate decision.

Common traps

Done means