CLI reference

The farthershore CLI creates and manages products from the terminal. Every command supports --format json for non-TTY scripting, so an agent can drive the whole platform without a browser. Install it globally, or run it with npx.

npm install -g @farthershore/cli
# or
npx @farthershore/cli --help

The same package ships an MCP stdio server (farthershore-mcp) projected from the same operation registry, so every MCP fs_* tool has a sibling CLI command by construction.

Authentication

Create a maker token at farthershore.com/settings/tokens, then store it. Tokens live in ~/.farthershore/credentials.json; FARTHERSHORE_TOKEN overrides the file (use it in CI / agents). See environment variables.

farthershore auth login                 # prompts for the token (TTY)
farthershore auth login --token mk_xxx  # non-interactive
farthershore auth whoami --format json  # current org, role, scopes
farthershore auth logout                # clear stored credentials
export FARTHERSHORE_TOKEN=mk_xxx         # skip the file entirely

Global flags

Available on every command.

Flag	Description
--token <token>	Override the auth token for this command.
--api-url <url>	Override the platform Core API URL.
--env <environment>	Environment scope. production / prod / main are aliases for production (the default when omitted).
--format <format>	json for machine-readable output (default for non-TTY). table is the human default where applicable.
--yes	Skip the confirmation prompt on destructive commands (delete / revoke).
--dry-run	On writes that support it (publish, plan create, plan migrate, backend create, env create, …), preview the change without applying it.
--version / --help	Show version / help.

The CLI exits 0 on success and 1 on any failure. API errors print the stable bracketed code (e.g. Error [STRIPE_NOT_CONNECTED]: …) plus a remediation hint — quote the bracketed code in support threads.

init — scaffold a product repo

Scaffold a starter product/product.config.ts (one decorated @Product class) plus a frontend/ project, from a named plan preset.

farthershore init                                   # interactive (TTY)
farthershore init --template starter --force
farthershore init --template metered --format json
farthershore init --template starter --surface frontend --surface agent

Flag	Description
--template <kind>	Plan preset: free | starter | pro | prepaid | metered. Required when not a TTY.
--surface <surface>	Initial Product SDK surface, repeatable. One of frontend | api | docs | widget | dashboard | webhook | worker | agent. Default: frontend, api.
--path <path>	Output path (default ./product/product.config.ts).
--force	Overwrite an existing config.

build — compile the product locally

Compile product/product.config.ts to a deterministic Manifest IR envelope. CI-safe; the GitHub bot runs the same build on push and applies accepted changes.

farthershore build
farthershore build --entry product/product.config.ts --out manifest-ir.json
farthershore build --format json

Flag	Description
--entry <path>	Entry file (default product/product.config.ts).
--out <path>	Output path (default manifest-ir.json).

product — product lifecycle

farthershore product list --format json
farthershore product show croncloud --env preview --format json
farthershore product status croncloud --format json     # verify it's live after publish
farthershore product create --name croncloud \
  --origin https://api.example.com \
  --repo-owner acme --repo-name croncloud \
  --meters requests --surface frontend --surface api --format json
farthershore product update croncloud --display-name "CronCloud" --format json
farthershore product publish croncloud --format json     # cut a release, go live
farthershore product delete croncloud --yes --format json

Command	Key flags
list	—
show <product>	--env <env>
status <product>	— (returns status, latestReleaseVersion, latestDeployment, derived live)
create	--name (req), --origin (req), --repo-owner (req), --repo-name (req), --display-name, --description, --meters <template>, --meter <key[:display[:unit]]> (repeatable), --surface <type> (repeatable)
update <product>	--display-name, --description, --origin, --confirm-origin-change, --env
publish <product>	--bump <major|minor|patch>, --version <vX.Y.Z>, --accept-breaking, --dry-run
delete <product>	--yes (browser-only for whole products; preview envs deletable via CLI)

--meters takes a template: requests (default) | ai-tokens | credits | spend | compute. Publish requires at least one plan, an origin, and a verified Stripe connection; it auto-derives the semver bump. Pricing lives on the plan (below), not the product.

plan — plan CRUD and migration

Plans use the unified 5-knob spec — pass cents-denominated flags for the knobs the plan needs. See plans and billing strategies.

farthershore plan list croncloud --format json
farthershore plan create croncloud --key free --name "Free" --free --format json
farthershore plan create croncloud --key starter --name "Starter" \
  --recurring-fee-cents 2900 --rate-limit 600 --format json
