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.