Youtube Data CLI

Search YouTube in bulk, grab transcripts, get embed snippets — for the photo-keywords-to-blog-post workflow.

A trimmed read-only YouTube Data API v3 CLI built for local research workflows. Bulk search from stdin, transcript fetching via timedtext (no OAuth needed), embed snippet generation, and a heuristic-based videos related that still works despite the 2023 deprecation.

Learn more at YouTube Data API v3.

Sample use case: justinwfu/pictovideo — photo-keywords → candidate-video → embedded blog draft pipeline using this CLI.

Created by @justinwfu (Justin).

Authentication

API-key only — set YOUTUBE_API_KEY and you're done. Read-only public-data operations only (10,000 quota units/day default). Write operations are not configured; this CLI is for discovery and research, not channel management.

Quick Start

# Verify the API key and reachability.
youtube-pp-cli doctor

# Single-term search.
youtube-pp-cli youtube search-list --q "sourdough scoring" --max-results 5 --json

# Bulk search from positional args — the photo-keywords -> videos shape (use --stdin to read from a file/pipe instead).
youtube-pp-cli youtube search-bulk "sourdough scoring" "latte art" --top 3 --json

# Fetch the transcript to verify topic relevance before picking the video.
youtube-pp-cli youtube videos-transcript dQw4w9WgXcQ --lang en

# Get a markdown embed snippet for the blog draft.
youtube-pp-cli youtube videos-embed dQw4w9WgXcQ --format markdown

# Find more candidates similar to a video you've already picked.
youtube-pp-cli youtube videos-related dQw4w9WgXcQ --limit 5

Known Gaps

• Enum flag values aren't validated client-side. Flags like --order, --safe-search, --video-duration, and similar carry a "one of:" hint in --help, but the CLI passes whatever string you supply straight to the API. An invalid value comes back as an HTTP 400 from YouTube rather than a local "unknown value" error. Use the documented values from --help to avoid the round-trip.

Unique Features

These capabilities aren't available in any other tool for this API.

Blog-post composition

• youtube search-bulk — Take a list of search terms from stdin or args, return top-N YouTube videos per term in one JSON document with titles, channels, embed URLs, and thumbnails.

  When you have N search terms from an upstream pipeline (image labels, photo tags, scraped keywords), reach for this instead of looping single searches.

  youtube-pp-cli youtube search-bulk "sourdough scoring" "latte art" --top 3
  

• youtube videos-transcript — Fetch the spoken-content transcript of a YouTube video using the timedtext endpoint. Works for auto-generated and manual captions on any public video. Caches into the local store.

  Read the transcript before deciding whether a candidate video actually fits the topic of the blog post or photo.

  youtube-pp-cli youtube videos-transcript dQw4w9WgXcQ --lang en --json
  

• youtube videos-embed — Print embed HTML, iframe, or markdown-style embed for a video ID. Direct copy-paste into a blog draft.

  Once you've picked a video for the blog, get the embed snippet without remembering the exact iframe URL pattern.

  youtube-pp-cli youtube videos-embed dQw4w9WgXcQ --format markdown
  

Reachability mitigation

• youtube videos-related — Find videos related to a target video using topicDetails + same-channel + tag overlap from the local store. Best-effort replacement for the deprecated relatedToVideoId parameter.

  When one candidate video is on-topic but you want more like it, this is the working stand-in for the deprecated parameter.

  youtube-pp-cli youtube videos-related dQw4w9WgXcQ --limit 10 --json
  

Audience signal

• youtube videos-comments — Fetch top comments on a video, ranked locally by likeCount. Pulls up to 5 pages from commentThreads.list and sorts so most-liked floats regardless of API order.

  Use to gauge whether a video is actually well-received before embedding, or to surface viewer-supplied context the description doesn't mention.

  youtube-pp-cli youtube videos-comments dQw4w9WgXcQ --top 10
  

Channel discovery

• youtube channel-uploads — List a channel's most recent uploads in one call. Resolves @handle or channelId, walks the auto-generated uploads playlist, returns video IDs + titles + publish times.

  Replaces the manual two-step lookup. Pairs naturally with --for-handle workflows.

  youtube-pp-cli youtube channel-uploads @veritasium --top 10
  

Usage

Run youtube-pp-cli --help for the full command reference and flag list.

Commands

YouTube Data API v3 endpoints

• youtube-pp-cli youtube channels-list - List channels by --id, --for-handle, --for-username, --mine, or --managed-by-me.
• youtube-pp-cli youtube comment-threads-list - List top-level comment threads, filterable by video, channel, or thread id.
• youtube-pp-cli youtube playlist-items-list - List items in a playlist by --playlist-id or --id.
• youtube-pp-cli youtube playlists-list - List playlists by --channel-id, --id, or --mine.
• youtube-pp-cli youtube search-list - Search videos, channels, and playlists with full filter support (--q, --order, --type, etc.).
• youtube-pp-cli youtube videos-list - List videos by --id, --chart, or --my-rating.

Novel commands (not in the API)

• youtube-pp-cli youtube search-bulk - Search multiple terms in one call; top-N per term.
• youtube-pp-cli youtube videos-transcript - Fetch a video's transcript via timedtext (no OAuth).
• youtube-pp-cli youtube videos-embed - Print HTML, iframe, or markdown embed snippet for a video.
• youtube-pp-cli youtube videos-related - Find related videos via topic + channel + tag overlap (replaces deprecated relatedToVideoId).
• youtube-pp-cli youtube videos-comments - Top comments on a video, ranked locally by likeCount.
• youtube-pp-cli youtube channel-uploads - List a channel's most recent uploads in one call (resolves @handle → uploads playlist).

Output Formats

# Human-readable table (default in terminal, JSON when piped)
youtube-pp-cli youtube channels-list

# JSON for scripting and agents
youtube-pp-cli youtube channels-list --json

# Filter to specific fields
youtube-pp-cli youtube channels-list --json --select id,name,status

# Dry run — show the request without sending
youtube-pp-cli youtube channels-list --dry-run

# Agent mode — JSON + compact + no prompts in one flag
youtube-pp-cli youtube channels-list --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

youtube-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/youtube-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
YOUTUBE_API_KEY	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

• Run youtube-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $YOUTUBE_API_KEY Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• videos transcript returns RequestBlocked — Run from a residential IP (your laptop). YouTube blocks AWS/GCP/Azure IPs from the timedtext endpoint.
• videos related returns no results for a fresh video ID — Run youtube-pp-cli youtube videos-list --id <id> --parts topicDetails,snippet first to populate topic/tag data in the local store, then retry.
• search returns HTTP 403 quotaExceeded — Daily quota (10,000 units) is exhausted. search.list costs 100 units per call, videos.list costs 1. Switch to cached results via youtube-pp-cli sql \"SELECT * FROM search_results WHERE query='...'\".

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• Bin-Huang/youtube-data-cli — JavaScript
• pauling-ai/youtube-mcp-server — Python
• jdepoix/youtube-transcript-api — Python
• djthorpe/ytapi — Go

Generated by CLI Printing Press