Guides

The CLI

tldw runs the same 100% local pipeline as the app, from your terminal. It's distributed on npm and works offline with Ollama (or any cloud key you bring).

Install

ffmpeg is required for audio extraction (yt-dlp and Whisper ship with the package):

💡
Apple Silicon macOS only. The CLI shares downloaded Whisper models with the Mac app.

Usage

tldw "<url-or-file>" [options]

The positional argument is a URL (YouTube, X, Vimeo, TikTok, … via yt-dlp) or a path to a local video/audio file. With no --skill, you get a Markdown note by default. A real example:

tldw "https://www.youtube.com/watch?v=IlqJqcl8ONE" --notes
⚠️
Always wrap URLs in quotes. A YouTube URL contains ? and &, which your shell (zsh) treats as special characters. Without quotes it fails before TLDW even runs — zsh: no matches found. Quoting the URL fixes it.
💡
You also need an AI to summarize. The CLI defaults to local Ollama — make sure it's installed and a model is pulled (ollama pull qwen2.5:14b-instruct), or use a cloud provider with --provider + a key (see API keys). Transcription is always local.

Options

FlagDescription
--notesProduce a Markdown note (default when no --skill is given).
--skill <fmt>Produce an agent skill: claude, codex, agents, cursor, or prompt. Combine with --notes for both.
--provider <p>ollama (default), openai, anthropic, gemini, or openrouter.
--model <id>Model id. Defaults per provider (e.g. qwen2.5:14b-instruct for Ollama).
--key <key>API key for a cloud provider (or use an env var — see below). Ollama needs none.
--style <id>Summary style: detailed (default), executive, or bullets.
--whisper <model>Transcription quality: tiny, base, small (default), medium, large-v3-turbo.
--out <dir>Output folder. Defaults to the current directory.
--no-tagsDisable AI tagging (on by default).
--transcriptAppend the full transcript to the note.
--jsonPrint the result(s) as JSON to stdout instead of plain paths.
--quietSuppress progress (errors still go to stderr).
-h, --helpShow help.
--versionShow the version.

API keys

Cloud providers read their key from --key or, if omitted, from an environment variable:

ProviderEnv var
OpenAIOPENAI_API_KEY
AnthropicANTHROPIC_API_KEY
OpenRouterOPENROUTER_API_KEY
Google GeminiGEMINI_API_KEY

Examples

# A Markdown note from a link (Ollama, offline) → printed path on stdout
tldw "https://www.youtube.com/watch?v=IlqJqcl8ONE"

# A Claude skill from a local file
tldw lecture.mp4 --skill claude

# Both a note AND a skill in one run, via Anthropic
ANTHROPIC_API_KEY=sk-ant-… tldw "https://www.youtube.com/watch?v=IlqJqcl8ONE" --notes --skill claude --provider anthropic

# Higher-accuracy transcription into a specific folder
tldw talk.mp3 --provider ollama --whisper medium --out ~/Notes

# Open the resulting note (paths print to stdout, so it composes)
note=$(tldw "$URL") && open "$note"

# Batch a list of links with a shell loop
while read url; do tldw "$url" --out ~/Notes; done < links.txt

Output

Progress is written to stderr; the resulting file path(s) to stdout — so tldw pipes and scripts cleanly. With --json, stdout is a structured object instead:

{
  "title": "Build a REST API in Python",
  "results": [
    { "format": "notes", "path": "/…/2026-06-03 — Build a REST API.md", "tags": ["Tutorial", "Reference"] },
    { "format": "claudeSkill", "path": "/…/build-a-rest-api/SKILL.md", "tags": ["Backend", "API"] }
  ]
}

Exit code is 0 when at least one output succeeds, 1 on failure, 2 on a usage error.

Troubleshooting

npm ls -g --depth=0 tldw-cli        # confirms it's installed
echo "$(npm prefix -g)/bin"          # where the 'tldw' command lives
# add that folder to your shell, then reload:
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
which tldw
← PreviousThe Mac appNext →The browser extension