shell-compose 0.2.0

Lightweight background process runner for long-running or scheduled jobs
Documentation

Shell Compose

Shell Compose is a lightweight background process runner for long-running or scheduled jobs.

Shell Compose

Features

  • Scheduling
    • Run background jobs from the command line
    • Run multiple jobs in parallel
    • Schedule commands to run like a cron job
    • Start just recipes
    • Configure commands and cron jobs in a YAML file
    • Support task dependencies (via Justfile)
    • Attach console to running job
    • Restarting failed jobs
    • Trigger execution by file change
    • Trigger execution by calling HTTP endpoint
  • Observability
    • Show process status
    • Show process resource usage
    • Show logs of all running jobs
    • Show logs of selected jobs
    • Metrics endpoint
  • Cross Platform
    • Linux
    • MacOS
    • Windows

Integration with just

just is a command runner with syntax inspired by make. It supports shell commands but also other languages like Python or NodeJS. Task can have dependencies and variables loaded from .env files.

Example:

# Simulate data processing
[group('autostart')]
processing:
  #!/usr/bin/env bash
  echo Start processing
  for i in {1..20}; do
    echo processing step $i
    sleep 1
  done
  echo Processing finished

# Play sounds from MQTT queue
[group('autostart')]
play:
  #!/usr/bin/env bash
  set -euo pipefail
  mosquitto_sub -t room/speaker | while read sound; do
    aplay sounds/$sound
  done

Running a just recipe:

shell-compose start processing

Running all recipes in a group:

shell-compose up autostart

Installation

Pre-built binaries

We provide several options to access pre-built binaries for a variety of platforms. If you would like to manually download a pre-built binary, checkout the latest release on GitHub.

Installer scripts

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/pka/shell-compose/releases/latest/download/shell-compose-installer.sh | sh

Windows PowerShell:

powershell -c "irm https://github.com/pka/shell-compose/releases/latest/download/shell-compose-installer.ps1 | iex"

Other Options

cargo-binstall

cargo binstall shell-compose

Build From Source

For users who need to install shell-compose on platforms that we do not yet provide pre-built binaries for, you will need to build from source. shell-compose is written in Rust and uses cargo to build. Once you've installed the Rust toolchain (rustup), run:

cargo install shell-compose --locked