Commands

Every verb uses the format collie <verb>. This is the canonical syntax across all installations, implemented directly in the binary (cli/). Before adding collie to your PATH (below), run bin/collie <verb> from the repository root. On a Herdr-managed installation, these same verbs register as Herdr actions (below) with identical behavior.

If the host runs multiple instances, prepend COLLIE_INSTANCE=<name> to every verb. See Multiple Collie instances on one host.

The CLI also includes build, serve, unserve, doctor, and pack … for less frequent tasks.

Both start and status output the Collie is running banner: a health mark and the version, then a service, a local and a tailnet line. First run shows it in full, including what a failed health check prints instead. The reported version reads from the served bundle stamp, reflecting the active build.

Ink or plain text. The start, status, doctor, pack add, and pack status commands render an interactive terminal UI when stdout is a TTY. Passing --plain, or redirecting output to a pipe, file, systemd journal, or CI runner, falls back to raw line output.

Put collie on your PATH

Run collie link to publish ~/.local/bin/collie:

bin/collie link          # ~/.local/bin/collie → <checkout>/bin/collie
collie status            # from anywhere
bin/collie unlink        # take the name back down

It creates a symlink to the checkout's binary, so future collie build updates take effect immediately without extra steps (ADR 0021). The command replaces existing links from other Collie checkouts and prints which one it overwrote. It refuses to overwrite non-Collie files at that path. unlink removes the symlink only if it targets your current checkout.

If ~/.local/bin is missing from your PATH, link warns you and exits. It never edits your shell profile. Run collie doctor to check the path-link line and see which checkout the bare collie command resolves to.

Herdr actions

Applies only to a Herdr-managed install created with herdr plugin install AltanS/collie or herdr plugin link. Herdr is one of three multiplexers Collie supports. These actions map directly to the adapter: each action forwards the verb to the same collie binary documented in the table above. On binary installs created via scripts/install.sh, plugin actions do not exist, and collie <verb> is the only syntax.

Collie registers these actions in herdr-plugin.toml. Invoke them with herdr plugin action invoke <id> --plugin herdr.collie, or view them with herdr plugin action list --plugin herdr.collie:

qr, pair, devices, link, logs, and stt have no corresponding plugin action because they require a terminal, positional arguments, or both. Run them as collie <verb>.

Herdr actions return Herdr's JSON envelope instead of the terminal banner. View the action's captured stdout with herdr plugin log list --plugin herdr.collie, or run collie <verb> directly to print output inline. Output from herdr plugin list --json reflects the version cached during plugin link, not the active version. For linked clones, update re-links automatically to fix the cache. You can force this with herdr plugin link "$(pwd)". Herdr ≥0.8.0 re-reads the manifest from disk on each invocation.

Note. scripts/collie-ctl.sh <verb> remains supported. It operates as a bootstrap shim: it locates Bun, compiles bin/collie if the checkout lacks it, and passes along argv. A freshly linked clone uses this path to build its initial binary. Herdr actions continue to point to this script because Herdr <0.8.0 freezes the action definitions cached at install time (ADR 0006). Each verb is implemented once inside the compiled binary in cli/.