GitHub CLI: what every Git & GitHub developer should know

Introduction

Most of us spend our days context-switching between the terminal and the GitHub web interface, losing momentum every time we need to open a browser to create a PR or check on an issue. GitHub CLI: what every Git & GitHub developer should know is about reclaiming that flow—staying in the terminal where we're already comfortable, and handling the full GitHub workflow without leaving your editor or shell. In this guide, we'll walk through the essentials that will make you faster and more efficient.

What is GitHub CLI and Why It Matters

GitHub CLI (gh) is a command-line interface that brings GitHub operations directly into your terminal. Instead of reaching for the mouse to navigate the web UI, you can create PRs, manage issues, run workflows, and deploy—all without breaking your keyboard rhythm. For teams working in fast-paced environments like e-commerce or SaaS, this means fewer context switches and fewer mistakes. We've found that teams who adopt gh early tend to have tighter feedback loops and faster code review cycles.

The tool is built by GitHub and integrates natively with your local git setup. It respects your existing repository configuration and uses the same authentication that git uses, so there's minimal setup friction.

Install and Authenticate

Getting started is straightforward. On macOS with Homebrew, install with:

brew install gh

On Linux, use your package manager (apt, dnf, pacman, etc.), or download the binary directly from the releases page. Windows users can use Homebrew, Scoop, Chocolatey, or the MSI installer.

Once installed, authenticate with:

gh auth login

This opens an interactive prompt. Choose GitHub.com (unless you're on GitHub Enterprise), select HTTPS or SSH based on your setup, and authenticate via the browser. The CLI will save your authentication token securely—on most systems using the OS credential manager (keychain on macOS, credential-manager-core on Windows).

Verify your setup by checking your authenticated user:

gh auth status

You should see output confirming your username and the login host. This single command eliminates the need to generate personal access tokens manually and manage them in config files. We recommend running this when onboarding new team members—it's fast and removes a common friction point.

Working with Pull Requests

Pull requests are where code review happens. The gh CLI makes creating, checking out, and merging PRs a matter of seconds, keeping you in the terminal where you're already working.

Create a Pull Request

After pushing your branch, create a PR with:

gh pr create --fill

The --fill flag automatically populates the PR title from your commit message and body from your branch description (if you've set one). This is perfect for straightforward changes. If you need more control, omit the flag and you'll be prompted interactively:

gh pr create --title "Add user caching layer" --body "Reduces database load by 40%" --reviewer @john-team --assignee @me

You can assign reviewers, add labels, link issues, and set the base branch, all from the command line. For teams practicing code ownership (using CODEOWNERS files), gh respects those and suggests reviewers automatically when you use --fill.

Check Out a Pull Request Locally

Instead of manually creating a local branch and pulling down someone's PR to review it, use:

gh pr checkout 123

Replace 123 with the PR number. This fetches the branch, checks it out, and sets up tracking—all in one command. You can now test the code, run the test suite, or make suggestions. This workflow is invaluable during intense review periods; we've cut review turnaround times by 15–20% just by eliminating the manual branch setup step.

Merge and Clean Up

Once approved, merge directly from the CLI:

gh pr merge 123 --squash

The --squash flag combines commits into one, keeping your main branch history clean. You can also use --rebase or --merge depending on your team's preferences. The PR is automatically closed and the remote branch deleted if you pass --delete-branch.

For teams on a release cadence, this standardization prevents accidental merge-commit pollution and keeps everyone aligned on commit hygiene.

Managing Issues

Issues track bugs, feature requests, and tasks. The CLI lets you list, create, and manage them without touching the web UI.

List Issues with Filters

Get a quick overview of open issues in your repository:

gh issue list

Filter by state, assignee, label, or milestone:

gh issue list --state open --assignee @me --label "bug"

Output shows the issue number, title, and state. For a more detailed view, add the --json flag to export as JSON, which you can pipe into jq for further processing.

Create an Issue Programmatically

Create issues from the terminal:

gh issue create --title "Database connection pool exhausted" --body "Observed on 2025-01-15 at 14:30 UTC in production. Rate limit spike correlates with new cron job."<p></p>

<p>This is especially useful in automation—for example, if a monitoring alert fires, you can have a script create an issue with structured details before your team even knows there's a problem. In one e-commerce deployment we worked on, a failed deployment hook automatically created an issue and pinged the on-call engineer, cutting MTTR from 30 minutes to under 5.</p>

<h2 id="monitoring-github-actions-workflows">Monitoring GitHub Actions Workflows</h2>

<p>GitHub Actions automate testing, deployment, and other CI/CD tasks. The CLI lets you watch workflows run without polling the web UI.</p>

<h3>Watch Workflow Runs in Real Time</h3>

<p>After pushing a commit, follow the workflow run:</p>

<pre><code class="language-bash">gh run watch

This command picks up the latest run for your current branch and streams logs as jobs complete. You see job names, status, and durations, and can jump to logs on GitHub if needed. If you need to watch a specific run, get its ID first:

gh run list --limit 5

Then watch it:

gh run watch 789456

For fast-moving teams, this eliminates the context switch to the browser and keeps you focused on the terminal. We've found that engineers who adopt this tend to catch and fix CI failures faster because the feedback is immediate and local.

View and Debug Logs

If a job fails, pull its logs:

gh run view 789456 --log

This streams the full log to your terminal, searchable and pipeable. You can grep for errors, tail the end, or save to a file for later analysis.

Common Mistakes

• Forgetting to set up SSH or HTTPS correctly before authenticating. If your git config uses SSH but you authenticated gh with HTTPS (or vice versa), you may hit permission errors. Run gh auth status to check your auth method, and ensure your local git config aligns.
• Using --fill when your commit message is vague. The flag is powerful but relies on good commit messages. If your branch has a commit that just says "fix," your PR will too. Spend the 10 seconds writing a clear message upfront.
• Not checking out PRs locally before approving. The web UI diff is helpful, but running the code (tests, linter, actual feature) catches issues the diff won't. Use gh pr checkout before approving.
• Ignoring issue templates. Many teams have issue templates to structure bug reports and features. The CLI respects these, but you have to use the interactive mode (omit --title and --body flags) to see them.
• Assuming gh run watch waits for a new run. The command watches the latest run on your current branch. If no run is active, it exits. You need to trigger a workflow (push a commit, manually trigger via the web UI) before watching.

Key Takeaways

• GitHub CLI keeps you in the terminal for the full GitHub workflow—authentication, PR creation and review, issue management, and CI/CD monitoring.
• Use gh auth login once to set up secure, OS-level credential storage. No manual token juggling.
• gh pr create --fill and gh pr checkout are the workhorse commands; they eliminate context switches and reduce review cycle time.
• gh issue list and gh issue create keep your task management terminal-native, useful for scripting and automation.
• gh run watch brings CI/CD feedback into your shell, letting you catch failures and debug faster without browser tabs.
• Combine gh commands with shell pipes and jq to build custom scripts for your team's workflow—e.g., auto-creating issues from alerts or bulk-closing stale PRs.