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
| Feature | Description |
|---|---|
| Multi-channel analysis | Analyze N channels in one run |
| Engagement metrics | View rate, like rate, comment rate, viral detection |
| CSV export | Raw data with all computed fields |
| Text reports | Channel stats, trends, top/latest video URLs |
| Transcript download | Multi-language with 3-level fallback chain |
| API resilience | Exponential backoff on rate limits (403/429) |
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
| Metric | Formula | Interpretation |
|---|---|---|
| Engagement Rate | (likes + comments) / views * 100 |
Overall audience interaction |
| View Rate | views / subscribers * 100 |
Reach beyond subscriber base (>100% = viral) |
| Like Rate | likes / views * 100 |
Content satisfaction signal |
| Comment Rate | comments / views * 100 |
Discussion engagement level |
Configuration
All settings can be set via environment variables or .env file:
| Variable | Default | Description |
|---|---|---|
YOUTUBE_API_KEY |
(required) | YouTube Data API v3 key |
MAX_RESULTS_PER_CHANNEL |
50 |
Videos to fetch per channel |
OUTPUT_DIR |
./output |
Report output directory |
CHANNELS_FILE |
channels.yml |
Channel list file path |
VIDEO_ID |
— | Default video for transcript mode |
TRANSCRIPT_LANGUAGES |
es,en |
Preferred transcript languages |
Development
git clone https://github.com/mlorentedev/yt-metrics-cli.git
cd yt-metrics-cli
make install # Create venv + install deps
make check # Lint + typecheck + test
make build # Full build
See CONTRIBUTING.md for details.
License
Documentation
Project-bound knowledge lives in docs/ (docs-as-code): ADRs, runbooks, troubleshooting, and lessons.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file yt_metrics_cli-0.2.4.tar.gz.
File metadata
- Download URL: yt_metrics_cli-0.2.4.tar.gz
- Upload date:
- Size: 143.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2e9aef1d8b277dec9c870e74895cd6b26594ce515fc453ef055b54ddc510b600
|
|
| MD5 |
cd5e6ed0c5bb133f9efd7f0a8e8b1b5c
|
|
| BLAKE2b-256 |
2babdc5ceb820872929c15ccffc2ea1ee58415254216d69258229703b4699fb1
|
Provenance
The following attestation bundles were made for yt_metrics_cli-0.2.4.tar.gz:
Publisher:
release.yml on mlorentedev/yt-metrics-cli
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
yt_metrics_cli-0.2.4.tar.gz -
Subject digest:
2e9aef1d8b277dec9c870e74895cd6b26594ce515fc453ef055b54ddc510b600 - Sigstore transparency entry: 2415016387
- Sigstore integration time:
-
Permalink:
mlorentedev/yt-metrics-cli@fe0baf11010139f128e57c227fa598e5d2668fe4 -
Branch / Tag:
refs/heads/master - Owner: https://github.com/mlorentedev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fe0baf11010139f128e57c227fa598e5d2668fe4 -
Trigger Event:
push
-
Statement type:
File details
Details for the file yt_metrics_cli-0.2.4-py3-none-any.whl.
File metadata
- Download URL: yt_metrics_cli-0.2.4-py3-none-any.whl
- Upload date:
- Size: 20.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2b93a8eeced4ef1805944ab6969641771f0a573b529be2a41481a5c50d17eb85
|
|
| MD5 |
b65bffb8197eb248103b5b17d513844a
|
|
| BLAKE2b-256 |
1779cd2abd02364b1d54643ed7f020c94b38fd6259a3082e8b552c7abe11e890
|
Provenance
The following attestation bundles were made for yt_metrics_cli-0.2.4-py3-none-any.whl:
Publisher:
release.yml on mlorentedev/yt-metrics-cli
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
yt_metrics_cli-0.2.4-py3-none-any.whl -
Subject digest:
2b93a8eeced4ef1805944ab6969641771f0a573b529be2a41481a5c50d17eb85 - Sigstore transparency entry: 2415016398
- Sigstore integration time:
-
Permalink:
mlorentedev/yt-metrics-cli@fe0baf11010139f128e57c227fa598e5d2668fe4 -
Branch / Tag:
refs/heads/master - Owner: https://github.com/mlorentedev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fe0baf11010139f128e57c227fa598e5d2668fe4 -
Trigger Event:
push
-
Statement type:
