@farthershore/cli 0.33.5 → 0.34.0

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.33.5`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.34.0`.** Pre-1.0 — the command surface is stable but may still
 change between minor versions. Pin an exact version in CI.
 
 FartherShore lets you define a software business as code, then sells, meters,
@@ -21,19 +21,19 @@ the explicitly agent-operable subset of the CLI surface.
 ## Install
 
 ```bash
-npm install -g @farthershore/cli@0.33.5
+npm install -g @farthershore/cli@0.34.0
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx -p @farthershore/cli@0.33.5 farthershore --help
+npx -p @farthershore/cli@0.34.0 farthershore --help
 ```
 
 The package also ships an MCP stdio server for agents:
 
 ```bash
-npx -p @farthershore/cli@0.33.5 farthershore-mcp
+npx -p @farthershore/cli@0.34.0 farthershore-mcp
 ```
 
 ## Authentication
@@ -87,12 +87,11 @@ credentials into the managed repository.
 Create a managed business repo, author the business, validate it, and push:
 
 ```bash
-# 1. Create the managed repo. Human output is exactly its URL.
-REPO_URL=$(farthershore business create weather-api \
-  --idempotency-key <persisted-business-create-attempt-key>)
+# 1. Create the managed repo. The command prints its URL.
+farthershore business create weather-api
 
 # 2. Clone it and author business/ from scratch.
-git clone "$REPO_URL"
+git clone <printed-repository-url>
 cd weather-api
 # ...author business/ with @farthershore/business...
 
@@ -246,9 +245,8 @@ Run the same verdict the GitHub `farthershore/validate` PR check produces, befor
 you push. It builds the manifest twice and compares the IR hash (the determinism
 check the build runner enforces), then — when you pass `--business` — submits the
 IR for a server verdict that returns compile diagnostics, the semantic diff, and
-an economic-change verdict. The server may retain a diagnostic compilation
-record, but validation never accepts or publishes business state, so it is safe
-to repeat and does not take an idempotency key.
+an economic-change verdict. Validation never accepts or publishes business
+state, so it is safe to repeat.
 
 ```bash
 farthershore validate                       # local build + determinism only
@@ -273,11 +271,10 @@ farthershore business subdomain-check weather-api --format json
 
 farthershore business create weather-api \
   --display-name "Weather API" \
-  --idempotency-key <persisted-business-create-attempt-key> \
   --format json
 
-farthershore business publish weather-api --format json --idempotency-key <persisted-business-publish-attempt-key>
-farthershore business rollback weather-api wfe_previous --reason "bad release" --format json --idempotency-key <persisted-business-rollback-attempt-key>
+farthershore business publish weather-api --format json
+farthershore business rollback weather-api wfe_previous --reason "bad release" --format json
 ```
 
 Deleting a business is **stage only** — the command is not registered in the
@@ -377,7 +374,7 @@ farthershore organization role list <organizationId> --filter builtIn=true --sor
 farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
 
 # Primary owner only; hands ultimate authority to another existing member.
-farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json --idempotency-key <persisted-organization-ownership-transfer-attempt-key>
+farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json
 ```
 
 Selecting the default organization is a local credential concern, not an API
@@ -399,20 +396,17 @@ farthershore token permission-catalog --org --format json
 farthershore token create deploy-bot --org \
   --permissions '["business:read","business:publish"]' \
   --businesses business_1,business_2 \
-  --idempotency-key org-token-create-2026-08-11 \
   --format json
 
 farthershore token list --org --format json
 farthershore token approvals --org --format json
-farthershore token approve <approvalId> --org --format json --idempotency-key <persisted-token-approve-attempt-key>
+farthershore token approve <approvalId> --org --format json
 farthershore token approve <approvalId> --org \
-  --idempotency-key <persisted-token-approve-attempt-key> \
   --permissions '["business:read"]' --format json # trim on approval
 farthershore token deny <approvalId> --org --format json
 farthershore token update <tokenId> --org \
