==========
Quickstart
==========

Installation
------------

Install using ``pip``::

    pip install runchain

or run directly using `uv <https://docs.astral.sh/uv/>`_ (recommended)::

    uvx runchain <command> [<options>]


Basic usage
-----------

Create a backup chain by adding scripts::

  runchain add backup ~/scripts/database-backup.sh 10
  runchain add backup /usr/local/bin/file-backup.py 20-files
  runchain add backup ./30-cleanup.sh

List your chains::

  runchain list

List scripts in a specific chain::

  runchain list backup

Run a chain manually::

  runchain run backup

Schedule a chain with crondir::

  runchain cron backup "0 2 * * *"

Remove a script from a chain::

  runchain remove backup 20-files

Remove an entire chain::

  runchain remove backup


Scripts and naming
------------------

Scripts in chains use init-style numbering (e.g., ``10-backup.sh``, ``20-cleanup.py``)
and are executed in alphabetical order. You can:

- specify the number to control the order: ``runchain add mychain script.sh 25`` → ``25-script.sh``
- add with a number and custom name: ``runchain add mychain script.sh 25-backup`` → ``25-backup``
- add scripts that already have numbers: ``runchain add mychain 30-deploy.sh``

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

For full command line options, see :doc:`commands`.