GitHub 23 🌐 GitHub CLI (gh) Usage and Terminal Workflows - KandZ

⏱️ Estimated read: 9 min | |

The GitHub CLI (gh) is the official command-line interface for GitHub. It brings the platform’s core operations—repositories, issues, pull requests, Actions, releases—into the terminal, where they can be scripted, aliased, and composed. For the exam, the critical distinction is between gh and git: git manages the local repository and its history; gh manages the GitHub platform and its resources. A git push sends commits to a remote; a gh pr create opens a pull request on that remote. The two are complementary, not interchangeable.

Key point: gh auth login is the first command. It stores a token in the system keyring and grants the scopes needed for subsequent commands. Without authentication, every gh command fails. For automation, the GH_TOKEN environment variable bypasses the interactive login.

Why the GitHub CLI exists

The context-switching problem. A developer’s workflow spans the terminal and the browser. Code is written in the terminal, but a pull request is reviewed in the browser, an issue is triaged in the browser, and a release is published in the browser. Each switch costs attention. gh collapses these operations into the terminal, where they can be scripted and combined with git commands .

The scripting problem. The GitHub REST API can be called with curl, but constructing headers, handling pagination, and parsing JSON is tedious. gh api wraps the API with authentication and sane defaults. gh pr list --json number,title --jq '.[]' produces structured output that can be piped into other tools .

The Actions problem. Triggering a workflow, watching a run, and downloading its artifacts are three separate API calls. gh workflow run, gh run watch, and gh run download are single commands. They make CI/CD operations as accessible as git push .

The alias problem. Frequently used commands can be shortened with gh alias set. gh alias set pv 'pr view' means gh pv is equivalent to gh pr view. The alias system reduces the verbosity that plagues complex CLI tools .

The trade-off. gh requires installation and authentication. git ships with the operating system. For a one-off repository clone, git clone is sufficient. For the full platform workflow—issues, pull requests, Actions, releases—gh is the tool that eliminates the browser round-trip.

a. Authentication and configuration

The first command is gh auth login. It prompts for the host (github.com or GitHub Enterprise), the authentication method (browser or token), and the scopes. The browser flow opens a page, generates a one-time code, and stores the resulting token in the system keyring .

# Interactive login
gh auth login

# Login with workflow scope (required to push workflow files)
gh auth login -s workflow

# Verify authentication
gh auth status

# Non-interactive login for scripts
export GH_TOKEN="ghp_xxxxxxxxxxxx"

The workflow scope is a common stumbling block. Without it, pushing changes to .github/workflows/ fails with “refusing to allow an OAuth App to create or update workflow.” The -s workflow flag grants the scope at login. The gh auth refresh -s workflow command adds it to an existing token .

For automation, the GH_TOKEN environment variable is respected by every gh command. This is the correct approach for CI pipelines and scripts, where interactive login is impossible .

b. Repositories, issues, and pull requests

The core workflow commands mirror the website. gh repo create creates a repository and optionally clones it. gh issue create opens an issue. gh pr create opens a pull request, and gh pr merge merges it.

# Create and clone a repository
gh repo create my-project --public --clone

# Create an issue
gh issue create --title "Bug: login fails" --body "Steps to reproduce..." --label bug

# Create a pull request (auto-fill from commits)
gh pr create --fill

# Check PR status
gh pr status

# Merge a PR (squash)
gh pr merge 42 --squash

# Check CI status before merging
gh pr checks 42

The --fill flag on gh pr create auto-populates the title and body from the commit messages on the branch. This eliminates the most tedious part of the PR creation workflow . The gh pr checkout <number> command switches the local repository to the PR’s branch, enabling local testing before review .

c. GitHub Actions and releases

The Actions commands provide terminal access to workflow runs. gh run list shows recent runs. gh run view shows details. gh run watch follows a run in real time. gh run download retrieves artifacts.

# List workflow runs
gh run list

# Watch a specific run
gh run watch 123456789

# Rerun failed jobs
gh run rerun 123456789 --failed

# Download artifacts
gh run download 123456789 --name build

# Trigger a workflow manually
gh workflow run ci.yml --ref main -f environment=staging

The gh workflow run command requires the workflow to have a workflow_dispatch trigger. The -f flag passes inputs as key-value pairs .

The release commands create a release from a tag, optionally generating notes from merged pull requests.

# Create a release with auto-generated notes
gh release create v1.0.0 --generate-notes

# Create a draft release
gh release create v1.0.0 --draft --generate-notes

# View the latest release
gh release view

The --generate-notes flag uses GitHub’s Release Notes API to produce a changelog from merged PRs. The --draft flag keeps the release unpublished until it is manually published .

Complete Example Session

# ============================================
# PART 1: AUTHENTICATE
# ============================================

gh auth login
# Select: GitHub.com
# Select: Login with a web browser
# Copy the one-time code and paste in browser
# Authentication complete.

# ============================================
# PART 2: VERIFY AUTHENTICATION
# ============================================

gh auth status
# Logged in to github.com as USERNAME
# Token scopes: 'repo', 'read:org', 'workflow'

# ============================================
# PART 3: CREATE A REPOSITORY
# ============================================

gh repo create my-cli-project --public --clone
# Repository created and cloned locally.
cd my-cli-project

# ============================================
# PART 4: CREATE AN ISSUE
# ============================================

gh issue create --title "Add authentication" --body "Implement OAuth flow" --label enhancement
# Issue #1 created.

# ============================================
# PART 5: CREATE A PULL REQUEST
# ============================================

git checkout -b feature/auth
# Make changes...
git add .
git commit -m "Add OAuth authentication"
git push -u origin feature/auth

