@farthershore/cli 0.7.1 → 0.8.0

package/README.md

@@ -1,6 +1,8 @@
 # @farthershore/cli
 
-Create and manage [FartherShore](https://farthershore.com) API products from the terminal.
+Create and manage [FartherShore](https://farthershore.com) API products from
+the terminal. Designed for AI agents and humans alike — every command supports
+`--format json` for non-TTY scripting.
 
 ## Install
 
@@ -11,7 +13,7 @@ npm install -g @farthershore/cli
 Or use directly with npx:
 
 ```bash
-npx @farthershore/cli init my-api
+npx @farthershore/cli --help
 ```
 
 The package also ships an MCP stdio server for agents:
@@ -22,225 +24,413 @@ FARTHERSHORE_TOKEN=mk_xxx npx -p @farthershore/cli farthershore-mcp
 
 ## Authentication
 
-Create an API token at [farthershore.com/settings/tokens](https://farthershore.com/settings/tokens), then:
+Create a maker token at
+[farthershore.com/settings/tokens](https://farthershore.com/settings/tokens),
+then store it locally:
 
 ```bash
-# Interactive — prompts for token
-farthershore set-key
+# Interactive — prompts for the token
+farthershore auth login
 
-# Non-interactive — pass token directly
-farthershore set-key mk_xxx
+# Non-interactive — pass it directly
+farthershore auth login --token mk_xxx
 
-# Agent-friendly alias
-farthershore auth set-key mk_xxx
-
-# Environment variable (CI / agents)
+# Or skip the file entirely with an env var (CI / agents)
 export FARTHERSHORE_TOKEN=mk_xxx
 ```
 
-Tokens are stored in `~/.farthershore/credentials.json`.
-
-## Environment scope
-
-Most product commands can run against production or a named environment.
-Production is the default. `production`, `prod`, and `main` all mean the
-production scope.
+Tokens are stored in `~/.farthershore/credentials.json`. Maker tokens are
+exchanged for a short-lived CLI access token on first authenticated request.
 
 ```bash
-farthershore env create preview --branch env/preview --format json
-farthershore env use preview --format json
-farthershore plan list --env preview --format json
-farthershore --env preview meter list --format json
-farthershore env run preview -- plan add pro --price-monthly 2900 --format json
-farthershore env use production --format json
+farthershore auth whoami         # Show current org, role, scopes
+farthershore auth logout         # Clear stored credentials
 ```
 
-`env use` is stored per product in `~/.farthershore/config.json`, so
-switching products does not accidentally carry the previous product's
-environment.
+## Global flags
+
+| Flag                  | Description                                              |
+| --------------------- | -------------------------------------------------------- |
+| `--token <token>`     | Override auth token for this command                     |
+| `--api-url <url>`     | Override API base URL                                    |
+| `--env <environment>` | Environment scope (use `production`/`prod`/`main`)       |
+| `--format <format>`   | `json` for machine-readable output (default for non-TTY) |
+| `--version`           | Show version                                             |
+| `--help`              | Show help                                                |
+
+## Environment variables
+
+| Variable               | Description                                             |
+| ---------------------- | ------------------------------------------------------- |
+| `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                |
+| `FARTHERSHORE_API_URL` | API base URL (default: `https://core.farthershore.com`) |
+| `FARTHERSHORE_ENV`     | Default environment scope when `--env` is omitted       |
 
 ## Commands
 
-### `farthershore init <name>`
+### `farthershore init`
 
-Create a new API product with a GitHub repo. Returns a clone URL and instructions for an AI agent (or human) to configure it.
+Scaffold a starter `product.yaml` from a named plan preset. Each preset
+fills in the 5-knob spec for a common shape so first-time builders skip
+the blank-page problem.
 
 ```bash
-farthershore init my-weather-api
-```
+# Interactive walkthrough (TTY only) — pick a preset by number/name + path
+farthershore init
 
-Options:
+# Non-interactive — pass --template explicitly (required when not a TTY)
+farthershore init --template free
+farthershore init --template starter --force
+farthershore init --template metered --format json
+```
 
-- `--base-url <url>` — Backend API base URL
-- `--description <text>` — Product description
-- `--display-name <name>` — Display name for the product portal
+Templates (sourced from shared-types `listPlanPresets()`):
 
-The created repo contains:
+| Template  | Shape                                                        |
+| --------- | ------------------------------------------------------------ |
+| `free`    | $0 plan, hard-enforced 1k requests/month limit               |
+| `starter` | $20/mo + $20 included usage, $0.001/request overage          |
+| `pro`     | $100/mo + $200 included usage, 14-day trial, $0.0005/request |
+| `prepaid` | $50 one-time signup credit, then PAYG                        |
+| `metered` | Pure pay-as-you-go at $0.001/request                         |
 
-- `product.yaml` — template config (edit and push to go live)
-- `AGENTS.md` — full configuration reference for AI agents
-- `docs/` — developer portal documentation
-- `.skills/` — task-specific instructions
+After `init`, edit `product.name` + `product.baseUrl`, then run
+`farthershore validate` to confirm the scaffolded YAML is acceptable.
 
-### `farthershore product create <name>`
+### `farthershore product`
 
-Create a product through the API and select it as the active product for
-subsequent CLI commands. This is the fastest path for an agent that wants
-to configure a product without opening the UI.
+Product lifecycle commands — direct API, no local `product.yaml` round-trip.
 
 ```bash
-farthershore product create weather-api \
+farthershore product list --format json
+farthershore product show weather-api --format json
+farthershore product show weather-api --env preview --format json
+
+farthershore product create \
+  --name weather-api \
+  --display-name "Weather API" \
   --base-url https://api.example.com \
-  --strategy prepaid_credits \
   --format json
-```
 
-### `farthershore product status`
+# Meter templates — the same smart defaults the dashboard offers:
+#   requests (default) | ai-tokens | credits | spend | compute
+farthershore product create --name llm-api --meters ai-tokens --format json
 
-Return the latest accepted internal product config metadata, including
-the accepted config hash and GitHub sync state.
+# Or a fully custom meter list (key[:display[:unit]], repeatable):
+farthershore product create --name image-api \
+  --meter requests \
+  --meter images:Images:image \
+  --format json
 
-```bash
-farthershore product status --format json
-farthershore product status --env preview --format json
+farthershore product update weather-api --display-name "Weather" --format json
+farthershore product publish weather-api --format json
+farthershore product delete weather-api --yes --format json
+
+farthershore product compile weather-api --dry-run --format json
+farthershore product compile weather-api --branch env/preview --format json
 ```
 
-### `farthershore product config`
+`product create` provisions a managed GitHub repo and returns clone-URL +
+agent bootstrap instructions in the response. Plan pricing lives on the
+plan (see `farthershore plan create` below) — the product itself no
+longer carries a `billingStrategy`. Omitting both meter flags gives the
+product a `requests` meter; variable-value meters (tokens, credits, spend)
+are settled from upstream `x-fs-cost-{key}` response headers.
 
-Print the accepted or draft product config from FartherShore. GitHub,
-the UI, MCP, and the CLI all write through the same validated internal
-config path. Accepted config is live; draft config is staged until
-`farthershore apply` publishes it.
+A new product starts as a DRAFT with its portal already live in template
+mode. Going live mirrors the dashboard's "Finish setting up" checklist:
 
 ```bash
-farthershore product config --format json
-farthershore product config --format yaml
-farthershore product config --state draft --format json
-farthershore product config --env preview --format json
+farthershore product create --name llm-api --meters ai-tokens   # 1. create
+farthershore plan create llm-api --key pro --name "Pro" \
+  --recurring-fee-cents 2900                                    # 2. how you charge
+farthershore product update llm-api \
+  --base-url https://api.example.com                            # 3. endpoint
+farthershore product publish llm-api                            # 4. go live
 ```
 
-### `farthershore product attempts`
+`product publish` enforces the same gates as the dashboard: at least one
+plan, a base URL, and a verified Stripe connection (clear remediation is
+printed for `STRIPE_NOT_CONNECTED` / `STRIPE_NOT_VERIFIED` /
+`BILLING_TAX_NOT_ENROLLED`).
+
+### `farthershore env`
 
-List rejected config proposals. Invalid proposals are recorded for
-diagnostics but do not replace the accepted internal config or mutate live
-product state.
+Manage preview/production environments. Production is the default scope
+when `--env` is omitted; `production`, `prod`, and `main` are aliases.
 
 ```bash
-farthershore product attempts --format json
-farthershore product attempts --env preview --format json
+farthershore env list weather-api --format json
+farthershore env create weather-api --name preview --branch env/preview --format json
+farthershore env delete weather-api preview --yes --format json
 ```
 
-### `farthershore meter`
+### `farthershore plan`
 
-Create and manage usage meters in the shared draft product config.
+Plan CRUD via the management API. The body uses the unified 5-knob
+spec (see "`product.yaml` plan shape" below) — pass cents-denominated
+flags for whichever knobs the plan flavor needs.
 
 ```bash
-farthershore meter add ai_tokens \
-  --selector model \
-  --measure input_tokens \
-  --measure output_tokens \
-  --rating provider_catalog \
-  --catalog llm_models \
+# Human-readable table (default in TTY)
+farthershore plan list weather-api
+farthershore plan list weather-api --format table
+
+# JSON envelope (default outside TTY; suitable for jq pipelines)
+farthershore plan list weather-api --format json
+
+# Flat subscription: recurring fee only
+farthershore plan create weather-api \
+  --key pro \
+  --name "Pro" \
+  --recurring-fee-cents 2900 \
+  --format json
+
+# Included usage: fee + monthly credit grant
+farthershore plan create weather-api \
+  --key included \
+  --name "Included" \
+  --recurring-fee-cents 2000 \
+  --recurring-credit-grant-cents 2000 \
   --format json
 
-farthershore meter list --format json
-farthershore meter list --env preview --format json
+# Free plan
+farthershore plan create weather-api --key free --name "Free" --free --format json
+
+farthershore plan update weather-api <planId> --recurring-fee-cents 3900 --format json
+farthershore plan delete weather-api <planId> --yes --env preview --format json
 ```
 
-### `farthershore feature`
+### `farthershore persona`
 
-Create features and bind or unbind them from plans.
+Test-environment personas — mint fresh `fsk_test_*` API keys so an agent
+can exercise the gateway end-to-end. Only works in test-strategy envs.
 
 ```bash
-farthershore feature add chat_completions \
-  --route POST:/v1/chat/completions \
-  --format json
-
-farthershore feature bind chat_completions --plan pro --format json
-farthershore feature list --env preview --format json
+farthershore persona bootstrap weather-api --env preview --plan pro --format json
+farthershore persona list weather-api --env preview --format json
+farthershore persona revoke weather-api <personaId> --env preview --format json
 ```
 
-### `farthershore plan`
+### `farthershore usage`
 
-Create and update plans in the shared draft product config. Server-side
-validation remains authoritative for rules like one free plan, duplicate
-paid prices, and product-level billing strategy consistency before apply
-can publish.
+Read recent usage off the management API.
 
 ```bash
-farthershore plan add free \
-  --free \
-  --limit ai_tokens:month:100000:enforce \
-  --feature chat_completions \
-  --format json
-
-farthershore plan add pro \
-  --price-monthly 2900 \
-  --credits-monthly-micros 500000000 \
-  --meter ai_tokens \
-  --feature chat_completions \
-  --format json
-
-farthershore plan list --env preview --format json
+farthershore usage summary weather-api --format json
 ```
 
-### `farthershore billing`
+### `farthershore connect`
 
-Read or change the product-level billing strategy and subscriber change
-policy.
+GitHub OAuth and Stripe Connect flows are browser-only. These commands
+report status so an agent can poll until the user finishes the flow.
 
 ```bash
-farthershore billing strategy get --format json
-farthershore billing strategy get --env preview --format json
-
-farthershore billing strategy set prepaid_credits \
-  --transition preserve_current_period \
-  --format json
-
-farthershore billing policy set \
-  --default preserve_current_period \
-  --proration none \
-  --format json
+farthershore connect github --format json
+farthershore connect stripe weather-api --format json
 ```
 
-### `farthershore transition preview`
+### `farthershore token`
 
-Preview how billing-affecting config changes apply to existing
-subscribers before applying them.
+Manage maker tokens for the current org.
 
 ```bash
-farthershore transition preview --format json
-farthershore transition preview --env preview --format json
+farthershore token list --format json
+farthershore token create --name "ci-bot" --scope products:update products:publish --format json
+farthershore token revoke <tokenId> --yes --format json
 ```
 
 ### `farthershore validate`
 
-Validate the managed repo through the same backend checks used by the Farther Shore GitHub bot. The command uploads local `product.yaml`, `brand.yaml`, `docs/`, and disallowed managed paths for validation, then prints the canonical errors and warnings.
+Validate the managed repo (`product.yaml`, `brand.yaml`, `docs/`,
+`skills/`, `.github/workflows/`) through the same backend checks the
+Farther Shore GitHub bot runs.
 
 ```bash
-# Validate the current managed repo
 farthershore validate
-
-# Machine-readable diagnostics
 farthershore validate --format json
 ```
 
+Emits GitHub Actions-formatted annotations when run under `CI` /
+`GITHUB_ACTIONS`.
+
+#### `product.yaml` plan shape
+
+Every plan is a configuration of 5 orthogonal knobs (shared-types
+v0.53.0). Older shapes with `pricing.{model, monthlyPriceCents}` and
+top-level `billing.strategy` are no longer accepted by the validator.
+
+| Knob                           | Cents/unit       | Meaning                                                 |
+| ------------------------------ | ---------------- | ------------------------------------------------------- |
+| `meters[]`                     | micros/unit      | Per-dimension usage price (zero or more dimensions)     |
+| `recurring_fee_cents`          | cents            | Charged each billing period (recurring subscription)    |
+| `recurring_credit_grant_cents` | cents            | Credit issued each period; drains against meter charges |
+| `one_time_credit_grant_cents`  | cents            | Prepaid balance at subscription start; drains once      |
+| `trial_days`                   | days             | Waive everything for N days at the start                |
+| `max_monthly_spend_cents`      | cents (optional) | Hard cap; the gateway blocks once exceeded (orthogonal) |
+
+Billing math (handled by Stripe Billing v2 at invoice finalization):
+`bill = recurring_fee + max(0, total_meter_cost − applied_credit_balance)`.
+
+Every plan flavor — free, flat, included, overage, prepaid, trial,
+pay-as-you-go — is a knob combination. Examples:
+
+```yaml
+# Free plan: explicit `free: true` flag + hard-enforced limit
+plans:
+  - key: free
+    name: Free
+    free: true
+    recurring_fee_cents: 0
+    limits:
+      - dimension: requests
+        window: { type: named, name: month }
+        capacity: 1000
+        enforcement: enforce
+
+  # Flat subscription: recurring fee only
+  - key: starter
+    name: Starter
+    recurring_fee_cents: 2900
+
+  # Included usage: fee + monthly credit grant + metered
+  - key: pro
+    name: Pro
+    recurring_fee_cents: 2000
+    recurring_credit_grant_cents: 2000
+    meters:
+      - dimension: requests
+        price_per_unit_micros: 1000 # $0.001/request
+
+  # Overage: fee + metered, no credit
+  - key: growth
+    name: Growth
+    recurring_fee_cents: 4900
+    meters:
+      - dimension: requests
+        price_per_unit_micros: 500
+
+  # Prepaid: one-time grant + metered
+  - key: prepaid
+    name: Prepaid
+    one_time_credit_grant_cents: 10000
+    meters:
+      - dimension: requests
+        price_per_unit_micros: 1000
+
+  # Trial: trial_days + recurring fee
+  - key: trial
+    name: Trial
+    recurring_fee_cents: 2900
+    trial_days: 14
+
+  # Pay-as-you-go: metered only (no recurring fee)
+  - key: metered
+    name: Metered
+    meters:
+      - dimension: tokens
+        price_per_unit_micros: 100
+```
+
+#### `grants[]` array (shared-types v0.56.0)
+
+Plans now accept a typed `grants[]` array that supersedes the two
+legacy grant knobs (`recurring_credit_grant_cents`,
+`one_time_credit_grant_cents`). When `grants[]` is present, the legacy
+knobs are ignored. When absent, the validator silently synthesizes
+entries from the legacy knobs so existing specs keep working.
+
+Valid `kind` values:
+
+| Kind            | Required fields                                        | Use case                                            |
+| --------------- | ------------------------------------------------------ | --------------------------------------------------- |
+| `recurring`     | `amount_cents`                                         | Monthly credit (e.g. $20 included usage)            |
+| `one_time`      | `amount_cents`                                         | Signup bonus / prepaid balance                      |
+| `promotional`   | `amount_cents`, `label`, optional `expires_after_days` | Launch bonus, win-back, holiday promo               |
+| `trial`         | (none)                                                 | Trial entry — requires `trial_days > 0` on the plan |
+| `rollover`      | `percent` (0–100)                                      | "Unused balance rolls over X% to the next period"   |
+| `top_up`        | `sku`, `label`, `price_cents`, `credit_cents`          | Buy-extra-credit SKU exposed in checkout            |
+| `auto_recharge` | `threshold_cents`, `refill_cents`                      | "When balance < $X auto-purchase $Y"                |
+
+`recurring`, `rollover`, and `trial` are single-shot per plan;
+declaring more than one entry of the same kind triggers a warning
+(only the first is honored).
+
+Example:
+
+```yaml
+plans:
+  - key: pro
+    name: Pro
+    recurring_fee_cents: 10000
+    trial_days: 14
+    meters:
+      - dimension: requests
+        price_per_unit_micros: 500
+    grants:
+      - kind: recurring
+        amount_cents: 20000
+      - kind: trial
+      - kind: promotional
+        amount_cents: 1000
+        label: launch-bonus
+        expires_after_days: 30
+      - kind: rollover
+        percent: 25
+      - kind: auto_recharge
+        threshold_cents: 500
+        refill_cents: 5000
+```
+
+The validator surfaces:
+
+- **error** — invalid `kind` is rewritten to `Unknown grant kind. Valid kinds: …`
+- **warning** — `grants[]` declares `recurring`/`one_time` _and_ the matching legacy knob is also non-zero (legacy is silently ignored)
+- **warning** — `{ kind: trial }` declared but `trial_days` is 0
+- **warning** — singleton kinds (`recurring`, `rollover`, `trial`) declared more than once
+
+#### Deprecation window (Phase 3b)
+
+The product top-level `lifecycle.breaking_changes` block declares the
+breaking-change governance policy enforced on `apply`:
+
+```yaml
+lifecycle:
+  breaking_changes:
+    require_deprecation_window_days: 90
+    require_successor_route: true
+```
+
+When the policy is set:
+
+- `farthershore validate` emits an informational warning so the builder
+  sees the active policy locally.
+- `farthershore apply` (which compares the proposed spec against the
+  accepted spec) emits a `route_removed` change for every route
+  dropped from `features.<x>.routes[]` and warns that the server-side
+  `breaking-change-safety-check` cron will gate the publish via
+  `ConsumerActivity` lookup. When `require_successor_route` is true,
+  the apply path additionally surfaces a successor-required warning.
+
+The CLI never blocks on the window itself — the per-consumer lookup
+lives server-side (Phase 1c `ConsumerActivity` table + Phase 3b cron).
+The CLI's job is to surface the policy and the route delta locally so
+the builder knows what the gate will see.
+
 ### `farthershore apply [product]`
 
 Publish the shared server draft as one product release. Core accepts the
-release only after schema validation, transition-safety validation, and a
-compiler dry-run pass. Mutation commands such as `meter add`,
-`feature add`, and `plan set-price` stage draft changes by default; they
-do not create live product or plan versions until `apply`.
+release only after schema validation, transition-safety validation, and
+a compiler dry-run all pass.
 
 ```bash
 # Publish the current shared draft
 farthershore apply
 
-# Or pass the product slug explicitly
-farthershore apply my-weather-api
+# Or pass the product slug/UUID explicitly
+farthershore apply weather-api
 
-# Validate and compile the draft without publishing
+# Validate and compile without publishing
 farthershore apply --dry-run --format json
 farthershore apply --env preview --dry-run --format json
 
@@ -248,133 +438,62 @@ farthershore apply --env preview --dry-run --format json
 farthershore apply --to product.yaml --dry-run --format json
 farthershore apply --to product.yaml --format json
 
-# Also save that local file as the shared draft before publishing
+# Also stage that file as the shared draft before publishing
 farthershore apply --to product.yaml --save-draft --format json
-```
 
-Draft commands help agents inspect and control the release boundary:
-
-```bash
-farthershore draft status --format json
-farthershore draft diff --format json
-farthershore draft validate --format json
-farthershore draft reset --format json
+# Pin compilation to a specific branch
+farthershore apply weather-api --branch feature/billing-change --dry-run --format json
 ```
 
-## MCP tools
-
-Run the MCP server with a maker token:
-
-```bash
-FARTHERSHORE_TOKEN=mk_xxx farthershore-mcp
-```
-
-The MCP server exposes the same product-building workflow as the CLI:
-product create/status/config, environment list/create/use, billing strategy
-set, meter add, feature add, plan add, transition preview, and apply.
-Every tool accepts optional `product` and `env` fields where relevant and
-returns secret-free JSON.
-
-### `farthershore set-key [token]`
-
-Set your API token. Interactive when run in a terminal, or pass the token as an argument for scripts.
-
-### `farthershore whoami`
-
-Show your current authentication context (organization, auth method).
-
-### `farthershore logout`
-
-Clear stored credentials.
-
-### `farthershore set-url <url>`
-
-Override the API base URL (persisted in `~/.farthershore/config.json`).
+JSON output is stable: `{ ok, success, errors, warnings, lifecyclePlan,
+nextActions, ... }`. `lifecyclePlan` is always present (or `null` on
+first deploys / older core builds) and surfaces ADR-0010 per-domain
+subscriber-migration actions.
 
-### `farthershore reset-url`
+## Agent workflow
 
-Reset the API base URL to the default (`https://core.farthershore.com`).
-
-## Agent Workflow
-
-The CLI is designed for AI agents to create and configure API products:
+A typical agent flow:
 
 ```bash
-# 1. Agent receives: create a weather API product
-farthershore init weather-api --format json
+export FARTHERSHORE_TOKEN=mk_xxx
 
-# 2. Agent clones the repo
-git clone https://github.com/org/weather-api.git
-cd weather-api
+farthershore product create \
+  --name weather-api \
+  --base-url https://api.example.com \
+  --format json
 
-# 3. Agent reads AGENTS.md for configuration reference
-cat AGENTS.md
+farthershore plan create weather-api --key free --name "Free" --free --format json
+farthershore plan create weather-api \
+  --key pro --name "Pro" --recurring-fee-cents 2900 --format json
 
-# 4. Agent validates locally before pushing
-farthershore validate
-
-# 5. Agent pushes — product goes live automatically on valid config
-git add -A && git commit -m "Configure product" && git push
+farthershore apply weather-api --dry-run --format json
+farthershore apply weather-api --format json
+farthershore product show weather-api --format json
 ```
 
-Agents can also complete the flow entirely through API-backed CLI
-commands:
+For a YAML-driven flow, edit `product.yaml` in the managed repo, then:
 
 ```bash
-farthershore auth set-key "$FARTHERSHORE_TOKEN"
-farthershore product create weather-api \
-  --base-url https://api.example.com \
-  --strategy prepaid_credits \
-  --format json
-farthershore meter add ai_tokens \
-  --selector model \
-  --measure input_tokens \
-  --measure output_tokens \
-  --rating provider_catalog \
-  --catalog llm_models \
-  --format json
-farthershore feature add chat_completions \
-  --route POST:/v1/chat/completions \
-  --format json
-farthershore plan add free \
-  --free \
-  --limit ai_tokens:month:100000:enforce \
-  --feature chat_completions \
-  --format json
-farthershore plan add pro \
-  --price-monthly 2900 \
-  --credits-monthly-micros 500000000 \
-  --meter ai_tokens \
-  --feature chat_completions \
-  --format json
-farthershore draft validate --format json
-farthershore transition preview --format json
-farthershore apply --dry-run --format json
-farthershore apply --format json
-farthershore product status --format json
+farthershore validate --format json
+farthershore apply --to product.yaml --dry-run --format json
+farthershore apply --to product.yaml --format json
 ```
 
-## Global Flags
+## MCP server
 
-| Flag              | Description                          |
-| ----------------- | ------------------------------------ |
-| `--token <token>` | Override auth token for this command |
-| `--api-url <url>` | Override API base URL                |
-| `--format json`   | Output as JSON (default for non-TTY) |
-| `--version`       | Show version                         |
-| `--help`          | Show help                            |
+The MCP server (`farthershore-mcp`) exposes two tools:
 
-## Environment Variables
+- `farthershore_draft_validate` — run server-side validation on the shared
+  draft.
+- `farthershore_apply` — apply the draft, optionally with a `product.yaml`
+  proposal via `toFile`. Defaults to `dryRun: true`.
 
-| Variable               | Description                                             |
-| ---------------------- | ------------------------------------------------------- |
-| `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                |
-| `FARTHERSHORE_API_URL` | API base URL (default: `https://core.farthershore.com`) |
+Both accept optional `product` and `env` fields and return JSON.
 
 ## Errors and exit codes
 
 The CLI exits `0` on success and `1` on any failure (including
-`commander`-level argument errors). When the API returns a 4XX/5XX, the
+commander-level argument errors). When the API returns a 4XX/5XX, the
 CLI prints the canonical error code in brackets and a one-line
 remediation hint when one is registered:
 
@@ -383,17 +502,15 @@ Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
 Hint: Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.
 ```
 
-The bracketed code is stable across releases — quote it in support
-threads.
+The bracketed code is stable across releases — quote it in support threads.
 
-`farthershore whoami --format json` emits a stable JSON shape suitable
-for CI scripts. On the not-authenticated path it emits
-`{ "authenticated": false }` with exit code `1`.
+`farthershore auth whoami --format json` emits a stable JSON shape suitable
+for CI scripts.
 
 ## CI / agent usage
 
 The CLI is non-interactive whenever a token is available via the
-`--token` flag or `FARTHERSHORE_TOKEN` env var — `set-key` only prompts
-when stdin is a TTY and no token argument was passed, so it's safe to
-script. `validate` and `apply` emit GitHub Actions-formatted annotations
-when run under `CI` / `GITHUB_ACTIONS`.
+`--token` flag or `FARTHERSHORE_TOKEN` env var — `auth login` only
+prompts when stdin is a TTY and no token argument was passed, so it's
+safe to script. `validate` and `apply` emit GitHub Actions-formatted
+annotations when run under `CI` / `GITHUB_ACTIONS`.