-  --permissions '["business:read"]' \
-  --idempotency-key org-token-update-2026-08-11 --format json
-farthershore token rotate <tokenId> --org --format json --idempotency-key <persisted-token-rotate-attempt-key>
+  --permissions '["business:read"]' --format json
+farthershore token rotate <tokenId> --org --format json
 farthershore token revoke <tokenId> --org --yes --format json
 ```
 
@@ -423,10 +417,7 @@ exactly once; store it immediately. Human output follows the same rule: it
 prints plaintext only for an ACTIVE one-time-secret response and says explicitly
 when a PENDING request minted nothing.
 
-Create and update require `--idempotency-key`. Persist the key before the first
-dispatch and reuse it only when repeating that exact logical request after an
-interrupted invocation. The CLI never generates a key: a process-local key
-would be lost across the restart where retry safety matters most.
+If a create or update times out, run `token list --org` before trying again.
 
 ### `farthershore stripe`
 
@@ -462,26 +453,22 @@ export FARTHERSHORE_SUBSCRIBER_ORGANIZATION_ID='<subscriber organization UUID>'
 farthershore service-account list <businessId> --format json
 farthershore service-account create <businessId> deploy-bot \
   --permissions '["route:read","route:write"]' \
-  --scopes '["production"]' \
-  --idempotency-key sa-create-2026-08-11 --format json
+  --scopes '["production"]' --format json
 farthershore service-account update <businessId> <serviceAccountId> \
-  --permissions '["route:read"]' \
-  --idempotency-key sa-update-2026-08-11 --format json
+  --permissions '["route:read"]' --format json
 farthershore service-account approvals <businessId> --format json
 farthershore service-account approve <businessId> <approvalId> \
   --permissions '["route:read"]' --format json # optional trim
 farthershore service-account deny <businessId> <approvalId> --format json
-farthershore service-account rotate <businessId> <serviceAccountId> --format json --idempotency-key <persisted-service-account-rotate-attempt-key>
+farthershore service-account rotate <businessId> <serviceAccountId> --format json
 farthershore service-account revoke <businessId> <serviceAccountId> --yes --format json
 ```
 
 Pass `--environment-id` and `--subscriber-organization` to override the two
 context environment variables for one command. PENDING create/update responses
 never print `plaintext`. ACTIVE creates
-and rotations print the one-time key once. Create, update, and rotate require a
-caller-persisted key, just like one-time-secret org-token operations. A replayed
-success includes `meta.idempotency.replayed: true`; follow it with a list read
-before reporting current state.
+and rotations print the one-time key once. If one of these commands times out,
+run `service-account list` before trying again.
 
 This group is direct CLI-only and deliberately has no MCP projection: the MCP
 operation registry carries builder principals, not portal consumer sessions.
@@ -573,7 +560,7 @@ organization composes those permissions into its own product roles.
 
 ```bash
 # First persona creates and owns a temporary subscriber workspace.
-farthershore persona bootstrap weather-api --env preview --plan pro --format json --idempotency-key <persisted-persona-bootstrap-attempt-key>
+farthershore persona bootstrap weather-api --env preview --plan pro --format json
 farthershore persona list weather-api --env preview --format json
 farthershore persona login weather-api <ownerPersonaId> --env preview --format json
 
@@ -581,9 +568,9 @@ farthershore persona login weather-api <ownerPersonaId> --env preview --format j
 # created roles/defaults through the normal customer RBAC surface.
 farthershore persona bootstrap weather-api --env preview --plan pro \
   --subscriber-id <subscriberId> --account-role member --role viewer \
-  --format json --idempotency-key <persisted-member-bootstrap-attempt-key>
+  --format json
 
-farthershore persona rotate weather-api <personaId> --env preview --format json --idempotency-key <persisted-persona-rotate-attempt-key>
+farthershore persona rotate weather-api <personaId> --env preview --format json
 farthershore persona delete weather-api <personaId> --env preview --format json
 ```
 
@@ -591,7 +578,13 @@ Bootstrap and rotation return a key once. `login` sends the 60-second,
 single-use handoff only in the browser URL fragment to the platform-owned
 `/persona-sign-in` bridge. The bridge establishes an HttpOnly browser session
 and returns to the exact original portal path, query, and fragment. CLI output
-contains portal metadata but never the handoff or a session bearer. Product
+contains portal metadata but never the handoff or a session bearer. `login`
+emits `opened: true` only after the system browser launcher (`open` /
+`xdg-open`) has exited successfully, so the URL has been handed off before the
+command returns; a launcher failure is reported as an error. The wait is capped
+at 20 seconds: a launcher still running then (for example `xdg-open` running
+the browser in the foreground) is detached, and `login` emits `opened: false`
+with a stderr notice instead of hanging until the browser closes. Product
 role keys must already exist in that subscriber's role catalog; omit `--role` to use its
 configured default. Deletion tears down the temporary user and credential, and
 deleting the environment also removes the remaining persona-owned workspace.
@@ -636,11 +629,11 @@ compiled integration that references it.
 ```bash
 farthershore variables list weather-api --format json
 printf '%s' "$SENTRY_AUTH_TOKEN" | farthershore variables set weather-api \
-  SENTRY_AUTH_TOKEN --format json --idempotency-key <persisted-sentry-variable-attempt-key>
+  SENTRY_AUTH_TOKEN --format json
 printf '%s' "$POSTHOG_PROJECT_KEY" | farthershore variables set weather-api \
-  FS_PUBLIC_POSTHOG_KEY --format json --idempotency-key <persisted-posthog-variable-attempt-key>
-farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json --idempotency-key <persisted-variables-revoke-attempt-key>
-farthershore variables rm weather-api POSTHOG_SECRET --yes --format json --idempotency-key <persisted-variables-rm-attempt-key>
+  FS_PUBLIC_POSTHOG_KEY --format json
+farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json
+farthershore variables rm weather-api POSTHOG_SECRET --yes --format json
 ```
 
 There is no builder-managed public-variable surface and values are never
