github-repo-stats 🔎

🔎 CLI to inspect GitHub repository statistics: popularity, activity, issues, releases, timeline, and traffic.

Give a ⭐️ if this project helped you!

Preview 🎉

Features

• ✅ Overview: language, license, size, topics, archived/fork flags
• ✅ Popularity: stars, forks, watchers
• ✅ Activity: last push, commits from the last 52 weeks, contributors
• ✅ Issues / PRs: open issues (without PRs) and open pull requests
• ✅ Releases: count, latest tag, total asset downloads
• ✅ Timeline: repository created → first commit → first release → latest release → last push, with human-readable gaps
• ✅ Traffic (with GITHUB_TOKEN and push access): views, clones, top referrers, top paths
• ✅ --json output for scripting
• ✅ Zero runtime dependencies

Usage

Run without installation:

npx github-repo-stats <owner>/<repo>

Or install globally:

npm install -g github-repo-stats

github-repo-stats <owner>/<repo>

Examples:

github-repo-stats piecioshka/super-event-emitter
github-repo-stats https://github.com/nodejs/node
github-repo-stats piecioshka/super-event-emitter --json
github-repo-stats piecioshka/super-event-emitter --no-color

Authentication (optional)

Without a token the tool uses the anonymous GitHub API limit (60 requests/hour). Generate a token on the Personal access tokens page and set the GITHUB_TOKEN environment variable to raise the limit and unlock the traffic section:

GITHUB_TOKEN=ghp_xxx github-repo-stats <owner>/<repo>

Alternatively, put the token in a .env file in the current working directory (see .env.example):

cp .env.example .env
# edit .env and set GITHUB_TOKEN
github-repo-stats <owner>/<repo>

Variables already present in the shell environment take precedence over the .env file.

Required token permissions

Fine-grained tokens (the default on the linked page) start with the mandatory Metadata: Read-only permission only. Each report section needs the following access:

| Report section | Fine-grained permission | Classic token scope | | --- | --- | --- | | Overview, Popularity, Activity, Timeline | Metadata: Read-only | none (repo for private) | | Issues / Pull requests | Pull requests: Read-only | none (repo for private) | | Releases | Contents: Read-only | none (repo for private) | | Traffic | Administration: Read-only | repo |

[!WARNING]

A fine-grained token without these permissions responds with 403 Resource not accessible by personal access token — the affected sections show an error while the rest of the report still renders.

If you use the GitHub CLI, the quickest option is reusing its token, which already has the repo scope:

GITHUB_TOKEN=$(gh auth token) github-repo-stats <owner>/<repo>

GitHub Enterprise

Set the GITHUB_API_URL environment variable (or put it in .env) to point the tool at a GitHub Enterprise instance:

GITHUB_API_URL=https://github.mycompany.com/api/v3 github-repo-stats <owner>/<repo>

When the variable is not set, the tool talks to https://api.github.com.

[!NOTE]

The traffic section requires push access to the repository — GitHub exposes views and clones only to maintainers, and only for the last 14 days.

[!TIP]

The token is read exclusively from the environment. There is no --token flag on purpose: command-line arguments end up in the shell history.

How it works

• The open PR count is read from the Link pagination header of /pulls?per_page=1 — no Search API, no listing thousands of items. The open issue count is the repository's open_issues_count (which includes pull requests) minus that PR count.
• The first commit is found with two requests: the Link header points at the last page of /commits?per_page=1, which holds the oldest commit.
• The HTTP client waits out GitHub's secondary rate limit (detected by response body, not headers), retries transient failures, and reports the reset time when the primary limit is exhausted.

Development

npm test              # unit tests (Vitest)
npm run lint          # ESLint
npm run build         # TypeScript
npm run format:check  # Prettier

License

The MIT License @ 2026