diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 5062b2f4..f7aab3f6 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -186,6 +186,7 @@ export default defineConfig({ label: 'Reference', collapsed: true, items: [ + { label: 'CLI (paddock)', slug: 'reference/cli' }, { label: 'API overview', slug: 'reference/api' }, { label: 'HTTP API (Swagger)', link: '/api/' }, { label: 'WebSocket protocol', slug: 'reference/websocket' }, diff --git a/website/src/content/docs/getting-started.md b/website/src/content/docs/getting-started.md index fa73f2b9..7d6dee3d 100644 --- a/website/src/content/docs/getting-started.md +++ b/website/src/content/docs/getting-started.md @@ -86,11 +86,14 @@ Useful flags: --host Bind address (default 127.0.0.1) -d, --data-dir Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR) -o, --open Open the app in your browser once it is listening + -q, --quiet Print only the first line, `Paddock : ` --verbose Show the server's own logs (quiet by default) -v, --version Print the Paddock version and exit -h, --help Show this help ``` +Every command and flag is in the [CLI reference](/reference/cli/). + `--data-dir` is the only thing that picks which instance you get; the directory you happen to be standing in has no effect. `--verbose` is worth one run on a new instance: several of Paddock's startup notices — which login it found, what it bridged from `~/.claude`, what it diff --git a/website/src/content/docs/reference/cli.md b/website/src/content/docs/reference/cli.md new file mode 100644 index 00000000..95cd439e --- /dev/null +++ b/website/src/content/docs/reference/cli.md @@ -0,0 +1,270 @@ +--- +title: "CLI reference" +description: "Every paddock command and flag: serve, service, busy, update, doctor and config, with the exit codes and the environment variables the CLI reads." +--- + +The `paddock` command, all of it. For the why and the walkthroughs, see +[Running as a service](/guides/running-as-a-service/), [Updating](/guides/updating/) and +[Config profiles](/configuration/profiles/); this page is the lookup table. + +```bash +npm i -g @edspencer/paddock # installs `paddock` +npx @edspencer/paddock # or run it without installing +``` + +``` +paddock [serve] [options] run the server in this terminal +paddock service [options] install|uninstall|status|start|stop|restart|logs +paddock busy [--json] is the running instance busy? +paddock update [--check] [--to ] install a newer Paddock +paddock doctor [--json] [--offline] checks, with a fix for each problem +paddock config [options] what this instance's config resolved to +paddock -v | --version print the version and exit +paddock -h | --help the full help +``` + +Every command takes `--help` (`paddock service --help`, `paddock update --help`, …), which +is the same text as this page in more words. + +## Conventions + +The CLI follows the [CLI contract](https://github.com/edspencer/cli-contract) (SPEC 0.2) +that Ed's local tools share, so these hold for every command: + +- **The command comes first, flags after it.** `paddock serve --port 7300` and + `paddock service install --port 7300` use the same flag grammar. +- **A flag a command can't act on is a usage error (exit 2)**, not something quietly + ignored: `--force` on `service uninstall`, `--json` on `serve`, `--offline` on anything + but `doctor`. The message names the commands it does apply to. +- **`--json` prints exactly one JSON document on stdout**, and every word of prose goes + to stderr. The exit code is the same with or without it. +- **Colour** is on for a terminal and off otherwise. `NO_COLOR` (any non-empty value) + turns it off; `FORCE_COLOR` turns it on, or off with `0` or `false`. +- **Only `update`, `update --check` and `doctor` contact the npm registry**, and only when + you run them. Nothing else in the CLI or the server checks for updates. + +## `paddock serve` + +Runs the server in this terminal until Ctrl-C. **`paddock start` is an alias, kept for +good**, and a bare `paddock` (or `npx @edspencer/paddock`) runs `serve` too. + +```bash +paddock serve +paddock serve --port 7300 --open +paddock serve -d ~/paddock-work # a second, separate instance +``` + +| Option | What it does | +|---|---| +| `-p, --port ` | the HTTP/WS port, 1–65535 (default `7233`, or `$PORT`) | +| `--host ` | the bind address (default `127.0.0.1`, or `$HOST`). A routable address needs auth: see [Binding & network exposure](/configuration/binding-and-exposure/) | +| `-d, --data-dir ` | the instance: projects, transcripts and state (default `~/.paddock`, or `$PADDOCK_DATA_DIR`) | +| `-o, --open` | open the app in your browser once it is listening | +| `-q, --quiet` | print only the first line, `Paddock : ` | +| `--verbose` | show the server's own logs, which are quiet (`warn`) by default | + +**The first line on stdout is `Paddock : `**, and nothing comes before it, +so a script can read the URL from it. The server's logs and any first-run notice go to +stderr. The data dir alone decides which instance you get: the directory you run it from +makes no difference. A port that is already in use exits 1, with a suggestion of another. + +## `paddock service` + +Runs Paddock in the background as a per-user service: a launchd LaunchAgent on macOS, a +`systemd --user` unit on Linux. Not on Windows yet. The full story is +[Running as a service](/guides/running-as-a-service/). + +| Command | What it does | +|---|---| +| `paddock service install` | write the unit, enable it, start it, and wait until it answers | +| `paddock service uninstall` | stop it and remove the unit. Your data and logs stay | +| `paddock service start` | start an installed service, and wait until it answers | +| `paddock service stop` | stop it until `service start`, or the next login or boot. It stays installed | +| `paddock service restart` | stop it and start it again, re-reading the unit and config | +| `paddock service status` | installed? running? answering? which version? | +| `paddock service logs` | the last 50 lines of `/logs/service.log` | + +| Option | On | What it does | +|---|---|---| +| `-p, --port ` | `install` | the port recorded in the unit (default `7233`) | +| `--host ` | `install` | the bind address recorded in the unit (default `127.0.0.1`) | +| `-d, --data-dir ` | `install` | a data dir *separate* from your terminal's instance. Left out of the unit unless you pass it or `PADDOCK_DATA_DIR` is set | +| `--verbose` | `install` | record the server's own logs, not just warnings | +| `--dry-run` | `install` | print the unit on stdout (and where it would go on stderr), and write nothing | +| `--from-checkout` | `install` | install from a git checkout or `npm link` anyway | +| `--refresh` | `install` | re-write the unit from the settings the installed one records; exit 4 if there is none | +| `--force` | `stop`, `restart` | go ahead even though Paddock is busy | +| `--json` | all but `logs` | one document on stdout: `ok`, `action`, `error` on a failure, and the same fields as `status --json` | +| `-f, --follow` | `logs` | keep printing what gets appended, until Ctrl-C | +| `-n, --lines ` | `logs` | how many lines to print first (default 50) | + +**Running `install` again keeps the port, host, data dir and verbosity** the installed +unit records, unless a flag gives new ones, and restarts the service onto the new unit. +It refuses, with exit 1, from an npx cache, from a git checkout without +`--from-checkout`, and when something other than Paddock holds the port. + +**`stop` and `restart` refuse with exit 75 while Paddock is busy** unless you add +`--force`, which prints the same message prefixed `Overriding:`. `start` and `uninstall` +don't ask. `status --json` reports `installed`, `running`, `answering`, +`installedVersion`, `runningVersion`, `port`, `url`, `pid`, `unit`, `log`, `warnings`, and +`update` when a check has found one. + +## `paddock busy` + +Asks the running instance whether it is in the middle of something a restart would lose: +a chat turn (a human turn, a fired trigger, a cron fire), a background task a live +session still holds, or a scheduled job. An idle session, an open tab or a pending sweep +is not busy. + +```bash +paddock busy # a sentence, and the exit code +paddock busy --json # { running, busy, url, version, counts } +``` + +| Option | What it does | +|---|---| +| `-d, --data-dir ` | which instance to ask (default `~/.paddock`, or `$PADDOCK_DATA_DIR`) | +| `--json` | one JSON document on stdout; prose on stderr | + +**This command is for its exit code:** 0 not busy, 75 busy, 3 nothing answering, and 1 +when something answered but not as Paddock's busy check. It finds the instance through +`/runtime.json` and never guesses a port. 75 is the code Watchtower's +pre-update hook reads as "skip this one"; see +[Docker and Watchtower](/guides/updating/#docker-and-watchtower). Run it from a terminal: +a Paddock chat that runs it counts itself as busy. + +The same answer is `GET /api/busy` over HTTP, with no authentication, since it carries +counts and nothing else. + +## `paddock update` + +Installs a newer Paddock, restarts the service onto it, waits for it to answer, and puts +the old version back if it doesn't. Step by step, and what each failure means, is on +[Updating](/guides/updating/). + +```bash +paddock update # the latest release, asking first +paddock update --check --json # what a new version would be; changes nothing +paddock update --to 0.82.1 # a version: the only way to go back +paddock update --to next # a dist-tag +paddock update --yes # from a script +``` + +| Option | What it does | +|---|---| +| `--check` | ask the registry, report, and change nothing. Exits 0 either way; scripts read `updateAvailable` from `--json` | +| `--to ` | a version or dist-tag instead of `latest`. Required to move to a lower version | +| `-y, --yes` | don't ask. Required without a terminal, where `update` otherwise exits 2 | +| `--force` | skip the busy check, and nothing else: the health check and the rollback still run | +| `--json` | one JSON document on stdout; prose on stderr | + +An install that isn't Paddock's to replace (Docker, npx, a git checkout, a dependency of +another project, a yarn classic global, a global folder you can't write to, or anything +with `PADDOCK_UPDATE_HINT` set) exits 5 and prints the command that would work. A global +npm, pnpm, bun or volta install updates in place. + +## `paddock doctor` + +Checks that Paddock can run here, one line each, with a `fix:` under every warning and +failure. Each line starts `✓` (fine), `!` (a warning), `✗` (a failure) or `-` (doesn't +apply here). There's an example on +[Updating](/guides/updating/#checking-an-install-paddock-doctor). + +| Option | What it does | +|---|---| +| `--json` | one document on stdout: `{ ok, version, checks: [{ id, status, message, fix? }] }`. The update notice goes to stderr | +| `--offline` | skip the update check, the only one that uses the network | +| `-d, --data-dir ` | which instance to check (default: the service's, else `$PADDOCK_DATA_DIR`, else `~/.paddock`) | + +| Check | What it looks at | +|---|---| +| `node-engines` | this Node satisfies the package's `engines` (Node 22 or later) | +| `install-method` | how Paddock was installed, and whether `paddock update` can update it | +| `unit` | the service: installed, running and answering, its Node and CLI still there, the same install as this CLI | +| `running-version` | the running Paddock is the installed version | +| `port` | the port is free, or held by Paddock | +| `linger` | on Linux, whether the service keeps running after you log out | +| `data-home` | the data dir is writable | +| `config` | `paddock.config.yaml` and the environment load as `serve` would load them | +| `projects` | the projects folder is writable | +| `claude-login` | a Claude login Paddock can use: which kind, never its value | +| `claude-cli` | a `claude` on `PATH`, which the sweeper always needs, and chats and triggers on `driveMode: batch` | +| `update` | a newer version on the registry (skipped with `--offline`) | + +It exits 1 if any check failed; warnings don't count. Apart from the update check's +cache, `/update-check.json`, it writes nothing, and never creates a data dir. + +## `paddock config` + +What this instance's configuration resolved to, and where each value came from. The +detail is on [Config profiles](/configuration/profiles/#seeing-what-your-profile-actually-resolved-to). + +| Command | What it does | +|---|---| +| `paddock config show` | the decisions: your profile, the keys your config file sets, the variables your environment sets | +| `paddock config eject` | preview what freezing the resolution into `paddock.config.yaml` would write. Writes nothing | + +| Option | On | What it does | +|---|---|---| +| `-d, --data-dir ` | both | which instance to inspect (default `~/.paddock`, or `$PADDOCK_DATA_DIR`) | +| `--resolved` | `show` | every effective value, not just the ones someone set | +| `--json` | `show` | the whole report as JSON, long values in full | +| `--show-sensitive` | `show` | print the values of fields marked sensitive | +| `--write` | `eject` | actually write the file | +| `--include-env` | `eject` | also freeze values an environment variable currently supplies | + +## `-v` and `-h` + +| Flag | What it does | +|---|---| +| `-v, --version` | print the Paddock version and exit | +| `-h, --help` | print the help and exit. After a command (`paddock doctor --help`), that command's help | + +## Exit codes + +The codes are the CLI contract's (SPEC §2), and mean the same in every tool that follows +it. + +| Code | Meaning | From | +|---|---|---| +| 0 | done; running and answering; up to date; not busy | everything | +| 1 | failed. Also: an install or start that never answered, a refused `service install`, a `doctor` check that failed | everything | +| 2 | usage: an unknown command or flag, a bad value, a flag the command can't act on, or `update` with no terminal and no `--yes`. The usage follows the message | everything | +| 3 | not running: installed but not running or not answering, or nothing answers. From `update`: a foreground `serve` is still answering | `service status`, `busy`, `update` | +| 4 | not installed: there is no service unit | `service status`, `start`, `stop`, `restart`, `logs`, `install --refresh` | +| 5 | this install can't update itself; the right command was printed | `update` | +| 6 | the update failed and was rolled back; the old version is running again | `update` | +| 7 | the update failed and couldn't be rolled back; a person is needed | `update` | +| 75 | busy: refused, and why was printed. Try later, or use `--force` | `busy`, `update`, `service stop`, `restart` | + +3 and 4 are the codes `systemctl status` and LSB init scripts use. 75 is `EX_TEMPFAIL` +from `sysexits.h`. + +## Environment + +What the CLI itself reads. The server reads many more, all on +[Environment variables](/configuration/environment/). + +| Variable | Read by | What it does | +|---|---|---| +| `PADDOCK_DATA_DIR` | every command | the data dir when `-d` isn't given (default `~/.paddock`). `service install` records it in the unit if it is set | +| `PORT` | `serve` | the port when `-p` isn't given (default `7233`) | +| `HOST` | `serve` | the bind address when `--host` isn't given (default `127.0.0.1`) | +| `LOG_LEVEL`, `HERDCTL_LOG_LEVEL` | `serve` | left alone if set; otherwise `serve` sets both to `warn` unless `--verbose` | +| `PADDOCK_IN_DOCKER` | `update`, `doctor` | set to `1` by the image: `update` prints the image to pull and exits 5 | +| `PADDOCK_UPDATE_HINT` | `update`, `doctor` | for an install something else manages: `update` prints it and exits 5 | +| `npm_config_registry` | `update`, `doctor` | the registry to ask; else `npm config get registry`, else `https://registry.npmjs.org` | +| `XDG_CONFIG_HOME` | `service` | where the systemd user unit goes (default `~/.config`) | +| `NO_COLOR`, `FORCE_COLOR` | every command | colour off, or forced on (`FORCE_COLOR=0` or `false` forces it off) | + +## Files + +| Path | What it is | +|---|---| +| `~/.paddock/` | the default data dir: projects, transcripts, state and `paddock.config.yaml` | +| `/runtime.json` | written 0600 while `serve` is listening, removed when it stops: how `busy` and `update` find the instance | +| `/logs/service.log` | the service's log, rotated by Paddock at 8 MB, keeping three older generations | +| `/update-check.json` | what the last `update --check` or `doctor` found, which `service status` repeats | +| `/update.lock` | held while `update` runs, so two updates can't interleave | +| `~/Library/LaunchAgents/net.edspencer.paddock.plist` | the service unit on macOS | +| `~/.config/systemd/user/paddock.service` | the service unit on Linux | diff --git a/website/src/content/docs/whats-new.mdx b/website/src/content/docs/whats-new.mdx index 96ad25ad..cc36b0c0 100644 --- a/website/src/content/docs/whats-new.mdx +++ b/website/src/content/docs/whats-new.mdx @@ -1,6 +1,6 @@ --- title: What's New -description: "User-facing highlights of each Paddock release, newest first — Stop then send without a five-minute wait, foldable sidebar groups, hardware WebGL for the devbox browser, browser tabs that name the chat and show live status, finished chats that stay on the fleet strip, Running & Recent on Home, Copy and Download on sent files, a full-screen viewer for sent files, a one-row project header, Claude Opus 5.5 as the default, delete from Settings, fast-opening long chats, PDFs in the Files tab, posture profiles and a config report that shows where every value came from, moving your chats into ~/.claude, service start/stop/restart, Home as the front door, stopping one background task instead of all of them, the git surfaces for linked directories, live background work above the composer, Discover and the removal of --here, four themes with an accent picker that solves for contrast, the fleet readout, and queued messages. Earlier releases are archived on a companion page." +description: "User-facing highlights of each Paddock release, newest first — paddock doctor and a service install that checks first, paddock update with a rollback, a service stop that waits for a quiet moment and paddock busy, a CLI scripts can rely on (serve, exit codes, service status --json, service logs), Stop then send without a five-minute wait, foldable sidebar groups, hardware WebGL for the devbox browser, browser tabs that name the chat and show live status, finished chats that stay on the fleet strip, Running & Recent on Home, Copy and Download on sent files, a full-screen viewer for sent files, a one-row project header, Claude Opus 5.5 as the default, delete from Settings, fast-opening long chats, PDFs in the Files tab, posture profiles and a config report that shows where every value came from, moving your chats into ~/.claude, service start/stop/restart, Home as the front door, stopping one background task instead of all of them, the git surfaces for linked directories, live background work above the composer, Discover and the removal of --here, four themes with an accent picker that solves for contrast, the fleet readout, and queued messages. Earlier releases are archived on a companion page." --- import DemoVideo from '../../components/DemoVideo.astro'; @@ -14,6 +14,191 @@ removed in favour of Discover. Both of those entries are now on the [archive page](/whats-new-archive/). ::: +## 0.83 — `paddock doctor`, and an install that checks first + +- **`paddock doctor` checks that Paddock can run here, and says how to fix what + can't.** One line per check: your Node, how Paddock was installed, the + service, the running version, the port, linger on Linux, the data dir, the + config, the projects folder, your Claude login and the `claude` CLI. Each + starts `✓`, `!`, `✗` or `-` (doesn't apply here), and every warning and + failure has a `fix:` line under it. + + ``` + ✓ Node 22.23.4 (Paddock needs >=22) + ! the service is installed (systemd) but not running + fix: paddock service start (and `paddock service logs` if it doesn't stay up) + ! linger is off for ed: the service stops when you log out, and starts only when you log in + fix: sudo loginctl enable-linger ed (Paddock never runs sudo itself) + ✓ Paddock shares this machine's Claude Code login (~/.claude, claude.credentials: host) + ``` + + It exits 1 if a check failed; warnings don't count. `--json` gives a script + the same checks as one document, and `--offline` skips the only check that + leaves the machine, the one that asks npm for a newer version. It never + creates an instance. More on + [Updating](/guides/updating/#checking-an-install-paddock-doctor). + +- **`paddock service install` refuses a service that could only crash-loop.** + If something other than Paddock holds the port, it exits 1 instead of writing + a unit that will never bind. A Paddock on the port is fine: that's a reinstall. + Installing from a git checkout or an `npm link` is refused too, unless you add + `--from-checkout`, because a unit that runs a working tree follows every + rebuild, branch switch and move of it. + +- **Running `service install` again keeps your settings.** A plain reinstall + over a service on `--port 9000` used to put it back on 7233. It now keeps the + installed unit's port, host, data dir and verbosity unless a flag says + otherwise, which in 0.82 only `--refresh` did. A first install that systemd or + launchd refuses no longer leaves its unit behind. + +- **`service install --dry-run` prints the unit and writes nothing**, not even a + folder. The unit goes to stdout and where it would go to stderr, so + `paddock service install --dry-run > paddock.service` captures the unit alone. + +- **For scripts: `--json` on every service action, and `serve --quiet`.** + `install`, `uninstall`, `start`, `stop` and `restart` take `--json` and print + one document, `{ ok, action, error?, … }`, with the same fields as + `status --json` as they are afterwards, and all prose on stderr. The exit + codes don't change. `paddock serve --quiet` (`-q`) prints only + `Paddock : `. A flag a command can't act on, such as `--json` on + `serve`, `service logs` or `config eject`, now exits 2 rather than being + accepted and ignored. + +Every command and flag is now on one page: the [CLI reference](/reference/cli/). + +## 0.82 — `paddock update` + +- **`paddock update` installs a newer Paddock, and puts the old one back if the + new one doesn't start.** Updating a service used to be `npm i -g`, then + remembering to restart it. Now it's one command. It checks Paddock isn't busy + before stopping anything, asks you, downloads the new version while the old + one is still serving, stops the service, installs, and waits until + `/api/health` reports the new version. If it never does, `update` reinstalls + the old version and exits 6. If the old one doesn't come back either, it exits + 7 and prints the commands to run by hand. + + ``` + paddock update update to the latest release, asking first + paddock update --check [--json] what a new version would be; changes nothing + paddock update --to 0.79.1 a version — the only way to go BACK + paddock update --to next a dist-tag + paddock update --yes do not ask (required with no terminal) + paddock update --force skip the busy check, and nothing else + ``` + + The whole sequence is on [Updating](/guides/updating/). Run it from a + terminal: a Paddock chat that runs it is itself one of the turns the busy + check counts. + +- **An install that isn't Paddock's to replace says what would work.** A Docker + container, npx, a git checkout, a dependency of another project, a yarn + classic global or a global folder you can't write to exits 5 and prints the + right command. That includes a `sudo` line, which Paddock never runs itself. + Set `PADDOCK_UPDATE_HINT` for an install something else manages, and `update` + prints that instead. A global npm, pnpm, bun or volta install updates in place. + +- **The image puts `paddock` on `PATH`.** `docker exec paddock + update --check` names the image to pull, and `paddock busy` there is what + lets Watchtower's pre-update hook wait for a quiet moment. + +- **Nothing checks for updates on its own**: not the server, not at startup, + not in the background. The registry is asked only when you run `update`. + `service status` repeats what the last `update --check` found. + +- **`paddock service install --refresh`** re-writes the unit from the settings + the installed one records (its port, host, data dir and verbosity) rather than + from the shell you happen to run it in. With nothing installed it exits 4. On + Linux, a reinstall now restarts the service onto the new unit, where before + it left the old process serving. + +- **`update` with no terminal exits 2 unless you give `--yes`**, rather than + guessing. `--force`, `--check`, `--to`, `--yes` and `--refresh` on a command + that can't act on them exit 2 too. + +- **0.82.1: steadier `update` and `service`**, now running on the shared code + from the [CLI contract](https://github.com/edspencer/cli-contract). The + "is available" notice goes to stderr, so a script should read + `updateAvailable` from `update --check --json`. `update` waits for the old + version to stop answering before it installs, and `service stop` on macOS + waits for launchd to finish, so a `start` straight after it doesn't race it. + `service start` and `restart` clear systemd's failed state first, so a unit + that hit the start limit comes back. Exit codes are unchanged. + +## 0.81 — A stop that won't cut a turn off + +- **`paddock service stop` and `restart` refuse while Paddock is busy.** Busy + means a chat turn running (yours, a trigger's or a cron fire's), a background + task a live session still holds, or a scheduled job. A restart kills a turn + mid-sentence, and the turn can't pick up where it was. So they exit 75 and say + what's running. `--force` goes ahead, printing the same message prefixed + `Overriding:`. **A script that stops Paddock unconditionally needs `--force`, + or needs to handle 75.** `start` and `uninstall` don't ask. + + ``` + paddock: Paddock is busy: 1 chat turn is running. Run it from a terminal, not from inside + a Paddock chat. + ``` + + That last sentence is there because a chat that runs the command counts as + one of the turns, and `--force` from there would stop the service running the + chat. + +- **`paddock busy` asks the same question on its own**: exit 0 not busy, 75 + busy, 3 nothing running, and `--json` for the counts. 75 is also the code + Watchtower's pre-update hook reads as "skip this one", so labelling a + container `com.centurylinklabs.watchtower.lifecycle.pre-update: paddock busy` + makes an image update wait for a quiet moment. Over HTTP it's + `GET /api/busy`, which needs no authentication because it carries counts and + nothing else: no chat title, session or project name. + +- **Stopping Paddock takes 15 seconds at most**, inside launchd's 20-second + kill budget. An open WebSocket could make it overrun before. A second Ctrl-C + or `SIGTERM` no longer starts a second shutdown, and the log says how many + chat turns were cut short. + +- **Fixed: on macOS, `service install` and `restart` could stop Paddock and not + start it again**, exiting 1 with `Bootstrap failed: 5: Input/output error`. + They raced launchd's teardown of the old job. They now wait for it to go, and + retry launchd's two "still busy" errors. + +## 0.80 — A command line scripts can rely on + +- **`paddock serve` runs Paddock in the foreground.** `paddock start` stays as an + alias for good, since every installed unit names it, and a bare `paddock` + still does the same. The first line on stdout is now always + `Paddock : `. The server's logs and the first-run welcome moved + to stderr, so a machine with no Claude login no longer prints a warning ahead + of it. A log shipper that collects stdout alone is the one thing that changes. + +- **Exit codes say what happened.** A typo (an unknown command or flag, or a bad + value) now exits **2**, not 1, and prints the usage after the message, so `1` + means only that something failed. `service status` exits **0** installed, + running and answering, **3** installed but not running or not answering, and + **4** not installed: the codes `systemctl status` uses. An `install`, `start` + or `restart` that never answers exits 1, where it used to print a caveat and + exit 0. All of them are in the [CLI reference](/reference/cli/#exit-codes). + +- **`paddock service status --json`** reports installed, running and answering, + the **installed and running versions**, the port, URL, pid, unit, log and any + warnings. `status` also warns when the Node a unit runs has gone, and when the + running version isn't the installed one. + +- **`paddock service logs [-f] [-n ]`, and on Linux the log is a file.** + Both platforms now write both streams to `/logs/service.log`, which + Paddock rotates at 8 MB, keeping three older ones. `journalctl --user -u + paddock.service` has nothing in it any more. An existing unit keeps the path it + names until you run `paddock service install` again. + +- **Service units survive your Node version manager.** The unit names Node by + its real path (an fnm path died with the terminal that installed it), leaves + per-session entries out of the `PATH` it records, and quotes every + `ExecStart` word, so a data dir with a space in it works. On Linux, `install` + and `status` check whether linger is on rather than telling everyone to turn + it on. + +- **`GET /api/health` reports the version**, `{ ok, version }`, with no + authentication. + ## 0.79.1 — Stop, then say something else - **Stop followed by a new message now starts straight away.** Stopping a