Guide

Authentication

octoscope talks to the GitHub GraphQL API on your behalf. It never asks you to paste a token — it picks one up from where you already keep it.

The token cascade

On startup octoscope looks for a token in order, and uses the first it finds:

$GITHUB_TOKEN — the environment variable, if set.
gh auth token — the token from the GitHub CLI, if you're logged in with gh.
Unauthenticated — falls back to anonymous requests, capped at GitHub's 60 requests/hour.

If you use the gh CLI, you're already done — nothing to configure. Otherwise, export a token:

$ export GITHUB_TOKEN=github_pat_…
$ octoscope

A token is effectively required for your own dashboard, and for keeping any dashboard open. The 60/hour anonymous limit won't survive the 60-second auto-refresh loop — octoscope backs off when it hits the ceiling, but you'll spend most of the hour rate-limited. Any public profile is browsable unauthenticated for a while; your own account always needs a token.

Scopes — octoscope is read-only

octoscope never writes to GitHub, so it only needs read access. Pick whichever token style you prefer:

Classic PAT — read:user is enough for public data; add repo if you want private repositories, PRs and issues to show up.
Fine-grained PAT — grant read on Metadata, Contents, Issues, Pull requests, Profile and Followers. No write permission is ever used.

Create one at github.com/settings/tokens.

✓

If a token is expired or under-scoped, octoscope says so in the footer and names the fix — token rejected · check $GITHUB_TOKEN, run gh auth refresh, or the missing scope — rather than failing silently.