@farthershore/cli 0.29.0 → 0.31.0

package/README.md

@@ -3,96 +3,117 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.25.0`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.31.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,
 and bills access to it at the edge. Business behavior — plans, pricing, limits,
-routes, meters, and origins — is authored in your GitHub repo with
+routes and meters — is authored in your GitHub repo with
 [`@farthershore/business`](https://www.npmjs.com/package/@farthershore/business)
-and applied automatically when you push. This CLI is the tool layer around that
-repo: scaffold a new business, validate it locally before you push, connect
-billing, publish it live, and run day-to-day operations (consumers, secrets,
-backends, webhooks, promo codes, usage). It is designed to be safe for both
-humans and agents — every command takes `--format json` for non-interactive
-scripting, and the same surface is exposed as an MCP server.
+and reconciled through repository checks and the apply timeline after you push.
+This CLI is the tool layer around that repo: provision a managed business repo,
+validate it locally before you push, inspect publication state, and run
+day-to-day operations (consumers, secrets, backends, webhooks, promo codes,
+usage). It is designed to be safe for both humans and agents — every command
+takes `--format json` for non-interactive scripting, and the MCP server exposes
+the explicitly agent-operable subset of the CLI surface.
 
 ## Install
 
 ```bash
-npm install -g @farthershore/cli
+npm install -g @farthershore/cli@0.31.0
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx @farthershore/cli --help
+npx @farthershore/cli@0.31.0 --help
 ```
 
 The package also ships an MCP stdio server for agents:
 
 ```bash
-FARTHERSHORE_TOKEN=mk_xxx npx -p @farthershore/cli farthershore-mcp
+npx -p @farthershore/cli@0.31.0 farthershore-mcp
 ```
 
 ## Authentication
 
-Create a maker token at
-[farthershore.com/settings/tokens](https://farthershore.com/settings/tokens),
-then store it locally:
+Start the device login. The CLI prints a verification URL and user code, opens
+the browser when possible, and waits for a human to review and approve access:
 
 ```bash
-# Interactive — prompts for the token
-farthershore auth login
+farthershore login
+farthershore auth whoami --format json
+```
+
+On a headless machine, print the same handoff without trying to open a browser:
+
+```bash
+farthershore login --headless
+```
 
-# Non-interactive — pass it directly
-farthershore auth login --token mk_xxx
+Normal login creates a user-bound CLI session. It uses your live role in each
+organization instead of copying a permission list into the credential. By
+default it follows all of your current and future organization memberships and
+all businesses in them. Normal login has no permission or scope choices: use an
+organization-scoped MakerToken when automation needs narrower access.
 
-# Or skip the file entirely with an env var (CI / agents)
-export FARTHERSHORE_TOKEN=mk_xxx
+Choose the active organization for a command with `--organization <id-or-slug>`,
+or save a default context:
+
+```bash
+farthershore auth organization list
+farthershore auth organization use <id-or-slug>
 ```
 
-Tokens are stored in `~/.farthershore/credentials.json`. A maker token is
-exchanged for a short-lived CLI access token on the first authenticated request.
+For a separately issued organization-scoped MakerToken, pipe it through bounded stdin:
 
 ```bash
-farthershore auth whoami         # Show current org, role, and scopes
-farthershore auth logout         # Clear stored credentials
+printf %s "$FARTHERSHORE_MAKER_TOKEN" | farthershore login --token-stdin
 ```
 
-GitHub account linking and Stripe Connect/KYC are browser-hosted flows; the CLI
-reports their status (see `connect`) so you — or an agent — can continue once the
-flow is finished in the dashboard.
+`FARTHERSHORE_TOKEN` accepts an organization-scoped MakerToken as an ephemeral
+process override and is never persisted automatically. `farthershore logout` deletes the stored credential after
+revoking the current user CLI session on the platform. Signing in again also
+supersedes older user CLI sessions.
+Membership and role changes take effect on the next authenticated request. A
+restricted MakerToken remains available through `--token-stdin` or
+`FARTHERSHORE_TOKEN`. Never write
+credentials into the managed repository.
 
 ## Quickstart
 
-Scaffold a business, validate it, connect billing, and publish:
+Create a managed business repo, author the business, validate it, and push:
 
 ```bash
-export FARTHERSHORE_TOKEN=mk_xxx
-
-# 1. Create the managed repo (provisions GitHub repo + starter frontend)
-farthershore business create --name weather-api --display-name "Weather API"
+# 1. Create the managed repo. Human output is exactly its URL.
+REPO_URL=$(farthershore business create weather-api)
 
