CLI Commands¶

The vdl command provides a full-featured media download toolkit with subcommands for different workflows.

The main day-to-day commands are:

Command	Use
`vdl`	Launch interactive mode
`vdl download`	Download a direct URL, link file, or playlist with `--playlist`
`vdl crawl`	Crawl a page and download discovered media links
`vdl playlist`	Download all items from a playlist URL
`vdl resolve`	List playlist items without downloading
`vdl status`	Read interactive-mode download history
`vdl doctor`	Check local dependencies and runtime health

Global Flags¶

These flags work at the top level and on the download-oriented subcommands. For convenience, --json, --output, and --quality can appear before or after download, playlist, or crawl.

Flag	Short	Description
`--version`	`-V`	Print VDL version and exit
`--json`		Output results as JSON (machine-readable)
`--output`	`-o`	Override default output directory
`--quality`	`-q`	Quality preference (best, 720p, 1080p, audio, etc.)

vdl (Interactive Mode)¶

Run VDL with no subcommand to launch the interactive app:

vdl

This opens a guided interface for: - URL/file input - Quality selection - Download folder - Media options (thumbnails, subtitles) - Mode selection (direct download or crawl)

See Quick Start for a walkthrough.

vdl download¶

Download a single video or use --playlist to download all playlist items.

Syntax¶

vdl download <URL> [OPTIONS]

Options¶

Flag	Description	Example
`--quality`, `-q`	Video quality	`--quality 720p`
`--if-exists`	Collision policy (rename, skip, overwrite, fail)	`--if-exists skip`
`--playlist`	Download all playlist items	`--playlist`
`--cookies`	Path to Netscape cookies file	`--cookies ~/cookies.txt`
`--cookies-from-browser`	Browser to extract cookies from	`--cookies-from-browser firefox`

Examples¶

# Simple download at best quality
vdl download "https://example.com/video"

# Download at 720p to a specific folder
vdl download "https://example.com/video" -q 720p -o ~/Videos

# Download all playlist items
vdl download "https://example.com/playlist" --playlist

# Skip if file exists
vdl download "https://example.com/video" --if-exists skip

# With cookies
vdl download "https://example.com/video" --cookies-from-browser chrome

# Output JSON results
vdl download "https://example.com/video" --json

vdl playlist¶

Download all items from a playlist. Equivalent to vdl download --playlist.

Syntax¶

vdl playlist <URL> [OPTIONS]

Options¶

Same as vdl download (see above). If you need to select specific items from a playlist, use interactive mode instead.

Examples¶

vdl playlist "https://example.com/playlist"
vdl playlist "https://example.com/playlist" --if-exists skip
vdl playlist "https://example.com/playlist" -q audio  # Audio-only

vdl crawl¶

Crawl a page for downloadable media links and download the discovered items.

Syntax¶

vdl crawl <URL> [OPTIONS]

Options¶

Flag	Description	Example
`--first`	Stop after N successful downloads	`--first 3`
`--min-filesize`	Reject crawl downloads smaller than SIZE	`--min-filesize 10MB`
`--allow-tiny`	Disable the crawl minimum filesize filter	`--allow-tiny`
`--crawl-pagination`	Follow numbered/navigation pages discovered during crawl	`--crawl-pagination`
`--quality`, `-q`	Video quality	`--quality 720p`
`--output`, `-o`	Output directory	`--output ~/Videos`
`--if-exists`	Collision policy (rename, skip, overwrite, fail)	`--if-exists skip`
`--cookies`	Path to Netscape cookies file	`--cookies ~/cookies.txt`
`--cookies-from-browser`	Browser to extract cookies from	`--cookies-from-browser chrome`
`--json`	Output final results as JSON	`--json`

Examples¶

# Crawl a page and download every discovered media link
vdl crawl "https://example.com/gallery"

# Crawl until the first three downloads complete or skip successfully
vdl crawl "https://example.com/gallery" --first 3

# Crawl into a specific folder
vdl crawl "https://example.com/gallery" --first 3 --output ~/Videos

# Turn off the default crawl tiny-file filter
vdl crawl "https://example.com/gallery" --allow-tiny

# Crawl page 1 and follow discovered navigation pages too
vdl crawl "https://example.com/gallery" --crawl-pagination

# JSON output for scripts
vdl crawl "https://example.com/gallery" --first 3 --json

vdl resolve¶

List items in a playlist without downloading.

Syntax¶

vdl resolve <URL>

Output¶

Plain text (one line per item):

  1 | First Video      | https://example.com/video1 | 3:45
  2 | Second Video     | https://example.com/video2 | 5:20
  3 | Third Video      | https://example.com/video3 | 2:10

With --json, outputs structured data for parsing.

Examples¶

# List playlist items
vdl resolve "https://example.com/playlist"

# Get JSON for scripting
vdl resolve "https://example.com/playlist" --json | jq '.items[].title'

vdl status¶

Query download history from the interactive state database.

Syntax¶

vdl status [ID]

