@usepowerplant/cli 0.4.3 → 0.4.5

package/README.md

@@ -24,7 +24,11 @@ re-run at any time — finished steps are skipped with a note:
    ones in scope. If recent sessions name repositories under a macOS-protected
    location such as Documents, init lists the location and asks before reading
    Git metadata there; declining leaves those sessions local. The service
-   starts on login and keeps itself running.
+   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`,
@@ -36,7 +40,10 @@ re-run at any time — finished steps are skipped with a note:
    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.
+   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
@@ -59,7 +66,8 @@ sync-everything option.
 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 today. A report contains the error and its
+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,
@@ -76,7 +84,7 @@ something out.
 ```bash
 powerplant status     # what the sync service is doing (add --json for tools)
 powerplant doctor     # a diagnostics summary to paste into a support email
-powerplant pause      # stop uploads without uninstalling
+powerplant pause      # stop background uploads without uninstalling
 powerplant resume     # start again — a catch-up pass covers the pause
 powerplant restart    # restart the background service
 powerplant connect    # connect agents installed after setup, or re-sign-in
@@ -86,12 +94,17 @@ 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: nothing
-uploads while paused, and `resume` goes back and covers everything the pause
+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. `disconnect` is 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
 
@@ -99,10 +112,28 @@ sign-in stored with it, and agents that were never connected just say so.
 powerplant update
 ```
 
-That runs `npm install -g @usepowerplant/cli` for you (running it yourself
-works too). Either way, the background service notices the new version on
-disk and restarts itself onto it within moments. `powerplant status` tells
-you when a newer version is available.
+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. 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. 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.
 
 Powerplant also publishes the oldest version it still supports. When yours
 is older, `powerplant status`, `powerplant doctor`, the menu bar app, and
@@ -110,6 +141,50 @@ 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.
 
+### How a release reaches production
+
+Every release is published to npm's `next` dist-tag. Machines pinned to
+the staging environment (and our own development and agent machines)
+follow `next`, so a release runs on our own machines first. Production
+machines never follow npm: they ask the production API which version is
+promoted and install exactly that, pinned. When a release has held up on
+staging, dispatch the Promote CLI workflow (leave the version blank to
+promote what `next` points at) with a current one-time code for the
+`forestwalklabs` npm account from 1Password: it moves npm's `latest` to
+the same artifact staging tested, so a fresh `npm install -g` always gets
+exactly what production runs, and points production machines at it;
+machines with automatic updates install it within the hour, and everyone
+else sees it in the menu bar and `powerplant status`. Until something is
+promoted, production sees no update at all, only the supported-version
+floor. Promoting an older version than the current one is a hold:
+production stops advancing, `latest` moves back for new installs, and no
+enrolled machine downgrades. A bad release is undone by a new release and
+a new promotion.
+
+### Staging beside production on one Mac
+
+A machine has one global `powerplant` by default, and the background sync
+for each environment runs whatever copy `init` was run from. To try
+releases on staging while production keeps the promoted version, give
+staging its own copy under its own npm prefix and set it up from there:
+
+```bash
+npm install -g --prefix ~/.powerplant-staging @usepowerplant/cli@next
+~/.powerplant-staging/bin/powerplant init --env staging
+```
+
+The `@next` pin matters: a bare install resolves `latest`, the production
+channel, so the new staging copy would start on the promoted release and
+test nothing until its first update.
+
+The staging daemon runs that copy and updates it in place (the updater
+pins npm to the prefix the running copy lives under), so
+`~/.powerplant-staging` follows the `next` channel while the production
+install follows the promoted one. Run staging commands through that path,
+`~/.powerplant-staging/bin/powerplant status --env staging`, or put the
+directory on your PATH after the production one. `powerplant doctor` names
+the install it is running from.
+
 ### Moving from @powerplant-sh/cli
 
 Releases up to 0.2.1 were published as `@powerplant-sh/cli`. That package