========
Commands
========

If using `uv <https://docs.astral.sh/uv/>`_, add ``uvx`` to the start of the following
commands.

The ``runchain`` command supports the following operations:


``runchain list``
=================

List all chains or scripts within a specific chain::

    runchain list [<chain>]

Without a chain argument, lists all available chains.
With a chain argument, lists all scripts in that chain in alphabetical order.

Examples
--------

List all chains::

    runchain list

List scripts in the backup chain::

    runchain list backup


``runchain add``
================

Add a script to a chain::

    runchain add <chain> <script> [<target>]

where:

* ``<chain>`` - the name of the chain (creates directory if it doesn't exist)
* ``<script>`` - path to the script file to add  
* ``<target>`` - optional naming specification:
  
  * Number (e.g., ``20``) - script will be named ``20-<basename>``
  * Full name starting with ``NN-`` (e.g., ``20-backup``) - uses exact name
  * If omitted - script basename must already follow ``NN-*`` format

Chain names must contain only lowercase letters (a-z).

Examples
--------

Add script with number target::

    runchain add backup ~/scripts/database.sh 10
    # Creates: 10-database.sh

Add script with full name target::

    runchain add backup ~/scripts/files.py 20-backup-files
    # Creates: 20-backup-files

Add script that already has correct format::

    runchain add backup ./30-cleanup.sh
    # Creates: 30-cleanup.sh


``runchain remove``
===================

Remove a script from a chain, or remove an entire chain::

    runchain remove <chain> [<script>] [<target>] [--force]

where:

* ``<chain>`` - name of the chain
* ``<script>`` - optional script filename in the chain
* ``<target>`` - optional full filename to remove
* ``--force`` - skip confirmation prompts when removing entire chains

If only ``<chain>`` is provided, removes the entire chain.
If ``<script>`` is provided, removes that specific script.

Examples
--------

Remove a specific script::

    runchain remove backup 10-database.sh

Remove entire chain with confirmation::

    runchain remove backup

Remove entire chain without confirmation::

    runchain remove backup --force


``runchain cron``
=================

Register a chain to run on a cron schedule using crondir::

    runchain cron <chain> "<schedule>"

where:

* ``<chain>`` - name of the chain to schedule
* ``<schedule>`` - cron schedule string (e.g., ``"0 2 * * *"`` for daily at 2am)

This integrates with crondir to manage the cron entries.

Examples
--------

Schedule backup chain to run daily at 2am::

    runchain cron backup "0 2 * * *"

Schedule maintenance chain to run weekly on Sundays at 3am::

    runchain cron maintenance "0 3 * * 0"


``runchain run``
================

Execute all scripts in a chain in alphabetical order::

    runchain run <chain>

Scripts are executed in alphabetical order by filename.
Execution stops on the first script failure (non-zero exit code).

Examples
--------

Run the backup chain manually::

    runchain run backup

Run a maintenance chain::

    runchain run maintenance