/youtube-cli

name: youtube-cli
description: Searches YouTube and fetches video transcripts via the cli-web-youtube command-line tool — video search, video details (views, duration, description, keywords), trending by category, channel info, and timestamped transcripts/captions with language selection and translation. Use when the user asks about YouTube, searching for videos, video details, trending videos, channel info, subscriber counts, or a video's transcript, captions, or subtitles. Prefer this CLI over fetching the YouTube website. No authentication required.

cli-web-youtube

Search and explore YouTube from the terminal (read-only, no auth, InnerTube API). Install: `pip install cli-web-youtube`

Commands

| Command | Purpose | Key options | |---------|---------|-------------| | `search videos QUERY` | Search videos | `-l/--limit N` (default 10) | | `video get VIDEO_ID` | Video details (views, duration, description, keywords) | accepts 11-char ID or full URL | | `trending list` | Trending/popular videos | `-c/--category now\|music\|gaming\|movies`, `-l/--limit N` | | `channel get HANDLE` | Channel info + recent videos | accepts `@handle`, `UC...` ID, or URL | | `transcript get VIDEO` | Timestamped transcript + full text | `-l/--lang CODE` (repeatable, priority order), `-t/--translate CODE`, `--text-only`; accepts ID or URL | | `transcript list VIDEO` | Available caption languages | accepts ID or URL |

Examples

# Search (returns id, title, channel, views, duration, published, url per video)
cli-web-youtube search videos "python tutorial" --limit 5 --json

# Video details by ID or URL
cli-web-youtube video get dQw4w9WgXcQ --json

# Trending music videos
cli-web-youtube trending list --category music --limit 10 --json

# Channel info and subscriber count
cli-web-youtube channel get @mkbhd --json | jq '{title, subscriber_count}'

# Plain-text transcript (ideal for feeding to an LLM)
cli-web-youtube transcript get dQw4w9WgXcQ --text-only

# Transcript in a preferred language, or translated, as JSON
cli-web-youtube transcript get dQw4w9WgXcQ --lang en --json
cli-web-youtube transcript get dQw4w9WgXcQ --translate en --json | jq -r '.segments[].text'

# What caption languages exist?
cli-web-youtube transcript list dQw4w9WgXcQ --json

JSON output

Every command accepts `--json`. Success returns the data object directly, e.g. search: `{"query", "estimated_results", "videos": [...]}`; video get: `{"id", "title", "channel", "views", "duration_seconds", ...}`; transcript get: `{"video_id", "title", "language_code", "kind", "is_translated", "segment_count", "segments": [{"text", "start", "duration"}], "text"}`. Errors return `{"error": true, "code": "...", "message": "..."}`.

Utilities

`cli-web-youtube doctor [--json]` self-diagnoses the local setup (install, auth, dependencies). `cli-web-youtube mcp-serve` serves the commands as MCP tools over stdio.

Agent tips

• Video IDs are 11 characters; channel handles start with `@`.
• Running with no subcommand opens an interactive REPL.