github

Use the

gh

CLI for everything. The user's OAuth access token is exported as

$GH_TOKEN

;

gh

reads it automatically —

gh auth status

will say "not logged in" because gh keeps no config file in the sandbox, but every authenticated subcommand works regardless.

gh --help

and

gh <subcommand> --help

are always current. When unsure, read the help first instead of guessing flags.

Two ways to call gh — prefer subcommands

Style A: First-class subcommands — START HERE

gh issue

gh pr

gh repo

gh search

gh release

gh workflow

gh run

gh status

gh project

gh label

gh secret

gh variable

gh gist

. Use these whenever they cover the task; they output formatted text by default and structured JSON via

--json <fields> [--jq <expr>]

Style B: Raw REST / GraphQL via

gh api

gh api <endpoint>

for REST,

gh api graphql -f query='…'

for GraphQL. Useful when no first-class subcommand exists. Notable flags:

```
-X POST|PATCH|PUT|DELETE
```
— override method (default
```
GET
```
, becomes
```
POST
```
automatically when
```
-f
```
/
```
-F
```
is set).
```
-f key=value
```
— string field;
```
-F key=value
```
— JSON-typed field (
```
true
```
/
```
123
```
/
```
@file.json
```
); both URL-encode for
```
GET
```
and JSON-encode for body methods.
```
-q '<jq>'
```
— same as
```
--jq
```
. With a primitive top-level value (string / number) it prints the raw value (no quotes).
```
-H 'Accept: application/vnd.github.raw'
```
— fetch a file's raw bytes instead of the JSON wrapper.
```
--paginate
```
— auto-walk
```
Link: rel="next"
```
.

Recipes

Triage what's on my plate (issues + PRs + reviews + mentions)

gh status

List recent issues in a repo

gh issue list --repo OWNER/REPO --limit 20
gh issue list --repo OWNER/REPO --state all --limit 20 \
  --json number,title,state,author,updatedAt,labels --jq '.[]'

View an issue with comments

gh issue view 123 --repo OWNER/REPO --comments
gh issue view 123 --repo OWNER/REPO --json title,body,comments \
  --jq '{title, body, comments: [.comments[] | {author: .author.login, body, createdAt}]}'

Create / comment / close an issue

gh issue create --repo OWNER/REPO --title "Bug: foo" --body "Repro steps…" --label bug
gh issue comment 123 --repo OWNER/REPO --body "LGTM"
gh issue close 123 --repo OWNER/REPO --comment "Fixed in #456"

List PRs assigned to / authored by me

gh search prs --assignee=@me --state=open --json number,title,repository,updatedAt
gh search prs --author=@me --state=open

View a PR with diff and CI checks

gh pr view 456 --repo OWNER/REPO
gh pr diff 456 --repo OWNER/REPO
gh pr checks 456 --repo OWNER/REPO

Comment / review / merge a PR

gh pr comment 456 --repo OWNER/REPO --body "Please rebase on main."
gh pr review 456 --repo OWNER/REPO --approve --body "LGTM"
gh pr review 456 --repo OWNER/REPO --request-changes --body "See nits"
gh pr merge 456 --repo OWNER/REPO --squash --delete-branch

Search code across GitHub

gh search code 'someFunction language:typescript' --limit 20 \
  --json repository,path,url --jq '.[] | "\(.repository.nameWithOwner) \(.path)"'

Read a file from a repo (raw bytes, no base64 dance)

gh api "repos/OWNER/REPO/contents/path/to/file.ts" \
  -H 'Accept: application/vnd.github.raw'

List recent commits on the default branch

gh api "repos/OWNER/REPO/commits?per_page=20" \
  --jq '.[] | "\(.sha[0:7]) \(.commit.author.date) \(.commit.message | split("\n")[0])"'

Trigger / inspect Actions workflows

gh workflow list --repo OWNER/REPO
gh workflow run ci.yaml --repo OWNER/REPO --ref main -f key=value
gh run list --repo OWNER/REPO --workflow ci.yaml --limit 5
gh run view <RUN_ID> --repo OWNER/REPO --log-failed

View a repo's metadata

gh repo view OWNER/REPO
gh repo view OWNER/REPO --json description,url,stargazerCount,defaultBranchRef

GraphQL for things REST can't do (e.g. project board items)

gh api graphql -f query='
  query($owner: String!, $repo: String!, $num: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $num) {
        title
        timelineItems(first: 50) {
          nodes { __typename ... on CrossReferencedEvent { source { ... on PullRequest { number title state } } } }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F num=123

Notes

For private repos the user MUST have granted
```
repo
```
scope when they authorized the connection at
```
auth.acedata.cloud/user/connections
```
. A 404 on a repo you know exists usually means missing scope, not a wrong URL.
When
```
--json
```
rejects a field name, gh prints the full list of valid fields — re-read the error and pick from there.

gh issue list --search

and

gh search issues

use the GitHub search syntax (

is:open

assignee:@me

repo:owner/name

, etc.). Use

gh search issues

gh search prs

for cross-repo queries; use

gh issue list

for one repo.

```
gh api --paginate
```
only works on endpoints that emit a
```
Link
```
header; for cursor-paginated endpoints you have to follow
```
pagination.next
```
yourself.