{"slug": "a-youtube-transcript-cli-built-for-humans-and-ai-agents", "title": "A YouTube Transcript CLI Built for Humans and AI Agents", "summary": "Developer nmdra released yt-transcript v1.1.0, a CLI and MCP server that fetches English YouTube transcripts with chapter and timestamp context without downloading audio or video or requiring FFmpeg. The tool offers raw captions, previews, and model-edited Markdown, with Pi as the default editing backend and direct API options including OpenRouter and DeepSeek; raw CLI output and MCP plain text make no model calls. The release pins installation to v1.1.0 via uv and warns that 'uvx yt-transcript' selects an unrelated PyPI project, while OpenRouter requires an explicit model ID and OPENROUTER_API_KEY in the environment with a default max_output_tokens of 16384 per model call.", "body_md": "Get English YouTube transcripts with chapter and timestamp context. Use the CLI to get raw captions or model-edited Markdown. You can also connect an AI agent to the MCP server. The tool does not download audio or video. The tool does not require FFmpeg.\n\n- **CLI:** raw captions, previews, or model-edited Markdown\n- **MCP:**`get_transcript` with`filtered` and`full` modes\n- **Context:** keeps supplied chapters or adds timestamp blocks with original video times\n- **SponsorBlock:** enabled by default for MCP; opt-in for CLI; includes full-caption fallback\n- **No model required:** raw CLI output and MCP plain text make no model calls\n- **Optional model editing:** Pi is the default; direct API backends include OpenRouter and DeepSeek\n\nRequirements:\n\nNote\n\nThe default backend uses Pi for Markdown editing and focused cleanup after caption extraction. Install and configure Pi separately, or select OpenRouter with an explicit model and environment-only API key. Raw transcript output and plain-text MCP output do not require Pi.\n\nInstall the pinned release:\n\n```\nuv tool install --python 3.14.7 \\\n  'yt-transcript[mcp] @ git+https://github.com/nmdra/yt-transcript.git@v1.1.0'\n\nyt-transcript --version\nyt-transcript --doctor\n```\n\nThis command pins the application to **1.1.0**.\n\nSee the [installation guide](https://github.com/nmdra/yt-transcript/blob/main/docs/installation.md) for verified release assets, checksum checks, and exact dependency versions.\n\n**Important:** `uvx yt-transcript` selects an unrelated PyPI project. Install this project from the pinned GitHub release instead.\n\nReplace `URL` with a YouTube video URL:\n\n```\n# Raw captions — no model call\nyt-transcript URL --no-config --raw -o transcript.txt\n\n# Preview planned processing without calling Pi\nyt-transcript URL --no-config --preview\n\n# Pi-edited Markdown\nyt-transcript URL --no-config --max-chunks 3 -o transcript.md\n\n# Focused editing removes separable non-substantive passages\nyt-transcript URL --no-config --editorial-mode focused --max-chunks 3 -o focused.md\n\n# Whole-video summary; the cap includes the final synthesis call\nyt-transcript URL --no-config --editorial-mode summarized --max-chunks 3 -o summary.md\n```\n\nRaw output does not require a model.\n`--preview` fetches captions without calling Pi.\nThe preview shows the number of planned calls before Markdown editing.\nWhen the captions clearly identify the intended word, all Markdown modes allow conservative ordinary-word spelling correction.\nNames, technical terms, numbers, URLs, code, commands, and uncertain words remain protected.\nThese are model instructions, not a guaranteed spelling check.\nRaw output and MCP plain text are unchanged.\nSee [spelling correction limits](https://github.com/nmdra/yt-transcript/blob/main/docs/behavior.md#conservative-spelling-correction).\nIf you use `-o`, the output file includes YAML metadata.\nStdout contains only the transcript body.\n\nDirect OpenRouter formatting does not require Pi:\n\n```\n# Set OPENROUTER_API_KEY in the environment first; do not store it in TOML.\nyt-transcript URL --no-config --provider openrouter --model openai/gpt-4o --max-chunks 3 -o transcript.md\nyt-transcript URL --no-config --provider openrouter --model openai/gpt-4o --editorial-mode summarized --max-chunks 20 -o summary.md\n```\n\nPi remains the default backend.\nRaw output and MCP plain text do not use a model.\nThis release uses `[formatting]` instead of `[pi]`, with a separate `[openrouter]` token limit.\nOpenRouter requires an explicit model ID and `OPENROUTER_API_KEY` in the process environment.\nThe default `openrouter.max_output_tokens` is **16384 tokens per model call**.\nReasoning tokens can consume this allowance.\nThe selected model must support the limit.\nA larger allowance does not guarantee completion.\nTo save settings, edit your existing tables using [config.example.toml](https://github.com/nmdra/yt-transcript/blob/main/config.example.toml).\nFor MCP, select the backend in server TOML and make the key available in the server environment.\nThe tool does not retry automatically or use a fallback provider.\nThe tool does not return partial output.\nThe tool sends transcript text to OpenRouter and its upstream provider.\nThis can incur charges.\nSee the [CLI provider guide](https://github.com/nmdra/yt-transcript/blob/main/docs/cli.md#providers).\nWhen you update from dev7, rename `[pi]` to `[formatting]`.\nKeep your existing Pi settings.\n\nDirect DeepSeek formatting does not require Pi:\n\n```\n# Set DEEPSEEK_API_KEY in the environment first; never store it in TOML.\nyt-transcript URL --no-config --provider deepseek --model deepseek-flash --max-chunks 3 -o transcript.md\n```\n\nDeepSeek requires an explicit model and uses the fixed HTTPS endpoint `https://api.deepseek.com/chat/completions`.\n`deepseek-flash` and `deepseek-v4-pro` are model examples, not a permanent allowlist.\n`[deepseek].max_output_tokens` defaults to 16384 per call and allows integers from 1 through 393216.\nThe selected model must support the limit.\nTranscript text goes directly to DeepSeek, without OpenRouter's `data_collection=\"deny\"` routing request.\nDo not assume equivalent retention or privacy guarantees.\n\nOptional TOML settings `formatting.thinking` and `formatting.thinking_level` control all three backends.\nWith both omitted, summarized Markdown requests thinking at medium for every stage.\nStandard and focused preserve Pi/OpenRouter defaults and request DeepSeek thinking off.\n`thinking = false` always requests off, including summaries, and ignores a configured level.\n`thinking = true` uses the configured scalar level (`low`, `medium`, or `high`), or medium when omitted.\nA level alone is valid for summarized mode; outside summarized mode it requires explicit true unless thinking is explicitly false.\nDeepSeek maps medium to high.\nPi and OpenRouter can clamp, map, or reject requested settings; some models always reason.\n\nThinking can increase cost and latency and compete with visible output for the token allowance.\nThe tool does not automatically raise token limits, retry, repair, or publish partial output.\nHiding reasoning does not disable thinking or billing.\nThis policy does not establish improved summary fidelity.\nRaw output, plain-text MCP, and retrieval tools remain model-free.\nThe source-caption cache does not store provider-generated output or reasoning.\nThere are no new CLI thinking flags or public MCP arguments.\nSee [thinking policy](https://github.com/nmdra/yt-transcript/blob/main/docs/cli.md#thinking-policy) and [backend limits](https://github.com/nmdra/yt-transcript/blob/main/docs/behavior.md#backend-independent-formatting).\nThese changes are not included in the pinned 1.0.0 installation above.\n\nFor a compatible MCP client, follow the [MCP setup guide](https://github.com/nmdra/yt-transcript/blob/main/docs/mcp.md).\n\nThe MCP server provides `get_transcript`:\n\n- `filtered` is the default and attempts SponsorBlock filtering\n- `full` skips SponsorBlock filtering\n- Plain-text output makes no model call\n- `output_format=\"markdown\"` explicitly enables the server-selected model backend\n- Plain text keeps supplied chapters; otherwise, it adds timestamp context\n- Server-configured `summarized` mode produces a whole-video summary for explicit Markdown requests\n- The CLI writes progress to terminal stderr\n\n**MCP retrieval tools:** The server also provides `get_video_info`, `get_transcript_segment`, `search_transcript`, and `get_transcript_page`.\nThe retrieval tools share a private local source-caption cache with `get_transcript`.\nBy default, the cache is enabled and snapshots expire 24 hours after creation.\nThe retrieval tools do not call a model.\nMarkdown still makes model calls on each request.\nMarkdown can also send optional progress notifications.\nSee [retrieval tools and cache](https://github.com/nmdra/yt-transcript/blob/main/docs/mcp.md#retrieval-tools).\n\nCopy this prompt into an agent that has local shell and file access:\n\n```\nInstall `nmdra/yt-transcript` `v1.1.0` for my user account with the MCP extra and exactly Python `3.14.7`.\n\nFirst read the official installation guide, MCP guide, and release page:\nhttps://github.com/nmdra/yt-transcript/blob/main/docs/installation.md\nhttps://github.com/nmdra/yt-transcript/blob/main/docs/mcp.md\nhttps://github.com/nmdra/yt-transcript/releases/tag/v1.0.0\n\nUse the GitHub release wheel, not the unrelated PyPI package `yt-transcript`. Verify the wheel and source archive against the release `SHA256SUMS`. Stop if either check fails. Extract dependency constraints from that release source archive's `uv.lock` without executing archive content. Install the verified wheel in an isolated user-level `uv tool` environment with the MCP extra and exactly Python `3.14.7`.\n\nAsk before replacing an existing installation, changing configuration, or installing missing runtimes/tools such as Python, Deno, Pi, or `uv`. Keep unrelated tools, environment variables, API keys, model credentials, and existing MCP servers unchanged. Preserve the existing backend, model, editorial mode, limits, and other TOML settings unless I approve a change. Do not overwrite an existing TOML file with the example configuration.\n\nConfigure MCP only for the client(s) I select. Read each client's official MCP documentation first. Use its native setup command or configuration format, not another client's schema. Use the installed executable's absolute path. Load the saved server TOML if I want its backend and editorial settings; explain that `--no-config` bypasses those settings.\n\nPi remains the default backend. If I select OpenRouter, require an explicit OpenRouter model ID and `OPENROUTER_API_KEY` in the MCP server's inherited process environment. Do not put the key in TOML, command arguments, MCP tool arguments, or chat. Explain that a running client does not inherit a key exported later in another terminal. The version 1.0.0 OpenRouter default is 16384 output tokens per model call; reasoning tokens can consume this allowance, and the selected model must support it. A larger allowance does not guarantee completion. Preserve any explicit output-token override.\n\nExplain that version 1.0.0 permits only conservative ordinary-word spelling correction in model-generated Markdown. Uncertain words, names, technical terms, and protected literals remain unchanged. This is a prompt policy, not a guaranteed spelling checker. Raw output and MCP plain text remain model-free.\n\nExplain that version 1.0.0 exposes five MCP tools, with `get_transcript` still primary and its public arguments unchanged. Source captions and metadata are stored privately in a shared local SQLite cache for 24 hours by default, with a 50 MiB retained-payload budget. Preserve any saved `[cache]` settings. The four retrieval helpers are model-free; Markdown still formats on each explicit request. Pagination needs a stored snapshot and expired cursors fail without refetching. No extra dependency or setup service is needed.\n\nPerform offline installation checks only: inspect the installed version and Python version, run CLI help and doctor, and initialize MCP and list its tools if supported. Do not call any retrieval tool, fetch a video, run preview, or make a model request without separate approval. Doctor checks local readiness, not authentication or model accuracy. Explain how to reconnect the selected MCP client; for an active Pi session, use `/reload`.\n\nIf an asset, checksum, lockfile, compatibility detail, or configuration is ambiguous, stop and explain instead of guessing. Report the installed version, Python version, checksum results, release-locked dependency versions, install location, configuration changes, and offline startup/connectivity results without secrets.\n```\n\n- [Installation](https://github.com/nmdra/yt-transcript/blob/main/docs/installation.md) : prerequisites, pinned releases, updates, and uninstall\n- [CLI reference](https://github.com/nmdra/yt-transcript/blob/main/docs/cli.md) : modes, configuration, preview, and file safety\n- [MCP setup](https://github.com/nmdra/yt-transcript/blob/main/docs/mcp.md) : client configuration, tool results, and limits\n- [Transcript behavior](https://github.com/nmdra/yt-transcript/blob/main/docs/behavior.md) : chapters, cleanup, focused editing, metadata, and filtering\n- [Troubleshooting](https://github.com/nmdra/yt-transcript/blob/main/docs/troubleshooting.md) : error codes and recovery\n- [Development and releases](https://github.com/nmdra/yt-transcript/blob/main/docs/development.md) : tests, conditions for live checks, and release workflow\n- [Changelog](https://github.com/nmdra/yt-transcript/blob/main/CHANGELOG.md)\n\nThe code has an [MIT](https://github.com/nmdra/yt-transcript/blob/main/LICENSE) license.\n\nSponsorBlock data has a [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license unless separate permission is granted.\n\nGitHub releases use the tag-triggered public release workflow. PyPI publication requires separate approval.", "url": "https://wpnews.pro/news/a-youtube-transcript-cli-built-for-humans-and-ai-agents", "canonical_source": "https://github.com/nmdra/yt-transcript", "published_at": "2026-10-12 16:59:11+00:00", "updated_at": "2026-10-12 17:20:11.868894+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "agent-protocols", "ai-agents"], "entities": ["nmdra", "yt-transcript", "Pi", "OpenRouter", "DeepSeek", "YouTube", "uv", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/a-youtube-transcript-cli-built-for-humans-and-ai-agents", "markdown": "https://wpnews.pro/news/a-youtube-transcript-cli-built-for-humans-and-ai-agents.md", "text": "https://wpnews.pro/news/a-youtube-transcript-cli-built-for-humans-and-ai-agents.txt", "jsonld": "https://wpnews.pro/news/a-youtube-transcript-cli-built-for-humans-and-ai-agents.jsonld"}}