@revturbine/cli 0.19.5 → 0.21.0

package/README.md

@@ -37,7 +37,7 @@ Requires Node ≥ 22.13. Source builds use the npm 11.18.0 version declared in
 ## Quick start
 
 ```bash
-revturbine signup                             # create an account (email + password + emailed code)
+revturbine signup                             # create an operator login (email + password + emailed code)
 revturbine login                              # authorize this machine (device flow)
 revturbine download --live --save ./revturbine.playbook.json
 # …edit ./revturbine.playbook.json…
@@ -48,6 +48,48 @@ revturbine launch ./revturbine.playbook.json               # upload, gate, and g
 
 `revturbine <command> --help` documents every flag.
 
+## Customer application provisioning with Clerk Billing
+
+`signup` creates a RevTurbine operator login. `customer-accounts` and
+`customer-users` create records for **your application's customers**. They never
+create operator logins. A customer account can represent a Clerk organization or
+a personal Clerk user; a customer user represents an application user.
+
+The `customer-accounts`, `customer-users`, `plans`, and `plan-variations` groups
+each provide `create <file>`, `list`, `get <key>`, `link <key> <file>`, and
+`links <key>`. Use `--json` for automation and `list --all` to follow all pages
+(`--page`, `--per-page`, maximum 100). Every command accepts `--url` and
+`--tenant-id` using the existing operator credentials.
+
+Catalog commands require `--environment <handle>` (for example `production`, never the environment database row ID) and exactly one of `--draft`,
+`--live`, or `--release <id>`. Creates accept only `--draft` and do not launch.
+Links additionally require `--provider-instance <Clerk-instance-id>`; identity
+links have no Playbook selector. Keys are your application IDs or stable catalog
+handles, never version-row IDs. Catalog reads use the selected environment's
+draft or frozen release and return 404 if that version is absent.
+Operators can disable this endpoint family with the `customer-provisioning`
+feature flag in the admin UI; disabled endpoints return 503. It defaults to enabled.
+
+Clerk Billing manages its plans, prices, and subscriptions; these are not Stripe
+Billing catalog records. Use Clerk's CLI/API or dashboard to provision those
+entities, then record their IDs in RevTurbine. Stripe CLI is optional for payment
+inspection. RevTurbine stores manually authored price snapshots with
+`price_source: "clerk"`, monthly/annual billing, and no `stripe_price_id`.
+See [Clerk Billing overview](https://clerk.com/docs/guides/billing/overview),
+[Clerk CLI](https://clerk.com/docs/cli), and the
+[PowerShell walkthrough](docs/clerk-customer-provisioning.md).
+
+Links are scoped to tenant, environment, and Clerk instance and are always
+`unverified`. Recording an ID does not contact Clerk, create a subscription,
+prove payment, or grant entitlements. Exact account/user/link retries return
+the existing record; conflicting associations return 409. Existing user context
+fields are preserved. Rebinding and unlinking are not supported.
+
+Catalog creates can mint handles. If a response is lost, the CLI does not retry:
+list the selected draft and reconcile the returned handles before another
+create. Links survive catalog version changes, but reads revalidate the selected
+target: missing/discarded targets return 404 and incompatible prices return 409.
+
 ## Version selectors
 
 Commands that read a config name the version explicitly — there is no default:
@@ -64,14 +106,14 @@ Commands that read a config name the version explicitly — there is no default:
 | Command | What it does |
 |---|---|
 | `init` (alias `create`) | Set up RevTurbine while preserving existing integrations: install missing packages, pin the CLI exactly, create a starter for a fresh integration, and install skills for one agent. Use `--scaffold` to create a missing root starter explicitly; existing files are never overwritten. `--agent claude-code\|cursor\|codex` overrides environment detection; an unknown agent skips skills and prints the selection command. Also supports `--dir`, `--dry-run`, `--no-skills`, `--json`. With no `package.json`, offers a new project (`--yes` for noninteractive creation). Runs the invoked CLI even inside a repo that pins a different one. |
-| `signup` | Create an account headlessly: email + password, then an emailed one-time code to verify, then a token is stored. |
-| `login` / `logout` | Device-flow auth; tokens stored at `~/.revturbine/credentials.json` (mode 0600). |
-| `whoami` | Authentication state first: not logged in, credentials accepted, credentials rejected for the selected instance/tenant, or verification unavailable. Then shows instance, tenant, and credentials source; configured tenant information alone does not prove login. Verification and subsequent telemetry each time out after 3 seconds. Status reports exit 0. `--json` retains its seven fields: `instance`, `tenant`, `tenant_source`, `credentials_dir`, `credentials_source`, `token_present` (boolean), and `token_valid` (`true` for 2xx, `false` for 401/403, `null` when absent or unverified, including redirects, other HTTP errors, timeouts and network failures). |
+| `signup` | Create a RevTurbine operator login headlessly: email + password, then an emailed one-time code to verify, then a token is stored. |
+| `login` / `logout` | Device-flow auth; tokens stored at `~/.revturbine/credentials.json` (mode 0600). For CI, skip login and set `REVTURBINE_TOKEN` (see [CI / non-interactive use](#ci--non-interactive-use)). |
+| `whoami` | Authentication state first: not logged in, credentials accepted, credentials rejected for the selected instance/tenant, or verification unavailable. Then shows instance, tenant, and credentials source; configured tenant information alone does not prove login. Verification and subsequent telemetry each time out after 3 seconds. Status reports exit 0. `--json` retains its seven fields: `instance`, `tenant` (`null` when `REVTURBINE_TOKEN` is set without `-t`: the server resolves the token user's own tenant, and `tenant_source` names the variable), `tenant_source`, `credentials_dir`, `credentials_source`, `token_present` (boolean), and `token_valid` (`true` for 2xx, `false` for 401/403, `null` when absent or unverified, including redirects, other HTTP errors, timeouts and network failures). |
 | `schema` | Emit the bundled `RevTurbineConfig` JSON schema (for agents to author against). |
 | `docs` | Print the canonical documentation URL. |
 | `download` | Fetch a config version (`--live` / `--draft` / `--release <id>`); `--save`. |
 | `validate` | Offline schema validation of a `<file>`, or the full server catalog against the open draft (`--draft`). |
-| `diff` | Compare any two versions (dry-run, no writes). A file vs `--draft`/`--live`/`--release` previews the launch — the server side is the base, so `+`/`-` read as created/pruned on launch. |
+| `diff` | Compare any two versions (dry-run, no writes). A file vs `--draft`/`--live`/`--release` previews the launch — the server side is the base, so `+`/`-` read as created/pruned on launch. `--exit-code` makes the status machine-readable: `0` no differences, `1` differences, anything else an error (an unexpected internal error exits `70` so `1` always means "differences"). Every top-level Playbook collection is compared. |
 | `show <kind>` | Summary tables: `plans` · `entitlements` · `segments` · `placements` · `trials` for any version. |
 | `upload` | Stage a Playbook file as the open draft. |
 | `launch` | Take a config live: validate (launch gate) → submit → approve → deploy. `launch <file>` or `launch --draft`. |
@@ -145,6 +187,33 @@ Public ingest tokens are intentionally embeddable but remain tenant-bound,
 origin-restricted, and optionally IP-restricted. They cannot mint other tokens
 or access private control-plane APIs.
 
+## CI / non-interactive use
+
+`login` and `signup` are interactive. In CI, supply the token through the
+environment instead:
+
+| Variable | Meaning |
+|---|---|
+| `REVTURBINE_TOKEN` | Bearer token for every request. Wins over any stored credential (which is then ignored). With it set and no `-t/--tenant-id`, **no `x-tenant-id` header is sent** and the server resolves the token user's own tenant; `-t` still sends one (it must be that tenant). |
+| `REVTURBINE_HTTP_HEADERS` | A JSON object of extra headers added to every request to the RevTurbine instance, e.g. `{"x-vercel-protection-bypass":"…"}` to reach a protection-gated preview/staging deployment. It may not set `Authorization`, `x-tenant-id`, `x-rt-tenant-id` or `Content-Type`. A malformed value exits `2`. |
+
+Neither the token nor any header value is ever logged, echoed in an error, or
+sent as telemetry: diagnostics name only the variable and the header names, and
+any stderr line that would contain a registered secret shows `<redacted>`.
+
+```bash
+export REVTURBINE_TOKEN="$RT_TOKEN"
+export REVTURBINE_HTTP_HEADERS="{\"x-vercel-protection-bypass\":\"$VERCEL_BYPASS\"}"
+URL=https://staging.example.com/app
+if revturbine diff ./seed.playbook.json --live --url "$URL" --exit-code; then
+  echo "no changes: skip launch"
+else
+  status=$?
+  [ "$status" -eq 1 ] || exit "$status"   # 2-7 / 70 = a real error
+  revturbine launch ./seed.playbook.json --url "$URL"
+fi
+```
+
 ## Exit-code classes
 
 ```
@@ -158,6 +227,9 @@ or access private control-plane APIs.
 7  server error
 ```
 
+`diff --exit-code` is the one exception: `1` means "differences" there, and an
+unexpected internal error exits `70` instead.
+
 ## Schema validation
 
 Validation is **mandatory** and runs fully offline against a vendored,