watch-cli

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.

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/:

The prompt library is what turns "video → frames + transcript" into "video → working artifact". The full 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

$ 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).

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

# 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 <url> as a first-class command.

Pin a specific version:

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:

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:

brew install yt-dlp ffmpeg jq

On Debian/Ubuntu:

sudo apt install yt-dlp ffmpeg jq python3 curl

Optional install flags

./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.
• --with-mcp prints the manual install line for @sonpiaz/watch-cli-mcp,
  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

export KYMA_API_KEY=kyma-xxxxxxxx

Get a Kyma key at kymaapi.com. About 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.

Runs on Kyma API: one key covers speech-to-text and audio scene Q&A for every watch / transcribe / audio-q run.

Default Kyma calls (scripts send capability aliases; Kyma resolves them to the models below):

Why Kyma

watch-cli uses Kyma as its AI backend. A few things you get for free:

• 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

watch <url> [frame-count] [--cookies <file>] [--no-cache]
  Orchestrator. Downloads, extracts frames, transcribes — one block out.
  Archives the result; watching the same URL again reuses it.

watch-archive ls | find <query> | get <id|url> | 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 <url> [out-dir] [--cookies <file>]
  Just download the video. Returns the local mp4 path.

extract-frames <video> [count] [out-dir]
  Pull N evenly-spaced JPG frames. Default 8.

transcribe <audio-or-video> [language] [--segments-out <path>]
  Speech-to-text. Auto-extracts audio from video first.
  --segments-out also writes timestamped segments to a JSON sidecar.

audio-q <audio-or-video> "<question>"
  Audio scene Q&A — tone, music, SFX, language, emotion.
  Beyond pure transcription.

models [--all]
  List audio models available on Kyma (live, no hardcoded list).
  --all to see every Kyma SKU (text + image + video + audio).

Watch once, keep it

Every successful run is archived to ~/.watch-cli/archive, so the same
video is never transcribed twice. A second watch on the same URL skips
both the download and the ASR call and prints byte-identical output.

watch https://youtu.be/xyz          # first run: downloads, transcribes
watch https://youtu.be/xyz          # cache hit, no API spend
watch-archive find "context graph"  # → id, [04:32], the line, across everything

Records are plain JSON, SRT and JPG on disk. grep and jq read them
perfectly well without this tool, and transcript.srt drops straight into
any video player. Full layout in docs/archive.md.

How transcribe and audio-q stay current

The scripts call Kyma using the transcribe and audio-understand aliases,
not raw model IDs. When Kyma swaps the underlying model (Whisper v4,
Voxtral, a faster ASR), watch-cli keeps working without an update — the
alias points to whichever model is current. Run watch-cli models any time
to see what's behind the alias today.

Login-walled videos

Most YouTube / TikTok / Reddit / Vimeo / public X work without setup.
LinkedIn, private X posts, and Facebook need a session.

watch-cli fetches every URL anonymously and never reads a browser
session on its own. For a login-walled URL, opt in per run:

WATCH_BROWSER=auto watch <url>      # any signed-in browser: Chrome → Firefox → Safari → Edge → Brave → Chromium
WATCH_BROWSER=firefox watch <url>   # one browser

Cookies are read from the local browser profile by yt-dlp, sent only to
that platform, and never stored or uploaded.

For servers / CI without browsers, pass a manual cookies file:

watch <url> --cookies ~/cookies.txt

Full setup walkthrough: docs/cookies.md.

Use with Claude Code (or any agent)

You have access to a `watch` command that takes a URL and returns
a video, 8 frames, and the transcript. Read the frames as images and
the transcript as text — that's enough to "watch" any social video.

The output block is structured so an agent can parse it without help:
VIDEO: line, FRAMES: block (one path per line), TRANSCRIPT: block.

Prompt library

Beyond the generic prompt above, five copy-paste prompts in
prompts/ turn watch output into a specific artifact:

Paste the chosen prompt above the watch output, hand the whole thing
to your agent.

Use as a Claude Code skill

Drop skills/watch-cli/ into your
~/.claude/skills/ folder and the agent will pick up /watch <url>
as a first-class command, including the prompt library above.

mkdir -p ~/.claude/skills
cp -r skills/watch-cli ~/.claude/skills/

How it works

URL ──▶ yt-dlp ──▶ video.mp4 ──┬──▶ ffmpeg ──▶ frames/*.jpg
                                │
                                └──▶ ffmpeg ──▶ audio.mp3 ──┬──▶ Kyma /v1/audio/transcriptions
                                                            │     (Whisper Large v3 Turbo, 228× realtime)
                                                            │
                                                            └──▶ Kyma /v1/audio/understand
                                                                  (Gemini 3 Flash audio — tone/music/SFX)

Each step is a primitive. None of them needs a vision LLM.

Show what you build

Built something cool from a video? Drop it in
Discussions under
Show and tell. Post the source URL, the prompt you used, and your
artifact. Curated highlights make it back into the README.

Limitations and cost

Watch-cli is fast and cheap because it composes primitives instead of
calling a video LLM. The tradeoffs are honest.

Cost per video

Transcription is the only paid step. Frame extraction is local ffmpeg,
free.

Free credit at Kyma signup covers about 9 hours of transcribe. A BYOK
path is available — see .env.example.

What works well

• Talking-head content: tutorials, conference talks, lectures, walkthroughs
• Architecture and system diagrams shown for at least 3 seconds
• Code that stays on screen long enough to read
• ~95 languages (anything Whisper v3 turbo supports)

What works poorly

• Music videos, action movies, fast-cut content. Eight evenly-spaced
  frames miss key moments. Bump count: watch <url> 24.
• Editor sessions that scroll fast through code. Same fix.
• Audio with heavy background music and overlapping speakers. Transcript
  quality drops. Use audio-q for a scene description instead.
• Videos longer than ~2 hours. The transcribe provider has a 25MB audio
  cap. Watch-cli auto-downsamples but a 3-hour talk may still exceed.
  Workaround: split via ffmpeg -ss before piping.

What does not work yet

• Region-locked videos (some YouTube, TikTok). yt-dlp returns an error;
  watch-cli surfaces it.
• Live streams. Download finishes only after the stream ends.
• Silent screencasts. Transcribe returns empty. Increase frame count and
  use audio-q for any sound design instead.

Frame count guidance

License

MIT. © 2026 Son Piaz.