Without ID¶

Shows recent downloads (up to 20):

vdl status

Output:

ID           | URL                    | Quality | Status    | Path
-------------|------------------------|---------|-----------|-----
abc123...    | https://example.com/v1 | 720p    | completed | ~/Videos/video1.mp4
def456...    | https://example.com/v2 | 1080p   | skipped   | ~/Videos/video2.mp4

With ID¶

Show details for a specific download:

vdl status abc123

Output:

ID:          abc123...
URL:         https://example.com/video
Quality:     720p
Status:      completed
Output:      ~/Videos/video.mp4
Started:     2024-01-15 10:30:45
Completed:   2024-01-15 10:32:12

Note¶

The status database is only created when you use interactive mode (vdl with no args). Headless downloads (CLI subcommands) do not record state.

vdl doctor¶

Health check for VDL dependencies and configuration.

Syntax¶

vdl doctor

Output¶

Tool            | Status | Version
----------------|--------|------------
vdl             | ✓      | 1.0.4
ffmpeg          | ✓      | 6.0
ffprobe         | ✓      | 6.0
yt-dlp          | ✓      | 2024.01.15
js-runtime      | ✓      | node 20.1.0
config          | ✓      | valid
state           | ✓      | /path/to/vdl.db
cache           | ✓      | /path/to/cache
mcp             | ✓      | available

If any tool is missing, doctor will suggest installation commands.

Exit Code¶

0 if all critical tools (ffmpeg, ffprobe, yt-dlp) are available
1 if any are missing

vdl config¶

Manage VDL configuration.

Subcommands¶

`vdl config show`¶

Display the entire configuration:

vdl config show

Output:

output_dir = /home/user/Downloads/VDL
default_quality = best
audio_only = false
max_concurrent_downloads = 3
...

`vdl config get <KEY>`¶

Get a single config value:

vdl config get output_dir
vdl config get max_concurrent_downloads

Output:

/home/user/Downloads/VDL

`vdl config set <KEY> <VALUE>`¶

Set a config value:

vdl config set output_dir ~/Videos
vdl config set max_concurrent_downloads 5
vdl config set write_subtitles true

Tip: Use vdl config show to see all valid keys.

vdl interactive¶

Explicitly launch the interactive mode (same as vdl with no args):

vdl interactive

vdl help¶

Show help and command reference.

Syntax¶

vdl help [TOPIC]

Examples¶

# Top-level help
vdl help

# Help for a specific subcommand
vdl help download
vdl help playlist
vdl help status
vdl help config

vdl mcp¶

MCP server utilities.

`vdl mcp setup`¶

Generate configuration snippets for integrating with Claude Desktop or other MCP hosts:

vdl mcp setup

This outputs JSON configs you can paste into claude_desktop_config.json or your MCP client configuration file.

See MCP & Tools for details.

Exit Codes¶

Code	Meaning
0	All operations succeeded (or skipped)
1	One or more operations failed, or dependency missing

For vdl download / vdl playlist: - Returns 0 if all results have status of COMPLETED or SKIPPED - Returns 1 if any result has status of FAILED

JSON Output Format¶

Many commands support --json for machine-readable output:

vdl download "URL" --json

Output:

{
  "id": "abc123...",
  "source_url": "https://example.com/video",
  "status": "completed",
  "quality": "720p",
  "output_path": "/path/to/video.mp4",
  "error": null,
  "skip_reason": null,
  "metadata": {}
}

Examples¶

Download and save to a specific folder¶

vdl download "https://example.com/video" -o ~/my-videos

Batch download playlists with concurrency control¶

# Change max downloads in config first
vdl config set max_concurrent_downloads 2

vdl playlist "https://example.com/playlist"

Check download history¶

vdl status
vdl status abc123...

Health check before automation¶

vdl doctor
if [ $? -eq 0 ]; then
  vdl download "URL"
fi

CLI Commands¶

Global Flags¶

vdl (Interactive Mode)¶

vdl download¶

Syntax¶

Options¶

Examples¶

vdl playlist¶

Syntax¶

Options¶

Examples¶

vdl crawl¶

Syntax¶

Options¶

Examples¶

vdl resolve¶

Syntax¶

Output¶

Examples¶

vdl status¶

Syntax¶

Without ID¶

With ID¶

Note¶

vdl doctor¶

Syntax¶

Output¶

Exit Code¶

vdl config¶

Subcommands¶

vdl config show¶

vdl config get <KEY>¶

vdl config set <KEY> <VALUE>¶

vdl interactive¶

vdl help¶

Syntax¶

Examples¶

vdl mcp¶

vdl mcp setup¶

Exit Codes¶

JSON Output Format¶

Examples¶

Download and save to a specific folder¶

Batch download playlists with concurrency control¶

Check download history¶

Health check before automation¶

See Also¶

`vdl config show`¶

`vdl config get <KEY>`¶

`vdl config set <KEY> <VALUE>`¶

`vdl mcp setup`¶