GitHub CLI: Install, Commands, Agent Usage & Alternatives

92 /100

Excellent for agents when --json, scoped auth, and explicit approval gates are used.

Structured output 96/100

Many repo, issue, PR, release, and API commands support --json fields that agents can parse.

Non-interactive use 88/100

Most read operations run without prompts after auth, but first-time login remains interactive.

Safety boundaries 82/100

Safe read commands are clear, while merge/delete/edit actions need explicit approval and scoped tokens.

Agent docs 86/100

The command surface is discoverable through help output and can be documented cleanly in AGENTS.md.

Install options

Homebrew $ brew install gh

Windows $ winget install --id GitHub.cli

Debian/Ubuntu $ sudo apt install gh

Common commands

View repository metadata · safe $ gh repo view owner/repo --json name,description,stargazerCount,defaultBranchRef

Read-only repository context for agents.

List pull requests · safe $ gh pr list --state open --json number,title,author,url,reviewDecision,mergeStateStatus,updatedAt

Useful for triage, release checks, and review summaries.

Inspect one pull request · safe $ gh pr view 123 --json number,title,files,commits,reviews,statusCheckRollup,url

Reads review and CI context before the agent summarizes risk.

Merge a pull request · requires review $ gh pr merge 123 --squash

Changes repository state and must require human approval.

Agent usage examples

Claude Code / Codex CLI

Use gh only for read-only GitHub inspection unless I approve a state-changing command. Prefer --json and summarize PR blockers before suggesting next steps.

Paste this into AGENTS.md for repositories where the agent can inspect GitHub state.

Safety notes

Treat repo view, issue list, pr list, and pr view as the default safe command set.
Require approval before merge, close, delete, edit, release, or workflow-run commands.
Prefer scoped or read-only tokens for agent sessions and always request JSON output where supported.

TL;DR

GitHub CLI is one of the strongest default tools for coding agents because it exposes repository, issue, pull request, release, and workflow state without scraping GitHub pages.

Best for: PR triage, issue lookup, release context, workflow status, repository metadata.
Not for autonomous use: merge, close, delete, repo settings changes, workflow dispatch, release deletion.
Agent rule: use read-only commands first, prefer `--json`, and ask before changing repository state.

Safe commands for agents

gh repo view owner/repo --json name,description,stargazerCount,defaultBranchRef
gh pr list --state open --json number,title,author,url,reviewDecision,mergeStateStatus,updatedAt
gh pr view 123 --json number,title,body,files,commits,reviews,statusCheckRollup,url
gh issue list --state open --json number,title,labels,updatedAt,url

Requires human confirmation

gh pr merge
gh issue close
gh release delete
gh repo edit
gh workflow run

Standard agent instruction

Use GitHub CLI only for read-only inspection unless the user explicitly approves a state-changing command. Always prefer `--json`. Before any merge, close, delete, edit, or workflow-run command, summarize the command, expected effect, rollback option, and why approval is needed.

Example workflow: summarize PR risk

1. Read the open PR list with `gh pr list --json ...`. 2. Inspect the risky PR with `gh pr view --json ...`. 3. Summarize review blockers, merge conflicts, CI state, and age. 4. Do not merge. Ask for confirmation if the next step changes repository state.

Common failure modes

Not authenticated: run `gh auth status` and then `gh auth login` manually.
Token too broad: prefer read-only scopes for agent sessions.
Wrong repository context: pass `owner/repo` explicitly.
Missing JSON fields: check `gh help pr list` or reduce the requested field list.

GitHub CLI for pull requests, issues, and repository automation