@usepowerplant/cli 0.3.0

package/README.md

@@ -0,0 +1,169 @@
+# @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.
+
+Requires Node 20 or newer.
+
+## Get started
+
+```bash
+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. The machine's credential is stored in the macOS
+   keychain; on other platforms, in 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 before reading
+   Git metadata there; declining leaves those sessions local. The service
+   starts on login and keeps itself running.
+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.
+
+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.
+
+## 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 today. 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
+
+```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 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
+powerplant disconnect # remove the Powerplant MCP (and its sign-in) from your agents
+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
+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
+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.
+
+## Updating
+
+```bash
+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.
+
+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:
+
+```bash
+npm uninstall -g @powerplant-sh/cli
+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.
+
+## Uninstalling
+
+```bash
+powerplant disconnect          # disconnect your coding agents from Powerplant
+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.
+
+## 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.
+
+## 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).