pitchfork-cli 1.5.0

Daemons with DX
Documentation

What is it?

Pitchfork is a CLI for managing daemons with a focus on developer experience.

  • Start services once - Only start daemons if they have not already been started
  • Auto start/stop - Automatically start daemons when entering a project directory, stop when leaving
  • Ready checks - Based on delay, output or HTTP response
  • Restart on failure - Automatically restart daemons when they crash
  • Cron jobs - Schedule recurring tasks
  • Start on boot - Automatically start daemons when your system boots
  • Project configuration - Define all your project's daemons in pitchfork.toml

[!WARNING] This project is experimental. It works in basic situations but you'll undoubtedly encounter bugs.

Use Cases

  • Launching development services like web APIs and databases
  • Running rsync/unison to synchronize directories with a remote machine
  • Managing background processes for your project

Quickstart

Install pitchfork

mise-en-place is the recommended way to install pitchfork:

$ mise use -g pitchfork

Or install via cargo:

$ cargo install pitchfork-cli

Or download from GitHub releases.

Launch a one-off daemon

Run a process in the background—an alternative to shell jobs (mytask &):

$ pitchfork run docs -- npm start docs-dev-server

Add daemons to your project

Create a pitchfork.toml in your project root:

[daemons.redis]
run = "redis-server"

[daemons.api]
run = "npm run server:api"

[daemons.docs]
run = "npm run server:docs"

Start all daemons or multiple daemons in parallel:

$ pitchfork start --all

$ pitchfork start redis api

Shell hook (auto start/stop)

Enable automatic daemon management when entering/leaving project directories:

echo '$(pitchfork activate bash)' >> ~/.bashrc
echo '$(pitchfork activate zsh)' >> ~/.zshrc
echo 'pitchfork activate fish | source' >> ~/.config/fish/config.fish

Configure daemons with auto start/stop:

[daemons.api]
run = "npm run server:api"
auto = ["start", "stop"]

View logs

View daemon logs:

$ pitchfork logs api
[2021-08-01T12:00:00Z] api: starting
[2021-08-01T12:00:01Z] api: listening on

Logs will be saved to ~/.local/state/pitchfork/logs.

Example Project

Here's a complete example showing how to use pitchfork for a development environment:

# pitchfork.toml
[daemons.postgres]
run = "docker run --rm -p 5432:5432 -e POSTGRES_PASSWORD=dev postgres:16"
auto = ["start", "stop"]
ready_delay = 5

[daemons.redis]
run = "redis-server --port 6379"
auto = ["start", "stop"]
ready_delay = 2

[daemons.api]
run = "npm run dev:api"
auto = ["start", "stop"]
ready_output = "listening on"
depends = ["postgres", "redis"]

[daemons.worker]
run = "npm run dev:worker"
auto = ["start"]
depends = ["postgres", "redis"]

[daemons.sync]
run = "rsync -avz --delete remote:/data/ ./local-data/"
cron = "0 */5 * * * *"  # Run every 5 minutes

Start everything:

$ pitchfork start --all

Full Documentation

See pitchfork.jdx.dev

Contributors

Contributors