Skip to content

CLI Usage

Basics

python manual.py -h                                                       # help + available sites
python manual.py -i streamingcommunity --search "interstellar"            # search and download
python manual.py -i streamingcommunity --search "interstellar" --item 0   # pick a result (0-based) without prompting
python manual.py -i 0 --search "interstellar"                             # site by index number
python manual.py -i streamingcommunity --search "interstellar" --skip-ts  # skip TS/CAM (StreamingCommunity only)
python manual.py -i streamingcommunity --search "interstellar" --no-log   # no log file for this run
python manual.py --dep                                                    # show dependency paths
python manual.py --migrate-config --dry-run                               # preview local JSON-to-TOML migration

For JSON configuration upgrades, see Migrating from JSON, including backups and --overwrite when TOML files already exist. python manual.py --migrate-config --help lists migration options without starting the application.

Site index numbers follow the services that are switched on: services listed in hidden_services are not loaded and the others are renumbered without gaps, so check -h for the current numbers (names never change).

Series and year

--season / --episode skip the prompts. Values: a number, a range "1-5", or "*" for all.

python manual.py -i streamingcommunity --search "breaking bad" --item 0 --season 1 --episode 3
python manual.py -i streamingcommunity --search "breaking bad" --item 0 --season 1 --episode "1-5"
python manual.py -i streamingcommunity --search "breaking bad" --item 0 --season 1 --episode "*"   # whole season
python manual.py -i streamingcommunity --search "breaking bad" --item 0 --season "*"               # all seasons
python manual.py -i streamingcommunity --search "breaking bad" --item 0 --season "1-3"

python manual.py -i streamingcommunity --search "dune" --year 2021          # exact year
python manual.py -i streamingcommunity --search "batman" --year "1990-2015" # range

Track selection and output

python manual.py ... -sv 1080                  # video
python manual.py ... -sa "eng"                 # audio language (long form: --audio-langs)
python manual.py ... -ss "eng"                 # subtitles (long form: --sub-langs)
python manual.py ... -ss "ita_forced"          # only the forced subtitle track
python manual.py ... -sa "deu" --skip-no-match # skip the whole download if the filter matches no track
python manual.py ... --extension mp4           # container (overrides PROCESS.extension for this run)

Full filter syntax: Stream selection filters.

Console, proxy, progress

python manual.py --close-console false                                # keep the console open (loop mode)
python manual.py -i ... --close-console true                          # close it after the download

python manual.py -i ... --use_proxy                                   # configured proxy, default scope
python manual.py -i ... --use_proxy --proxy-scope down                # only downloads (Velora)
python manual.py -i ... --use_proxy --proxy-scope scrap               # only scraping

python manual.py -i ... --plain-progress                              # one line per track every 5s, e.g.
#   Vid [H.264] 720p 2.4 Mbps  28%  290.2M / 1012.7M  65.27M/s  ETA 00:11
python manual.py -i ... --plain-progress --progress-interval 2        # every 2s
python manual.py -i ... --no-progress                                 # no progress output

Metadata sidecars

.nfo + artwork for Jellyfin/Emby/Kodi, only for a reliable match; off by default (DOWNLOAD.write_sidecars). See Metadata providers.

python manual.py -i ... --sidecars                                    # TMDB, then IMDb
python manual.py -i ... --sidecars --metadata-provider imdb           # IMDb only, no key
python manual.py -i ... --sidecars --metadata-provider tvdb,tmdb      # needs TVDB_API_KEY or Provider.tvdb
python manual.py -i ... --no-sidecars                                 # off for this run

Direct download (--down)

Download from a URL, skipping site search. Type is auto-detected (MP4 / HLS / DASH / ISM) or forced with --type.

# MP4 / auto-detected
python manual.py --down "https://example.com/video.mp4" -o "./Video/clip.mp4"

# HLS with a known key
python manual.py --down "https://example.com/master.m3u8" --type hls --key "<KID>:<KEY>" -o "./Video/movie.mkv"

# DASH + Widevine license server (--license-headers adds headers for the license request; repeatable like --headers)
python manual.py --down "https://example.com/manifest.mpd" --type dash \
  --license-url "https://example.com/wv/license" --drm widevine \
  --headers "Authorization: Bearer <token>" --license-headers "Authorization: Bearer <token>" -o "./Video/movie.mkv"

# Only a clip: segments 10-50, or a time range
python manual.py --down "https://example.com/master.m3u8" --type hls --max-segments "10-50" -o "./Video/clip.mkv"
python manual.py --down "https://example.com/master.m3u8" --type hls --max-time "00:01:00-00:05:00" -o "./Video/clip.mkv"

