Commands

If using 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