Usage

Usage#

ytdl-sub [GENERAL OPTIONS] {sub,dl,view} [COMMAND OPTIONS]

For Windows users, it would be ytdl-sub.exe

General Options#

CLI options common to all sub-commands. Must be specified before the sub-command, for example $ ytdl-sub --dry-run sub ...:

-h, --help            show this help message and exit
-v, --version         show program's version number and exit
-c CONFIGPATH, --config CONFIGPATH
                      path to the config yaml, uses config.yaml if not provided
-d, --dry-run         preview what a download would output, does not perform any video downloads or writes to output directories
-l quiet|info|verbose|debug, --log-level quiet|info|verbose|debug
                      level of logs to print to console, defaults to verbose
-t TRANSACTIONPATH, --transaction-log TRANSACTIONPATH
                      path to store the transaction log output of all files added, modified, deleted
-st, --suppress-transaction-log
                      do not output transaction logs to console or file
-nc, --suppress-colors
                      do not use colors in ytdl-sub output
-m MATCH [MATCH ...], --match MATCH [MATCH ...]
                      match subscription names to one or more substrings, and only run those subscriptions

Subscriptions Options#

Download all subscriptions specified in each subscriptions file.

ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...]

SUBPATH is one or more paths to subscription files and defaults to ./subscriptions.yaml if none are given. It will use the config specified by --config, or ./config.yaml, if not provided.

Additional Options#
-u, --update-with-info-json
                      update all subscriptions with the current config using info.json files
-o DL_OVERRIDE, --dl-override DL_OVERRIDE
                      override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3'

Download Options#

Download a single subscription in the form of CLI arguments instead of from a subscriptions file:

ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS]

SUBSCRIPTION ARGUMENTS are the same as YAML arguments, but use periods (.) instead of indents. For example, you can represent this subscription:

rick_a:
  preset:
    - "tv_show"
  overrides:
    tv_show_name: "Rick A"
    url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"

Using the command:

ytdl-sub dl \
    --preset "tv_show" \
    --overrides.tv_show_name "Rick A" \
    --overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"

See how to shorten commands using download aliases.

View Options#

Preview the source variables for a given URL. Helpful to create new subscriptions:

ytdl-sub view [-sc] [URL]
Additional Options#
-sc, --split-chapters
                      View source variables after splitting by chapters

CLI to SUB Options#

Convert yt-dlp cli arguments to ytdl-sub ytdl_options arguments.

ytdl-sub cli-to-sub [YT-DLP ARGS]

Inspect#

Inspect a single subscription’s underlying preset representation. This can be utilized for numerous purposes including:

  • Ensuring your custom preset is getting applied correctly.

  • Figuring out which variables set things like file names, metadata, etc.

  • Understanding how subscription syntax translates to preset representation.

Usage:

ytdl-sub inspect --match "Game Chops" --mock 'title=Lets Play' examples/music_subscriptions.yaml
Additional Options#
   -l 0,1,2,3, --level 0,1,2,3
                         level of inspection to perform:
                             0 - original   present the subscription as-is
                             1 - fill       fill in defined values
                             2 - resolve    resolve all possible variables (default)
                             3 - internal   resolve all variables to their internal representation

   -m MATCH [MATCH ...], --match MATCH [MATCH ...]
                         match subscription names to one or more substrings, and only run those subscriptions
   -o DL_OVERRIDE, --dl-override DL_OVERRIDE
                         override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3'
   -k VAR=VALUE, --mock VAR=VALUE
                         ability to mock one or more variable values, i.e. --mock 'title=Lets Play'