Custom JSON manifest

--down also takes a .json file/URL containing "vibravid_manifest" (auto-detected, no --type) for sources without a real manifest:

{
  "vibravid_manifest": true,
  "base_url": "https://cdn.example.com/movie/",
  "duration": 5410.0,
  "tracks": [
    {
      "type": "video", "id": "v1", "codecs": "avc1.640028",
      "width": 1920, "height": 1080, "bitrate": 4500000,
      "init": "init_video.mp4",
      "segments": {"template": "chunk_video_$Number$.m4s", "start": 1, "end": 1352, "duration": 4.0}
    },
    {
      "type": "audio", "id": "a1", "language": "eng", "codecs": "mp4a.40.2",
      "init": "init_audio.mp4",
      "segments": {"list": ["seg0.m4s", "seg1.m4s", "seg2.m4s"]}
    }
  ]
}
python manual.py --down "https://example.com/manifest.json" -o "./Video/movie.mkv"
segments mode Fields Behaviour
list URLs, or objects with url/size/duration/range explicit list
template template, start, step (or duration), end (or count) DASH-style $Number$ / $Time$ / $RepresentationID$ expansion
ranges / chunk url + ranges array, or chunk + size to auto-split byte ranges of a single file

init is a URL string, an object (url, range) or inline base64 (data). Placeholders support zero-padding ($Number%05d$); $$ is a literal $.

Export and import (--export, --import)

--export [FILE] resolves the tracks and keys like a normal run but does not download: it writes the result to a JSON file (default .cache/export/<site>_<type>_<title>.json). --import FILE downloads every entry of such a file, in sequence, with no search and (when the keys were exported) no CDM. Both work for MP4, HLS, DASH and ISM, from --down or from a service search (-i SITE -s QUERY --export).

python manual.py --down "https://example.com/master.m3u8" --key "<KID>:<KEY>" --export ./movie.json
python manual.py --import ./movie.json              # add -o to pick the output name (single entry)

Metadata for a direct download (--meta-*)

A plain --down has no title context, so title-dependent hooks and Vault upload/lookup are skipped. --meta-* attaches it (--resolve-only sets these automatically):

python manual.py --down "https://example.com/master.m3u8" --type hls --key "<KID>:<KEY>" \
  -o "./Video/Movie (2024)/movie.mkv" --meta-title "Movie Name" --meta-type Film --meta-site streamingcommunity

python manual.py --down "..." --type hls --key "<KID>:<KEY>" -o "./Video/Show/Season 01/episode.mkv" \
  --meta-title "Show Name" --meta-type TV --meta-season 1 --meta-episode 3

yt-dlp (--yt-dlp)

Any site yt-dlp supports (separate from --down, which is for HLS/DASH/ISM/MP4 URLs).