gh pr create --fill
# Pull request #2 created with title and body from commit.

# ============================================
# PART 6: CHECK CI STATUS
# ============================================

gh pr checks 2
# All checks passed.

# ============================================
# PART 7: MERGE THE PR
# ============================================

gh pr merge 2 --squash --delete-branch
# PR merged and branch deleted.

# ============================================
# PART 8: CREATE A RELEASE
# ============================================

git tag -a v1.0.0 -m "First release"
git push origin v1.0.0

gh release create v1.0.0 --generate-notes
# Release created with auto-generated notes.

# ============================================
# PART 9: TRIGGER A WORKFLOW
# ============================================

gh workflow run deploy.yml --ref main -f environment=staging
# Workflow triggered.
gh run watch
# Watching run in real time.

The nine parts trace the gh lifecycle: authentication, verification, repository creation, issue creation, pull request creation, CI check, merge, release, and workflow trigger. Each command replaces a browser interaction.

Quick Reference

Authentication

Command	Purpose
`gh auth login`	Interactive login
`gh auth login -s workflow`	Login with workflow scope
`gh auth status`	Verify authentication
`gh auth refresh -s workflow`	Add scope to existing token

Repository and Issues

Command	Purpose
`gh repo create <name> --clone`	Create and clone
`gh repo view <owner/repo>`	View repository details
`gh issue create --title "..."`	Create issue
`gh issue list --label bug`	List issues by label

Pull Requests

Command	Purpose
`gh pr create --fill`	Create PR from commits
`gh pr status`	Check PR status
`gh pr checks <number>`	Check CI status
`gh pr merge <number> --squash`	Merge with squash
`gh pr checkout <number>`	Switch to PR branch

Actions

Command	Purpose
`gh run list`	List workflow runs
`gh run watch <id>`	Watch run in real time
`gh run rerun <id> --failed`	Rerun failed jobs
`gh workflow run <file>`	Trigger workflow manually

Releases

Command	Purpose
`gh release create <tag> --generate-notes`	Create release with auto notes
`gh release view`	View latest release
`gh release list`	List releases

Best Practices

✅ Do This:

gh auth login -s workflow
<!-- Grant workflow scope at login -->                # ✅

gh pr create --fill
<!-- Auto-populate PR from commits -->                # ✅

gh pr checks 42
<!-- Verify CI before merging -->                    # ✅

❌ Don’t Do This:

# Use gh without authentication
<!-- Every command fails -->                          # ❌

# Merge a PR without checking CI
<!-- gh pr checks should pass first -->              # ❌

# Hardcode GH_TOKEN in scripts
<!-- Use environment variables securely -->          # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
`not logged in`	No authentication	`gh auth login`
Push fails on workflow file	Missing `workflow` scope	`gh auth refresh -s workflow`
`gh pr create` fails	No commits on branch	Commit before creating PR
Workflow not found	File not in `.github/workflows/`	Verify path
`gh run watch` hangs	Run is queued or waiting	Check `gh run list` first

Real-World Examples

1. Login with Workflow Scope

gh auth login -s workflow

2. Create Repository

gh repo create my-app --public --clone

3. Create Issue

gh issue create --title "Bug" --label bug

4. Create PR from Commits

gh pr create --fill

5. Check CI

gh pr checks 42

6. Merge PR

gh pr merge 42 --squash --delete-branch

7. List Runs

gh run list

8. Watch Run

gh run watch 123456789

9. Download Artifact

gh run download 123456789 --name build

10. Create Release

gh release create v1.0.0 --generate-notes

Visual

gh vs git

┌──────────────────────────────────────────────┐
│  git                                         │
│  ├── Local repository management            │
│  ├── Commit history                         │
│  ├── Branch and merge                       │
│  └── Push to remote                         │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  gh                                          │
│  ├── Platform operations                    │
│  ├── Issues, PRs, Actions                   │
│  ├── Releases, packages                     │
│  └── API wrapper                            │
└──────────────────────────────────────────────┘

git manages the code. gh manages the platform.

PR Workflow

git push origin feature
        │
        ▼
gh pr create --fill
        │
        ▼
gh pr checks 42
        │
        ▼
gh pr merge 42 --squash
        │
        ▼
gh release create v1.0.0 --generate-notes

The entire workflow is terminal-native.

Summary

Item	Value
CLI tool	`gh`
Authentication	`gh auth login`
Workflow scope	`-s workflow`
Create PR from commits	`gh pr create --fill`
Check CI	`gh pr checks <number>`
Merge PR	`gh pr merge <number> --squash`
Trigger workflow	`gh workflow run <file>`
Create release	`gh release create <tag> --generate-notes`
Non-interactive auth	`GH_TOKEN` environment variable

Key takeaways:

gh is the platform CLI, not the Git CLI. git manages local history; gh manages GitHub resources. They are used together, not interchangeably.
Authentication is the prerequisite. gh auth login stores a token in the keyring. The workflow scope is required to push changes to .github/workflows/ .
--fill eliminates PR boilerplate. gh pr create --fill auto-populates the title and body from commit messages, reducing the friction of opening a pull request .
CI status is a first-class command. gh pr checks shows whether the pull request is ready to merge. It is the terminal equivalent of the green checkmark on the website.
Actions are fully accessible. gh run list, gh run watch, gh run rerun, and gh workflow run provide the entire CI/CD workflow from the terminal .

Remember: gh is the bridge between the terminal and the GitHub platform. It does not replace git; it extends it. The git commands manage the code, and the gh commands manage the platform. Together, they eliminate the browser from the development loop.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!