Quick start

You have installed ytb and it is on your PATH. This page is a five-minute tour that ends with you pulling real data out of YouTube. Nothing here needs an API key.

1. Resolve a video

Give ytb a video id or any watch URL:

ytb video dQw4w9WgXcQ

Writing to a terminal, list commands render an aligned table; piped, they switch to JSONL automatically. Ask for the whole record as JSON:

ytb video dQw4w9WgXcQ -o json

You get the title, channel, view and like counts, publish date, duration, category, tags, hashtags, the thumbnail, and more. Narrow it to the columns you care about:

ytb video dQw4w9WgXcQ --fields title,channel,views -o table

2. Walk a channel

Point at a channel by handle, id, or URL and stream its uploads. ytb follows the continuation tokens for you, so this keeps going until your limit is hit:

ytb uploads @RickAstleyYT -n 20

Add --kind shorts or --kind streams for those, ytb playlists for the channel's playlists (and --kind releases, podcasts or courses for the other three tabs), and ytb channel on its own for the channel record.

3. Search with filters

Search takes the same filter grid the site has:

ytb search "lofi hip hop" -n 25
ytb search "drone footage" --4k --duration long --sort date
ytb search "podcast" --type channel

Render just the URLs and pipe them straight into another command:

ytb search "go programming" -o url -n 10 | ytb video -

The trailing - tells video to read its arguments from stdin, one per line.

4. Read a transcript

List the caption tracks a video has:

ytb captions dQw4w9WgXcQ

Fetch one of them as text, as subtitles, or as timed cues:

ytb transcript dQw4w9WgXcQ
ytb transcript dQw4w9WgXcQ --format srt --out never.srt
ytb transcript dQw4w9WgXcQ --format json

Nothing here needs yt-dlp, ffmpeg, Deno or a JavaScript interpreter. The track is fetched and parsed in-process. See comments and transcripts for picking a track, the auto-generated one, and machine translation.

5. Download a video

ytb download has a built-in pure-Go engine, so a basic grab needs no API key and no external downloader:

ytb download dQw4w9WgXcQ
ytb download dQw4w9WgXcQ -x --audio-format mp3

The first saves the best combined stream; the second pulls audio only and transcodes to mp3 (which uses ffmpeg if it is on your PATH). See downloading media for format selection, playlists, and subtitles. Media download is your responsibility: respect YouTube's Terms of Service and copyright.

6. Keep what you fetch

ytb crawl walks the graph from a seed and writes what it saw into a local SQLite file under your data directory. Everything else just streams to stdout.

ytb crawl @RickAstleyYT --depth 2 --budget 200
ytb db stats
ytb query "select uri from nodes where kind='video' and record is null limit 5"

The nodes with no record are the frontier, so ytb crawl --resume picks up where the budget ran out. See the local store.

Where to go next

• The guides go deep on each area: videos, channels and playlists, search, comments and transcripts, music, and the local store.
• The CLI reference is the complete command and flag surface.
• Output formats covers -o, --fields, and --template in full.