⚡️ repostats

A CLI tool to fetch GitHub repository statistics.

Installation

# Basic installation
pip install repostats

# With TUI support
pip install repostats[tui]

Usage

Command Line Interface (CLI)

# Basic usage - single repository
repostats python/cpython

# Multiple repositories
repostats python/cpython golang/go rust-lang/rust

# With GitHub token for higher rate limits
export GITHUB_TOKEN=your_token_here
repostats python/cpython

# Or pass token directly
repostats python/cpython --token your_token_here

# Output as JSON
repostats python/cpython --format json

# Output as YAML
repostats python/cpython --format yaml

# Save output to a file
repostats python/cpython --format json --output stats.json

# Multiple repos with JSON output to file
repostats python/cpython golang/go --format json -o repos.json

Terminal User Interface (TUI)

For an interactive experience, use the TUI:

# Launch TUI (requires installation with [tui] extra)
repostats-tui

# Launch TUI with a pre-filled repository
repostats-tui python/cpython

The TUI provides:

• Interactive repository input with real-time validation
• Rich formatting with colors and organized sections
• Keyboard shortcuts: Press r to refresh, q to quit
• GitHub token support via GITHUB_TOKEN environment variable

Example output

Text format (default):

python/cpython statistics
-------------------------
Stars       : 70,399
Forks       : 33,713
Open issues : 9,248
Watchers    : 1,529
Language    : Python
License     : NOASSERTION
Size        : 754.8 MB
Default branch: main
Latest release: v3.13.0
Created     : 2017-02-10T19:23:51Z
Updated     : 2025-12-20T23:50:36Z

JSON format:

{
  "name": "python/cpython",
  "stars": 58000,
  "forks": 29000,
  "open_issues": 992,
  "watchers": 3400,
  "language": "Python",
  "created_at": "2007-02-20T00:00:00Z",
  "updated_at": "2024-01-15T12:34:56Z"
}

YAML format:

name: python/cpython
stars: 58000
forks: 29000
open_issues: 992
watchers: 3400
language: Python
created_at: '2007-02-20T00:00:00Z'
updated_at: '2024-01-15T12:34:56Z'

The command exits with code 1 when the GitHub API request fails (for example, when the repository is missing or you hit a rate limit), which makes it easy to integrate into scripts.

Features

• Two interfaces: Command-line tool and interactive TUI
• Multiple repositories: Fetch stats for multiple repos in a single command (CLI)
• Rich metrics: Stars, forks, issues, watchers, language, license, size, latest release, and more
• Multiple output formats: text (default), JSON, and YAML (CLI)
• File output: Save results to a file with --output (CLI)
• Interactive exploration: Navigate and refresh stats in real-time (TUI)
• GitHub token support: Authenticate to increase rate limits
• Clean output: Accessible formatting for all output types
• Helpful error messages: Clear guidance on rate limits and missing repos
• Exit codes: Non-zero exit on failure for scripting integration (CLI)
• Cross-platform: Works on macOS, Linux, and Windows

Development

# Clone the repository
git clone https://github.com/sahansera/repostats.git
cd repostats

# Create virtual environment
uv venv
source .venv/bin/activate

# Install in development mode (with TUI support)
uv pip install -e ".[dev,tui]"

# Run tests
make test

# Format code
make format

# Type checking
make type-check

# See all available commands
make help

License

MIT