github-cli-reference

name	github-cli-reference
description	Complete reference for GitHub CLI (gh) installation, authentication, and usage in Claude Code environment
type	reference
scope	project

GitHub CLI Reference

Purpose

Provide comprehensive, copy-paste ready instructions for GitHub CLI (gh) installation and usage to prevent common mistakes like missing full paths or forgetting GITHUB_TOKEN environment variable prefix.

Activation cues

• Requests to use GitHub CLI or gh commands
• Questions about GitHub API, PRs, issues, workflows
• Pull request operations (list, view, create, merge)
• GitHub repository queries
• Workflow run checks
• GitHub API operations
• Authentication errors or "command not found" errors

Installation (One-Time Setup)

Step 0: Check if Already Installed

if [ -f ~/.local/bin/gh ]; then
    echo "✅ gh CLI already installed"
    ~/.local/bin/gh --version
else
    echo "gh CLI not found, proceeding with installation..."
fi

Step 1: Download and Extract (Complies with TEMPORARY FILE ISOLATION)

# Only install if not already present
if [ ! -f ~/.local/bin/gh ]; then
    # Use mktemp for unique temporary directory (CLAUDE.md policy compliance)
    TMP_GH_DIR="$(mktemp -d)"
    cd "$TMP_GH_DIR"
    curl -sL https://github.com/cli/cli/releases/download/v2.40.1/gh_2.40.1_linux_amd64.tar.gz -o gh.tar.gz
    tar -xzf gh.tar.gz
    mkdir -p ~/.local/bin
    cp gh_2.40.1_linux_amd64/bin/gh ~/.local/bin/gh
    chmod +x ~/.local/bin/gh
    cd - > /dev/null
    rm -rf "$TMP_GH_DIR"
fi

Step 2: Verify Installation

~/.local/bin/gh --version

Expected output: gh version 2.40.1 (2023-12-13)

Step 3: Test Authentication

~/.local/bin/gh auth status

Expected output: ✓ Logged in to github.com account <username> (GITHUB_TOKEN) Note: GitHub CLI automatically uses the GITHUB_TOKEN environment variable - no prefix needed!

Critical Usage Rules

✅ ALWAYS Do This:

1. Use full path: ~/.local/bin/gh (installed to user bin, not /tmp)
2. GITHUB_TOKEN automatic: No prefix needed - gh automatically uses environment variable
3. Specify repo: Add --repo jleechanorg/worldarchitect.ai for clarity

❌ NEVER Do This:

1. Don't use: Just gh (it's not in PATH unless you add ~/.local/bin)
2. Don't use /tmp: Install to ~/.local/bin to comply with TEMPORARY FILE ISOLATION policy
3. Don't add redundant prefix: GITHUB_TOKEN=$GITHUB_TOKEN is unnecessary

Command Reference

Authentication & Status

Check auth status

~/.local/bin/gh auth status

Check API rate limit

~/.local/bin/gh api rate_limit --jq '.rate | {limit: .limit, remaining: .remaining}'

Repository Operations

View repository info

~/.local/bin/gh repo view jleechanorg/worldarchitect.ai

View repository info (JSON)

~/.local/bin/gh repo view jleechanorg/worldarchitect.ai --json name,owner,isPrivate,defaultBranchRef,description

List branches

~/.local/bin/gh api repos/jleechanorg/worldarchitect.ai/branches --jq '.[0:10] | .[] | {name: .name, protected: .protected}'

Pull Request Operations

List open PRs

~/.local/bin/gh pr list --repo jleechanorg/worldarchitect.ai --state open --limit 10

List all PRs (including closed)

~/.local/bin/gh pr list --repo jleechanorg/worldarchitect.ai --state all --limit 20

View specific PR

~/.local/bin/gh pr view <PR_NUMBER> --repo jleechanorg/worldarchitect.ai

View PR with JSON output

~/.local/bin/gh pr view <PR_NUMBER> --repo jleechanorg/worldarchitect.ai --json number,title,state,author,createdAt,body

View PR checks/status

~/.local/bin/gh pr checks <PR_NUMBER> --repo jleechanorg/worldarchitect.ai

Create PR

~/.local/bin/gh pr create --repo jleechanorg/worldarchitect.ai --title "PR Title" --body "PR Description"

Create PR (interactive)

~/.local/bin/gh pr create --repo jleechanorg/worldarchitect.ai --fill

Merge PR

~/.local/bin/gh pr merge <PR_NUMBER> --repo jleechanorg/worldarchitect.ai --squash

View PR comments

~/.local/bin/gh api repos/jleechanorg/worldarchitect.ai/pulls/<PR_NUMBER>/comments

Issue Operations

List issues

~/.local/bin/gh issue list --repo jleechanorg/worldarchitect.ai --limit 10

List open issues with labels

~/.local/bin/gh issue list --repo jleechanorg/worldarchitect.ai --state open --label bug --limit 10

View specific issue

~/.local/bin/gh issue view <ISSUE_NUMBER> --repo jleechanorg/worldarchitect.ai

Create issue

~/.local/bin/gh issue create --repo jleechanorg/worldarchitect.ai --title "Issue Title" --body "Issue Description"

Workflow Operations

List workflows

