CLI reference

Start a sheep from a script, a Flockfile, or stdin

Usage: shep start [OPTIONS] [TARGETS]...

Arguments:
  [TARGETS]...
          Selectors, script paths, Flockfiles, or `-` to read Flockfile JSON from stdin
          
          A target is resolved in four tiers and the first one that matches wins: a sheep the flock
          already has, by id or by name; then a fold, written either as `fold:<name>` or as the bare
          fold name; then a Flockfile, by its extension; then a path on disk, started as a script.
          
          So `shep start backed` starts the fold `backed` even when a file called `backed` is
          sitting in the current directory. Write `./backed` to mean the file: a sheep name may
          never contain a path separator, so a target carrying one is always a path.
          
          The wildcard selectors work here too, and mean what they mean everywhere else: `all`,
          `/regex/`, and glob patterns such as `web-*`. They reach only sheep the flock already has,
          since there is nothing to register. A sheep already running is reported and left alone;
          `restart` is the verb that replaces one.
          
          Omit the targets to start the Flockfile in the current directory, or, when there is none,
          to bring a shepherd up with nothing running yet.
          
          Several are started in turn, not atomically: if the second fails the first is already up,
          and the exit code is the first failure. `--name` is refused with more than one, since a
          name is unique to one sheep.

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --name <NAME>
          Name for this sheep (script form only)

      --fold <FOLD>
          Fold to place this sheep in

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --cwd <CWD>
          Working directory to run in (default: where you ran `shep start`)

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

      --interpreter <INTERPRETER>
          Interpreter to run the script with, overriding both shep.toml's extension mapping and a
          Flockfile app's own interpreter field.
          
          The precedence, lowest to highest: shep.toml's interpreters table (matched against the
          script's extension), then a Flockfile's own interpreter for that app, then this flag. shep
          never guesses an interpreter on its own; every one of those three is something an operator
          wrote down. Pass "none" to run the script directly, overriding a mapping or a Flockfile
          that would otherwise pick one.

      --flockfile
          Read TARGET as a Flockfile rather than as a script path.
          
          Required for a `.js` Flockfile and the only way to reach one: shep reads a `.js` config by
          running it through node, which is arbitrary code execution, so it never happens because a
          file merely has that extension. Without this flag `shep start server.js` starts
          `server.js` as a script, which is what it has always meant.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Serve a directory over plain HTTP, as a managed sheep.

Registers a sheep whose command line is this invocation, canonicalized and with `--foreground`
appended — the same worker that answers every request also IS the registered sheep, so `shep
describe` shows exactly what will run again on a restart.

Binds loopback (`127.0.0.1:8080`) by default. A wider `--bind` is allowed, not refused, and gets a
stderr notice naming what it exposes — the docroot is published to anything that can reach the port,
and unencrypted unless the operator puts a proxy in front. `--auth` narrows that to anyone who also
has the password, still sent as plain HTTP basic auth.

Dotfiles, directory listings, and any symlink under the docroot are all refused by default —
`--hidden`, `--listing`, and `--follow-symlinks` opt back in, each with its own reason a repo
checkout or a deploy layout might need it.

`--foreground` runs the worker directly in this terminal instead of registering a sheep — also how
the registered sheep runs; the flag on the end of its own command line is the only difference.

Usage: shep serve [OPTIONS] <ROOT>

