@farthershore/cli 0.7.1 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +342 -251
  2. package/dist/index.js +205 -154
  3. package/dist/mcp.js +141 -123
  4. package/package.json +14 -19
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # @farthershore/cli
2
2
 
3
- Create and manage [FartherShore](https://farthershore.com) API products from the terminal.
3
+ Create and manage [FartherShore](https://farthershore.com) API products from
4
+ the terminal. Designed for AI agents and humans alike — every command supports
5
+ `--format json` for non-TTY scripting.
4
6
 
5
7
  ## Install
6
8
 
@@ -11,7 +13,7 @@ npm install -g @farthershore/cli
11
13
  Or use directly with npx:
12
14
 
13
15
  ```bash
14
- npx @farthershore/cli init my-api
16
+ npx @farthershore/cli --help
15
17
  ```
16
18
 
17
19
  The package also ships an MCP stdio server for agents:
@@ -22,225 +24,387 @@ FARTHERSHORE_TOKEN=mk_xxx npx -p @farthershore/cli farthershore-mcp
22
24
 
23
25
  ## Authentication
24
26
 
25
- Create an API token at [farthershore.com/settings/tokens](https://farthershore.com/settings/tokens), then:
27
+ Create a maker token at
28
+ [farthershore.com/settings/tokens](https://farthershore.com/settings/tokens),
29
+ then store it locally:
26
30
 
27
31
  ```bash
28
- # Interactive — prompts for token
29
- farthershore set-key
32
+ # Interactive — prompts for the token
33
+ farthershore auth login
30
34
 
31
- # Non-interactive — pass token directly
32
- farthershore set-key mk_xxx
35
+ # Non-interactive — pass it directly
36
+ farthershore auth login --token mk_xxx
33
37
 
34
- # Agent-friendly alias
35
- farthershore auth set-key mk_xxx
36
-
37
- # Environment variable (CI / agents)
38
+ # Or skip the file entirely with an env var (CI / agents)
38
39
  export FARTHERSHORE_TOKEN=mk_xxx
39
40
  ```
40
41
 
41
- Tokens are stored in `~/.farthershore/credentials.json`.
42
-
43
- ## Environment scope
44
-
45
- Most product commands can run against production or a named environment.
46
- Production is the default. `production`, `prod`, and `main` all mean the
47
- production scope.
42
+ Tokens are stored in `~/.farthershore/credentials.json`. Maker tokens are
43
+ exchanged for a short-lived CLI access token on first authenticated request.
48
44
 
49
45
  ```bash
50
- farthershore env create preview --branch env/preview --format json
51
- farthershore env use preview --format json
52
- farthershore plan list --env preview --format json
53
- farthershore --env preview meter list --format json
54
- farthershore env run preview -- plan add pro --price-monthly 2900 --format json
55
- farthershore env use production --format json
46
+ farthershore auth whoami # Show current org, role, scopes
47
+ farthershore auth logout # Clear stored credentials
56
48
  ```
57
49
 
58
- `env use` is stored per product in `~/.farthershore/config.json`, so
59
- switching products does not accidentally carry the previous product's
60
- environment.
50
+ ## Global flags
51
+
52
+ | Flag | Description |
53
+ | ---------------------- | ----------------------------------------------------- |
54
+ | `--token <token>` | Override auth token for this command |
55
+ | `--api-url <url>` | Override API base URL |
56
+ | `--env <environment>` | Environment scope (use `production`/`prod`/`main`) |
57
+ | `--format <format>` | `json` for machine-readable output (default for non-TTY) |
58
+ | `--version` | Show version |
59
+ | `--help` | Show help |
60
+
61
+ ## Environment variables
62
+
63
+ | Variable | Description |
64
+ | ---------------------- | ------------------------------------------------------- |
65
+ | `FARTHERSHORE_TOKEN` | API token (overrides stored credentials) |
66
+ | `FARTHERSHORE_API_URL` | API base URL (default: `https://core.farthershore.com`) |
67
+ | `FARTHERSHORE_ENV` | Default environment scope when `--env` is omitted |
61
68
 
62
69
  ## Commands
63
70
 
64
- ### `farthershore init <name>`
71
+ ### `farthershore init`
65
72
 
66
- Create a new API product with a GitHub repo. Returns a clone URL and instructions for an AI agent (or human) to configure it.
73
+ Scaffold a starter `product.yaml` from a named plan preset. Each preset
74
+ fills in the 5-knob spec for a common shape so first-time builders skip
75
+ the blank-page problem.
67
76
 
68
77
  ```bash
69
- farthershore init my-weather-api
70
- ```
78
+ # Interactive walkthrough (TTY only) — pick a preset by number/name + path
79
+ farthershore init
71
80
 
72
- Options:
81
+ # Non-interactive — pass --template explicitly (required when not a TTY)
82
+ farthershore init --template free
83
+ farthershore init --template starter --force
84
+ farthershore init --template metered --format json
85
+ ```
73
86
 
74
- - `--base-url <url>` — Backend API base URL
75
- - `--description <text>` — Product description
76
- - `--display-name <name>` — Display name for the product portal
87
+ Templates (sourced from shared-types `listPlanPresets()`):
77
88
 
78
- The created repo contains:
89
+ | Template | Shape |
90
+ | --------- | ------------------------------------------------------------------ |
91
+ | `free` | $0 plan, hard-enforced 1k requests/month limit |
92
+ | `starter` | $20/mo + $20 included usage, $0.001/request overage |
93
+ | `pro` | $100/mo + $200 included usage, 14-day trial, $0.0005/request |
94
+ | `prepaid` | $50 one-time signup credit, then PAYG |
95
+ | `metered` | Pure pay-as-you-go at $0.001/request |
79
96
 
80
- - `product.yaml` — template config (edit and push to go live)
81
- - `AGENTS.md` — full configuration reference for AI agents
82
- - `docs/` — developer portal documentation
83
- - `.skills/` — task-specific instructions
97
+ After `init`, edit `product.name` + `product.baseUrl`, then run
98
+ `farthershore validate` to confirm the scaffolded YAML is acceptable.
84
99
 
85
- ### `farthershore product create <name>`
100
+ ### `farthershore product`
86
101
 
87
- Create a product through the API and select it as the active product for
88
- subsequent CLI commands. This is the fastest path for an agent that wants
89
- to configure a product without opening the UI.
102
+ Product lifecycle commands — direct API, no local `product.yaml` round-trip.
90
103
 
91
104
  ```bash
92
- farthershore product create weather-api \
105
+ farthershore product list --format json
106
+ farthershore product show weather-api --format json
107
+ farthershore product show weather-api --env preview --format json
108
+
109
+ farthershore product create \
110
+ --name weather-api \
111
+ --display-name "Weather API" \
93
112
  --base-url https://api.example.com \
94
- --strategy prepaid_credits \
95
113
  --format json
114
+
115
+ farthershore product update weather-api --display-name "Weather" --format json
116
+ farthershore product delete weather-api --yes --format json
117
+
118
+ farthershore product compile weather-api --dry-run --format json
119
+ farthershore product compile weather-api --branch env/preview --format json
96
120
  ```
97
121
 
98
- ### `farthershore product status`
122
+ `product create` provisions a managed GitHub repo and returns clone-URL +
123
+ agent bootstrap instructions in the response. Plan pricing lives on the
124
+ plan (see `farthershore plan create` below) — the product itself no
125
+ longer carries a `billingStrategy`.
126
+
127
+ ### `farthershore env`
99
128
 
100
- Return the latest accepted internal product config metadata, including
101
- the accepted config hash and GitHub sync state.
129
+ Manage preview/production environments. Production is the default scope
130
+ when `--env` is omitted; `production`, `prod`, and `main` are aliases.
102
131
 
103
132
  ```bash
104
- farthershore product status --format json
105
- farthershore product status --env preview --format json
133
+ farthershore env list weather-api --format json
134
+ farthershore env create weather-api --name preview --branch env/preview --format json
135
+ farthershore env delete weather-api preview --yes --format json
106
136
  ```
107
137
 
108
- ### `farthershore product config`
138
+ ### `farthershore plan`
109
139
 
110
- Print the accepted or draft product config from FartherShore. GitHub,
111
- the UI, MCP, and the CLI all write through the same validated internal
112
- config path. Accepted config is live; draft config is staged until
113
- `farthershore apply` publishes it.
140
+ Plan CRUD via the management API. The body uses the unified 5-knob
141
+ spec (see "`product.yaml` plan shape" below) — pass cents-denominated
142
+ flags for whichever knobs the plan flavor needs.
114
143
 
115
144
  ```bash
116
- farthershore product config --format json
117
- farthershore product config --format yaml
118
- farthershore product config --state draft --format json
119
- farthershore product config --env preview --format json
120
- ```
145
+ # Human-readable table (default in TTY)
146
+ farthershore plan list weather-api
147
+ farthershore plan list weather-api --format table
148
+
149
+ # JSON envelope (default outside TTY; suitable for jq pipelines)
150
+ farthershore plan list weather-api --format json
151
+
152
+ # Flat subscription: recurring fee only
153
+ farthershore plan create weather-api \
154
+ --key pro \
155
+ --name "Pro" \
156
+ --recurring-fee-cents 2900 \
157
+ --format json
121
158
 
122
- ### `farthershore product attempts`
159
+ # Included usage: fee + monthly credit grant
160
+ farthershore plan create weather-api \
161
+ --key included \
162
+ --name "Included" \
163
+ --recurring-fee-cents 2000 \
164
+ --recurring-credit-grant-cents 2000 \
165
+ --format json
123
166
 
124
- List rejected config proposals. Invalid proposals are recorded for
125
- diagnostics but do not replace the accepted internal config or mutate live
126
- product state.
167
+ # Free plan
168
+ farthershore plan create weather-api --key free --name "Free" --free --format json
127
169
 
128
- ```bash
129
- farthershore product attempts --format json
130
- farthershore product attempts --env preview --format json
170
+ farthershore plan update weather-api <planId> --recurring-fee-cents 3900 --format json
171
+ farthershore plan delete weather-api <planId> --yes --env preview --format json
131
172
  ```
132
173
 
133
- ### `farthershore meter`
174
+ ### `farthershore persona`
134
175
 
135
- Create and manage usage meters in the shared draft product config.
176
+ Test-environment personas — mint fresh `fsk_test_*` API keys so an agent
177
+ can exercise the gateway end-to-end. Only works in test-strategy envs.
136
178
 
137
179
  ```bash
138
- farthershore meter add ai_tokens \
139
- --selector model \
140
- --measure input_tokens \
141
- --measure output_tokens \
142
- --rating provider_catalog \
143
- --catalog llm_models \
144
- --format json
145
-
146
- farthershore meter list --format json
147
- farthershore meter list --env preview --format json
180
+ farthershore persona bootstrap weather-api --env preview --plan pro --format json
181
+ farthershore persona list weather-api --env preview --format json
182
+ farthershore persona revoke weather-api <personaId> --env preview --format json
148
183
  ```
149
184
 
150
- ### `farthershore feature`
185
+ ### `farthershore usage`
151
186
 
152
- Create features and bind or unbind them from plans.
187
+ Read recent usage off the management API.
153
188
 
154
189
  ```bash
155
- farthershore feature add chat_completions \
156
- --route POST:/v1/chat/completions \
157
- --format json
158
-
159
- farthershore feature bind chat_completions --plan pro --format json
160
- farthershore feature list --env preview --format json
190
+ farthershore usage summary weather-api --format json
161
191
  ```
162
192
 
163
- ### `farthershore plan`
193
+ ### `farthershore connect`
164
194
 
165
- Create and update plans in the shared draft product config. Server-side
166
- validation remains authoritative for rules like one free plan, duplicate
167
- paid prices, and product-level billing strategy consistency before apply
168
- can publish.
195
+ GitHub OAuth and Stripe Connect flows are browser-only. These commands
196
+ report status so an agent can poll until the user finishes the flow.
169
197
 
170
198
  ```bash
171
- farthershore plan add free \
172
- --free \
173
- --limit ai_tokens:month:100000:enforce \
174
- --feature chat_completions \
175
- --format json
199
+ farthershore connect github --format json
200
+ farthershore connect stripe weather-api --format json
201
+ ```
176
202
 
177
- farthershore plan add pro \
178
- --price-monthly 2900 \
179
- --credits-monthly-micros 500000000 \
180
- --meter ai_tokens \
181
- --feature chat_completions \
182
- --format json
203
+ ### `farthershore token`
204
+
205
+ Manage maker tokens for the current org.
183
206
 
184
- farthershore plan list --env preview --format json
207
+ ```bash
208
+ farthershore token list --format json
209
+ farthershore token create --name "ci-bot" --scope products:update products:publish --format json
210
+ farthershore token revoke <tokenId> --yes --format json
185
211
  ```
186
212
 
187
- ### `farthershore billing`
213
+ ### `farthershore validate`
188
214
 
189
- Read or change the product-level billing strategy and subscriber change
190
- policy.
215
+ Validate the managed repo (`product.yaml`, `brand.yaml`, `docs/`,
216
+ `skills/`, `.github/workflows/`) through the same backend checks the
217
+ Farther Shore GitHub bot runs.
191
218
 
192
219
  ```bash
193
- farthershore billing strategy get --format json
194
- farthershore billing strategy get --env preview --format json
220
+ farthershore validate
221
+ farthershore validate --format json
222
+ ```
195
223
 
196
- farthershore billing strategy set prepaid_credits \
197
- --transition preserve_current_period \
198
- --format json
224
+ Emits GitHub Actions-formatted annotations when run under `CI` /
225
+ `GITHUB_ACTIONS`.
226
+
227
+ #### `product.yaml` plan shape
228
+
229
+ Every plan is a configuration of 5 orthogonal knobs (shared-types
230
+ v0.53.0). Older shapes with `pricing.{model, monthlyPriceCents}` and
231
+ top-level `billing.strategy` are no longer accepted by the validator.
232
+
233
+ | Knob | Cents/unit | Meaning |
234
+ | ------------------------------- | ---------------- | ------------------------------------------------------------ |
235
+ | `meters[]` | micros/unit | Per-dimension usage price (zero or more dimensions) |
236
+ | `recurring_fee_cents` | cents | Charged each billing period (recurring subscription) |
237
+ | `recurring_credit_grant_cents` | cents | Credit issued each period; drains against meter charges |
238
+ | `one_time_credit_grant_cents` | cents | Prepaid balance at subscription start; drains once |
239
+ | `trial_days` | days | Waive everything for N days at the start |
240
+ | `max_monthly_spend_cents` | cents (optional) | Hard cap; the gateway blocks once exceeded (orthogonal) |
241
+
242
+ Billing math (handled by Stripe Billing v2 at invoice finalization):
243
+ `bill = recurring_fee + max(0, total_meter_cost − applied_credit_balance)`.
244
+
245
+ Every plan flavor — free, flat, included, overage, prepaid, trial,
246
+ pay-as-you-go — is a knob combination. Examples:
247
+
248
+ ```yaml
249
+ # Free plan: explicit `free: true` flag + hard-enforced limit
250
+ plans:
251
+ - key: free
252
+ name: Free
253
+ free: true
254
+ recurring_fee_cents: 0
255
+ limits:
256
+ - dimension: requests
257
+ window: { type: named, name: month }
258
+ capacity: 1000
259
+ enforcement: enforce
260
+
261
+ # Flat subscription: recurring fee only
262
+ - key: starter
263
+ name: Starter
264
+ recurring_fee_cents: 2900
265
+
266
+ # Included usage: fee + monthly credit grant + metered
267
+ - key: pro
268
+ name: Pro
269
+ recurring_fee_cents: 2000
270
+ recurring_credit_grant_cents: 2000
271
+ meters:
272
+ - dimension: requests
273
+ price_per_unit_micros: 1000 # $0.001/request
274
+
275
+ # Overage: fee + metered, no credit
276
+ - key: growth
277
+ name: Growth
278
+ recurring_fee_cents: 4900
279
+ meters:
280
+ - dimension: requests
281
+ price_per_unit_micros: 500
282
+
283
+ # Prepaid: one-time grant + metered
284
+ - key: prepaid
285
+ name: Prepaid
286
+ one_time_credit_grant_cents: 10000
287
+ meters:
288
+ - dimension: requests
289
+ price_per_unit_micros: 1000
290
+
291
+ # Trial: trial_days + recurring fee
292
+ - key: trial
293
+ name: Trial
294
+ recurring_fee_cents: 2900
295
+ trial_days: 14
296
+
297
+ # Pay-as-you-go: metered only (no recurring fee)
298
+ - key: metered
299
+ name: Metered
300
+ meters:
301
+ - dimension: tokens
302
+ price_per_unit_micros: 100
303
+ ```
199
304
 
200
- farthershore billing policy set \
201
- --default preserve_current_period \
202
- --proration none \
203
- --format json
305
+ #### `grants[]` array (shared-types v0.56.0)
306
+
307
+ Plans now accept a typed `grants[]` array that supersedes the two
308
+ legacy grant knobs (`recurring_credit_grant_cents`,
309
+ `one_time_credit_grant_cents`). When `grants[]` is present, the legacy
310
+ knobs are ignored. When absent, the validator silently synthesizes
311
+ entries from the legacy knobs so existing specs keep working.
312
+
313
+ Valid `kind` values:
314
+
315
+ | Kind | Required fields | Use case |
316
+ | --------------- | ---------------------------------------------------------- | -------------------------------------------------------- |
317
+ | `recurring` | `amount_cents` | Monthly credit (e.g. $20 included usage) |
318
+ | `one_time` | `amount_cents` | Signup bonus / prepaid balance |
319
+ | `promotional` | `amount_cents`, `label`, optional `expires_after_days` | Launch bonus, win-back, holiday promo |
320
+ | `trial` | (none) | Trial entry — requires `trial_days > 0` on the plan |
321
+ | `rollover` | `percent` (0–100) | "Unused balance rolls over X% to the next period" |
322
+ | `top_up` | `sku`, `label`, `price_cents`, `credit_cents` | Buy-extra-credit SKU exposed in checkout |
323
+ | `auto_recharge` | `threshold_cents`, `refill_cents` | "When balance < $X auto-purchase $Y" |
324
+ | `minimum_commit`| `period` (`monthly` / `annual`), `amount_cents` | Floor for billing — charge at least this much |
325
+
326
+ `recurring`, `rollover`, `trial`, and `minimum_commit` are single-shot
327
+ per plan; declaring more than one entry of the same kind triggers a
328
+ warning (only the first is honored).
329
+
330
+ Example:
331
+
332
+ ```yaml
333
+ plans:
334
+ - key: pro
335
+ name: Pro
336
+ recurring_fee_cents: 10000
337
+ trial_days: 14
338
+ meters:
339
+ - dimension: requests
340
+ price_per_unit_micros: 500
341
+ grants:
342
+ - kind: recurring
343
+ amount_cents: 20000
344
+ - kind: trial
345
+ - kind: promotional
346
+ amount_cents: 1000
347
+ label: launch-bonus
348
+ expires_after_days: 30
349
+ - kind: rollover
350
+ percent: 25
351
+ - kind: auto_recharge
352
+ threshold_cents: 500
353
+ refill_cents: 5000
354
+ - kind: minimum_commit
355
+ period: monthly
356
+ amount_cents: 5000
204
357
  ```
205
358
 
206
- ### `farthershore transition preview`
359
+ The validator surfaces:
207
360
 
208
- Preview how billing-affecting config changes apply to existing
209
- subscribers before applying them.
361
+ - **error** — invalid `kind` is rewritten to `Unknown grant kind. Valid kinds: …`
362
+ - **warning** — `grants[]` declares `recurring`/`one_time` *and* the matching legacy knob is also non-zero (legacy is silently ignored)
363
+ - **warning** — `{ kind: trial }` declared but `trial_days` is 0
364
+ - **warning** — singleton kinds (`recurring`, `rollover`, `trial`, `minimum_commit`) declared more than once
210
365
 
211
- ```bash
212
- farthershore transition preview --format json
213
- farthershore transition preview --env preview --format json
214
- ```
366
+ #### Deprecation window (Phase 3b)
215
367
 
216
- ### `farthershore validate`
368
+ The product top-level `lifecycle.breaking_changes` block declares the
369
+ breaking-change governance policy enforced on `apply`:
370
+
371
+ ```yaml
372
+ lifecycle:
373
+ breaking_changes:
374
+ require_deprecation_window_days: 90
375
+ require_successor_route: true
376
+ ```
217
377
 
218
- 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.
378
+ When the policy is set:
219
379
 
220
- ```bash
221
- # Validate the current managed repo
222
- farthershore validate
380
+ - `farthershore validate` emits an informational warning so the builder
381
+ sees the active policy locally.
382
+ - `farthershore apply` (which compares the proposed spec against the
383
+ accepted spec) emits a `route_removed` change for every route
384
+ dropped from `features.<x>.routes[]` and warns that the server-side
385
+ `breaking-change-safety-check` cron will gate the publish via
386
+ `ConsumerActivity` lookup. When `require_successor_route` is true,
387
+ the apply path additionally surfaces a successor-required warning.
223
388
 
224
- # Machine-readable diagnostics
225
- farthershore validate --format json
226
- ```
389
+ The CLI never blocks on the window itself — the per-consumer lookup
390
+ lives server-side (Phase 1c `ConsumerActivity` table + Phase 3b cron).
391
+ The CLI's job is to surface the policy and the route delta locally so
392
+ the builder knows what the gate will see.
227
393
 
228
394
  ### `farthershore apply [product]`
229
395
 
230
396
  Publish the shared server draft as one product release. Core accepts the
231
- release only after schema validation, transition-safety validation, and a
232
- compiler dry-run pass. Mutation commands such as `meter add`,
233
- `feature add`, and `plan set-price` stage draft changes by default; they
234
- do not create live product or plan versions until `apply`.
397
+ release only after schema validation, transition-safety validation, and
398
+ a compiler dry-run all pass.
235
399
 
236
400
  ```bash
237
401
  # Publish the current shared draft
238
402
  farthershore apply
239
403
 
240
- # Or pass the product slug explicitly
241
- farthershore apply my-weather-api
404
+ # Or pass the product slug/UUID explicitly
405
+ farthershore apply weather-api
242
406
 
243
- # Validate and compile the draft without publishing
407
+ # Validate and compile without publishing
244
408
  farthershore apply --dry-run --format json
245
409
  farthershore apply --env preview --dry-run --format json
246
410
 
@@ -248,133 +412,62 @@ farthershore apply --env preview --dry-run --format json
248
412
  farthershore apply --to product.yaml --dry-run --format json
249
413
  farthershore apply --to product.yaml --format json
250
414
 
251
- # Also save that local file as the shared draft before publishing
415
+ # Also stage that file as the shared draft before publishing
252
416
  farthershore apply --to product.yaml --save-draft --format json
253
- ```
254
417
 
255
- Draft commands help agents inspect and control the release boundary:
256
-
257
- ```bash
258
- farthershore draft status --format json
259
- farthershore draft diff --format json
260
- farthershore draft validate --format json
261
- farthershore draft reset --format json
418
+ # Pin compilation to a specific branch
419
+ farthershore apply weather-api --branch feature/billing-change --dry-run --format json
262
420
  ```
263
421
 
264
- ## MCP tools
265
-
266
- Run the MCP server with a maker token:
267
-
268
- ```bash
269
- FARTHERSHORE_TOKEN=mk_xxx farthershore-mcp
270
- ```
271
-
272
- The MCP server exposes the same product-building workflow as the CLI:
273
- product create/status/config, environment list/create/use, billing strategy
274
- set, meter add, feature add, plan add, transition preview, and apply.
275
- Every tool accepts optional `product` and `env` fields where relevant and
276
- returns secret-free JSON.
277
-
278
- ### `farthershore set-key [token]`
279
-
280
- Set your API token. Interactive when run in a terminal, or pass the token as an argument for scripts.
281
-
282
- ### `farthershore whoami`
283
-
284
- Show your current authentication context (organization, auth method).
285
-
286
- ### `farthershore logout`
287
-
288
- Clear stored credentials.
289
-
290
- ### `farthershore set-url <url>`
291
-
292
- Override the API base URL (persisted in `~/.farthershore/config.json`).
422
+ JSON output is stable: `{ ok, success, errors, warnings, lifecyclePlan,
423
+ nextActions, ... }`. `lifecyclePlan` is always present (or `null` on
424
+ first deploys / older core builds) and surfaces ADR-0010 per-domain
425
+ subscriber-migration actions.
293
426
 
294
- ### `farthershore reset-url`
427
+ ## Agent workflow
295
428
 
296
- Reset the API base URL to the default (`https://core.farthershore.com`).
297
-
298
- ## Agent Workflow
299
-
300
- The CLI is designed for AI agents to create and configure API products:
429
+ A typical agent flow:
301
430
 
302
431
  ```bash
303
- # 1. Agent receives: create a weather API product
304
- farthershore init weather-api --format json
432
+ export FARTHERSHORE_TOKEN=mk_xxx
305
433
 
306
- # 2. Agent clones the repo
307
- git clone https://github.com/org/weather-api.git
308
- cd weather-api
434
+ farthershore product create \
435
+ --name weather-api \
436
+ --base-url https://api.example.com \
437
+ --format json
309
438
 
310
- # 3. Agent reads AGENTS.md for configuration reference
311
- cat AGENTS.md
439
+ farthershore plan create weather-api --key free --name "Free" --free --format json
440
+ farthershore plan create weather-api \
441
+ --key pro --name "Pro" --recurring-fee-cents 2900 --format json
312
442
 
313
- # 4. Agent validates locally before pushing
314
- farthershore validate
315
-
316
- # 5. Agent pushes — product goes live automatically on valid config
317
- git add -A && git commit -m "Configure product" && git push
443
+ farthershore apply weather-api --dry-run --format json
444
+ farthershore apply weather-api --format json
445
+ farthershore product show weather-api --format json
318
446
  ```
319
447
 
320
- Agents can also complete the flow entirely through API-backed CLI
321
- commands:
448
+ For a YAML-driven flow, edit `product.yaml` in the managed repo, then:
322
449
 
323
450
  ```bash
324
- farthershore auth set-key "$FARTHERSHORE_TOKEN"
325
- farthershore product create weather-api \
326
- --base-url https://api.example.com \
327
- --strategy prepaid_credits \
328
- --format json
329
- farthershore meter add ai_tokens \
330
- --selector model \
331
- --measure input_tokens \
332
- --measure output_tokens \
333
- --rating provider_catalog \
334
- --catalog llm_models \
335
- --format json
336
- farthershore feature add chat_completions \
337
- --route POST:/v1/chat/completions \
338
- --format json
339
- farthershore plan add free \
340
- --free \
341
- --limit ai_tokens:month:100000:enforce \
342
- --feature chat_completions \
343
- --format json
344
- farthershore plan add pro \
345
- --price-monthly 2900 \
346
- --credits-monthly-micros 500000000 \
347
- --meter ai_tokens \
348
- --feature chat_completions \
349
- --format json
350
- farthershore draft validate --format json
351
- farthershore transition preview --format json
352
- farthershore apply --dry-run --format json
353
- farthershore apply --format json
354
- farthershore product status --format json
451
+ farthershore validate --format json
452
+ farthershore apply --to product.yaml --dry-run --format json
453
+ farthershore apply --to product.yaml --format json
355
454
  ```
356
455
 
357
- ## Global Flags
456
+ ## MCP server
358
457
 
359
- | Flag | Description |
360
- | ----------------- | ------------------------------------ |
361
- | `--token <token>` | Override auth token for this command |
362
- | `--api-url <url>` | Override API base URL |
363
- | `--format json` | Output as JSON (default for non-TTY) |
364
- | `--version` | Show version |
365
- | `--help` | Show help |
458
+ The MCP server (`farthershore-mcp`) exposes two tools:
366
459
 
367
- ## Environment Variables
460
+ - `farthershore_draft_validate` — run server-side validation on the shared
461
+ draft.
462
+ - `farthershore_apply` — apply the draft, optionally with a `product.yaml`
463
+ proposal via `toFile`. Defaults to `dryRun: true`.
368
464
 
369
- | Variable | Description |
370
- | ---------------------- | ------------------------------------------------------- |
371
- | `FARTHERSHORE_TOKEN` | API token (overrides stored credentials) |
372
- | `FARTHERSHORE_API_URL` | API base URL (default: `https://core.farthershore.com`) |
465
+ Both accept optional `product` and `env` fields and return JSON.
373
466
 
374
467
  ## Errors and exit codes
375
468
 
376
469
  The CLI exits `0` on success and `1` on any failure (including
377
- `commander`-level argument errors). When the API returns a 4XX/5XX, the
470
+ commander-level argument errors). When the API returns a 4XX/5XX, the
378
471
  CLI prints the canonical error code in brackets and a one-line
379
472
  remediation hint when one is registered:
380
473
 
@@ -383,17 +476,15 @@ Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
383
476
  Hint: Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.
384
477
  ```
385
478
 
386
- The bracketed code is stable across releases — quote it in support
387
- threads.
479
+ The bracketed code is stable across releases — quote it in support threads.
388
480
 
389
- `farthershore whoami --format json` emits a stable JSON shape suitable
390
- for CI scripts. On the not-authenticated path it emits
391
- `{ "authenticated": false }` with exit code `1`.
481
+ `farthershore auth whoami --format json` emits a stable JSON shape suitable
482
+ for CI scripts.
392
483
 
393
484
  ## CI / agent usage
394
485
 
395
486
  The CLI is non-interactive whenever a token is available via the
396
- `--token` flag or `FARTHERSHORE_TOKEN` env var — `set-key` only prompts
397
- when stdin is a TTY and no token argument was passed, so it's safe to
398
- script. `validate` and `apply` emit GitHub Actions-formatted annotations
399
- when run under `CI` / `GITHUB_ACTIONS`.
487
+ `--token` flag or `FARTHERSHORE_TOKEN` env var — `auth login` only
488
+ prompts when stdin is a TTY and no token argument was passed, so it's
489
+ safe to script. `validate` and `apply` emit GitHub Actions-formatted
490
+ annotations when run under `CI` / `GITHUB_ACTIONS`.