@usepowerplant/cli 0.4.15 → 0.4.17

package/README.md

@@ -6,9 +6,7 @@ Rule: docs/desktop-engineering-rules.md, "Releases".
 
 # @usepowerplant/cli
 
-Set up a machine for [Powerplant](https://powerplant.sh): enroll it into
-your org, run the session sync service in the background, and connect your
-coding agents so they can read your team's work.
+Set up a machine for [Powerplant](https://powerplant.sh): enroll it into your org, run the session sync service in the background, and connect your coding agents so they can read your team's work.
 
 Requires Node 20 or newer.
 
@@ -19,75 +17,23 @@ npm install -g @usepowerplant/cli
 powerplant init
 ```
 
-`powerplant init` is one setup pass with three steps, and it is safe to
-re-run at any time — finished steps are skipped with a note:
-
-1. **Enroll this machine.** Your browser opens so you can approve the
-   machine into your org. On macOS, the credential is encrypted in a local
-   file with its key in Keychain; other platforms use a file only your user
-   can read.
-2. **Install the background service.** The sync service watches your local
-   coding-agent sessions (Claude Code, Codex, and Cursor) and uploads the
-   ones in scope. If recent sessions name repositories under a macOS-protected
-   location such as Documents, init lists the location and asks once before
-   reading Git metadata there; declining leaves those sessions local, and a
-   yes covers locations that appear later (init still explains before macOS
-   asks). A location macOS refused is re-checked on every init until you
-   enable it in System Settings. The service
-   starts on login and keeps itself running. On macOS, init also installs
-   the Powerplant menu bar app from this package into `~/Applications` and
-   launches it; the app registers itself to start at login (turn that off
-   from its More menu), and the background service keeps it on the same
-   version as the CLI after every update.
-3. **Add MCP to your agents.** Init lists the agents it found — Claude Code,
-   Codex, and Cursor — as checked boxes. They all start selected; use the arrow
-   keys and Space to turn off any you want to skip, then press Enter (`--yes`,
-   or running without a terminal, adds MCP to everything without asking).
-   Each selected agent is pointed at the Powerplant MCP server and signed in:
-   for Claude Code and Codex the sign-in opens a browser window; for Cursor,
-   the Cursor app opens so you can approve the Powerplant server and sign in
-   there. This is how your agents read
-   the team's sessions, review rooms, and search. If you skip or cancel
-   a sign-in, nothing breaks: finish later with `powerplant connect`
-   (add `--client claude|codex|cursor` for just those — repeatable). Each
-   agent's own sign-in output prints as it runs. Connect supports Claude Code
-   2.1.186, Codex 0.134.0, and Cursor 3.4 or newer; an older installation is
-   reported with an update hint and, when the machine holds another copy of
-   the same agent, that copy is tried instead.
-
-The background service is macOS-only today. On other platforms, init still
-enrolls the machine and adds MCP to your agents, and points you at running
-`powerplant sync` on a schedule instead.
+`powerplant init` is one setup pass with three steps, and it is safe to re-run at any time — finished steps are skipped with a note:
+
+1. **Enroll this machine.** Your browser opens so you can approve the machine into your org. On macOS, the credential is encrypted in a local file with its key in Keychain; other platforms use a file only your user can read.
+2. **Install the background service.** The sync service watches your local coding-agent sessions (Claude Code, Codex, and Cursor) and uploads the ones in scope. If recent sessions name repositories under a macOS-protected location such as Documents, init lists the location and asks once before reading Git metadata there; declining leaves those sessions local, and a yes covers locations that appear later (init still explains before macOS asks). A location macOS refused is re-checked on every init until you enable it in System Settings. The service starts on login and keeps itself running. On macOS, init also installs the Powerplant menu bar app from this package into `~/Applications` and launches it; the app registers itself to start at login (turn that off from its More menu), and the background service keeps it on the same version as the CLI after every update.
+3. **Add MCP to your agents.** Init lists the agents it found — Claude Code, Codex, and Cursor — as checked boxes. They all start selected; use the arrow keys and Space to turn off any you want to skip, then press Enter (`--yes`, or running without a terminal, adds MCP to everything without asking). Each selected agent is pointed at the Powerplant MCP server and signed in: for Claude Code and Codex the sign-in opens a browser window; for Cursor, the Cursor app opens so you can approve the Powerplant server and sign in there. This is how your agents read the team's sessions, review rooms, and search. If you skip or cancel a sign-in, nothing breaks: finish later with `powerplant connect` (add `--client claude|codex|cursor` for just those — repeatable). Each agent's own sign-in output prints as it runs. Connect supports Claude Code 2.1.186, Codex 0.134.0, and Cursor 3.4 or newer; an older installation is reported with an update hint and, when the machine holds another copy of the same agent, that copy is tried instead.
+
+The background service is macOS-only today. On other platforms, init still enrolls the machine and adds MCP to your agents, and points you at running `powerplant sync` on a schedule instead.
 
 ## What gets uploaded
 
-By default, only sessions in repos your org's sync policy allows (the
-repos it chose in Settings, or its GitHub-owned repos until it chooses) are
-uploaded; everything else stays on your machine. Transcripts are redacted
-on your machine before upload. To narrow further, enroll with
-`--scope <path>` (repeatable) to sync only sessions under given
-directories; `powerplant folders add <path>` opts in extra folders later.
-Allowing Git metadata discovery in a macOS-protected location does not opt
-the folder into syncing; the org's repo policy still applies. There is no
-sync-everything option.
+By default, only sessions in repos your org's sync policy allows (the repos it chose in Settings, or its GitHub-owned repos until it chooses) are uploaded; everything else stays on your machine. Transcripts are redacted on your machine before upload. To narrow further, enroll with `--scope <path>` (repeatable) to sync only sessions under given directories; `powerplant folders add <path>` opts in extra folders later. Allowing Git metadata discovery in a macOS-protected location does not opt the folder into syncing; the org's repo policy still applies. There is no sync-everything option.
 
 ## Error reporting
 
-When the CLI itself hits a bug — a crash or an unexpected error — it sends
-an error report to [Sentry](https://sentry.io) so we can fix the problem
-without asking you to dig through logs. This is on by default, and there
-is no setting to turn it off for free users. Paid users can arrange an opt-out
-through [support](mailto:support@forestwalk.ai). A report contains the error and its
-stack trace, the CLI version and environment, which enrolled machine and
-org the background service belongs to, and diagnostic details such as ids
-and counts. It never contains session transcripts, code, or file contents,
-and secret-shaped values (tokens, keys, passwords) are removed on your
-machine before the report is sent. Errors whose fix is printed on screen
-(like "run `powerplant enroll` first") are not reported at all.
-
-If sending error reports is a problem for your machine or org, email
-[support@forestwalk.ai](mailto:support@forestwalk.ai) and we'll work
-something out.
+When the CLI itself hits a bug — a crash or an unexpected error — it sends an error report to [Sentry](https://sentry.io) so we can fix the problem without asking you to dig through logs. This is on by default, and there is no setting to turn it off for free users. Paid users can arrange an opt-out through [support](mailto:support@forestwalk.ai). A report contains the error and its stack trace, the CLI version and environment, which enrolled machine and org the background service belongs to, and diagnostic details such as ids and counts. It never contains session transcripts, code, or file contents, and secret-shaped values (tokens, keys, passwords) are removed on your machine before the report is sent. Errors whose fix is printed on screen (like "run `powerplant enroll` first") are not reported at all.
+
+If sending error reports is a problem for your machine or org, email [support@forestwalk.ai](mailto:support@forestwalk.ai) and we'll work something out.
 
 ## Day to day
 
@@ -102,19 +48,7 @@ powerplant disconnect # remove the Powerplant MCP (and its sign-in) from your ag
 powerplant sync       # run one upload pass now, in the foreground
 ```
 
-`status` tells you whether the machine is enrolled, whether the service is
-running, when it last uploaded, and what (if anything) is failing — with the
-command that fixes it. `pause` is safe for as long as you need: the background
-service uploads nothing while paused, every later command reminds you, `init`
-offers to resume, and `resume` goes back and covers everything the pause
-skipped. `sync` is the manual alternative to the background service — the
-day-to-day upload path on machines that can't run it; asked for explicitly, it
-still runs while paused and says so. `disconnect` is the
-inverse of `connect`: it removes each agent's Powerplant MCP entry and the
-sign-in stored with it, and agents that were never connected just say so.
-Use `powerplant disconnect --client claude` to remove only Claude's connection.
-The `--client` option also accepts `codex` and `cursor`, and can be repeated.
-Omitting it disconnects all detected agents.
+`status` tells you whether the machine is enrolled, whether the service is running, when it last uploaded, and what (if anything) is failing — with the command that fixes it. `pause` is safe for as long as you need: the background service uploads nothing while paused, every later command reminds you, `init` offers to resume, and `resume` goes back and covers everything the pause skipped. `sync` is the manual alternative to the background service — the day-to-day upload path on machines that can't run it; asked for explicitly, it still runs while paused and says so. `disconnect` is the inverse of `connect`: it removes each agent's Powerplant MCP entry and the sign-in stored with it, and agents that were never connected just say so. Use `powerplant disconnect --client claude` to remove only Claude's connection. The `--client` option also accepts `codex` and `cursor`, and can be repeated. Omitting it disconnects all detected agents.
 
 ## Updating
 
@@ -122,51 +56,17 @@ Omitting it disconnects all detected agents.
 powerplant update
 ```
 
-That reinstalls `@usepowerplant/cli` with whichever package manager put it
-on this machine (npm, pnpm, bun, or yarn), so the copy that is running is the
-copy that gets replaced, then restarts the background sync onto the new
-version. When this machine already has the newest version available to it,
-`update` says so and changes nothing. Running the manager's own global
-install yourself works too: the service notices the new version on disk and
-restarts itself within moments.
-When the install can't be replaced this way (a folder only an administrator
-can write, or a layout the CLI doesn't recognise), `update` says why and
-prints the command to run instead. `powerplant status` tells you when a
-newer version is available, and the menu bar app offers the update as one
-click; it runs in the background and the menu shows its progress.
-
-`powerplant init` asks once whether to keep the CLI up to date
-automatically (yes is the default at the prompt, and a non-interactive
-init says it took that default). With that on, the background sync checks
-the registry hourly (and at boot) and installs a new release the same way,
-then restarts itself onto it. The choice is per machine and only an
-explicit yes counts: a machine set up before the question existed stays
-off until someone turns it on. `powerplant status` and `powerplant doctor`
-report the current choice, and `powerplant update --automatic on` or
-`--automatic off`, or the menu bar's More menu, change it. Turning it on
-(there, or at init's question) makes the sync check within seconds, so a
-release already out installs now rather than at the next hourly check. A
-release that fails to install is not retried by itself; the menu bar shows
-the failure with a retry and the update log, and the next release clears it.
-The one exception is a registry that does not serve the release yet (npm's
-cache can lag a publish by a few minutes): the sync tries that release
-again on its next hourly checks, up to three times, and the menu says so.
-
-Powerplant offers your machine a release only after the team has tested
-it, so the version it offers can be older than the newest version listed on
-npm. Powerplant never offers or automatically installs a version older
-than the one you have.
-
-Powerplant also publishes the oldest version it still supports. When yours
-is older, `powerplant status`, `powerplant doctor`, the menu bar app, and
-the sync service log all say so and point you at `powerplant update`. Nothing
-stops working on that notice — an unsupported version keeps syncing, but
-it is no longer tested or fixed, so update when you see it.
+That reinstalls `@usepowerplant/cli` with whichever package manager put it on this machine (npm, pnpm, bun, or yarn), so the copy that is running is the copy that gets replaced, then restarts the background sync onto the new version. When this machine already has the newest version available to it, `update` says so and changes nothing. Running the manager's own global install yourself works too: the service notices the new version on disk and restarts itself within moments. When the install can't be replaced this way (a folder only an administrator can write, or a layout the CLI doesn't recognise), `update` says why and prints the command to run instead. `powerplant status` tells you when a newer version is available, and the menu bar app offers the update as one click; it runs in the background and the menu shows its progress.
+
+`powerplant init` asks once whether to keep the CLI up to date automatically (yes is the default at the prompt, and a non-interactive init says it took that default). With that on, the background sync checks the registry hourly (and at boot) and installs a new release the same way, then restarts itself onto it. The choice is per machine and only an explicit yes counts: a machine set up before the question existed stays off until someone turns it on. `powerplant status` and `powerplant doctor` report the current choice, and `powerplant update --automatic on` or `--automatic off`, or the menu bar's More menu, change it. Turning it on (there, or at init's question) makes the sync check within seconds, so a release already out installs now rather than at the next hourly check. A release that fails to install is not retried by itself; the menu bar shows the failure with a retry and the update log, and the next release clears it. The one exception is a registry that does not serve the release yet (npm's cache can lag a publish by a few minutes): the sync tries that release again on its next hourly checks, up to three times, and the menu says so.
+
+Powerplant offers your machine a release only after the team has tested it, so the version it offers can be older than the newest version listed on npm. Powerplant never offers or automatically installs a version older than the one you have.
+
+Powerplant also publishes the oldest version it still supports. When yours is older, `powerplant status`, `powerplant doctor`, the menu bar app, and the sync service log all say so and point you at `powerplant update`. Nothing stops working on that notice — an unsupported version keeps syncing, but it is no longer tested or fixed, so update when you see it.
 
 ### Moving from @powerplant-sh/cli
 
-Releases up to 0.2.1 were published as `@powerplant-sh/cli`. That package
-cannot update itself onto this one, so switch by hand:
+Releases up to 0.2.1 were published as `@powerplant-sh/cli`. That package cannot update itself onto this one, so switch by hand:
 
 ```bash
 npm uninstall -g @powerplant-sh/cli
@@ -174,11 +74,7 @@ npm install -g @usepowerplant/cli
 powerplant init
 ```
 
-The uninstall comes first: both packages provide the `powerplant` command,
-and npm refuses to install a second package over an existing one. Enrollment,
-connections, and settings are untouched — `powerplant init` only sees that
-the sync service points at the removed bundle and reinstalls it onto the new
-one.
+The uninstall comes first: both packages provide the `powerplant` command, and npm refuses to install a second package over an existing one. Enrollment, connections, and settings are untouched — `powerplant init` only sees that the sync service points at the removed bundle and reinstalls it onto the new one.
 
 ## Uninstalling
 
@@ -188,35 +84,18 @@ powerplant uninstall           # remove the background service
 powerplant uninstall --forget  # also delete this machine's stored credentials
 ```
 
-`uninstall` removes the background service only — your coding agents keep
-their Powerplant MCP connection until you run `powerplant disconnect` (and
-uninstall reminds you when that's the case). Disconnecting is local to this
-machine: the access you granted the agents stays on your Powerplant account
-until you revoke it from your Profile page in the web app.
+`uninstall` removes the background service only — your coding agents keep their Powerplant MCP connection until you run `powerplant disconnect` (and uninstall reminds you when that's the case). Disconnecting is local to this machine: the access you granted the agents stays on your Powerplant account until you revoke it from your Profile page in the web app.
 
 ## Troubleshooting
 
-- **`status` says "not enrolled"** — run `powerplant init` (or
-  `powerplant enroll` to redo just the enrollment).
-- **`status` says the service is installed but not loaded, or a daemon is
-  stalled** — run `powerplant restart`.
-- **An agent's sign-in was cancelled or expired** — run
-  `powerplant connect`; it skips agents that are already signed in and only
-  finishes what's missing.
-- **A deprecation warning prints on every command under Node 20** — it
-  comes from a dependency and is harmless; Node 22 or newer doesn't print
-  it.
-- **None of that fixed it** — run `powerplant doctor` and paste its output
-  into an email to [support@forestwalk.ai](mailto:support@forestwalk.ai).
-  It prints a diagnostics summary (status plus the tail of the sync service's
-  log with credentials redacted) and uploads nothing — you choose what to
-  share.
-
-The CLI is Powerplant's connector and installer only; agents read Powerplant
-through its MCP server, never through this command.
+- **`status` says "not enrolled"** — run `powerplant init` (or `powerplant enroll` to redo just the enrollment).
+- **`status` says the service is installed but not loaded, or a daemon is stalled** — run `powerplant restart`.
+- **An agent's sign-in was cancelled or expired** — run `powerplant connect`; it skips agents that are already signed in and only finishes what's missing.
+- **A deprecation warning prints on every command under Node 20** — it comes from a dependency and is harmless; Node 22 or newer doesn't print it.
+- **None of that fixed it** — run `powerplant doctor` and paste its output into an email to [support@forestwalk.ai](mailto:support@forestwalk.ai). It prints a diagnostics summary (status plus the tail of the sync service's log with credentials redacted) and uploads nothing — you choose what to share.
+
+The CLI is Powerplant's connector and installer only; agents read Powerplant through its MCP server, never through this command.
 
 ## About this package
 
-Powerplant's source code is private today, so this package carries no
-repository link — it ships the compiled CLI only. Questions or problems:
-[support@forestwalk.ai](mailto:support@forestwalk.ai).
+Powerplant's source code is private today, so this package carries no repository link — it ships the compiled CLI only. Questions or problems: [support@forestwalk.ai](mailto:support@forestwalk.ai).