gh-auth

Log in with interactive prompt

$ gh auth login

$ echo [your_token] | gh auth login --with-token

$ gh auth status

$ gh auth logout

$ gh auth login [[-h|--hostname]] [github.example.com]

$ gh auth refresh

$ gh auth refresh [[-s|--scopes]] [repo,admin:repo_hook,admin:org,admin:public_key,admin:org_hook,...]

gh auth <subcommand> [flags]

The primary subcommands are:
login: Log in to GitHub.
logout: Log out of GitHub.
refresh: Refresh authentication scopes.
status: View authentication status.
token: Print the authentication token.

For example, to log in with a web browser:
gh auth login --web
To log in using a Personal Access Token:
gh auth login --pat

--hostname <string>
    Specifies the GitHub host to authenticate against. Defaults to github.com. Useful for GitHub Enterprise instances.

--scopes <strings>
    Requests additional authentication scopes beyond the default set. Scopes define the permissions granted to the GitHub CLI token (e.g., repo, admin:org, gist).

--web
    Authenticates through a web browser. This is the default and recommended method for gh auth login, opening a browser for interactive authentication.

--pat
    Reads a Personal Access Token (PAT) from standard input for authentication. This method is useful for automated scripts or when a browser is unavailable.

--token <string>
    Directly uses the provided string as an authentication token. Less secure for interactive use compared to --pat from stdin or --web.

--git-protocol <string>
    Sets the protocol to use for Git operations cloned by gh (e.g., gh repo clone). Options are https or ssh. Defaults to https.

--no-browser
    Prevents gh auth login from automatically opening a web browser. Useful when using a text-based terminal or for specific authentication flows.

The gh-auth functionality, primarily accessed via the gh auth command and its subcommands, provides a comprehensive interface for authenticating the GitHub CLI (gh) with your GitHub account. It manages the tokens required for the CLI to interact with GitHub APIs, enabling actions like creating pull requests, managing issues, and cloning repositories securely. Users can log in using a web browser flow (the recommended default for ease and security) or by providing a Personal Access Token (PAT). It also allows users to log out, refresh authentication scopes, check their current authentication status, and retrieve their active authentication token. This setup ensures seamless integration of the command-line experience with GitHub.

The gh-auth commands require the GitHub CLI (gh) to be installed and available in your system's PATH. Authentication tokens are securely stored by gh, typically in your system's credential manager. Be mindful of the scopes requested, as they determine the permissions of your CLI token. Using Personal Access Tokens directly should be done with caution, especially in shared environments, due to security implications.

The primary way to authenticate using gh auth login is via a web browser (the default --web flag). This method guides you through the GitHub OAuth flow. Alternatively, you can use a Personal Access Token (PAT) via the --pat flag, where the token is read from standard input, or directly provide it using --token (less recommended for security). The CLI securely stores the obtained token for subsequent commands.

Beyond logging in, gh auth provides commands for managing your session. gh auth status shows your current authenticated user and host, along with granted scopes. gh auth refresh allows you to update your token's scopes without a full re-login. gh auth logout removes your authentication credentials for a given host. gh auth token prints the active authentication token, which can be useful for debugging or integration with other tools.

The authentication capabilities have been an integral part of the GitHub CLI (gh) since its initial public releases. As the CLI matured, the gh auth command group evolved to provide more robust and user-friendly authentication methods, such as the streamlined web browser flow and enhanced token management, adapting to GitHub's API authentication best practices and security requirements.

gh(1), git(1), ssh(1), curl(1)