Getting started with the command line tool for version control requires establishing a secure connection to your account. You can connect your terminal to your remote repositories by using the official authentication flow, which removes the need to manually handle personal access tokens for every single action.
To complete this connection, you'll run the core login command in your terminal and follow the interactive prompts in your browser or supply a token directly. This setup process takes less than two minutes and grants you the ability to manage issues, pull requests, and workflows straight from your local environment.
Installing the Command Line Tool
Before you can connect your account, you must install the official tool on your operating system. The package name is gh, and it's available across all major platforms. You shouldn't confuse it with older third-party packages because the official binary is maintained directly by the platform team.
On macOS, you can install the package using Homebrew with a simple terminal command:
brew install gh
On Ubuntu or Debian Linux, you'll set up the official repository key and install the package using your package manager:
type -p curl >/dev/null || sudo apt install curl -y
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo-tee /etc/apt/sources.list.d/github-client.list > /dev/null
sudo apt update
sudo apt install gh
On Windows, you can use winget from your command prompt or PowerShell:
winget install --id GitHub.cli
You can verify that the installation succeeded by checking the version number in your terminal window:
gh --version
Running the Interactive Login Process
Once the utility is installed, you're ready to start the authentication workflow. The primary command for this task is gh auth login. When you execute this command, you'll answer a few interactive prompts that configure how your local machine communicates with the remote server.
Run the login command in your terminal:
gh auth login
The terminal will ask you to choose your account type. You'll select whether you use the standard public hosting service or an enterprise server instance. Next, you'll choose your preferred protocol for Git operations. Most developers choose HTTPS because it avoids complex SSH key configuration, though SSH remains a solid choice if you've already set up your public keys.
After making those selections, the utility will ask how you want to authenticate. You can choose to log in through a web browser or paste an authentication token directly. Choosing the web browser method is the fastest route for most users.
Completing Browser-Based Authentication
When you choose the web browser option, the tool generates a one-time eight-character code and prints it in your terminal. It will attempt to open your default web browser automatically to the verification page.
- Copy the one-time code shown in your terminal if it hasn't been copied automatically.
- Confirm that the code matches what appears on your browser screen.
- Grant permissions to the application so it can read and write repository data on your behalf.
- Return to your terminal once the browser confirms a successful connection.
The terminal will display a success message confirming that you're logged in as your specific username. At this point, the application securely stores your authentication credentials in your operating system's native credential store, such as the macOS Keychain or Windows Credential Manager. You won't need to log in again unless your token is revoked.
Configuring Git Credentials
Logging into the tool doesn't automatically configure your local Git client to use those credentials for pushes and pulls. If you want to run standard Git commands without managing separate passwords or tokens, you need to run an extra setup command.
Configure Git to use your credentials by running:
gh auth setup-git
This command updates your local Git configuration file so that standard operations like git push and git pull use your authenticated session automatically. It's a massive timesaver that prevents authentication errors when working with private repositories.
Managing Automated Environments and Scripts
If you're running commands inside an automated CI/CD pipeline or a headless server, you can't use an interactive browser login. Instead, you must authenticate using environment variables.
You'll generate a fine-grained personal access token from your account settings page on GitHub and assign it to a specific environment variable before running your scripts.
Set the token in your current terminal session like this:
export GH_TOKEN="your_personal_access_token_here"
When this environment variable is present, the tool automatically detects it and uses it for all API requests without writing any sensitive data to your disk. If you're building workflows using GitHub Actions, you don't even need to generate a manual token because the environment provides one automatically through the built-in context.
Troubleshooting Common Connection Errors
Sometimes authentication fails due to expired tokens, mismatched permissions, or network blocks. Knowing how to check your current status saves you hours of frustration.
You can inspect your active connection details by running:
gh auth status
This command displays which accounts are currently active, which host you're connected to, and whether your token has sufficient scopes. If you notice that your token lacks permissions for specific actions like managing workflows or reading packages, you can update your scopes without logging out entirely:
gh auth refresh --scopes repo,workflow
If your credentials become corrupted or you want to switch accounts completely, you can log out and clear all stored data by running:
gh auth logout
Frequently Asked Questions
Where does the tool store my authentication credentials?
By default, your credentials go into your operating system's secure keyring or credential manager. If your system doesn't have a supported keyring, the tool falls back to a configuration file, though it always restricts file permissions to protect your data.
How do I check if my current session is still valid?
You can run gh auth status at any time. This command pings the remote server and reports whether your token is active, expired, or missing necessary permission scopes.
Can I stay logged into multiple accounts at once?
Yes, you can log into multiple hosts, such as your personal account on the public platform and an enterprise instance on a separate server. However, each individual host supports only one active user session at a time.
What should I do if my token is compromised?
You should immediately navigate to your account security settings on the web platform, locate your personal access tokens or authorized OAuth apps, and revoke the compromised token. Afterward, run gh auth logout locally and sign in again with a fresh credential.