python manual.py --yt-dlp "https://www.youtube.com/watch?v=..." -o "./Video/clip.mp4"
python manual.py --yt-dlp "<URL>" --extract-audio --audio-format mp3 --audio-quality 0
Flag Effect
--yt-dlp <URL> Download with yt-dlp instead of the site-search/--down flow
--format <SPEC> Format selector (default bestvideo+bestaudio/best)
--list-formats List formats and exit
--interactive-format Show formats and prompt for the format ID
--extract-audio Audio only
--audio-format <FORMAT> mp3, m4a, wav, opus, ...
--audio-quality <QUALITY> 0, 5, 8k, ...
--playlist-end <N> Only the first N playlist entries
--sub-langs <LANGS> Subtitle languages (it,en); same flag as -ss
--write-subs / --write-auto-subs Write subtitles / auto-generated subtitles
--cookies-from-browser <BROWSER> Load cookies from a browser (chrome, firefox, edge, chrome:Profile 1). Needed for YouTube's "Sign in to confirm you're not a bot"
--cookies <FILE> Netscape cookies.txt file (same as yt-dlp's --cookies)
--extractor-args <IE:ARGS> Extra yt-dlp extractor arguments, repeatable (e.g. youtube:player_client=web_safari)
VIBRAVID_YTDLP_COOKIES_FROM_BROWSER / VIBRAVID_YTDLP_COOKIEFILE Environment-variable equivalents, applied to every yt-dlp call (including YouTube search)

Advanced options

Flag Effect
--use-curl-cffi Download segments via curl_cffi (browser TLS impersonation) instead of Velora, for Cloudflare-protected segments
--http-version {1.1,2,3} Force the HTTP version
-o, --output <PATH> Output path for --down / --yt-dlp
--clear Delete the cached login/session tokens of the service given with -i (requires -i; never touches other services or login.toml)
--key <KID:KEY> Hex decryption key, repeatable. With --down or a service run (-i 0 --key <KID>:<KEY>): used instead of the vault/CDM for the KIDs it covers, other KIDs resolve normally
--no-vault-cache Bypass the vault cache; fresh CDM license request every run
--vault-import <PATH> Send the keys of a local vault .db (or every vault.db in a folder, e.g. .cache/services) to the server of [DRM.vault.default], then exit. The server skips keys it already has. The service is the folder name under .cache/services/, else --meta-site, else generic. Add --vault-import-all to send the already imported keys again, --vault-import-dry-run to only count
--cdm <CDM> CDM for this run, above login.toml and config.toml: a .wvd/.prd name, search, or a remote CDM id. Repeatable, one per DRM system (--cdm mine.wvd --cdm my_playready). A JSON list/table is accepted for quality rules. Unknown file/id stops the run before downloading
--no-decrypt Debug: no decryption at all (in-flight or post-download)
--no-livemux / --livemux Disable / force the streaming-mux fast path (off by default: turn it on with process in login.toml or PROCESS.use_live_mux)
--no-live-decrypt Disable in-flight (per-segment) decryption for this run: segments are decrypted after the download. It is on only with process.live_decrypt / DOWNLOAD.use_live_decrypt (process in login.toml, DOWNLOAD.use_live_decrypt)
--no-concurrent Download video, audio and subtitles sequentially (concurrent by default)
--skip-no-match Skip the download if -sv/-sa/-ss match no track, instead of falling back to the best
--log-decryptor-output Write flux's stdout/stderr to the log, tagged with the engine name (e.g. [FLUX])
--abc Anonymize printed KID:KEY pairs (alternating characters masked with ?)
--hls-method AES_128\|NONE Override the HLS encryption method, ignoring #EXT-X-KEY (or supplying it). NONE = clear segments; AES_128 = AES-128-CBC (pair with --hls-key/--hls-iv)
--hls-key <HEX\|BASE64\|FILE> Raw AES-128 key instead of fetching the manifest's URI=
--hls-iv <HEX> IV instead of the manifest's IV=0x... (or the implicit per-segment IV)
--skip-content-check Skip the HEAD content-type check for MP4 downloads (--type mp4), for single-use URLs
--skip-sanitize Use -o verbatim (no transliteration of non-ASCII characters)
--no-manifest-info Don't print the manifest/streams table
--binary-update Check FFmpeg/Flux/Packager/dovi_tool/MKVToolNix/Velora against AstraeLabs/Binary and re-download outdated ones (the CLI also does it every 2 days: auto_update_binaries)
--resolve-only Resolve and cache manifest/keys/license/playlist without downloading (pairs with the queue)
--export [FILE] Resolve tracks and keys, write them to a JSON file instead of downloading (see Export and import)
--import <FILE> Download every entry of a file written by --export, no search and no CDM when the keys were exported
--tui Launch the Textual terminal UI
-UP, --update Auto-update to the latest release (binary builds only)
--check-update Print how to update for your installation (binary, source, Docker) and exit
--skip-update-check Skip the background startup check (cached 24h; failures retried after 30 min); auto_check_update = false in config.toml turns it off for good
--version Print the version and exit
# Manual AES-128 override (manifest without its own #EXT-X-KEY)
python manual.py --down "https://example.com/master.m3u8" --type hls --hls-method AES_128 \
  --hls-key "0011223344556677889900112233445566" --hls-iv "00000000000000000000000000000001" -o "./Video/clip.mkv"

Default options for a service

python manual.py -i <service> --help lists a service's options; args in login.toml sets permanent defaults for them (details).

Download queue (--queue-*)

python manual.py -i streamingcommunity --search "interstellar" --item 0 --queue-add   # queue instead of downloading
python manual.py --down "https://example.com/movie.mkv" -o "./Video/movie.mkv" --queue-add
python manual.py --queue-list
python manual.py --queue-remove <ID>
python manual.py --queue-clear
python manual.py --queue-run                       # process every pending/interrupted item in order

Note

Only invocations that complete without any prompt can be queued; ambiguous ones (--global, a site search without --item) are rejected when enqueued.

Items enqueued together share an auto-generated queue name (e.g. 20260723-152525, shown by --queue-list). Pass it to target one batch:

python manual.py --queue-run 20260723-152525       # also --queue-list / --queue-clear <name>
python manual.py --queue-run --queue-ids abc12345,def67890   # only these item ids (see --queue-list)
python manual.py --queue-select                    # pick the queue from a numbered list
python manual.py --global -s "cars"
python manual.py --category 1    # Anime   (2: Movies & Series, 3: Series only, 4: Movies only)