-# 2. Edit business behavior in the repo
-gh repo clone acme/weather-api
+# 2. Clone it and author business/ from scratch.
+git clone "$REPO_URL"
 cd weather-api
-# ...edit business/business.ts with @farthershore/business...
+# ...author business/ with @farthershore/business...
 
 # 3. Validate the same way the PR check will, before pushing
 farthershore validate --business weather-api
 
-# 4. Push — the GitHub bot compiles + applies your manifest
+# 4. Push — the GitHub bot validates and records apply state
 git push --set-upstream origin feature/pricing
-farthershore change-set list weather-api    # inspect checks + apply state
+farthershore apply-timeline list weather-api # inspect checks + apply state
 
-# 5. Connect billing, then go live
-farthershore connect stripe weather-api
-farthershore business publish weather-api
+# 5. Inspect accepted state, then use the CLI for platform operations.
+farthershore business status weather-api --format json
+farthershore operations list --format json
 ```
 
-Plans, prices, limits, routes, meters, and origins are **repo-controlled**:
-change them by editing `business/business.ts` and pushing. The CLI's
+Do not infer a successful apply from a push alone. A default-branch runtime-only
+change may publish after validation; an economic change is deferred to a GitHub
+Release. Preview-environment branches publish only to that environment. Inspect
+the repository checks and apply timeline for the actual outcome.
+
+Plans, prices, limits, routes, and meters are **repo-controlled**: change them
+by editing the program under `business/` and pushing. Presentation and origin bindings
+are platform-owned operating state. The CLI's
 write commands cover **operational** state that lives outside the manifest
 (consumers, secrets, backends, webhooks, promo codes, brand presentation).
 
@@ -100,7 +121,6 @@ write commands cover **operational** state that lives outside the manifest
 
 | Flag                  | Description                                              |
 | --------------------- | -------------------------------------------------------- |
-| `--token <token>`     | Override auth token for this command                     |
 | `--api-url <url>`     | Override platform Core API URL                           |
 | `--env <environment>` | Environment scope (`production`/`prod`/`main` aliases)   |
 | `--format <format>`   | `json` for machine-readable output (default for non-TTY) |
@@ -112,7 +132,7 @@ write commands cover **operational** state that lives outside the manifest
 
 | Variable               | Description                                                     |
 | ---------------------- | --------------------------------------------------------------- |
-| `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                        |
+| `FARTHERSHORE_TOKEN`   | Ephemeral organization-scoped MakerToken; never persisted       |
 | `FARTHERSHORE_API_URL` | Platform Core API URL (default `https://core.farthershore.com`) |
 | `FARTHERSHORE_ENV`     | Default environment scope when `--env` is omitted               |
 
@@ -120,40 +140,13 @@ write commands cover **operational** state that lives outside the manifest
 
 Run `farthershore <group> --help` for the full flag set of any command.
 
-### `farthershore init`
-
-Scaffold a starter business repo locally from a named plan preset. Each preset
-fills in a functional `business/business.ts` using `fs.requests()`,
-`fs.route()`, `fs.plan()`, and a default `fs.business()` export, then creates the matching customer
-`frontend/` project, repo-local `business/package.json`, `business/tsconfig.json`,
-and `.gitignore`.
-
-```bash
-# Interactive walkthrough (TTY only) — pick a preset and a path
-farthershore init
-
-# 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
-farthershore init --template starter --surface frontend --surface agent
-```
-
-| 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 pay-as-you-go               |
-| `metered` | Pure pay-as-you-go at $0.001/request                         |
-
-After `init`, add functional meter, route, group, and plan declarations to grow
-the business. Configure the platform-owned upstream origin separately.
-Pass repeatable
-`--surface <frontend|api|docs|widget|dashboard|webhook|worker|agent>` to seed a
-specific shape; omitting it keeps the default `frontend + api` starter. Run
-`npm install` in `business/`, then `farthershore build` from the repo root to
-confirm it compiles.
+Database-backed list commands use Core's shared query contract: repeat
+`--filter field=value` for exact AND filters, pass one
+`--sort field[:asc|desc]` (ascending when omitted), and use
+`--search <text>` for case-insensitive text search. Core applies all three
+before pagination; the CLI does not sort or filter a partial page locally.
+Each command rejects fields outside its endpoint-specific allowlist shown by
+`--help`.
 
 ### `farthershore create`
 
@@ -174,7 +167,7 @@ planned.
 
 ### `farthershore build`
 
