Skip to content

Quick Start

When VDL Helps

VDL is not trying to be a better one-off downloader command for every user. It is a developer-friendly orchestration layer for building local-first media apps, crawlers, batch managers, tools, and workflows.

Use VDL when you want structured results, progress callbacks, cancellation, planning, discovery, playlist/list handling, and clean Python/CLI/tool surfaces. If you only need to download one URL manually, a lower-level downloader command may be enough.

Surfaces and State

VDL has three surfaces:

Surface State Model Notes
Python library Stateless by default Embeddable; your app owns persistence
Headless CLI Stateless by default Script-friendly; no implicit DB/bootstrap
Interactive app Intentionally stateful Creates local app dirs, SQLite, and logs for history/status UX

First Run — Interactive Mode (macOS & Linux)

The simplest way to use VDL is the interactive app (available on macOS and Linux):

vdl

This launches a guided interface:

  1. Enter a URL — paste a video, playlist, or page URL
  2. Choose quality — select resolution (720p, 1080p, best, audio, etc.)
  3. Set output directory — where to save the file(s)
  4. Download options — write thumbnails, subtitles, etc.
  5. Choose action — download now, or just preview

The app then: - Detects if the URL is a single video or playlist - Shows available items - Handles collisions (rename, skip, overwrite) - Displays progress with speed and ETA - Saves state to ~/.local/state/vdl/vdl.db for later review

CLI — One-Shot Download (All Platforms)

If you prefer the command line or are on Windows, download a single video:

vdl download "https://example.com/video" --quality 720p

This downloads to your configured output directory (default: ~/Downloads/VDL).

See CLI Commands for all flags.

CLI — Crawl a Page

Use vdl crawl when the input is a gallery, index page, or collection page and you want VDL to discover media links first. --first 3 means VDL keeps trying discovered candidates until three downloads complete or skip successfully:

vdl crawl "https://example.com/gallery" --first 3

To save into a specific folder:

vdl crawl "https://example.com/gallery" --first 3 --output ~/Videos

Python Library — Programmatic Control

Use VDL in your own code:

import asyncio
from vdl import VDLClient
from vdl.models import Quality

async def main():
    client = VDLClient()  # Loads config from ~/.config/vdl/config.toml
    result = await client.download(
        "https://example.com/video",
        quality=Quality.P720,
        output_dir="~/Downloads/VDL"
    )
    print(result.status)  # DownloadStatus.COMPLETED
    print(result.output_path)  # /path/to/video.mp4

asyncio.run(main())

This is stateless by default — no database is created unless you explicitly use interactive mode.

Common Workflows

Download a Playlist

CLI: 

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

Python: 

results = await client.download_playlist("https://example.com/playlist")
for result in results:
    print(result.status, result.output_path)

Batch Download from a File

Create links.txt: 

https://example.com/video1
https://example.com/video2
https://example.com/playlist

Python: 

plan = await client.plan("links.txt")
results = await client.execute_plan(plan)

See Planning for details.

Handle Existing Files

Use the --if-exists flag (or if_exists parameter):

# Skip if file exists
vdl download "URL" --if-exists skip

# Rename with a suffix instead
vdl download "URL" --if-exists rename  # default

# Delete and re-download
vdl download "URL" --if-exists overwrite

# Fail if file exists
vdl download "URL" --if-exists fail

See Downloads for the collision policy table.

Getting Help

# General help
vdl help

# Subcommand help
vdl help download
vdl help crawl
vdl help playlist

# Version
vdl --version

# Health check
vdl doctor

Next Steps