~/.local/bin/gh workflow list --repo jleechanorg/worldarchitect.ai

List workflow runs

~/.local/bin/gh run list --repo jleechanorg/worldarchitect.ai --limit 10

List workflow runs for specific workflow

~/.local/bin/gh run list --repo jleechanorg/worldarchitect.ai --workflow "Workflow Name" --limit 10

View workflow run details

~/.local/bin/gh run view <RUN_ID> --repo jleechanorg/worldarchitect.ai

Watch workflow run

~/.local/bin/gh run watch <RUN_ID> --repo jleechanorg/worldarchitect.ai

Label Operations

List labels

~/.local/bin/gh label list --repo jleechanorg/worldarchitect.ai

Create label

~/.local/bin/gh label create "label-name" --repo jleechanorg/worldarchitect.ai --description "Label description" --color "ff0000"

GitHub API Direct Access

Get user info

~/.local/bin/gh api user --jq '.login'

Get latest commit on main

~/.local/bin/gh api repos/jleechanorg/worldarchitect.ai/commits/main --jq '{sha: .sha[0:7], author: .commit.author.name, message: .commit.message | split("\n")[0]}'

Get repository collaborators

~/.local/bin/gh api repos/jleechanorg/worldarchitect.ai/collaborators

Get repository topics

~/.local/bin/gh api repos/jleechanorg/worldarchitect.ai/topics

Troubleshooting

Error: "command not found: gh"

Cause: Used gh instead of full path Solution: Always use ~/.local/bin/gh

Error: "You are not logged into any GitHub hosts"

Cause: GITHUB_TOKEN environment variable not set Solution: Verify GITHUB_TOKEN is set with echo $GITHUB_TOKEN (should show token value)

Error: "HTTP 404: Not Found"

Cause: Missing --repo flag or incorrect repo name Solution: Add --repo jleechanorg/worldarchitect.ai to command

Error: "Resource not accessible by integration"

Cause: Token lacks required permissions Solution: Verify token scopes with gh auth status, ensure token has repo scope

Binary not found: "~/.local/bin/gh"

Cause: gh CLI not installed yet Solution: Run installation steps from "Installation (One-Time Setup)" section

Advanced Patterns

Check if gh is installed

if [ -f ~/.local/bin/gh ]; then
    echo "gh CLI is installed"
else
    echo "gh CLI not installed, run installation steps"
fi

Get PR number from current branch

PR_NUMBER=$(~/.local/bin/gh pr list --repo jleechanorg/worldarchitect.ai --head $(git branch --show-current) --json number --jq '.[0].number')
echo "Current branch PR: #$PR_NUMBER"

Check if PR exists for current branch

PR_EXISTS=$(~/.local/bin/gh pr list --repo jleechanorg/worldarchitect.ai --head $(git branch --show-current) --json number --jq 'length')
if [ "$PR_EXISTS" -gt 0 ]; then
    echo "PR exists for current branch"
else
    echo "No PR for current branch"
fi

Get PR status with detailed info

~/.local/bin/gh pr view <PR_NUMBER> --repo jleechanorg/worldarchitect.ai --json number,title,state,isDraft,mergeable,reviewDecision,statusCheckRollup

Environment Variables

GITHUB_TOKEN

• Purpose: Authentication token for GitHub API
• Set automatically: Available as environment variable
• Usage: GitHub CLI automatically uses this environment variable (no manual prefix needed)
• Scopes: Full access (admin:org, repo, workflow, etc.)

Integration with Other Tools

Use with jq for JSON parsing

~/.local/bin/gh pr list --repo jleechanorg/worldarchitect.ai --json number,title --jq '.[] | "\(.number): \(.title)"'

Use in scripts

#!/bin/bash
set -e

# Define gh command
GH="~/.local/bin/gh"
REPO="jleechanorg/worldarchitect.ai"

# Use in script
$GH pr list --repo $REPO --limit 5

Use with grep for filtering

~/.local/bin/gh pr list --repo jleechanorg/worldarchitect.ai | grep "OPEN"

Best Practices

1. Always use full path: Never assume gh is in PATH (use ~/.local/bin/gh)
2. GITHUB_TOKEN automatic: gh CLI automatically uses environment variable (no prefix needed)
3. Always specify --repo: Makes commands explicit and prevents errors
4. Use --json with --jq: For parsing specific fields from responses
5. Check installation first: Verify gh binary exists before using
6. Use --limit: Prevent overwhelming output for list commands
7. Store in variable: Define GH variable in scripts for reusability

Quick Copy-Paste Commands

# Set up gh command variable for easy reuse
GH="~/.local/bin/gh"
REPO="jleechanorg/worldarchitect.ai"

# Now you can use it like this:
$GH pr list --repo $REPO
$GH issue list --repo $REPO
$GH workflow list --repo $REPO

Related Skills

• pr-workflow-manager.md - PR creation and management best practices
• build-test-lint-autopilot.md - Pre-PR validation
• cloud-ops-credential-guard.md - Token and credential management

Reporting Expectations

When using gh CLI, always:

1. Confirm gh binary exists before running commands
2. Include full command with GITHUB_TOKEN prefix in output
3. Show actual output from gh commands
4. Report any errors with full error message
5. Verify authentication status if commands fail