# watch-cli [Health: Active] **Category:** ๐Ÿ’ป Developer Tools **Repository:** https://github.com/sonpiaz/watch-cli **GitHub Stars:** 250 **npm Downloads (last month):** 29635 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/watch-cli ## Description Hand any social video to your AI agent โ€” frames + transcript bundled. MCP server for watch-cli. ## Claude Desktop Quick Installation Heuristic fallback โ€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "watch-cli": { "command": "npx", "args": ["-y","watch-cli"] } } ``` ## Documentation & README # watch-cli ![CI](https://github.com/sonpiaz/watch-cli/actions/workflows/ci.yml/badge.svg) **Watch any social video โ†’ get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet โ€” automatically.** Eyes and ears for your AI agent. watch-cli composes `yt-dlp` + `ffmpeg` + a Whisper-class ASR into a single command that hands an agent the raw materials to "watch" any video: VIDEO + FRAMES + TRANSCRIPT, ready for an LLM to read frames as images and transcript as text. ```bash watch https://twitter.com/anyone/status/12345 ``` Works on YouTube, X, LinkedIn, TikTok, Reddit, Vimeo, and Facebook. Login-walled posts (LinkedIn, private X, FB) work with `WATCH_BROWSER=auto`, which reads cookies from a browser you are signed in to. ## What you can build Hand the `watch` output to your agent with one of five prompts in [`prompts/`](https://github.com/sonpiaz/watch-cli/blob/HEAD/prompts/): | Drop in a video ofโ€ฆ | Get back | |---|---| | A coding walkthrough | [Working project files](https://github.com/sonpiaz/watch-cli/blob/HEAD/prompts/implement-from-video.md) | | A system architecture talk | [Interactive architecture diagram](https://github.com/sonpiaz/watch-cli/blob/HEAD/prompts/extract-architecture.md) | | A UI / motion demo | [Working React component](https://github.com/sonpiaz/watch-cli/blob/HEAD/prompts/clone-ux.md) | | A paper or research talk | [Runnable notebook](https://github.com/sonpiaz/watch-cli/blob/HEAD/prompts/paper-to-code.md) | | A long tutorial | [Step-by-step cheat sheet](https://github.com/sonpiaz/watch-cli/blob/HEAD/prompts/tutorial-walkthrough.md) | The prompt library is what turns *"video โ†’ frames + transcript"* into *"video โ†’ working artifact"*. The full [Prompt library](#prompt-library) section below has copy-paste templates. --- ## Why this exists Large language models can't watch video natively โ€” they read text and look at still images. You can hand a video to a multimodal API and get back a chat-style summary, but for an agent workflow that's the wrong artifact: the agent wants the raw frames and the full transcript so it can reason for itself, not someone else's pre-digested recap. A video is just frames + audio, and each piece already has a fast, near-free primitive: - `yt-dlp` downloads from any social platform - `ffmpeg` extracts evenly-spaced frames - An ASR model transcribes the audio - A multimodal LLM hears tone, music, SFX, language, mood Compose them and your agent has the materials to watch any social video. --- ## What it looks like ```text $ watch https://www.linkedin.com/posts/some-talk_activity-12345 VIDEO: /tmp/dl-video/abc123.mp4 DURATION: 218 FRAMES: /tmp/frames_abc123/frame_01.jpg /tmp/frames_abc123/frame_02.jpg โ€ฆ TRANSCRIPT: Today I want to talk about how decomposition unlocks 10ร— cost reduction in multimodal pipelines โ€ฆ ``` Your agent reads the JPGs and the transcript. That's the whole watch. --- ## Why pay-per-use, not subscription Most subscription summary tools start around **$15/month** and deliver a polished, human-readable summary. If you're feeding an AI agent, that's the wrong artifact โ€” agents need raw frames and the full transcript to reason for themselves, not someone else's pre-digested recap. A typical research session is 1โ€“3 videos, not 100. Through Kyma โ€” the default backend โ€” a 1-hour video costs **~$0.05** (transcribe is the only paid step; frame extraction is local ffmpeg). | This month you watch | You pay | |---|---| | 0 videos | $0 | | 1 one-hour video | ~$0.05 | | 100 one-hour videos | ~$5 | No monthly minimum, no seat license, no lock-in. The free credit at Kyma signup is enough to run the full pipeline end-to-end before you spend a cent. --- ## Install ```bash # macOS โ€” Homebrew (recommended) brew tap sonpiaz/tap brew install watch-cli # Any OS โ€” curl curl -fsSL https://github.com/sonpiaz/watch-cli/releases/latest/download/install.sh | bash ``` > The curl one-liner auto-falls back to `git clone` of `main` if no > published release tarball is reachable. ### Claude Code (skill marketplace) If you use Claude Code, install watch-cli as a skill: ``` /plugin marketplace add sonpiaz/watch-cli /plugin install watch-cli@watch-cli ``` The agent then picks up `watch ` as a first-class command. Pin a specific version: ```bash curl -fsSL https://github.com/sonpiaz/watch-cli/releases/download/v0.3.4/install.sh \ | WATCH_CLI_VERSION=0.3.4 bash ``` Or from a clone: ```bash git clone https://github.com/sonpiaz/watch-cli ~/.watch-cli cd ~/.watch-cli && ./install.sh ``` The installer checks for `yt-dlp`, `ffmpeg`, `jq`, `curl`, `python3` and symlinks the commands into `~/.local/bin`. On macOS: ```bash brew install yt-dlp ffmpeg jq ``` On Debian/Ubuntu: ```bash sudo apt install yt-dlp ffmpeg jq python3 curl ``` ### Optional install flags ```bash ./install.sh --with-skill # also drop SKILL.md into ~/.claude/skills/watch-cli/ ./install.sh --with-mcp # print the npm install hint for the MCP stdio server ``` - `--with-skill` copies the portable `SKILL.md` into `~/.claude/skills/watch-cli/` so Claude Code picks up watch-cli as a skill on next start. The same file works in OpenClaw and hermes-agent โ€” see [`SKILL.md`](https://github.com/sonpiaz/watch-cli/blob/HEAD/SKILL.md). - `--with-mcp` prints the manual install line for [`@sonpiaz/watch-cli-mcp`](https://github.com/sonpiaz/watch-cli/blob/HEAD/mcp-server/), the MCP stdio server that exposes watch-cli to Claude Desktop, Cursor, Cline, Continue.dev, Windsurf, Zed, and any other MCP-capable client. The flag will auto-install once the package is published to npm. --- ## Setup ```bash export KYMA_API_KEY=kyma-xxxxxxxx ``` Get a Kyma key at [kymaapi.com](https://kymaapi.com/?src=skill:watch) โ€” 60 seconds, no card. Prefer bring-your-own-keys? Comment in `GROQ_API_KEY` and `GOOGLE_AI_KEY` in `.env.example` and watch-cli falls back to direct provider calls. --- ## Why Kyma watch-cli uses Kyma as its AI backend. A few things you get for free: ![models](https://img.shields.io/endpoint?url=https://api.kymaapi.com/api/badge/models.json) ![creators](https://img.shields.io/endpoint?url=https://api.kymaapi.com/api/badge/creators.json) ![free credit](https://img.shields.io/endpoint?url=https://api.kymaapi.com/api/badge/free-credit.json) - **One key, every model in this CLI.** watch-cli calls Kyma using capability aliases (`transcribe`, `audio-understand`). When Kyma swaps in a better model behind the alias, your scripts keep working unchanged. - **Per-call cost in the response.** Every transcribe gives you a real number, not an end-of-month dashboard surprise. - **Auto-fallback across providers.** If the underlying audio provider is throttling or down, Kyma routes through another. Your script never sees the outage. - **Free credit at signup.** About 9 hours of audio at the default rate. Enough to know if you like it before you spend a cent. The badges above pull live from `api.kymaapi.com/api/stats`, so the model count and free-credit number stay current without a watch-cli release. --- ## Commands ```text watch [frame-count] [--cookies ] [--no-cache] Orchestrator. Downloads, extracts frames, transcribes โ€” one block out. Archives the result; watching the same URL again reuses it. watch-archive ls | find | get | where Query everything you've watched. `find` returns the timestamp of the matching line, so you get a seek position, not a video to re-watch. dl-video [out-dir] [--cookies ] Just download the video. Returns the local mp4 path. extract-frames