@@ -658,14 +651,13 @@ farthershore backend list weather-api --format json
 farthershore backend create weather-api \
   --name "Production API" \
   --origin-url https://api.example.com \
-  --idempotency-key <persisted-backend-create-attempt-key> \
   --format json
 farthershore backend bind weather-api api \
   --env preview-42 \
   --origin-url https://api-pr-42.example.com \
   --format json
-farthershore backend tokens create weather-api --backend <backendId> --format json --idempotency-key <persisted-backend-tokens-create-attempt-key>
-farthershore backend tokens rotate weather-api <tokenId> --format json --idempotency-key <persisted-backend-tokens-rotate-attempt-key>
+farthershore backend tokens create weather-api --backend <backendId> --format json
+farthershore backend tokens rotate weather-api <tokenId> --format json
 farthershore backend tokens revoke weather-api <tokenId> --yes --format json
 ```
 
@@ -710,13 +702,12 @@ farthershore webhook list weather-api --format json
 farthershore webhook create weather-api \
   --url https://hooks.example.com/farthershore \
   --events subscription.created,payment.failed \
-  --idempotency-key <persisted-webhook-create-attempt-key> \
   --format json
 farthershore webhook update weather-api <webhookId> --disable --format json
-farthershore webhook test weather-api <webhookId> --idempotency-key <persisted-test-attempt-key> --format json
-farthershore webhook trigger weather-api <webhookId> --type payment.failed --idempotency-key <persisted-trigger-attempt-key> --format json
+farthershore webhook test weather-api <webhookId> --format json
+farthershore webhook trigger weather-api <webhookId> --type payment.failed --format json
 farthershore webhook deliveries weather-api <webhookId> --limit 20 --format json
-farthershore webhook rotate weather-api <webhookId> --format json --idempotency-key <persisted-webhook-rotate-attempt-key>
+farthershore webhook rotate weather-api <webhookId> --format json
 farthershore webhook delete weather-api <webhookId> --yes --format json
 ```
 
@@ -755,10 +746,8 @@ Manage checkout promo codes (operational state, not part of the manifest).
 farthershore promo-code list weather-api --format json
 farthershore promo-code create weather-api \
   --code LAUNCH25 --kind percent_off --percent 25 --duration-months 3 \
-  --idempotency-key <persisted-promo-code-create-attempt-key> \
   --plan <planId> --format json
 farthershore promo-code create weather-api \
-  --idempotency-key <persisted-promo-code-create-attempt-key> \
   --code SAVE500 --kind amount_off --amount-cents 500 --duration-months 1 --format json
 farthershore promo-code archive weather-api <promoCodeId> --format json
 farthershore promo-code reactivate weather-api <promoCodeId> --format json
@@ -774,18 +763,18 @@ Use `--all-plans` to clear plan scoping.
 Install or refresh the platform-verified skills bundle together. The platform
 pins this immutable release, and CI plus a daily repository check compare it to
 GitHub's latest stable release so the guidance cannot silently drift.
-This command requires `@farthershore/cli` 0.33.5 or newer.
+This command requires `@farthershore/cli` 0.34.0 or newer.
 
 ```bash
 set -euo pipefail
 CLI_VERSION=$(farthershore --version)
-printf '%s' "$CLI_VERSION" | node -e 'let v=""; process.stdin.on("data", c => v += c).on("end", () => { const m = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim()); if (!m || !(+m[1] > 0 || +m[2] > 33 || (+m[2] === 33 && +m[3] >= 5))) { console.error("Stop: CLI 0.33.5 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
+printf '%s' "$CLI_VERSION" | node -e 'let v=""; process.stdin.on("data", c => v += c).on("end", () => { const m = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim()); if (!m || !(+m[1] > 0 || +m[2] > 34 || (+m[2] === 34 && +m[3] >= 0))) { console.error("Stop: CLI 0.34.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
 farthershore skills install --help
 farthershore skills install
 ```
 
 If either prerequisite fails, stop and ask the human to run
-`npm install -g @farthershore/cli@0.33.5`, then repeat the checks.
+`npm install -g @farthershore/cli@0.34.0`, then repeat the checks.
 Do not install or upgrade global tooling autonomously.
 
 The Farther Shore CLI downloads the exact installer archive and verifies this