Usage
=====

.. code-block::

  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 ...``:

.. code-block:: text

  -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 :doc:`subscriptions file
<./guides/getting_started/subscriptions>`.

.. code-block::

   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.

.. code-block:: text
  :caption: 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 :doc:`a
subscriptions file <./guides/getting_started/subscriptions>`:

.. code-block::

  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:

.. code-block:: yaml

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

Using the command:

.. code-block:: bash

  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 :ref:`download aliases <config_reference/config_yaml:dl_aliases>`.


View Options
------------

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

.. code-block::

   ytdl-sub view [-sc] [URL]

.. code-block:: text
  :caption: 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.

.. code-block::

   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:

.. code-block:: bash

   ytdl-sub inspect --match "Game Chops" --mock 'title=Lets Play' examples/music_subscriptions.yaml

.. code-block:: text
  :caption: 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'