yt-metrics-cli

CLI tool that analyzes YouTube channels and downloads video transcripts, generating engagement metrics and structured reports.

Problem

YouTube Studio gives you analytics for your own channels. If you want to compare multiple channels, benchmark engagement rates, or bulk-download transcripts for research, you're stuck with manual work or fragmented browser extensions.

yt-metrics-cli solves this: point it at a list of channels, get CSV data, engagement reports, and transcript files in one command.

Quick Start

# Install
pip install yt-metrics-cli
# or
uv tool install yt-metrics-cli

# Set your API key
export YOUTUBE_API_KEY=your_key_here
# Get one at: https://console.cloud.google.com/apis/credentials

# Create channels.yml
cat > channels.yml << 'EOF'
- custom_url: "@mkbhd"
- custom_url: "@veritasium"
EOF

# Analyze
yt-metrics channels

Features

Usage

Analyze Channels

yt-metrics channels                        # Use defaults from .env
yt-metrics channels -c my_channels.yml     # Custom channel list
yt-metrics channels -n 100 -o ./reports    # 100 videos, custom output

Generates timestamped reports in output/<timestamp>/:

• CSV — Raw data with all metrics per video
• Channel Stats — Per-channel analysis with top 5 videos
• Engagement Trends — Cross-channel comparisons and rankings
• Best/Latest Videos — URL lists for quick access
• README — Index explaining all generated files

Download Transcripts

yt-metrics transcript -v dQw4w9WgXcQ       # Specific video
yt-metrics transcript -v abc123 -l es,en    # Language preference

Engagement Metrics

Configuration

All settings can be set via environment variables or .env file:

Development

git clone https://github.com/mlorentedev/yt-metrics-cli.git
cd yt-metrics-cli
make install    # Create venv + install deps
make check      # Lock check + lint + typecheck + test
make build      # Full build

See CONTRIBUTING.md for details.

License

MIT

Documentation

Project-bound knowledge lives in docs/ (docs-as-code) — currently docs/lessons/, one file per lesson. The build/operate docs live in the repo; the published site is site/.

Working on this repo with an AI agent? Start at AGENTS.md — architecture, invariants, commands and the knowledge-placement rules.