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, and `add` never starts anything in the first
          place.
          
          Omit the targets to read the Flockfile in the current directory. With no Flockfile there,
          `shep start` brings a shepherd up with nothing running yet, and `shep add` has nothing it
          could register.
          
          A target may be preceded by `NAME=VALUE` assignments, read the way a shell reads them:
          `shep start KOJI_TOKEN=secret ./koji` registers koji with that variable set and records
          it, so a later `shep start koji` needs no assignment. A name takes a letter or `_` and
          then letters, digits or `_`, which is what makes `./A=1` a path and `1A=1` a target. Quote
          the value and never the pair: `shep start "A=x y" ./koji`.
          
          Assignments take one target, and it must be a script path or a sheep the flock already
          has. A Flockfile or a fold can name several sheep, and an assignment names none of them.
          The value passes through this command line, so it reaches `ps` and your shell history;
          write `{{secret:NAME}}` to read a credential from `shep secret` instead.
          
          Several are handled in turn, not atomically: if the second fails the first has already
          landed, 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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.

      --no-log-timestamps
          Write this sheep's log lines without the timestamp shep puts in front of each one.
          
          The flag form of a Flockfile's `log_timestamps = false`, and it wins over a Flockfile's
          own value. `shep bleats` shows the same lines either way; only the files on disk differ.

      --reset[=<RESET>]
          Widen a Flockfile load past its additive default: append nothing, overwrite instead. A
          mode touches only what its name says; see the four below. Refused when the target supplies
          no template to reset to: a sheep name reads no file, and a bare script path is a command
          line rather than a file.
          
          The value is required, with an equals sign: `--reset=file`, never `--reset file`.
          `targets` is a greedy variadic positional, and a space-separated value next to one of
          those is where argument parsing gets ambiguous.

          Possible values:
          - file:   Put back what the template declares, `env` kept
          - policy: Put back every setting but `env`, declared or not
          - env:    Put back only `env`
          - all:    Put back everything, `env` included, and drop the override record

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

  -V, --version
          Print version

Register a sheep without starting it.

The same targets `shep start` takes and the same load path. The one difference is that nothing
spawns: the app lands registered and stopped, and `shep start <name>` is what brings it up.

It is here for the Flockfile a project commits with its secrets left blank: `env = { DB_HOST = "",
DB_PASSWORD = "" }`, the `.env.example` convention. Starting that file spawns a process against an
empty database URL, which crashes, spends its restart budget, and has to be stopped before anyone
can configure it. This registers it instead, so the order becomes register, fill in, start.

An app the flock already has is merged into and left exactly as it is, running or not.

