Automating
==========

Automate downloading your subscriptions by running the :ref:`'sub' sub-command
<usage:subscriptions options>` periodically. There are various tools that can run
commands on a schedule you may use any of them that work with your installation
method. Most users use `cron`_ in `Docker containers <docker and unraid_>`_.


Docker and Unraid
-----------------

:doc:`The 'ytdl-sub' Docker container images <../install/docker>` provide optional cron
support. Enable cron support by setting `a cron schedule`_ in the ``CRON_SCHEDULE``
environment variable:

.. code-block:: yaml
  :caption: ./compose.yaml
  :emphasize-lines: 4

  services:
    ytdl-sub:
      environment:
        CRON_SCHEDULE: "0 */6 * * *"

Then recreate the container to apply the change and start it to generate the default
``/config/ytdl-sub-configs/cron`` script. Read the comments in that script and edit as
appropriate.

The container cron wrapper script will write output from the cron job to
``/config/ytdl-sub-configs/.cron.log``. The default image ``ENTRYPOINT`` will ``$ tail
...`` that file so you can monitor the cron job in the container's output and thus also
in the Docker logs.

You may also set the ``CRON_RUN_ON_START`` environment variable to ``true`` to have the
image run your cron script whenever the container starts in addition to the cron
schedule.

.. warning::

   Using ``CRON_RUN_ON_START`` is not recommended because it may cause your cron script
   to run too often and may trigger throttles and bans. When enabled, your cron script
   will run *whenever* the container starts including when the host reboots, when ``#
   dockerd`` is upgraded, when a new image is pulled, when something applies Compose
   changes, etc.. This may result in running ``ytdl-sub`` right before or after the next
   cron scheduled run or even at the same time on top of each other. Instead, run your
   cron script manually inside the running container as needed:

   .. code-block:: console

      docker compose exec ytdl-sub bash /config/ytdl-sub-configs/cron


.. _linux-setup:

Linux, Mac OS X, BSD, or other UNIX's
-------------------------------------

For installations on systems already running ``# crond``, you can also use cron to run
``ytdl-sub`` periodically. Write a script to run ``ytdl-sub`` in the cron job. Be sure
the script changes to the same directory as your configuration and uses the full path to
``ytdl-sub``:

.. code-block:: shell
   :caption: ~/.local/bin/ytdl-sub-cron
   :emphasize-lines: 2,3

   #!/bin/bash
   cd "~/.config/ytdl-sub/"
   ~/.local/bin/ytdl-sub --dry-run sub -o '--ytdl_options.max_downloads 3' |&
       tee -a "~/.local/state/ytdl-sub/.cron.log"

Then tell ``# crond`` when to run the script:

.. code-block:: console

   echo "0 */6 * * * ${HOME}/.local/bin/ytdl-sub-cron" | crontab "-"

Remove the ``--dry-run`` and ``-o ...`` CLI options from your cron script when you've
tested your configuration and you're ready to download entries unattended.


.. _windows-setup:

Windows
-------

For most Windows users, the best way to run commands periodically is `the Task
Scheduler`_:

.. attention::

   These instructions are untested. Use at your own risk. If you use them, whether they
   work or not, please let us know how it went in `a support post in Discord`_ or `a new
   GitHub issue`_.

#. Open the Task Scheduler app.

#. Click ``Create Basic Task`` at the top of the right sidebar.

#. Set all the fields as appropriate until you get to the ``Action``...

#. For the ``Action``, select ``Start a program``...

#. Click ``Browse...`` to the installed ``ytdl-sub.exe`` executable...

#. Add CLI arguments to ``Add arguments (optional):``, for example ``--dry-run sub -o
   '--ytdl_options.max_downloads 3'``...

#. Set ``Start in (optional):`` to the directory containing your configuration.

#. Finish the rest of the ``Create Basic Task`` wizard.


Next Steps
----------

At this point, ``ytdl-sub`` should run periodically and keep your subscriptions current
in your media library without your intervention. As your :doc:`subscriptions file
<./subscriptions>` grows or you discover new use cases, it becomes worth while to
simplify things by :doc:`defining your own custom presets <./first_config>`.



.. _`cron`:
   https://en.wikipedia.org/wiki/Cron
.. _`a cron schedule`:
   https://crontab.cronhub.io/

.. _`the Task Scheduler`:
   https://learn.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page
.. _`a support post in Discord`:
   https://discord.com/channels/994270357957648404/1084886228266127460
.. _`a new GitHub issue`:
   https://github.com/jmbannon/ytdl-sub/issues/new