# shep

> A process manager written in Rust. One binary runs a daemon called the
> shepherd, which keeps a flock of long-running processes alive, captures
> what they print, and says plainly when something is wrong.

## Get it running

- [Quickstart](https://shep-pm.com/docs/getting-started): Install shep, write a two-field Flockfile, and start your first flock.
- [Coming from pm2](https://shep-pm.com/docs/from-pm2): shep import pm2 reads a real dump.pm2 and writes a Flockfile. It starts nothing, and names on stderr everything that could not survive the trip unchanged.
- [pm2 verb reference](https://shep-pm.com/docs/pm2-verbs): Every pm2 verb and the shep one to type instead, with a note wherever the behaviour differs rather than the spelling.
- [Surviving a reboot](https://shep-pm.com/docs/startup): shep startup installs the init unit that brings the shepherd, and the flock it last saved, back after a reboot.
- [Examples](https://shep-pm.com/docs/examples): Seven small Rust programs and a Flockfile that need only cargo and a Unix host, plus a second, polyglot layer over the top for Node, Bun, Python and Go, to watch shep's supervision behaviours happen instead of reading about them.
- [The words](https://shep-pm.com/docs/terminology): The full shep lexicon: what each themed word means, where you meet it, and whether it's built yet.

## Day to day

- [Reading logs](https://shep-pm.com/docs/logs): Where a sheep's output lands, how to read it, and the two verbs that act on the files themselves: reopen for an external rotator, flush to empty them.
- [Changing a setting](https://shep-pm.com/docs/overrides): A Flockfile is a template your app's repository owns. What you tune on a running flock lives somewhere shep owns, and a load appends rather than overwrites.
- [Stopping and replacing](https://shep-pm.com/docs/lifecycle): What shep stop, restart, reload and delete each do to a running sheep and to the muster roll: one kill ladder shared by three of them, two different orders a reload can run, and the one difference between stop and delete that decides what comes back after a restart.
- [Talking to a sheep](https://shep-pm.com/docs/talking-to-a-sheep): Reaching an app that is already running: a unix signal, a line on its stdin, or a named action over the shepherd channel. None of the three restarts it, though a signal it does not handle can still kill it.
- [Upgrading](https://shep-pm.com/docs/upgrading): cargo install replaces the binary on disk and changes nothing that is running. shep daemon reload is what moves a live flock onto it.
- [The lookout](https://shep-pm.com/docs/lookout): A terminal dashboard over the shepherd: the flock table, a host-usage strip, and a selected sheep's detail pane and bleats feed.
- [Editing config in lookout](https://shep-pm.com/docs/lookout-config): The four panes lookout edits through: the shepherd's settings, secrets, a sheep's Flockfile fields, and a dog's own schema.
- [Terminal output](https://shep-pm.com/docs/output): shep draws boxes, colour and sheep at a terminal, and plain columns everywhere else. One dial changes how much, and a pipe always gets the plain version.

## Configuration

- [Folds](https://shep-pm.com/docs/folds): A fold is a namespace: fold = in a Flockfile puts a sheep in one, and fold:<name> reaches it from any verb.
- [Boot order](https://shep-pm.com/docs/boot-order): depends_on names what a sheep waits for. shep sorts the flock into stages and starts them in order.
- [Secrets](https://shep-pm.com/docs/secrets): A value per key per environment, read by a {{secret:NAME}} reference instead of written into the Flockfile itself.
- [The KV store](https://shep-pm.com/docs/kv): Three verbs, a file-locked JSON store, and no shepherd required: for the small stuff that has nowhere else to live.

## Dogs

- [Dogs](https://shep-pm.com/docs/dogs): The shepherd's own plugins: built-in metrics and alerting, and how to adopt a binary of your own.
- [Writing a dog](https://shep-pm.com/docs/writing-a-dog): A dog is an ordinary binary that answers --version and --schema on stdout and speaks the dog protocol on a socket the shepherd hands it.
- [Community dogs](https://shep-pm.com/docs/community-dogs): Dogs other people wrote and adopted with shep adopt, listed for anyone who doesn't want to write their own.

## Machine surfaces

- [Whistle (MCP)](https://shep-pm.com/docs/whistle): An MCP server over stdio that hands an AI agent the same flock a person reaches with shep flock.
- [JSON output](https://shep-pm.com/docs/json-output): Every shep command answers under --format json too, in a small versioned envelope built for piping rather than scraping.
- [The shepherd channel](https://shep-pm.com/docs/shepherd-channel): A plain file descriptor carrying newline JSON: readiness, custom metrics, and answering shep trigger.

## Other places it runs

- [Containers](https://shep-pm.com/docs/containers): shep runtime is the PID-1 entrypoint for a container. shep dev is the same idea for a laptop: an isolated session that tidies up after itself.
- [Serve](https://shep-pm.com/docs/serve): A static file server, hand-rolled and run as a managed sheep. Loopback by default, and every unsafe default is opt-in.

## Reference

- [CLI reference](https://shep-pm.com/docs/cli): Every verb, its aliases, its flags, and its exit codes: generated from the same clap tree the binary parses with.
- [Flockfile reference](https://shep-pm.com/docs/first-flockfile): Every field a Flockfile understands, the ten filenames config discovery searches, and the strict grammars that catch typos before they reach a running sheep.
- [What's not built](https://shep-pm.com/docs/not-built): What the Windows tier does not do, plus a short list of deliberate cuts and open design questions: sourced from docs/specs/deferred.md.