Arguments:
  <ROOT>
          Directory to serve

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --port <PORT>
          Port to listen on
          
          [default: 8080]

      --bind <BIND>
          Address to bind. Loopback unless you say otherwise — a wider bind publishes every file
          under the directory to anything that can reach the port
          
          [default: 127.0.0.1]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --name <NAME>
          Name for this sheep (default: the directory's own name)

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --fold <FOLD>
          Fold to place this sheep in

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

      --spa
          Serve index.html for paths that do not exist, for a single-page app. Only for requests
          that accept HTML, so a missing script still 404s

      --listing
          List a directory that has no index.html. Off by default: a listing publishes every
          filename under it

      --hidden
          Serve files and directories whose names begin with a dot. Off by default: serving a
          project directory would otherwise publish `.env` and the whole `.git` history. The one
          real use is `.well-known/acme-challenge`

      --follow-symlinks
          Follow symlinks under the docroot, reopening the check-then-open race refused by default.
          Needed for deploy layouts like `current -> releases/2026-08-15`; off unless you ask for it

      --auth <AUTH>
          File holding one `user:password` line, mode 0600, required on every request. Sent over
          plain HTTP — base64, not encryption

      --foreground
          Serve in this terminal instead of registering a sheep.
          
          This is also how the registered sheep runs: the command line in `shep describe` is this
          one with the flag on the end.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Stop one or more sheep

Usage: shep stop [OPTIONS] <SELECTORS>...

Arguments:
  <SELECTORS>...
          One or more: name, id, `name:slot`, `all`, `zeus-*`, `/regex/`, `fold:<name>`
          
          Several are applied in turn, not atomically: `shep stop a b c` where `b` matches nothing
          still stops `a` and `c`, and the exit code is the first failure.
          
          A pattern carrying `*`, `?`, `[` or `{` is a glob, anchored, so `zeus-*` selects
          `zeus-auth` and not `my-zeus-auth`. Quote it: your shell expands `zeus-*` against
          filenames first, and zsh refuses outright when none match. A name with no such character
          is exact, so `web.1` is the sheep called `web.1`.

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Restart one or more sheep

Usage: shep restart [OPTIONS] <SELECTORS>...

Arguments:
  <SELECTORS>...
          One or more: name, id, `name:slot`, `all`, `zeus-*`, `/regex/`, `fold:<name>`
          
          Several are applied in turn, not atomically: `shep stop a b c` where `b` matches nothing
          still stops `a` and `c`, and the exit code is the first failure.
          
          A pattern carrying `*`, `?`, `[` or `{` is a glob, anchored, so `zeus-*` selects
          `zeus-auth` and not `my-zeus-auth`. Quote it: your shell expands `zeus-*` against
          filenames first, and zsh refuses outright when none match. A name with no such character
          is exact, so `web.1` is the sheep called `web.1`.

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Reload one or more sheep, one instance at a time.

Each instance is replaced by a fresh one that has to become ready before the reload moves on, so a
release that never comes up is reported as a failure rather than as a success.

What that failure COSTS depends on the order, and the order depends on the app.

An app with a readiness_probe and no reuse_port is replaced serially: the old instance drains first,
then the new one starts in its place. A probe asks an address, and an address cannot say which
process answered it. Run both at once and the outgoing instance answers for the incoming one, so
shep would call a release ready that never bound anything.

The old instance is gone by the time the new one is judged, so there is nothing to go back to. A
replacement that never becomes ready is left running and NOT marked online, and the reload is
abandoned, which for a one-instance app means the gap lasts until you act on it. A rollback that
points the app back at working code and reloads again is what ends it; that reload can reach the
instance this one left behind.

Everything else overlaps, old and new running together: an app with no probe, an app using
wait_ready (its channel belongs to one instance, so nothing else can answer it), and a probed app
that sets reuse_port.

An overlap asks the same thing of all three. Both instances are bound at once, so an app that binds
an address has to share the socket itself, with SO_REUSEPORT set before it binds; shep binds nothing
and cannot set it on the app's behalf. Without that the replacement takes EADDRINUSE on every
reload, and the reload is abandoned with the old instance left serving. This command has already
exited 0 by then, so process.reload_abandoned on the bus is the only report of it.

reuse_port neither creates that requirement nor satisfies it. It is how a probed app says it is
already handling the sharing, and so asks for the overlap back.

An overlap is not zero downtime either. The old listener's queue of connections it has not accepted
yet is dropped when it closes, so an app that does not stop accepting and finish what it has in hand
before graceful_timeout runs out loses whatever was waiting there.

Exits as soon as the shepherd accepts the reload, printing the flock as it stood at that moment — a
clustered app takes longer to swap than any answer can wait for. The swaps themselves are reported
on the bus, under process.reload, process.reloaded and process.reload_abandoned.

Usage: shep reload [OPTIONS] <SELECTORS>...

Arguments:
  <SELECTORS>...
          One or more: name, id, `name:slot`, `all`, `zeus-*`, `/regex/`, `fold:<name>`
          
          Several are applied in turn, not atomically: `shep stop a b c` where `b` matches nothing
          still stops `a` and `c`, and the exit code is the first failure.
          
          A pattern carrying `*`, `?`, `[` or `{` is a glob, anchored, so `zeus-*` selects
          `zeus-auth` and not `my-zeus-auth`. Quote it: your shell expands `zeus-*` against
          filenames first, and zsh refuses outright when none match. A name with no such character
          is exact, so `web.1` is the sheep called `web.1`.

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Delete one or more sheep from the flock

Usage: shep delete [OPTIONS] <SELECTORS>...

Arguments:
  <SELECTORS>...
          One or more: name, id, `name:slot`, `all`, `zeus-*`, `/regex/`, `fold:<name>`
          
          Several are applied in turn, not atomically: `shep stop a b c` where `b` matches nothing
          still stops `a` and `c`, and the exit code is the first failure.
          
          A pattern carrying `*`, `?`, `[` or `{` is a glob, anchored, so `zeus-*` selects
          `zeus-auth` and not `my-zeus-auth`. Quote it: your shell expands `zeus-*` against
          filenames first, and zsh refuses outright when none match. A name with no such character
          is exact, so `web.1` is the sheep called `web.1`.

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Set how many instances one app runs — the stocking rate.

An absolute count, not a change: `shep stock web 4` means web has four instances afterwards,
whatever it had before. There is no +N/-N form — run it twice and get the same flock.

Stocking up fills the lowest free instance slots; stocking down releases the highest, so stocking
out and back returns the same slot numbers, the same SHEP_INSTANCE values and the same log files it
started with.

Exits as soon as the shepherd accepts, printing the instances that remain. On a stock-down the
departing instances are still running their stop ladders at that point; they report themselves on
the bus, under process.delete.

The new count is written to the muster roll, so `shep save` and a reboot keep it.

Usage: shep stock [OPTIONS] <NAME> <COUNT>

Arguments:
  <NAME>
          The app's name

  <COUNT>
          How many instances it runs afterwards

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

List the flock

Usage: shep flock [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Describe one sheep in detail.

Includes the sheep's lambs: the processes the OS reports as descendants of its pid. That is not the
same set the stop ladder kills, which acts on the process group — a double-forked descendant leaves
this list and is still killed, and a setsid() one stays in it and survives.

Lamb names are executable names, never command lines.

Usage: shep describe [OPTIONS] <SELECTORS>...

Arguments:
  <SELECTORS>...
          One or more: name, id, `name:slot`, `all`, `zeus-*`, `/regex/`, `fold:<name>`
          
          Several are applied in turn, not atomically: `shep stop a b c` where `b` matches nothing
          still stops `a` and `c`, and the exit code is the first failure.
          
          A pattern carrying `*`, `?`, `[` or `{` is a glob, anchored, so `zeus-*` selects
          `zeus-auth` and not `my-zeus-auth`. Quote it: your shell expands `zeus-*` against
          filenames first, and zsh refuses outright when none match. A name with no such character
          is exact, so `web.1` is the sheep called `web.1`.

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

List one fold

Usage: shep fold [OPTIONS] <NAME>

Arguments:
  <NAME>
          The fold to list

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

List the dogs, and nothing else. `--available` lists the community index of dogs you could adopt
instead of the ones this shepherd is running

Usage: shep dogs [OPTIONS] [FILTER]

Arguments:
  [FILTER]
          Narrow the listing to entries whose name, package or description contains this text,
          case-insensitively

Options:
      --available
          List the dogs published in the community index instead of the ones this shepherd is
          running. Needs no shepherd

      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Turn on a registered dog: writes `[daemon] enabled_dogs` in `shep.toml`, and starts it now if a
shepherd is running.

Writes the config either way and exits 0 even with no shepherd running — the dog comes up with the
next one. `shep muster` is the only verb that autostarts a shepherd; this is not it.

Usage: shep enable [OPTIONS] <NAME>

Arguments:
  <NAME>
          The dog's name — the `[dog.<name>]` config key

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Turn off a registered dog: removes it from `[daemon] enabled_dogs`, and stops it now if a shepherd
is running.

Leaves `[dog.<name>]` in place — the dog's own configuration survives a disable/enable cycle. `shep
rehome` is the verb that forgets a dog entirely.

Usage: shep disable [OPTIONS] <NAME>

Arguments:
  <NAME>
          The dog's name — the `[dog.<name>]` config key

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Vet a binary shep has never seen and register it as a dog: writes `[daemon] adopted_dogs` and
`[daemon] enabled_dogs` in `shep.toml`, and starts it now if a shepherd is running.

The path can be given as-is, with a leading `~/`, or as a bare name already on `$PATH` (`cargo
install` puts one there). Refuses, before touching the config at all, a path that resolves to
nothing that exists, is not a file, has no execute bit set, or that this kernel will not exec — and
refuses a name that already names a built-in verb or alias, since such a dog could never be reached.
An adopted dog runs at the shepherd's own trust level, with no sandboxing beyond it. Once adopted,
`shep <name> [args...]` runs it directly, passing `args` through untouched — a second invocation
mode from the one the shepherd itself uses to supervise it.

Usage: shep adopt [OPTIONS] <PATH>

Arguments:
  <PATH>
          Path to the dog's binary, vetted before `shep.toml` is touched. Resolved before vetting:
          as given, with a leading `~/` expanded, or looked up on `$PATH` if it names no directory —
          first hit wins

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --name <NAME>
          The dog's name — the `[dog.<name>]` config key. Defaults to the binary's file stem with a
          leading `shep-` stripped

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Forget an adopted dog entirely: stops it if a shepherd is running, and removes it from `[daemon]
enabled_dogs`, `[daemon] adopted_dogs`, and its own `[dog.<name>]` table.

`shep disable` stops a dog without forgetting its configuration; `rehome` is the verb that forgets
it.

Usage: shep rehome [OPTIONS] <NAME>

Arguments:
  <NAME>
          The dog's name — the `[dog.<name>]` config key

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Send a named action to matched sheep and report what each app answers.

Reaches an app over its shepherd channel — the fd-3 pipe the daemon opens when the app's Flockfile
sets `channel = true`. `wait_ready` and `shutdown_with_message` both imply the same channel, so
either one of the three is enough; a sheep with none of them answers a `no_channel` row instead of a
reply, naming the same fields.

`action` and any `params` are free-form and unvalidated here — sent to the app verbatim, on its own
shepherd-channel wire, for the app itself to recognize or refuse.

Usage: shep trigger [OPTIONS] <SELECTOR> <ACTION> [PARAMS]

Arguments:
  <SELECTOR>
          name, id, `name:slot`, `all`, `/regex/`, or `fold:<name>`

  <ACTION>
          Action name — free-form, defined by the app

  [PARAMS]
          Argument text for the action, passed through to the app verbatim

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Send a unix signal to matched sheep.

Delivered to each sheep's own process, not to its process group — the lambs it forked are not
signalled. This is a nudge to the application (SIGHUP to re-read config, SIGUSR1 to dump state);
`shep stop` is what runs the stop ladder, and `shep reload` is what swaps instances.

Accepted: SIGHUP, SIGINT, SIGQUIT, SIGTERM, SIGUSR1, SIGUSR2, SIGWINCH, SIGCONT, SIGKILL. The SIG
prefix and the case are both optional. SIGSTOP is refused: a stopped sheep still reads online in
every listing shep can produce.

Delivery is not action. A signal the app blocks or ignores is reported delivered, because the kernel
took it and there is nothing further shep can see.

Usage: shep signal [OPTIONS] <SELECTOR> <SIGNAL>

Arguments:
  <SELECTOR>
          name, id, `name:slot`, `all`, `/regex/`, or `fold:<name>`

  <SIGNAL>
          Signal name, e.g. `SIGHUP` or `hup`

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Write one line to matched sheep's stdin.

Only reaches an app whose Flockfile sets `stdin = true`. Nothing else implies it — unlike the
shepherd channel, which `wait_ready` and `shutdown_with_message` both turn on — because nothing in
shep needs a sheep's stdin except this verb. A sheep without it answers a `no_stdin` row naming the
field.

One line, and the terminator is shep's to add: a line containing a newline or a carriage return is a
usage error rather than two commands.

`sent` means the bytes were written and flushed to the pipe, not that the app read them. A pipe
holds 64 KiB before it blocks, so a short line to an app that never reads its stdin is still `sent`.

Usage: shep whisper [OPTIONS] <SELECTOR> <LINE>

Arguments:
  <SELECTOR>
          name, id, `name:slot`, `all`, `/regex/`, or `fold:<name>`

  <LINE>
          The line, without a trailing newline — shep adds exactly one

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Show or follow bleats (log output) for one or more sheep

Usage: shep bleats [OPTIONS] [SELECTOR]

Arguments:
  [SELECTOR]
          Which sheep (default: all)
          
          [default: all]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --no-follow
          Print the tail of each sheep's log file and exit, instead of following

      --lines <N>
          How many existing lines of each stream to print before following
          
          A sheep that already crashed has said everything it is going to say, so following alone
          shows an empty screen while the reason sits in the file. This prints that much history
          first, then follows.
          
          Counted per stream, so the default prints up to this many lines of stdout and up to this
          many of stderr for each matched sheep. Narrow it with `--out` or `--err`.
          
          `0` prints no history at all, following only what arrives next.
          
          [default: 15]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --err
          Only stderr

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

      --out
          Only stdout

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Reopen log files after an external rotator has renamed them

Usage: shep reopen [OPTIONS] [SELECTOR]

Arguments:
  [SELECTOR]
          Which sheep (default: all)
          
          [default: all]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Empty the log files of one or more sheep, or the shepherd's own

Usage: shep flush [OPTIONS] [SELECTOR]

Arguments:
  [SELECTOR]
          name, id, `name:slot`, `all`, `/regex/`, `fold:<name>` (required unless --daemon)

Options:
      --daemon
          Empty the shepherd's own logs instead of any sheep's

      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Show the alert history: `barks.jsonl`, newest last.

Reads the file directly and never connects to the shepherd — the history is on disk precisely so it
survives the shepherd, and the case this verb exists for is an operator reading it after a crash.
Same precedent as `shep flush --daemon`, which also works on files rather than through the socket.

Usage: shep barks [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --tail <TAIL>
          Show only the last N barks

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Store a value in the shepherd's key/value store.

Reads and writes `$SHEP_HOME/kv.json` directly and never connects to the shepherd — the store is for
ad-hoc notes and dog settings, and it has to work while nothing is running, exactly as `shep enable`
does.

Keys are flat: letters, digits, `.`, `_` and `-`, up to 128 bytes, not starting with a dot. A dot is
part of the name — `bark.cooldown` is one key, not a path into anything.

Usage: shep set [OPTIONS] <KEY> <VALUE>

Arguments:
  <KEY>
          The key

  <VALUE>
          The value

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Read one value from the store, or list the whole store with no key

Usage: shep get [OPTIONS] [KEY]

Arguments:
  [KEY]
          The key; omit to list every key

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Remove one key from the store, or every key with --all

Usage: shep unset [OPTIONS] [KEY]

Arguments:
  [KEY]
          The key to remove

Options:
      --all
          Remove every key

      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Watch the flock on a live dashboard.

Reads the shepherd two ways at once: it subscribes to the event bus so the screen moves as things
happen, and it re-lists the flock every two seconds so a dropped event cannot leave the screen
quietly wrong.

If the shepherd stops answering, lookout re-dials a few times and then says so and stops updating.
The values on screen stay exactly as they were, and it does not exit — you do.

Needs a terminal: with stdout redirected it refuses rather than writing escape sequences into a
file.

Usage: shep lookout [OPTIONS]

Options:
      --allow-control
          Open the dashboard's action gate. Off by default.
          
          With the gate open, `x` (stop), `R` (restart) and `L` (reload) each arm a confirm instead
          of acting on the keypress that pressed it; Enter sends the request, any other key cancels,
          and an unanswered confirm expires after ten seconds. Off, all three refuse outright with
          `read-only: actions need --allow-control`.
          
          A guard against a keystroke in a window you were reading, not a security boundary: lookout
          runs as you, so anything it could do you can already do with `shep stop`. Can also be set
          with `shep set lookout.allow_control true`; this flag wins.

      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Serve the MCP interface on stdin/stdout for an AI agent.

Speaks the Model Context Protocol over stdio: an agent host launches this process and talks JSON-RPC
to it on the pipe. It writes nothing else to stdout, because stdout is the wire.

Five read-only tools are always offered. The four that act — start_sheep, stop_sheep, restart_sheep,
reload_sheep — exist only when `[whistle] allow_control = true` in `$SHEP_HOME/shep.toml`.

That gate is a guard against an agent acting on its own reading of your flock, not a security
boundary: whistle runs as you, so anything it could do you can already do with `shep stop`. There is
deliberately no flag for it — legibility, not containment: a boolean in `shep.toml` has a diff and
an mtime an operator can audit, and `--home`/`SHEP_HOME` already choose which `shep.toml` that is,
so a flag would open nothing those don't already.

Usage: shep whistle [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Check whether the shepherd answers

Usage: shep ping [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Shut the shepherd down

Usage: shep kill [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Write the muster roll now, so a reboot can bring this flock back

Usage: shep save [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Assemble the flock from the muster roll `save` wrote, starting the shepherd first if none is running

Usage: shep muster [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Boot a shepherd in this process, run one Flockfile's flock in the foreground, and exit once nothing
is left online.

Meant for a container: no daemonization, no re-exec, no saved muster roll — `--no-restore` is always
on, because a container starts from its Flockfile every time, never from a roll left on the image by
a previous run.

Bleats stream to this process's own stdout/stderr while it runs, so `docker logs` is the flock's log
without any extra plumbing. The shepherd is still reachable over its own socket the whole time —
`shep flock` from a second terminal, or `docker exec`, works exactly as it would against a
daemonized one.

Exits 0 once the flock has been empty and clean (every sheep `stopped`, none `errored`) for three
consecutive two-second polls — a batch job finishing its work. Exits 11 (`flock_empty`) instead when
the flock emptied with at least one sheep `errored` — a restart budget exhausted, or a spawn that
never came up — so an orchestrator reading the exit status can tell "finished" from "died" and
restart the container only for the second.

Usage: shep runtime [OPTIONS] [TARGET]

Arguments:
  [TARGET]
          Flockfile to run (default: discovered in the current directory)

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Run one Flockfile's flock in an isolated, throwaway foreground session: `$SHEP_DEV_HOME` (default
`~/.shep-dev`), forced `watch = true` on every app, and a full stop-and-delete teardown when it
ends.

**`--home` and `$SHEP_HOME` are ignored.** Isolation is the whole feature: an operator who exports
`$SHEP_HOME` for their real flock gets a stderr notice rather than a `dev` session that shares it
and silently forces `watch = true` onto production apps.

Ends the moment the flock empties or this process is signalled — whichever comes first — and either
way leaves nothing running and no shepherd behind. A `shep dev` that leaked a supervisor would stop
being trusted.

Usage: shep dev [OPTIONS] [TARGET]

Arguments:
  [TARGET]
          Script or Flockfile to run (default: discovered in this directory)

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --name <NAME>
          Name for this sheep (script form only)

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Write a Flockfile from a pm2 dump. Starts nothing.

Reads `--from`, or `~/.pm2/dump.pm2` if it names nothing — whichever `pm2 save` last wrote. Every
clustered app is named on stderr: shep binds nothing, so N instances on one port need the app to set
`SO_REUSEPORT` itself, or the second instance hits EADDRINUSE at start. Every env key the dump
carried that was neither declared nor recognizable session junk is named on stderr too, and left out
of the Flockfile, for the operator to decide.

Usage: shep import [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --from <FROM>
          Read this pm2 dump instead of `~/.pm2/dump.pm2`

      --out <OUT>
          Write the Flockfile here instead of `./Flockfile.toml`

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --dry-run
          Print the Flockfile that would be written, and write nothing

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --force
          Overwrite an existing Flockfile

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Install an init unit so the shepherd starts at boot.

Writes an init unit for the target user — a systemd unit (`Type=notify`), a launchd plist, an openrc
script, or a FreeBSD or OpenBSD `rc.d` script, picked automatically for the running target or named
explicitly with `--init` below. Every unit carries this binary's own path, that user's $SHEP_HOME,
and the PATH of this invocation — which is what makes an interpreter installed under ~/.bun or
~/.cargo findable after a reboot.

The openrc and BSD scripts are rendered and pinned by exact-string tests; nobody on this project has
run them on their own init system.

Needs root, and never asks for it: without it this prints the exact command to run and exits
non-zero, so a script notices. Under sudo the unit is built for $SUDO_USER rather than root, so it
supervises the flock the operator actually has.

Under sudo this also warns that PATH may have been replaced by sudo's own secure_path before shep
ever saw it, and shows the exact PATH about to go into the unit so you can check it yourself.

Usage: shep startup [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --user <USER>
          The user the unit runs the shepherd as (default: $SUDO_USER, else the invoking user)

      --init <INIT>
          Write a unit for this init system instead of the detected one.
          
          `unstartup` takes it too: a unit installed under one init has to be removable after the
          host has changed to another.

          Possible values:
          - systemd:    Linux + systemd: a unit file, `Type=notify`
          - openrc:     Linux + openrc: an `openrc-run` script. No readiness protocol — see the
            renderer's own doc
          - launchd:    macOS: a `LaunchDaemon` plist
          - freebsd-rc: FreeBSD: an `/etc/rc.subr` script under `/usr/local/etc/rc.d`
          - openbsd-rc: OpenBSD: an `/etc/rc.d/rc.subr` script under `/etc/rc.d`

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Disable and remove whichever unit `startup` installed — systemd, openrc, launchd, or a BSD `rc.d`
script.

Needs root under the same rule: without it, prints the command to run and exits non-zero. A unit
that is not there is reported absent rather than failing.

Usage: shep unstartup [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --user <USER>
          The user the unit runs the shepherd as (default: $SUDO_USER, else the invoking user)

      --init <INIT>
          Write a unit for this init system instead of the detected one.
          
          `unstartup` takes it too: a unit installed under one init has to be removable after the
          host has changed to another.

          Possible values:
          - systemd:    Linux + systemd: a unit file, `Type=notify`
          - openrc:     Linux + openrc: an `openrc-run` script. No readiness protocol — see the
            renderer's own doc
          - launchd:    macOS: a `LaunchDaemon` plist
          - freebsd-rc: FreeBSD: an `/etc/rc.subr` script under `/usr/local/etc/rc.d`
          - openbsd-rc: OpenBSD: an `/etc/rc.d/rc.subr` script under `/etc/rc.d`

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Print a shell completion script.

Static only: sheep names, fold names and other daemon-side identifiers are never completed.

Usage: shep completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>
          Shell to generate a completion script for
          
          [possible values: bash, elvish, fish, powershell, zsh]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
@@VERB:init@@
Write a commented Flockfile to start from

Usage: shep init [OPTIONS] [PATH]

Arguments:
  [PATH]
          Where to write it. The extension picks the format: toml, yaml, yml, json or json5.
          Defaults to Flockfile.toml in this directory

Options:
      --all
          Show every option the grammar has, not just the common ones

      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

      --force
          Overwrite the Flockfile that is already here, keeping its own format

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
@@VERB:style@@
Show or set how much shep dresses up its output

`full` is sheep, boxes and colour; `plain` drops the sheep; `bare` is plain text. With no level,
prints the one in force and where it came from.

Usage: shep style [OPTIONS] [LEVEL]

Arguments:
  [LEVEL]
          `full`, `plain`, or `bare`
          
          Sets `shep.toml`'s `[style] level`. Omit to report the level currently in force instead of
          changing it.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
@@VERB:welcome@@
Print the welcome: the sheep, and the five commands worth knowing.

The same text a fresh `$SHEP_HOME` prints once on its own. Here it is the command's output rather
than a diagnostic, so it goes to stdout.

Usage: shep welcome [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table: Human-readable columns (the default)
          - json:  A versioned JSON envelope, one object per invocation
          
          [default: table]

  -q, --quiet
          Suppress non-essential output
          
          Currently narrows `bleats`' own notices (a dropped-events count, a daemon-shutdown notice,
          ...): diagnostics distinct from a sheep's own line or a real error, both of which still
          print regardless.

      --style <STYLE>
          How much this invocation dresses up its output: `full`, `plain`, or `bare`
          
          Wins over `$SHEP_STYLE` and `shep.toml`'s `[style] level`. Omit to let those decide; `shep
          style` reports which one answered.

          Possible values:
          - full:  Sheep, boxes and colour
          - plain: Boxes and colour, no sheep
          - bare:  Exactly what shep printed before any of this, and exactly what a pipe gets

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep.
          
          [env: SHEP_HOME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version