@farthershore/cli 0.7.3 → 0.8.0
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.
- package/README.md +76 -50
- package/dist/index.js +143 -143
- package/dist/mcp.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -49,14 +49,14 @@ farthershore auth logout # Clear stored credentials
|
|
|
49
49
|
|
|
50
50
|
## Global flags
|
|
51
51
|
|
|
52
|
-
| Flag
|
|
53
|
-
|
|
|
54
|
-
| `--token <token>`
|
|
55
|
-
| `--api-url <url>`
|
|
56
|
-
| `--env <environment>`
|
|
57
|
-
| `--format <format>`
|
|
58
|
-
| `--version`
|
|
59
|
-
| `--help`
|
|
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
60
|
|
|
61
61
|
## Environment variables
|
|
62
62
|
|
|
@@ -86,13 +86,13 @@ farthershore init --template metered --format json
|
|
|
86
86
|
|
|
87
87
|
Templates (sourced from shared-types `listPlanPresets()`):
|
|
88
88
|
|
|
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
|
|
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 |
|
|
96
96
|
|
|
97
97
|
After `init`, edit `product.name` + `product.baseUrl`, then run
|
|
98
98
|
`farthershore validate` to confirm the scaffolded YAML is acceptable.
|
|
@@ -112,7 +112,18 @@ farthershore product create \
|
|
|
112
112
|
--base-url https://api.example.com \
|
|
113
113
|
--format json
|
|
114
114
|
|
|
115
|
+
# Meter templates — the same smart defaults the dashboard offers:
|
|
116
|
+
# requests (default) | ai-tokens | credits | spend | compute
|
|
117
|
+
farthershore product create --name llm-api --meters ai-tokens --format json
|
|
118
|
+
|
|
119
|
+
# Or a fully custom meter list (key[:display[:unit]], repeatable):
|
|
120
|
+
farthershore product create --name image-api \
|
|
121
|
+
--meter requests \
|
|
122
|
+
--meter images:Images:image \
|
|
123
|
+
--format json
|
|
124
|
+
|
|
115
125
|
farthershore product update weather-api --display-name "Weather" --format json
|
|
126
|
+
farthershore product publish weather-api --format json
|
|
116
127
|
farthershore product delete weather-api --yes --format json
|
|
117
128
|
|
|
118
129
|
farthershore product compile weather-api --dry-run --format json
|
|
@@ -122,7 +133,26 @@ farthershore product compile weather-api --branch env/preview --format json
|
|
|
122
133
|
`product create` provisions a managed GitHub repo and returns clone-URL +
|
|
123
134
|
agent bootstrap instructions in the response. Plan pricing lives on the
|
|
124
135
|
plan (see `farthershore plan create` below) — the product itself no
|
|
125
|
-
longer carries a `billingStrategy`.
|
|
136
|
+
longer carries a `billingStrategy`. Omitting both meter flags gives the
|
|
137
|
+
product a `requests` meter; variable-value meters (tokens, credits, spend)
|
|
138
|
+
are settled from upstream `x-fs-cost-{key}` response headers.
|
|
139
|
+
|
|
140
|
+
A new product starts as a DRAFT with its portal already live in template
|
|
141
|
+
mode. Going live mirrors the dashboard's "Finish setting up" checklist:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
farthershore product create --name llm-api --meters ai-tokens # 1. create
|
|
145
|
+
farthershore plan create llm-api --key pro --name "Pro" \
|
|
146
|
+
--recurring-fee-cents 2900 # 2. how you charge
|
|
147
|
+
farthershore product update llm-api \
|
|
148
|
+
--base-url https://api.example.com # 3. endpoint
|
|
149
|
+
farthershore product publish llm-api # 4. go live
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
`product publish` enforces the same gates as the dashboard: at least one
|
|
153
|
+
plan, a base URL, and a verified Stripe connection (clear remediation is
|
|
154
|
+
printed for `STRIPE_NOT_CONNECTED` / `STRIPE_NOT_VERIFIED` /
|
|
155
|
+
`BILLING_TAX_NOT_ENROLLED`).
|
|
126
156
|
|
|
127
157
|
### `farthershore env`
|
|
128
158
|
|
|
@@ -230,14 +260,14 @@ Every plan is a configuration of 5 orthogonal knobs (shared-types
|
|
|
230
260
|
v0.53.0). Older shapes with `pricing.{model, monthlyPriceCents}` and
|
|
231
261
|
top-level `billing.strategy` are no longer accepted by the validator.
|
|
232
262
|
|
|
233
|
-
| Knob
|
|
234
|
-
|
|
|
235
|
-
| `meters[]`
|
|
236
|
-
| `recurring_fee_cents`
|
|
237
|
-
| `recurring_credit_grant_cents`
|
|
238
|
-
| `one_time_credit_grant_cents`
|
|
239
|
-
| `trial_days`
|
|
240
|
-
| `max_monthly_spend_cents`
|
|
263
|
+
| Knob | Cents/unit | Meaning |
|
|
264
|
+
| ------------------------------ | ---------------- | ------------------------------------------------------- |
|
|
265
|
+
| `meters[]` | micros/unit | Per-dimension usage price (zero or more dimensions) |
|
|
266
|
+
| `recurring_fee_cents` | cents | Charged each billing period (recurring subscription) |
|
|
267
|
+
| `recurring_credit_grant_cents` | cents | Credit issued each period; drains against meter charges |
|
|
268
|
+
| `one_time_credit_grant_cents` | cents | Prepaid balance at subscription start; drains once |
|
|
269
|
+
| `trial_days` | days | Waive everything for N days at the start |
|
|
270
|
+
| `max_monthly_spend_cents` | cents (optional) | Hard cap; the gateway blocks once exceeded (orthogonal) |
|
|
241
271
|
|
|
242
272
|
Billing math (handled by Stripe Billing v2 at invoice finalization):
|
|
243
273
|
`bill = recurring_fee + max(0, total_meter_cost − applied_credit_balance)`.
|
|
@@ -258,21 +288,21 @@ plans:
|
|
|
258
288
|
capacity: 1000
|
|
259
289
|
enforcement: enforce
|
|
260
290
|
|
|
261
|
-
# Flat subscription: recurring fee only
|
|
291
|
+
# Flat subscription: recurring fee only
|
|
262
292
|
- key: starter
|
|
263
293
|
name: Starter
|
|
264
294
|
recurring_fee_cents: 2900
|
|
265
295
|
|
|
266
|
-
# Included usage: fee + monthly credit grant + metered
|
|
296
|
+
# Included usage: fee + monthly credit grant + metered
|
|
267
297
|
- key: pro
|
|
268
298
|
name: Pro
|
|
269
299
|
recurring_fee_cents: 2000
|
|
270
300
|
recurring_credit_grant_cents: 2000
|
|
271
301
|
meters:
|
|
272
302
|
- dimension: requests
|
|
273
|
-
price_per_unit_micros: 1000
|
|
303
|
+
price_per_unit_micros: 1000 # $0.001/request
|
|
274
304
|
|
|
275
|
-
# Overage: fee + metered, no credit
|
|
305
|
+
# Overage: fee + metered, no credit
|
|
276
306
|
- key: growth
|
|
277
307
|
name: Growth
|
|
278
308
|
recurring_fee_cents: 4900
|
|
@@ -280,7 +310,7 @@ plans:
|
|
|
280
310
|
- dimension: requests
|
|
281
311
|
price_per_unit_micros: 500
|
|
282
312
|
|
|
283
|
-
# Prepaid: one-time grant + metered
|
|
313
|
+
# Prepaid: one-time grant + metered
|
|
284
314
|
- key: prepaid
|
|
285
315
|
name: Prepaid
|
|
286
316
|
one_time_credit_grant_cents: 10000
|
|
@@ -288,13 +318,13 @@ plans:
|
|
|
288
318
|
- dimension: requests
|
|
289
319
|
price_per_unit_micros: 1000
|
|
290
320
|
|
|
291
|
-
# Trial: trial_days + recurring fee
|
|
321
|
+
# Trial: trial_days + recurring fee
|
|
292
322
|
- key: trial
|
|
293
323
|
name: Trial
|
|
294
324
|
recurring_fee_cents: 2900
|
|
295
325
|
trial_days: 14
|
|
296
326
|
|
|
297
|
-
# Pay-as-you-go: metered only (no recurring fee)
|
|
327
|
+
# Pay-as-you-go: metered only (no recurring fee)
|
|
298
328
|
- key: metered
|
|
299
329
|
name: Metered
|
|
300
330
|
meters:
|
|
@@ -312,20 +342,19 @@ entries from the legacy knobs so existing specs keep working.
|
|
|
312
342
|
|
|
313
343
|
Valid `kind` values:
|
|
314
344
|
|
|
315
|
-
| Kind | Required fields
|
|
316
|
-
| --------------- |
|
|
317
|
-
| `recurring` | `amount_cents`
|
|
318
|
-
| `one_time` | `amount_cents`
|
|
319
|
-
| `promotional` | `amount_cents`, `label`, optional `expires_after_days`
|
|
320
|
-
| `trial` | (none)
|
|
321
|
-
| `rollover` | `percent` (0–100)
|
|
322
|
-
| `top_up` | `sku`, `label`, `price_cents`, `credit_cents`
|
|
323
|
-
| `auto_recharge` | `threshold_cents`, `refill_cents`
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
warning (only the first is honored).
|
|
345
|
+
| Kind | Required fields | Use case |
|
|
346
|
+
| --------------- | ------------------------------------------------------ | --------------------------------------------------- |
|
|
347
|
+
| `recurring` | `amount_cents` | Monthly credit (e.g. $20 included usage) |
|
|
348
|
+
| `one_time` | `amount_cents` | Signup bonus / prepaid balance |
|
|
349
|
+
| `promotional` | `amount_cents`, `label`, optional `expires_after_days` | Launch bonus, win-back, holiday promo |
|
|
350
|
+
| `trial` | (none) | Trial entry — requires `trial_days > 0` on the plan |
|
|
351
|
+
| `rollover` | `percent` (0–100) | "Unused balance rolls over X% to the next period" |
|
|
352
|
+
| `top_up` | `sku`, `label`, `price_cents`, `credit_cents` | Buy-extra-credit SKU exposed in checkout |
|
|
353
|
+
| `auto_recharge` | `threshold_cents`, `refill_cents` | "When balance < $X auto-purchase $Y" |
|
|
354
|
+
|
|
355
|
+
`recurring`, `rollover`, and `trial` are single-shot per plan;
|
|
356
|
+
declaring more than one entry of the same kind triggers a warning
|
|
357
|
+
(only the first is honored).
|
|
329
358
|
|
|
330
359
|
Example:
|
|
331
360
|
|
|
@@ -351,17 +380,14 @@ plans:
|
|
|
351
380
|
- kind: auto_recharge
|
|
352
381
|
threshold_cents: 500
|
|
353
382
|
refill_cents: 5000
|
|
354
|
-
- kind: minimum_commit
|
|
355
|
-
period: monthly
|
|
356
|
-
amount_cents: 5000
|
|
357
383
|
```
|
|
358
384
|
|
|
359
385
|
The validator surfaces:
|
|
360
386
|
|
|
361
387
|
- **error** — invalid `kind` is rewritten to `Unknown grant kind. Valid kinds: …`
|
|
362
|
-
- **warning** — `grants[]` declares `recurring`/`one_time`
|
|
388
|
+
- **warning** — `grants[]` declares `recurring`/`one_time` _and_ the matching legacy knob is also non-zero (legacy is silently ignored)
|
|
363
389
|
- **warning** — `{ kind: trial }` declared but `trial_days` is 0
|
|
364
|
-
- **warning** — singleton kinds (`recurring`, `rollover`, `trial
|
|
390
|
+
- **warning** — singleton kinds (`recurring`, `rollover`, `trial`) declared more than once
|
|
365
391
|
|
|
366
392
|
#### Deprecation window (Phase 3b)
|
|
367
393
|
|