repostats 1.3.0
A CLI tool to fetch GitHub repository statistics
Requires Python: >=3.8
Keywords: github, statistics, cli, api

# ⚡️ repostats

[![PyPI version](https://badge.fury.io/py/repostats.svg)](https://pypi.org/project/repostats/)
[![Tests](https://github.com/sahansera/repostats/workflows/Python%20CI/badge.svg)](https://github.com/sahansera/repostats/actions)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A CLI tool to fetch GitHub repository statistics.

## Installation

```bash
# Basic installation
pip install repostats

# With TUI support
pip install repostats[tui]
```

## Usage

### Command Line Interface (CLI)

```bash
# 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:

```bash
# 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):**
```text
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:**
```json
{
  "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:**
```yaml
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

```bash
# 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