Most read operations work without authentication, but anything that writes data (creating issues, PRs, pushing code) requires you to log in first.

Logging In

gh auth login

This starts an interactive flow:

1. Choose the host — github.com or GitHub Enterprise Server
2. Choose the authentication method:
   • Web browser (recommended) — generates a one-time code, opens your browser, and authenticates via OAuth
   • Paste a token — useful for CI/CD, scripts, or custom permission scopes
3. Choose the default Git protocol — HTTPS or SSH

Non-Interactive Login

For scripts and CI environments, skip the prompts:

# Login with a token from stdin
echo $MY_TOKEN | gh auth login --with-token
 
# Login with specific options
gh auth login --hostname github.com --git-protocol ssh --web

Checking Auth Status

gh auth status

Output shows:

• Which host you are authenticated to
• Your GitHub username
• The token type and scopes
• The Git protocol in use

Switching Accounts

If you have multiple GitHub accounts (e.g., personal and work):

# Add another account
gh auth login
 
# Switch between accounts
gh auth switch
 
# Switch to a specific account on a specific host
gh auth switch --hostname github.com --user mywork

Refreshing Tokens

If your token expires or you need additional permission scopes:

# Refresh with an interactive browser flow
gh auth refresh
 
# Add a specific scope
gh auth refresh --scopes repo,read:org
 
# Add the project scope (required for gh project commands)
gh auth refresh -s project

Viewing Your Token

gh auth token

This prints the raw token to stdout — useful for piping into other tools:

# Use the token with curl
curl -H "Authorization: token $(gh auth token)" https://api.github.com/user

Configuring Git Credentials

gh auth setup-git

This configures git to use gh as a credential helper, so git push, git pull, etc. automatically use your gh token.

Logging Out

gh auth logout
 
# Log out of a specific host
gh auth logout --hostname github.com

Where Tokens Are Stored

Configuration files live in ~/.config/gh/ (or $GH_CONFIG_DIR if set):

Security warning: Never share or commit your token. If you accidentally expose it, run gh auth refresh immediately to rotate it.

Token Scopes

When creating a personal access token manually (Settings → Developer settings → Tokens), enable at least:

The browser-based login flow automatically requests the scopes gh needs.

Exercises

1. Run gh auth login and authenticate via the browser flow
2. Run gh auth status and confirm your username appears
3. Run gh auth setup-git to configure Git credential integration
4. Run gh auth token and verify a token is printed (do not share it!)