@farthershore/cli 0.30.0 → 0.31.0

package/README.md

@@ -3,54 +3,84 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.30.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: provision a managed business repo, validate it locally before you push,
-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="$FARTHERSHORE_TOKEN" npx -p @farthershore/cli farthershore-mcp
+npx -p @farthershore/cli@0.31.0 farthershore-mcp
 ```
 
 ## Authentication
 
-Use the credential supplied to the current environment:
+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
-export FARTHERSHORE_TOKEN="<provided credential>"
+farthershore login
 farthershore auth whoami --format json
 ```
 
-The CLI exchanges that credential for a short-lived access token on the first
-authenticated request. Do not write credentials into the managed repository.
+On a headless machine, print the same handoff without trying to open a browser:
 
 ```bash
-farthershore auth logout         # Clear stored credentials
+farthershore login --headless
 ```
 
+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.
+
+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>
+```
+
+For a separately issued organization-scoped MakerToken, pipe it through bounded stdin:
+
+```bash
+printf %s "$FARTHERSHORE_MAKER_TOKEN" | farthershore login --token-stdin
+```
+
+`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
 
 Create a managed business repo, author the business, validate it, and push:
@@ -62,22 +92,28 @@ REPO_URL=$(farthershore business create 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. 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).
 
@@ -85,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) |
@@ -97,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               |
 
@@ -105,6 +140,14 @@ write commands cover **operational** state that lives outside the manifest
 
 Run `farthershore <group> --help` for the full flag set of any command.
 
+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`
 
 Create local project components inside a managed builder repo. `create api`
@@ -124,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.
@@ -157,6 +200,7 @@ 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
 
@@ -165,6 +209,7 @@ farthershore business create weather-api \
   --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
 ```
 
@@ -190,15 +235,17 @@ farthershore business update weather-api \
 
 `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`
@@ -208,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
@@ -354,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
@@ -393,14 +451,21 @@ Use `--all-plans` to clear plan scoping.
 
 ### Farther Shore agent skills
 
-Install or refresh the complete skills bundle together. When a newer tagged
-bundle is available, the CLI prints the same command with the release tag in
-the GitHub URL.
+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
-npx skills add https://github.com/farther-shore/skills/tree/v2.1.0 --skill '*' -g -y
+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
 ```
 
+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
@@ -434,22 +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, organizations, audit logs, notifications, plans, frontends,
-backends, runtime tokens, webhooks, promo codes, consumers, secrets, personas,
-and usage.
+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="$FARTHERSHORE_TOKEN" farthershore-mcp
+farthershore-mcp
 ```
 
 ## Learn more