@farthershore/cli 0.41.0 → 0.44.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/CHANGELOG.md +25 -0
- package/LICENSE +21 -0
- package/README.md +85 -22
- package/dist/index.js +648 -753
- package/package.json +6 -4
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,31 @@ All notable changes to the `farthershore` CLI are documented here. The CLI
|
|
|
4
4
|
versions independently from the SDKs. Pre-1.0: minor versions may include
|
|
5
5
|
breaking changes. Releases before 0.35.0 are recorded only in the git history.
|
|
6
6
|
|
|
7
|
+
## [0.44.0] - 2026-11-20
|
|
8
|
+
|
|
9
|
+
- Add `farthershore organization seller-details show`: the seller details every business in the organization shows its customers, read from the organization's Stripe account.
|
|
10
|
+
- Add `farthershore account export` to download your own personal data as JSON, and `farthershore account deletion-status` to follow an account deletion started in the dashboard.
|
|
11
|
+
- Add `farthershore consumer export` to export one customer's data as JSON, and `farthershore consumer erasure-status` to read the status of that customer's data erasure.
|
|
12
|
+
- Add `farthershore legal status` to read whether the platform's current legal documents have been accepted.
|
|
13
|
+
|
|
14
|
+
## [0.43.0] - 2026-11-18
|
|
15
|
+
|
|
16
|
+
- Global npm installs on macOS and Linux silently check npm latest hourly after successful commands. Upgrade-required responses update and re-run once (not when the command read stdin). pnpm and Windows installs are not updated automatically.
|
|
17
|
+
- Add `farthershore update`, `FARTHERSHORE_NO_UPDATE=1`, and `autoUpdate: false` configuration (a config file with only `autoUpdate` is valid). CI and unowned installs skip automatic updates.
|
|
18
|
+
- **Breaking:** Removed `business rollback` and the retired BusinessApply/Rollback workflow filters. Recover a Business contract through a reviewed repository fix and a new release.
|
|
19
|
+
- Protect configuration lock recovery and release with owner identity; identify reused processes and explain safe manual recovery when ownership cannot be confirmed.
|
|
20
|
+
- Serialize concurrent link and notice updates; warn when older directory links need explicit relinking with `farthershore link <business>`.
|
|
21
|
+
- Write configuration atomically, reject corrupt configuration, and scope directory links and saved organization selection to the API URL.
|
|
22
|
+
|
|
23
|
+
> A CLI published to `latest` must work against the Core running in
|
|
24
|
+
> production at publish time. A CLI that needs an unreleased Core is
|
|
25
|
+
> published under the `next` dist-tag and promoted to `latest` after the
|
|
26
|
+
> platform release.
|
|
27
|
+
|
|
28
|
+
## [0.42.0] - 2026-11-18
|
|
29
|
+
|
|
30
|
+
- Use `/agent/v1/whoami` for login and credential validation after retirement of `/management`. Core now requires CLI 0.42.0 or newer.
|
|
31
|
+
|
|
7
32
|
## [0.41.0] - 2026-11-09
|
|
8
33
|
|
|
9
34
|
- **Breaking:** `business rollback` now sends `publishId` and reads
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Farther Shore
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Create and operate [FartherShore](https://farthershore.com) software businesses
|
|
4
4
|
from the terminal.
|
|
5
5
|
|
|
6
|
-
**Status: `0.
|
|
6
|
+
**Status: `0.44.0`.** Pre-1.0 — the command surface is stable but may still
|
|
7
7
|
change between minor versions. Pin an exact version in CI.
|
|
8
8
|
|
|
9
9
|
FartherShore lets you define a software business as code, then sells, meters,
|
|
@@ -20,13 +20,13 @@ takes `--format json` for non-interactive scripting.
|
|
|
20
20
|
## Install
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
|
-
npm install -g @farthershore/cli@0.
|
|
23
|
+
npm install -g @farthershore/cli@0.44.0
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
Or run it directly with npx:
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
|
-
npx -p @farthershore/cli@0.
|
|
29
|
+
npx -p @farthershore/cli@0.44.0 farthershore --help
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
## Authentication
|
|
@@ -135,6 +135,16 @@ write commands cover **operational** state that lives outside the manifest
|
|
|
135
135
|
| `FS_CLI_CHANNEL` | `stage` enables stage-channel commands for one invocation (see below) |
|
|
136
136
|
| `FS_CLI_STAGE_HOSTS` | Extra hosts (comma separated) the stage-channel gate treats as stage |
|
|
137
137
|
|
|
138
|
+
Directory links (business, organization, and environment) and the saved default
|
|
139
|
+
organization apply only to the API base URL where they were selected. Switching
|
|
140
|
+
`--api-url` or `FARTHERSHORE_API_URL` does not reuse another API's context. Existing
|
|
141
|
+
unscoped directory links must be recreated with `farthershore link`; select a
|
|
142
|
+
default organization again with `farthershore auth organization use`.
|
|
143
|
+
|
|
144
|
+
Configuration writes use an atomic replacement. If an existing
|
|
145
|
+
`~/.farthershore/config.json` is corrupt or lacks a valid API URL, commands fail
|
|
146
|
+
with a repair message; restore or repair the file before continuing.
|
|
147
|
+
|
|
138
148
|
## Stage-channel commands
|
|
139
149
|
|
|
140
150
|
A few operations exist only to service stage. `farthershore business delete` is
|
|
@@ -163,7 +173,7 @@ Business deletion for teardown uses only the stage command’s raw request.
|
|
|
163
173
|
|
|
164
174
|
The raw `api` command applies both gates too: a request that the platform
|
|
165
175
|
serves as `business delete` (`-X DELETE /businesses/<id>`, or its
|
|
166
|
-
`/
|
|
176
|
+
`/agent/v1/...` forms) is refused with
|
|
167
177
|
`COMMAND_NOT_AVAILABLE_IN_PRODUCTION` outside the stage channel and against a
|
|
168
178
|
non-stage api-url, before any request and whatever `--yes` says.
|
|
169
179
|
|
|
@@ -309,7 +319,6 @@ farthershore business create weather-api \
|
|
|
309
319
|
--format json
|
|
310
320
|
|
|
311
321
|
farthershore business publish weather-api --format json
|
|
312
|
-
farthershore business rollback weather-api wfe_previous --reason "bad release" --yes --format json
|
|
313
322
|
```
|
|
314
323
|
|
|
315
324
|
Deleting a business is **stage only** — the command is not registered in the
|
|
@@ -349,11 +358,9 @@ farthershore business update weather-api \
|
|
|
349
358
|
|
|
350
359
|
`business publish` enforces the same go-live gates as the dashboard and returns
|
|
351
360
|
stable remediation errors when a prerequisite is missing.
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
`execution.id`. Pass that value unchanged. The rollback receipt returns
|
|
356
|
-
`rollbackPublishId` for the newly queued rollback.
|
|
361
|
+
Recover a Business contract by correcting or reverting its program in Git,
|
|
362
|
+
validating it in preview, and publishing a new release. Use `business status`
|
|
363
|
+
and Apply Timeline to verify the expected release is serving.
|
|
357
364
|
|
|
358
365
|
`business rbac` reads a business's Managed-RBAC state — the platform-owned
|
|
359
366
|
`rbacEnabled` flag. `business rbac enable` / `disable` toggle that flag (like
|
|
@@ -459,9 +466,10 @@ If a create or update times out, run `token list --org` before trying again.
|
|
|
459
466
|
### `farthershore stripe`
|
|
460
467
|
|
|
461
468
|
Read the Stripe account a business bills through. Reading status requires a
|
|
462
|
-
signed-in owner session. Connecting
|
|
463
|
-
settings
|
|
464
|
-
|
|
469
|
+
signed-in owner session. Connecting Stripe, finishing its setup, opening payout
|
|
470
|
+
settings, disconnecting and closing require a person in the dashboard after a
|
|
471
|
+
fresh sign-in; disconnecting and closing also ask for the name to be typed. The
|
|
472
|
+
CLI does not perform these actions.
|
|
465
473
|
|
|
466
474
|
```bash
|
|
467
475
|
farthershore stripe status weather-api --format json
|
|
@@ -543,6 +551,9 @@ farthershore plan list weather-api # table (default in TTY)
|
|
|
543
551
|
farthershore plan list weather-api --format json
|
|
544
552
|
```
|
|
545
553
|
|
|
554
|
+
Plan listings show recurring fees, trial days, and status. The v2 listing no longer
|
|
555
|
+
includes plan kind, a free flag, or a monthly spend cap.
|
|
556
|
+
|
|
546
557
|
### `farthershore frontend`
|
|
547
558
|
|
|
548
559
|
Managed Frontend Hosting status, rollback, and a local preview. Builds are
|
|
@@ -683,7 +694,14 @@ public `FS_PUBLIC_*` values and secret metadata. Business-wide variables are
|
|
|
683
694
|
inherited by previews unless an environment override exists. Inherited secrets
|
|
684
695
|
require a verified repository pusher with write access; fork previews and
|
|
685
696
|
previews without verified identity cannot use them. Rotation updates the source
|
|
686
|
-
value without copying secrets into previews.
|
|
697
|
+
value without copying secrets into previews. A preview stops using inherited
|
|
698
|
+
secrets within 15 seconds of GitHub reporting that the pusher was removed or their
|
|
699
|
+
access changed, for example a lowered collaborator permission or a team losing
|
|
700
|
+
the repository. Write access is also checked again every 15 minutes, so a change
|
|
701
|
+
GitHub does not report stops them within about 20 minutes.
|
|
702
|
+
|
|
703
|
+
Revoke, rotate and delete take effect for live requests within 15 seconds of
|
|
704
|
+
being acknowledged; until then a request may still use the previous value.
|
|
687
705
|
|
|
688
706
|
Use `--production-only` when creating a business-wide secret to exclude it from
|
|
689
707
|
previews. The flag cannot be used for public variables or with a preview
|
|
@@ -827,19 +845,23 @@ Use `--all-plans` to clear plan scoping.
|
|
|
827
845
|
Install or refresh the platform-verified skills bundle together. The platform
|
|
828
846
|
pins this immutable release, and CI plus a daily repository check compare it to
|
|
829
847
|
GitHub's latest stable release so the guidance cannot silently drift.
|
|
830
|
-
|
|
848
|
+
|
|
849
|
+
The v4.0.0 bundle replaces five prior workflow names with the six current
|
|
850
|
+
workflows. After a successful install, exact Farther Shore-owned retired
|
|
851
|
+
entries are moved to recoverable `.farthershore-retired-skills-*` backups only
|
|
852
|
+
in directories containing the complete verified new bundle. Incomplete installs,
|
|
853
|
+
custom and unrecognized skills are left in place.
|
|
831
854
|
|
|
832
855
|
```bash
|
|
833
856
|
set -euo pipefail
|
|
834
|
-
CLI_VERSION=$(farthershore --version)
|
|
835
|
-
printf '%s' "$CLI_VERSION" | node -e 'let v=""; process.stdin.on("data", c => v += c).on("end", () => { const m = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim()); if (!m || !(+m[1] > 0 || +m[2] > 41 || (+m[2] === 41 && +m[3] >= 0))) { console.error("Stop: CLI 0.41.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
|
|
836
857
|
farthershore skills install --help
|
|
837
858
|
farthershore skills install
|
|
838
859
|
```
|
|
839
860
|
|
|
840
|
-
If
|
|
841
|
-
`npm install -g @farthershore/cli@0.
|
|
842
|
-
|
|
861
|
+
If the platform-owned skills installer is unavailable, stop and ask the human to run
|
|
862
|
+
`npm install -g @farthershore/cli@0.44.0`, then repeat the installer help check.
|
|
863
|
+
The CLI keeps itself current (see Staying up to date); do not otherwise install
|
|
864
|
+
or upgrade global tooling autonomously.
|
|
843
865
|
|
|
844
866
|
The Farther Shore CLI downloads the exact installer archive and verifies this
|
|
845
867
|
SHA-512 before it extracts or executes any installer code.
|
|
@@ -864,7 +886,7 @@ yet. Every endpoint is described in the platform's OpenAPI document
|
|
|
864
886
|
farthershore api /businesses
|
|
865
887
|
farthershore api 'businesses/{business}/environments' --paginate
|
|
866
888
|
farthershore api -X PATCH 'businesses/{business}' -f displayName='Weather API'
|
|
867
|
-
farthershore api '
|
|
889
|
+
farthershore api 'agent/v1/businesses/{business}/backends' -f name=api -f originUrl=https://api.example.com -F isDefault=true --dry-run
|
|
868
890
|
farthershore api -X POST 'businesses/{business}/promo-codes' --input promo.json
|
|
869
891
|
farthershore api -X DELETE 'businesses/{business}/environments/{env}' --env preview-1 --yes
|
|
870
892
|
farthershore api 'builder/organizations/{org}/members' --include
|
|
@@ -1074,7 +1096,48 @@ Code discovery includes docs guides: `farthershore code search runtime token`.
|
|
|
1074
1096
|
Read one with `farthershore code describe docs:agents/overview`; describe accepts
|
|
1075
1097
|
1–25 method paths, opKeys, or docs refs. Use `--no-guides` or `--namespace` to
|
|
1076
1098
|
search methods only. Use `--stage` to select stage docs; production is the default.
|
|
1077
|
-
For exact catalog filtering, use `farthershore code search --code 'return catalog.filter(m => m.
|
|
1099
|
+
For exact catalog filtering, use `farthershore code search --code 'return catalog.filter(m => m.required.includes("tokenId")).map(m => m.method)'`
|
|
1078
1100
|
or `--code-file script.js`. Filters have a frozen catalog and no platform access.
|
|
1101
|
+
Entries include `input` and `output` as TypeScript text (`input` is null for
|
|
1102
|
+
methods without arguments), and `required` lists top-level required field names.
|
|
1079
1103
|
`farthershore docs search "runtime token"` uses docs search and falls back to
|
|
1080
1104
|
literal text when unavailable. `--literal` or `--collection` forces literal search.
|
|
1105
|
+
|
|
1106
|
+
Rename a usage unit for display without changing reporting keys or balances:
|
|
1107
|
+
|
|
1108
|
+
```sh
|
|
1109
|
+
farthershore business update <business> --usage-unit-label "Requests"
|
|
1110
|
+
farthershore business update <business> --clear-usage-unit-label
|
|
1111
|
+
```
|
|
1112
|
+
|
|
1113
|
+
The same operation is available to MCP as `fs.businesses.brand.update` with
|
|
1114
|
+
`body.usageUnitLabel: { unitKey: "credits:tokens", label: "Requests" }`.
|
|
1115
|
+
Use `label: null` to restore the default.
|
|
1116
|
+
|
|
1117
|
+
### Export your data
|
|
1118
|
+
|
|
1119
|
+
Run `farthershore account export --format json > personal-data.json` with your personal session to export your account data. Organization credentials cannot use this command.
|
|
1120
|
+
|
|
1121
|
+
Export a customer’s business-scoped data: `farthershore consumer export <businessIdOrSlug> <subscriberId> --format json`.
|
|
1122
|
+
|
|
1123
|
+
Check a request without changing customer data: `farthershore consumer erasure-status <businessIdOrSlug> <subscriberId> --format json`. A person must request erasure in the dashboard.
|
|
1124
|
+
|
|
1125
|
+
## Staying up to date
|
|
1126
|
+
|
|
1127
|
+
Global npm installs on macOS and Linux (including a custom npm `prefix` set
|
|
1128
|
+
in `~/.npmrc`) update automatically to npm `latest` in
|
|
1129
|
+
the background after a successful command, at most once an hour. A command
|
|
1130
|
+
refused because the CLI is too old updates immediately and re-runs once; a
|
|
1131
|
+
command that read standard input is not re-run, so run it again yourself.
|
|
1132
|
+
Updates only move forward, use the official npm registry, and never change
|
|
1133
|
+
command stdout. pnpm installs, Windows, CI, source checkouts, project
|
|
1134
|
+
dependencies, and `npx` runs are not updated automatically; update those with
|
|
1135
|
+
the tool you used to install the CLI.
|
|
1136
|
+
|
|
1137
|
+
To opt out, set `FARTHERSHORE_NO_UPDATE=1` or add `"autoUpdate": false` to
|
|
1138
|
+
`~/.farthershore/config.json`. A config file containing only
|
|
1139
|
+
`{"autoUpdate": false}` is valid. If that file exists but cannot be read,
|
|
1140
|
+
automatic updates stay off. Automation should set the environment variable.
|
|
1141
|
+
Run `farthershore update` to check and update explicitly, ignoring the hourly
|
|
1142
|
+
window and opt-outs (including CI); `--format json` reports
|
|
1143
|
+
`{ from, to, updated }`.
|