Usage: shep add [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, and `add` never starts anything in the first
          place.
          
          Omit the targets to read the Flockfile in the current directory. With no Flockfile there,
          `shep start` brings a shepherd up with nothing running yet, and `shep add` has nothing it
          could register.
          
          A target may be preceded by `NAME=VALUE` assignments, read the way a shell reads them:
          `shep start KOJI_TOKEN=secret ./koji` registers koji with that variable set and records
          it, so a later `shep start koji` needs no assignment. A name takes a letter or `_` and
          then letters, digits or `_`, which is what makes `./A=1` a path and `1A=1` a target. Quote
          the value and never the pair: `shep start "A=x y" ./koji`.
          
          Assignments take one target, and it must be a script path or a sheep the flock already
          has. A Flockfile or a fold can name several sheep, and an assignment names none of them.
          The value passes through this command line, so it reaches `ps` and your shell history;
          write `{{secret:NAME}}` to read a credential from `shep secret` instead.
          
          Several are handled in turn, not atomically: if the second fails the first has already
          landed, 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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.

      --no-log-timestamps
          Write this sheep's log lines without the timestamp shep puts in front of each one.
          
          The flag form of a Flockfile's `log_timestamps = false`, and it wins over a Flockfile's
          own value. `shep bleats` shows the same lines either way; only the files on disk differ.

      --reset[=<RESET>]
          Widen a Flockfile load past its additive default: append nothing, overwrite instead. A
          mode touches only what its name says; see the four below. Refused when the target supplies
          no template to reset to: a sheep name reads no file, and a bare script path is a command
          line rather than a file.
          
          The value is required, with an equals sign: `--reset=file`, never `--reset file`.
          `targets` is a greedy variadic positional, and a space-separated value next to one of
          those is where argument parsing gets ambiguous.

          Possible values:
          - file:   Put back what the template declares, `env` kept
          - policy: Put back every setting but `env`, declared or not
          - env:    Put back only `env`
          - all:    Put back everything, `env` included, and drop the override record

  -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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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`, `api-*`, `/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 `api-*` selects `api-auth`
          and not `my-api-auth`. Quote it: your shell expands `api-*` 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Restart one or more sheep.

The running process is killed and a new one spawned in its place, so there is a window with nothing
serving. `shep reload` is the verb that closes that window, at the cost of caring how the app is
configured.

A selector matching one sheep is answered as soon as the respawn is issued, printing the flock as it
stood at that moment.

A selector matching two or more is walked in dependency order instead, and the reply waits: each
stage is held until the apps a later stage depends on are back, so a fold comes back in the order
its depends_on lines describe rather than all at once. The wait is the sum of the stages.

That walk asks the shepherd once per app, so an app it could not restart is refused on its own and
the rest of the fold restarts anyway. The rows printed are what the walk finished with, the app it
went around is named on stderr, and the exit is non-zero. Under `--format json` the same names come
back under refused in the one envelope.

A sheep that came back errored is a different failure and is reported separately: that one was
reached, and it is the child that could not start. That failure empties stdout, the way every verb's
does, so a restart that BOTH refused an app and brought one back errored prints no envelope at all.
The refused names ride the stderr sentence in that case, which is the only place left for them.

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

Arguments:
  <SELECTORS>...
          One or more: name, id, `name:slot`, `all`, `api-*`, `/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 `api-*` selects `api-auth`
          and not `my-api-auth`. Quote it: your shell expands `api-*` 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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.

A selector matching one app 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.

A selector matching two or more apps is walked in dependency order instead, and the reply waits:
each stage is held until the apps a later stage depends on are back and ready, so the wait is the
sum of the stages rather than the longest swap in the fold. The rows printed are what the walk
finished with, and an app it could not reload is named, with a non-zero exit.

The swaps themselves are reported on the bus either way, under process.reload, process.reloaded and
process.reload_abandoned.

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

Arguments:
  <SELECTORS>...
          One or more: name, id, `name:slot`, `all`, `api-*`, `/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 `api-*` selects `api-auth`
          and not `my-api-auth`. Quote it: your shell expands `api-*` 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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`, `api-*`, `/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 `api-*` selects `api-auth`
          and not `my-api-auth`. Quote it: your shell expands `api-*` 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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 a reboot keeps 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

List the flock

Usage: shep flock [OPTIONS]

Options:
      --follow
          Keep the listing current: redraw it in place until Ctrl+C
          
          One listing to start, then a fresh one every `--interval` seconds while the shepherd stays
          reachable, each one painted over the last. A summary of the machine rides above the
          tables. Ctrl+C leaves an exit of zero, a stopped shepherd leaves the code its refusal
          carries: an interrupted follow and a dead shepherd must not read as the same thing.
          
          Needs a live shepherd: a saved roll is a single moment, and a follow's whole reason is the
          moments after it. Needs a terminal too, and refuses `--format json`, since neither has
          anywhere to put a redraw.

      --format <FORMAT>
          Output format

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

      --interval <SECONDS>
          Seconds between redraws, with `--follow`
          
          The floor is one second, which is also the default. Below it the listing costs the
          shepherd more than it tells the operator, and `sysinfo` reports no CPU at all over a
          window that short.
          
          [default: 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.

      --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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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`, `api-*`, `/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 `api-*` selects `api-auth`
          and not `my-api-auth`. Quote it: your shell expands `api-*` 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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 `[<name>]` config key in `dogs.toml`

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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 `[<name>]` in `dogs.toml` in place: the dog's own configuration survives a disable/enable
cycle. `shep rehome` leaves it too, and forgets the adoption as well.

Usage: shep disable [OPTIONS] <NAME>

Arguments:
  <NAME>
          The dog's name, the `[<name>]` config key in `dogs.toml`

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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.

A binary whose `--version` answer carries `shep-channel: true` is also written to `[daemon]
channel_dogs`, and runs with the shepherd channel: `shep trigger` reaches it, and a stop is a
message rather than a signal. The dog asks; there is no flag for it.

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 `[<name>]` config key in `dogs.toml`. 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Forget where an adopted dog's binary lived: stops it if a shepherd is running, and removes it from
`[daemon] enabled_dogs`, `[daemon] adopted_dogs` and `[daemon] channel_dogs`.

Its `[<name>]` table in `dogs.toml` stays, as it does through a `shep disable`: those settings are
the operator's, so adopting the same dog again finds them waiting. Delete that table by hand to be
rid of them. Only the adoption differs from `disable`, so recovery is a fresh `shep adopt <path>`
rather than an `enable`.

Usage: shep rehome [OPTIONS] <NAME>

Arguments:
  <NAME>
          The dog's name, the `[<name>]` config key in `dogs.toml`

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Store the values a Flockfile refers to and never carries.

Reads and writes `$SHEP_HOME/secrets.json` directly and never connects to the shepherd, exactly as
`shep set` does: filling the store before the first `shep start` is the ordinary first run.

A key holds one value per environment, so production and staging differ without two config files. A
`{{secret:NAME}}` reference in a Flockfile resolves against the sheep's own environment and then the
`all` slot, never another named environment.

Keys and environment names are letters, digits, `.`, `_` and `-`, up to 128 bytes, not starting with
a dot.

Reading a value back is off until `[secrets] allow_read = true` is in `$SHEP_HOME/shep.toml`.
`secret list` needs nothing: it names keys and the environments each has a value for, never a value.

Usage: shep secret [OPTIONS] <COMMAND>

Commands:
  set    Store a value
  get    Print a value back, if `[secrets] allow_read` is on
  unset  Remove a value
  list   List keys and the environments each has a value for
  help   Print this message or the help of the given subcommand(s)

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Store a value

The value is a positional argument by default, so it is visible in `ps` and in this shell's history
for as long as the command runs. Pass `--stdin` to keep it out of both.

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

Arguments:
  <KEY>
          The key

  [VALUE]
          The value; required unless --stdin is given

Options:
      --env <ENV>
          Which environment; omit for every environment

      --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.

      --stdin
          Read the value from stdin; the positional form is visible in `ps` and in shell history

      --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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Print a value back, if `[secrets] allow_read` is on

Usage: shep secret get [OPTIONS] <KEY>

Arguments:
  <KEY>
          The key

Options:
      --env <ENV>
          Which environment; omit to use `[daemon] environment`'s default, which an app's own
          environment may override

      --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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Remove a value

Usage: shep secret unset [OPTIONS] <KEY>

Arguments:
  <KEY>
          The key

Options:
      --env <ENV>
          Which environment; omit for the every-environment slot

      --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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

List keys and the environments each has a value for

Usage: shep secret list [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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:
      --format <FORMAT>
          Output format

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

      --read-only
          Close the dashboard's action gate. Actions are permitted 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. Closed, all three refuse outright.
          
          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
          closed with `shep set lookout.allow_control false`.

  -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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Write the muster roll now and say where it landed.

The shepherd already rewrites the roll after every change. This is for seeing it on disk before a
reboot rather than trusting that it is.

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Assemble the flock from the muster roll, 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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Read somebody else's config into shep: a pm2 dump, or a `.env`

Usage: shep import [OPTIONS] <COMMAND>

Commands:
  pm2   Write a Flockfile from a pm2 dump. Starts nothing
  env   Read a `.env` into the secret store and one sheep's own env
  help  Print this message or the help of the given subcommand(s)

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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 pm2 [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

Read a `.env` into the secret store and one sheep's own env.

Every key the file holds goes to the named sheep's env, where it reaches the app at its next spawn.
A key named by `--secret` has its value stored in `$SHEP_HOME/secrets.json` instead, and the sheep's
env gets `{{secret:KEY}}`, so the value never reaches `flock.json` or the handover blob.

A key that is not marked secret is stored in the clear, and is copied into both of those snapshots
along with the rest of the sheep's config.

The sheep has to exist already: this records an operator override, which is per sheep. Run `shep
start` first.

Any collision, any pattern that matches nothing, and any line the grammar does not accept refuses
the whole import. A refusal reached before the secret store is written leaves both stores alone; one
reached after counts the keys it left there, which nothing references until the import is re-run.

Usage: shep import env [OPTIONS] --app <APP> <FILE>

Arguments:
  <FILE>
          The `.env` to read
          
          A `{{...}}` in a plain value reaches the app as the literal text the file wrote, not as a
          shep template reference.

Options:
      --app <APP>
          The sheep whose env these keys belong to

      --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.

      --secret <SECRET>
          Store this key's value as a secret, and reference it from the env.
          
          An exact key, or a glob when it holds a metacharacter, the same rule a sheep-name selector
          takes. Repeatable. A pattern matching no key in the file refuses the import.

      --only <ONLY>
          Import only these keys; the default is all of them.
          
          Same grammar as `--secret`, and the same refusal.

      --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

      --env <ENV>
          Which environment's slot the secrets go in.
          
          The default is the sheep's own environment, which is its `environment` field, or `[daemon]
          environment` when it has none, and so is never the `all` slot that every environment
          reads. Naming `all` here writes that slot, as `shep secret set --env all` does.

      --home <HOME>
          Talk to a different shepherd
          
          Mostly plumbing: `shep dev` sessions, a system-wide flock, tests. You almost certainly
          want the default, ~/.shep. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

      --dry-run
          Print what would be written, and write nothing

      --force
          Overwrite keys that already hold a different value

  -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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version

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. Must be an absolute path: a relative one would name a different
          flock from every directory.
          
          [env: SHEP_HOME=]

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

  -V, --version
          Print version