yt-metrics-cli 0.2.0__tar.gz

yt_metrics_cli-0.2.0/.claude/CLAUDE.md

@@ -0,0 +1,51 @@
+# yt-metrics-cli
+
+> CLI for YouTube channel analysis and transcript downloading.
+
+## Architecture
+
+- **CLI Layer:** `src/main.py` — Entry point with `channels` and `transcript` commands
+- **Config:** `src/config.py` — Constants and environment variable management
+- **Core:** `src/analyzer.py` — YouTube API wrapper (channel resolution, batch video stats)
+- **Metrics:** `src/metrics.py` — Pure engagement calculations (6 computed fields)
+- **Transcript:** `src/transcript.py` — Transcript download with 3-level fallback
+- **Export:** `src/exporters.py` — Report generators (CSV, TXT, README)
+
+## Technical Standards
+
+| Requirement | Tool/Pattern |
+|---|---|
+| Python | 3.12+ |
+| Type hints | mypy --strict |
+| Dependencies | uv |
+| Formatting | Ruff |
+| Testing | pytest + pytest-cov |
+| Build | hatchling |
+
+## Key Paths
+
+| Path | Role |
+|---|---|
+| `src/main.py` | CLI entry point |
+| `src/config.py` | Configuration and constants |
+| `src/analyzer.py` | YouTube API wrapper |
+| `src/metrics.py` | Engagement metric calculations |
+| `src/transcript.py` | Transcript downloader with fallback chain |
+| `src/exporters.py` | Report generators (CSV, text, README) |
+| `tests/` | pytest suite |
+| `site/` | Astro Starlight documentation |
+
+## Verification Commands
+
+All commands go through the Makefile:
+
+```bash
+make install    # Create venv + install deps
+make lint       # Ruff linter
+make typecheck  # mypy --strict
+make test       # pytest with coverage
+make check      # lint + typecheck + test
+make build      # check + uv build
+make run        # Run channel analysis
+make clean      # Remove build artifacts
+```

yt_metrics_cli-0.2.0/.env.example

@@ -0,0 +1,15 @@
+# Required: YouTube Data API v3 key
+# Get one at: https://console.cloud.google.com/apis/credentials
+YOUTUBE_API_KEY=your_api_key_here
+
+# Optional: Max videos to fetch per channel (default: 50)
+# MAX_RESULTS_PER_CHANNEL=50
+
+# Optional: Output directory for reports (default: ./output)
+# OUTPUT_DIR=./output
+
+# Optional: Video ID for transcript mode (default: tLkRAqmAEtE)
+# VIDEO_ID=your_video_id_here
+
+# Optional: Local transcript fixtures directory
+# YOUTUBE_TRANSCRIPT_FIXTURES_DIR=./fixtures

yt_metrics_cli-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps to reproduce the issue
+      placeholder: |
+        1. Set up .env with YOUTUBE_API_KEY
+        2. Run `yt-metrics channels`
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, OS, yt-metrics-cli version
+      placeholder: |
+        - yt-metrics-cli version: 0.1.0
+        - Python: 3.12.8
+        - OS: macOS 15.2 / Ubuntu 24.04
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Error Output
+      description: Paste any relevant error messages or logs
+      render: text

yt_metrics_cli-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://mlorentedev.github.io/yt-metrics-cli/
+    about: Check the docs before opening an issue

yt_metrics_cli-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve? What's the current limitation?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How should this work? Include examples if possible.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What other approaches did you consider?

yt_metrics_cli-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+<!-- Brief description of what this PR does and why -->
+
+## Changes
+
+-
+
+## Testing
+
+- [ ] `make check` passes (lint + typecheck + tests)
+- [ ] New tests added for new functionality
+- [ ] Manual testing completed
+
+## Type
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] CI/Build

yt_metrics_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install
+        run: uv venv && uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest tests/ -v --cov=src --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+      - name: Build
+        run: uv build

yt_metrics_cli-0.2.0/.github/workflows/pages.yml

@@ -0,0 +1,41 @@
+name: Deploy to GitHub Pages
+on:
+  push:
+    branches: [master]
+    paths: ['site/**']
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: site/package-lock.json
+      - name: Install
+        working-directory: site
+        run: npm ci
+      - name: Build
+        working-directory: site
+        run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/dist
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

yt_metrics_cli-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: python
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

yt_metrics_cli-0.2.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+
+# Tool caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Astro / Node
+site/node_modules/
+site/dist/
+site/.astro/
+site/.vscode/
+
+# Claude
+.claude/plans/
+
+# Project
+output/
+.env
+channels.yml
+*.log
+
+# Editor
+*~
+*.swp
+
+# Worktrees
+.worktrees/
+
+# Legacy
+poetry.lock
+.cache/
+.cache_ggshield