-Compile `business/business.ts` to a Manifest IR envelope locally (default
+Compile the program under `business/` to a Manifest IR envelope locally (default
 output `business-build.json`). The CLI uses the Business SDK installed under
 `business/`, falling back to a root install. This is local compilation only;
 server-side validation and apply happen when you push `business/**` changes.
@@ -201,42 +194,29 @@ farthershore validate --local-only --format json
 
 ### `farthershore business`
 
-Business lifecycle. Creation provisions a managed GitHub repo (the source of
-truth for business behavior) under your connected GitHub account and returns the
-clone URL plus bootstrap instructions. A new business starts as a DRAFT with a
-generated `frontend/` ready to customize.
+Business lifecycle. Creation provisions a managed GitHub repo as the source of
+truth for business behavior and returns its URL. A new business starts as a
+DRAFT with repository tooling but no predefined business program.
 
 ```bash
 farthershore business list --format json
+farthershore business list --filter status=ACTIVE --sort updatedAt:desc --search weather --format json
 farthershore business show weather-api --format json
 farthershore business show weather-api --env preview --format json
 
-farthershore business create \
-  --name weather-api \
+farthershore business create weather-api \
   --display-name "Weather API" \
   --format json
 
-# Seed a meter from the same templates the dashboard offers:
-#   requests (default) | ai-tokens | credits | spend | compute
-farthershore business create --name llm-api --meters ai-tokens --format json
-
-# Or a fully custom meter list (key[:display[:unit]], repeatable):
-farthershore business create --name image-api \
-  --meter requests \
-  --meter images:Images:image \
-  --format json
-
-# Seed initial Business SDK surfaces (repeatable; defaults to frontend + api):
-farthershore business create \
-  --name support-agent \
-  --surface frontend \
-  --surface agent \
-  --format json
-
 farthershore business publish weather-api --format json
+farthershore business rollback weather-api wfe_previous --reason "bad release" --format json
 farthershore business delete weather-api --yes --format json
 ```
 
+The JSON result includes `data.business`, `data.repoUrl`, and recovery metadata.
+Gather the product requirements, create the `business/` program, and author its
+plans, prices, limits, routes, and meters from scratch.
+
 `business update` changes platform-owned fields such as display name,
 description, icon, and logo (icon/logo accept PNG, JPEG, or WEBP). Plans,
 prices, limits, routes, and meters are repo-controlled and must be changed
@@ -253,18 +233,19 @@ farthershore business update weather-api \
   --clear-icon --clear-logo --format json
 ```
 
-`business publish` enforces the same go-live gates as the dashboard: at least one
-plan, an origin, and a verified Stripe connection (clear remediation is printed
-for `STRIPE_NOT_CONNECTED` / `STRIPE_NOT_VERIFIED` / `BILLING_TAX_NOT_ENROLLED`).
+`business publish` enforces the same go-live gates as the dashboard and returns
+stable remediation errors when a prerequisite is missing.
+`business rollback` enqueues a rollback of the specified prior publish workflow
+and requires the exact `business:rollback` permission.
 
-### `farthershore change-set`
+### `farthershore apply-timeline`
 
-Inspect repo-backed change sets — PRs, pushes, releases, checks, semantic diffs,
+Inspect repo-backed applies — PRs, pushes, releases, checks, semantic diffs,
 and apply state — for a business.
 
 ```bash
-farthershore change-set list weather-api --format json
-farthershore change-set inspect weather-api 42 --format json   # by id, PR #, branch, or SHA
+farthershore apply-timeline list weather-api --format json
+farthershore apply-timeline inspect weather-api 42 --format json # by id, PR #, branch, or SHA
 ```
 
 ### `farthershore env`
@@ -274,10 +255,21 @@ Manage preview/production environments. Production is the default scope when
 
 ```bash
 farthershore env list weather-api --format json
+farthershore env list weather-api --filter branch=env/preview --sort createdAt:desc --search preview --format json
 farthershore env create weather-api --name preview --branch env/preview --format json
 farthershore env delete weather-api preview --yes --format json
 ```
 
+### `farthershore organization`
+
+Manage organization members and the exact platform-permission roles assigned
+to them. Built-in and custom roles use the same list contract.
+
+```bash
+farthershore organization role list <organizationId> --filter builtIn=true --sort name --search security --format json
+farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
+```
+
 ### `farthershore plan`
 
 Read code-managed plans and operate live subscriber migrations. The CLI does not
@@ -420,7 +412,7 @@ export async function POST(request: Request) {
 ### `farthershore webhook`
 
 Provision outbound webhook endpoints and inspect delivery health. If the business
-declares webhooks in `business/business.ts`, writes return
+declares webhooks under `business/`, writes return
 `409 MANAGED_BY_CODE` so the repo stays canonical.
 
 ```bash
@@ -457,46 +449,27 @@ update` requires `--kind`, `--duration-months`, and the amount flag for that kin
 whenever you change the code, amount, dates, plan scope, or redemption limits.
 Use `--all-plans` to clear plan scoping.
 
-### `farthershore connect`
+### Farther Shore agent skills
 
-GitHub OAuth and Stripe Connect are browser-only. These commands report status so
-you can poll until the flow is finished in the dashboard.
+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.31.0 or newer.
 
 ```bash
-farthershore connect github --format json
-farthershore connect stripe weather-api --format json
+farthershore skills install --help
+# If the command is unavailable, upgrade to the required CLI release:
+npm install -g @farthershore/cli@0.31.0
+farthershore skills install
 ```
 
-### `farthershore token`
-
-Manage maker tokens for the current org.
-
-```bash
-farthershore token list --format json
-farthershore token create --name "ci-bot" --scope businesses:update businesses:publish --format json
-farthershore token rotate <tokenId> --sync-to-github --format json
-farthershore token revoke <tokenId> --yes --format json
-```
-
-### `farthershore skills`
-
-Inside a business repo, recommend agent skills matching the FartherShore SDK
-versions the repo actually uses. The Business SDK and Frontend SDK tracks are
-recommended independently, so updating one does not force a skill update for the
-other.
-
-```bash
-farthershore skills recommend --format json
-SKILLS_CMD=$(farthershore skills recommend --format json | jq -r '.data.recommendation.command')
-eval "$SKILLS_CMD"
-```
+The Farther Shore CLI downloads the exact installer archive and verifies this
+SHA-512 before it extracts or executes any installer code.
 
 ### `farthershore operations`
 
 Print the machine-readable action boundary: which operations are repo-authored
-(`contract`), which are CLI/API operations (`operate`), which reconcile through
-either path (`dual`), and which are browser-only prerequisites (GitHub linking,
-Stripe Connect).
+(`contract`) and which are CLI/API operations (`operate`).
 
 ```bash
 farthershore operations list --format json
@@ -509,14 +482,8 @@ stdout — `{ ok, op, data }` on success, or `{ ok: false, op, error }` on failu
 where `error` carries a stable `code`, `message`, HTTP `status`, a `retryable`
 flag, and a remediation `hint` when one is registered. Diagnostics go to stderr.
 
-In table mode, failures print `Error [CODE]: message` plus a `Hint:` line:
-
-```text
-Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
-Hint: Stripe isn't connected on this business. Connect it in the dashboard before running billing operations.
-```
-
-The bracketed code is stable across releases — quote it in support threads.
+In table mode, failures print `Error [CODE]: message` plus a `Hint:` line. The
+bracketed code is stable across releases — quote it in support threads.
 
 Exit codes are a branchable taxonomy so a script can tell failure classes apart
 without parsing text:
@@ -532,21 +499,24 @@ without parsing text:
 
 ## CI and agent usage
 
-The CLI is non-interactive whenever a token is available via `--token` or
-`FARTHERSHORE_TOKEN` — `auth login` only prompts when stdin is a TTY and no token
-was passed, so it is safe to script. `farthershore build` and `farthershore
-validate --local-only` need no network or auth and are safe to run in CI.
+Authenticate before unattended work, or supply an organization-scoped
+MakerToken through `FARTHERSHORE_TOKEN`. Device login waits for human approval; use
+`--headless` when the CLI cannot open a browser. `farthershore build` and
+`farthershore validate --local-only` need no network or auth and are safe to
+run in CI.
 
 ## MCP server
 
 The MCP server (`farthershore-mcp`) projects its tools from the same operation
-registry that defines the CLI commands, so every MCP tool has a CLI sibling. Tool
-names use the `fs_*` prefix and cover the agent-operable surface: businesses,
-environments, plans, frontends, backends, runtime tokens, webhooks, promo codes,
-consumers, secrets, personas, usage, and maker tokens.
+registry that defines the CLI commands. Every MCP tool has a CLI sibling, but
+not every CLI command is exposed through MCP. Tool names use the `fs_*` prefix
+and cover only operations explicitly marked agent-operable in that registry.
+Organization, role, member, and invitation administration requires a live-user
+CLI session and is not projected into MCP; audit logs, notifications, and apply
+timelines are also CLI-only.
 
 ```bash
-FARTHERSHORE_TOKEN=mk_xxx farthershore-mcp
+farthershore-mcp
 ```
 
 ## Learn more