farthershore plan create croncloud --key pro --name "Pro" \
  --recurring-fee-cents 19900 --grant recurring:2000 --meter requests:1000 --format json
farthershore plan update croncloud <planId> --recurring-fee-cents 3900 --format json
farthershore plan delete croncloud <planId> --yes --format json
farthershore plan migrate croncloud pro --from 1 --to head --policy next_renewal

Command	Key flags
list <product>	--format table|json
create <product>	--key (req), --name (req), --free, --recurring-fee-cents, --grant <kind:cents> (repeatable; recurring/one_time), --trial-days, --max-monthly-spend-cents, --rate-limit <n> / --no-rate-limit, --rate-window <second|minute|hour>, --meter <dim:micros> (repeatable), --env
update <product> <planId>	--name, --recurring-fee-cents, --grant, --trial-days, --max-monthly-spend-cents, --meter, --env
delete <product> <planId>	--yes, --env
migrate <product> <planKey>	--from (req), --to (req), --policy <grandfather|next_renewal|immediate|by_date|opt_in> (req), --proration <none|prorate|credit>, --complete-by <iso8601>

migrate is an OPERATE verb — a transition over live subscribers — and is the replacement for the deleted @Migration decorator. Existing subscribers are grandfathered by default.

env — preview environments

Production is the default scope. A preview environment is bound to a git branch.

farthershore env list croncloud --format json
farthershore env create croncloud --name preview --branch env/preview --format json
farthershore env delete croncloud preview --yes --format json

Command	Key flags
create <product>	--name (req), --branch (req)
delete <product> <envName>	--yes

backend — BYO backends and runtime tokens

Create backends (origins) and mint runtime tokens. Core stores only token hashes; the raw token is returned once — deploy it as FS_RUNTIME_TOKEN and pair it with @farthershore/backend.

farthershore backend list croncloud --format json
farthershore backend create croncloud --name "Production API" \
  --origin-url https://api.example.com --transport direct --default --format json
farthershore backend tokens create croncloud --backend <backendId> --format json
farthershore backend tokens rotate croncloud <tokenId> --format json
farthershore backend tokens revoke croncloud <tokenId> --yes --format json
farthershore backend delete croncloud <backendId> --yes --format json

Command	Key flags
create <product>	--name (req), --slug, --env, --transport <direct|tunnel>, --runner <embedded|sidecar>, --runtime, --origin-url, --default
delete <product> <backendId>	--yes (revokes its runtime tokens)
tokens list <product>	—
tokens create <product>	--backend <id>, --env, --kind <live|test>, --capabilities <list> (gateway_verification, metering, health, tunnel), --meters <list>, --routes <list>
tokens rotate <product> <tokenId>	— (returns a fresh token once)
tokens revoke <product> <tokenId>	--yes

frontend — managed frontend hosting

farthershore frontend status croncloud --format json
farthershore frontend deploy croncloud --ref main --format json
farthershore frontend rollback croncloud --release-id <hash> --format json
farthershore frontend preview --core-url http://localhost:8787   # local vite dev

Command	Key flags
deploy <product>	--ref, --build-cmd, --env
status <product>	--env
rollback <product>	--release-id (req), --env
preview (alias dev)	--dir, --core-url, --clerk-publishable-key, --clerk-sign-in-url, --clerk-satellite-domain, --port (shells out to vite — not a registry op)

persona — test-environment personas

Mint fresh fsk_test_* API keys so an agent can exercise the gateway end-to-end. Test-strategy environments only. See API keys.

farthershore persona bootstrap croncloud --env preview --plan starter --format json
farthershore persona list croncloud --env preview --format json
farthershore persona revoke croncloud <personaId> --env preview --format json

Command	Key flags
bootstrap <product>	--env (req), --plan <planKey>, --display-name
list <product>	--env (req)
revoke <product> <personaId>	--env (req)

usage, connect, token

farthershore usage summary croncloud --format json
farthershore connect github --format json          # poll OAuth status
farthershore connect stripe croncloud --format json # poll Stripe Connect status
farthershore token list --format json
farthershore token create --name ci-bot --scope products:update products:publish --format json
farthershore token revoke <tokenId> --yes --format json

Command	Notes
usage summary <product>	Last-30-day metered usage.
connect github / connect stripe <product>	Status only — the OAuth/Connect flows are browser-only.
token list	List maker tokens.
token create	--name (req), --scope <scope...>, --product <id> (returns the secret once).
token revoke <tokenId>	--yes.