Guide
Scripting
octoscope isn't only a TUI. Two flags fetch once, print, and exit — for quick checks, shell status-lines, cron jobs and pipelines.
--plain — a text summary
A static, human-readable digest of the same data the dashboard shows, printed to stdout. No alt-screen, no colour codes to fight with.
$ octoscope --plain $ octoscope torvalds --plain # anyone's public profile
--json — a stable contract
The same data as JSON, versioned (schema_version) and documented — so a script can depend on its shape. Fields are added additively, every list is always an array, and a breaking change bumps the version.
$ octoscope --json | jq '.social.total_stars' $ octoscope --json --public-only > snapshot.json
Both honour --public-only and the usual auth cascade, and the two are mutually exclusive.
The full field-by-field JSON schema lives in the README's Scripting section — this page is the tour, the README is the contract.
Two things about the shape that a field list will not warn you about. Counts are separate from lists, because the lists are capped — sponsors holds up to 20 entries while sponsors_total is what GitHub reports, so comparing len(sponsors) against “how many sponsors do I have” is wrong on a busy account. Same for repositories, PRs and issues, which have caps of their own. And monthly_sponsors_income_cents is only ever present for the account the token belongs to — GitHub answers that field with 0 for anybody else, so it is omitted rather than emitted as a zero somebody could read as a measurement.
The notification inbox is deliberately not in either output. It is loaded on demand in the TUI rather than on every refresh, so putting it here would mean a REST call on every --json run for a field most callers do not want. Tracked as issue #125.
In a container
Since v0.31.0 the same two flags are available as an image, which is the shape a CI step wants — no install, fetch once, print, exit:
$ docker run --rm -e GITHUB_TOKEN ghcr.io/gfazioli/octoscope:latest --json | jq .social
-e GITHUB_TOKEN with no value passes the variable through from the surrounding environment rather than putting the token on the command line, where it would show up in ps and in shell history.
Two behaviours worth knowing before you depend on it. With no token it exits 1 and writes nothing to standard output — but a shell pipeline only notices that with set -o pipefail, since otherwise the exit status is jq's and jq is perfectly happy with no input. GitHub Actions does not enable it for you unless the step says shell: bash. And with no flag at all the container refuses rather than hanging, because the dashboard needs a terminal it does not have.