github-cli

GitHub CLI

Use gh for every GitHub lookup. A GitHub page fetched through the web is rate-limited, truncated and stripped of structure, while gh returns the exact file text or JSON and authenticates with the user's own token. Check it is usable before the first call: command -v gh && gh auth status. If either fails, say so and fall back to webfetch rather than guessing.

Every command takes --help, and gh <cmd> --json with no value lists the available JSON fields. Outside a git checkout, pass the repository explicitly: -R OWNER/REPO on issue, pr, release, run, workflow and label commands, OWNER/REPO as the argument to gh repo view and gh repo clone, and a literal repos/OWNER/REPO/... path to gh api. The {owner} and {repo} placeholders resolve from the current directory's remote, so in research they would silently point at the wrong repository.

This file covers reading. Anything that changes state on GitHub is in references/write-ops.md (see Writing to GitHub below).

Research recipes

Pin reads to a commit SHA, not a branch, so the lines you cite stay the lines you read.

Resolve a ref to a SHA

SHA=$(gh api repos/OWNER/REPO/commits/main --jq .sha)        # branch, tag or short SHA all work

Read a file at that commit

gh api -H 'Accept: application/vnd.github.raw+json' "repos/OWNER/REPO/contents/path/to/file.ts?ref=$SHA"
gh api "repos/OWNER/REPO/contents/path/to/file.ts?ref=$SHA" --jq .content | base64 -d    # same, via the JSON form

The raw header returns the file body directly. The JSON form is for when you also need .sha, .size or .download_url. Files over 1 MB come back without content; use the blob API (repos/OWNER/REPO/git/blobs/<blob-sha>) or a clone.

List a directory or the whole tree

gh api "repos/OWNER/REPO/contents/src?ref=$SHA" --jq '.[] | .type + " " + .path'     # one directory
gh api "repos/OWNER/REPO/git/trees/$SHA?recursive=1" --jq '.tree[].path'            # every path