yt_metrics_cli-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

yt_metrics_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.2.0](https://github.com/mlorentedev/yt-metrics-cli/compare/v0.1.0...v0.2.0) (2026-03-15)
+
+
+### Features
+
+* add API rate limiting and README overhaul ([#8](https://github.com/mlorentedev/yt-metrics-cli/issues/8)) ([d7e474d](https://github.com/mlorentedev/yt-metrics-cli/commit/d7e474d2fce5627b6bca13543193fd85dcb6da6d))
+
+## 0.1.0 (2026-03-15)
+
+
+### Bug Fixes
+
+* add poetry.lock to .gitignore ([a501d2c](https://github.com/mlorentedev/youtube-toolkit/commit/a501d2c126366eb866ec791c9d1901438477a29b))
+* use correct RELEASE_TOKEN secret name ([#6](https://github.com/mlorentedev/youtube-toolkit/issues/6)) ([357c212](https://github.com/mlorentedev/youtube-toolkit/commit/357c212d8ce22bd6cde7ab3a01855b35e9f9aa3a))

yt_metrics_cli-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

yt_metrics_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/mlorentedev/yt-metrics-cli.git
+cd yt-metrics-cli
+make install
+```
+
+## Development
+
+```bash
+make check    # lint + typecheck + test (run before every PR)
+make lint     # ruff only
+make typecheck # mypy --strict only
+make test     # pytest only
+make build    # full build (runs check first)
+make run      # run channel analysis
+make site     # build documentation site
+make site-dev # start docs dev server
+```
+
+## Pull Requests
+
+1. Create a feature branch from `master`
+2. Follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, etc.)
+3. Run `make check` — all gates must pass
+4. Open a PR against `master`
+5. CI runs automatically (Python 3.12 + 3.13)
+6. Squash merge after CI passes
+
+## Code Standards
+
+- Python 3.12+, type hints everywhere (`mypy --strict`)
+- Formatting: Ruff
+- Tests: pytest, TDD preferred (write test first)
+- Functions < 40 lines, nesting < 4 levels
+
+## Release Process
+
+Automated via [release-please](https://github.com/googleapis/release-please). Merging to `master` with conventional commits triggers:
+
+1. Release PR with changelog (auto-created)
+2. Merge Release PR → GitHub Release + PyPI publish (trusted publishing)

yt_metrics_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Lorente
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yt_metrics_cli-0.2.0/Makefile

@@ -0,0 +1,37 @@
+.PHONY: help install lint typecheck test check build clean run site site-dev site-preview
+.DEFAULT_GOAL := help
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+install: ## Create venv and install deps
+	uv venv && uv pip install -e ".[dev]"
+
+lint: ## Run ruff linter
+	uv run ruff check src/ tests/
+
+typecheck: ## Run mypy --strict
+	uv run mypy src/
+
+test: ## Run tests with coverage
+	uv run pytest tests/ -v --cov=src --cov-report=term-missing
+
+check: lint typecheck test ## Lint + typecheck + test
+
+build: check ## Check + build package
+	uv build
+
+clean: ## Remove build artifacts
+	rm -rf dist/ .venv/ *.egg-info/ .ruff_cache/ .mypy_cache/ .pytest_cache/ htmlcov/ .coverage coverage.xml site/dist/ site/node_modules/
+
+run: ## Run channel analysis (requires .env)
+	uv run yt-metrics channels
+
+site: ## Build documentation site (requires Node.js)
+	cd site && npm ci && npm run build
+
+site-dev: ## Start documentation dev server
+	cd site && npm run dev
+
+site-preview: ## Preview documentation production build
+	cd site && npm run preview

yt_metrics_cli-0.2.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: yt-metrics-cli
+Version: 0.2.0
+Summary: CLI for YouTube channel analysis and transcript downloading
+Project-URL: Homepage, https://github.com/mlorentedev/yt-metrics-cli
+Project-URL: Documentation, https://mlorentedev.github.io/yt-metrics-cli/
+Project-URL: Repository, https://github.com/mlorentedev/yt-metrics-cli
+Project-URL: Issues, https://github.com/mlorentedev/yt-metrics-cli/issues
+Author-email: Manuel Lorente <info@mlorente.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,cli,engagement-metrics,transcripts,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.12
+Requires-Dist: google-api-python-client>=2.112.0
+Requires-Dist: google-auth-oauthlib>=1.2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: youtube-transcript-api>=1.2.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yt-metrics-cli
+
+[![CI](https://github.com/mlorentedev/yt-metrics-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mlorentedev/yt-metrics-cli/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-Starlight-purple)](https://mlorentedev.github.io/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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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](CONTRIBUTING.md) for details.
+
+## License
+
+[MIT](LICENSE)