Quickstart

Installing shep and getting a flock running takes about two minutes.

Already running pm2? Start at Coming from pm2 instead.

./server is your own binary or start script, and shep writes neither: point script at something that already exists or the start fails to spawn. Nothing to hand yet? shep serve ./site puts a real sheep in the flock out of the install you just did, no Flockfile needed. See Serve.

careful

shep is pre-1.0, so anything here can still change. macOS, Linux and Windows all work; the Windows tier is newer, and two limits are worth knowing before you rely on it: shep stop has no graceful signal to send unless your app reads the shepherd channel, and shep startup is not built there. Your flock lives in %USERPROFILE%\.shep on Windows, since it sets no HOME.

Other ways to install

Homebrew:

$ brew install shep-pm/shep/shep

Scoop:

> scoop bucket add shep https://github.com/shep-pm/scoop-shep

> scoop install shep

If shep.exe will not start, it wants the Visual C++ redistributable: scoop bucket add extras, thenscoop install extras/vcredist2022.

Prebuilt binaries:

Each link redirects to the newest release. Checksums are in SHA256SUMS.

Or build it yourself:

$ git clone https://github.com/shep-pm/shep.git

$ cd shep

$ cargo build --release

$ ./target/release/shep --help

Rust 1.88 or newer, edition 2024.

Shell completions and the first-run greeting

shep completions <shell> prints a completion script for your shell. It completes verbs and flags only, never sheep or fold names. shep welcome reprints the one-time greeting a fresh $SHEP_HOME shows on its own.

Scripts that need an interpreter

script is run directly, so a compiled binary or a file with a shebang and the executable bit needs nothing further. A plain server.js has neither, and shep will not guess: guessing is how a process manager ends up with opinions you did not ask for.

Instead you tell it once. On first run shep writes a starter mapping into ~/.shep/shep.toml, commented so you can see exactly what it will do:

~/.shep/shep.toml

[interpreters]
js = "node"
py = "python3"
sh = "sh"

From then on shep start server.js works. The table is yours to edit: add an extension, or delete it to turn interpreters off. An individual app can override it with its own interpreter field, and a single run can override both with --interpreter; the last one named wins.

Reading the flock table

$ shep ls

ID NAME STATUS PID RESTARTS EXIT CFG CPU MEM UPTIME FOLD SMIT

1 web online 1001 1 - - 12.5% 48.1M 1m backend -

2 cron online 1003 3 - - - 48.1M 30s backend -

The CPU column prints - rather than 0.0% when a reading is unavailable, because a confident zero is worse than an obvious blank. EXIT uses the same convention, and shows why a stopped sheep stopped. CFG reads - until a sheep has config waiting on it; see Overrides.

shep bleats

same as shep logs

shep flock

same as shep list / ls

shep muster

same as resurrect

shep thatlldo

same as graceful stop

Piping it somewhere

Every command renders as --format json too, under a versioned envelope, so nothing has to scrape columns.

"schema_version": 1, "command": "flock", "data": [ { "id": 1, "name": "web", "status": "online", "pid": 1001, "restarts": 1, "uptime_ms": 60000, "fold": "backend", "cpu_percent": 12.5, "memory_bytes": 50462720, "dog": null } ] }