Environments
Preview, stage, and production environments — each bound to a git branch, each with its own edge snapshot.
Preview, stage, and production environments — each bound to a git branch, each with its own edge snapshot.
A product has one production environment plus any number of preview environments. Each preview is bound to a git branch: push the branch and that environment's snapshot applies to its own edge, with its own portal and runtime hostnames — fully isolated from production. Use a preview to exercise a real product (gateway enforcement, metering, plan limits, routing) with a real test key before a paying subscriber depends on the change.
Production is the default scope when --env is omitted. production, prod, and
main are interchangeable aliases for it.
A preview tracks a branch. Pushing that branch applies the product's manifest to
the preview edge synchronously (the ENV_PUSH apply path — see
Apply & deploy); creating the environment via the CLI is the
equivalent of pushing the branch — both reconcile to the same environment.
# Create a preview env bound to a git branch.
farthershore env create croncloud \
--name preview \
--branch env/preview \
--format json
# List a product's environments (name, branch, hostnames, status).
farthershore env list croncloud --format json
# Tear a preview down (production cannot be deleted this way).
farthershore env delete croncloud preview --yes --format json
env list returns each environment's name, the branch it tracks, its
portalHostname and runtimeHostname (the per-env edge endpoints), and a derived
status:
{
"productId": "prod_...",
"count": 2,
"environments": [
{ "id": "env_prod", "name": "production", "branch": "main",
"portalHostname": "croncloud.farthershore.xyz", "runtimeHostname": "croncloud.farthershore.com", "status": "active" },
{ "id": "env_preview", "name": "preview", "branch": "env/preview",
"portalHostname": "preview.croncloud.farthershore.xyz", "runtimeHostname": "preview.croncloud.farthershore.com", "status": "active" }
]
}
Pass --env <name> to read or write within a preview. The same flag scopes
product, plan, backend, and persona operations. Without it, you operate on
production.
# Read a product as it exists in a preview.
farthershore product show croncloud --env preview --format json
# Edit a plan only in the preview (production untouched).
farthershore plan delete croncloud <planId> --env preview --yes --format json
Plans, pricing, and routes are managed as code. A
preview is the right place to try a manifest change behind a branch, but the
change still lands by editing product/product.config.ts and pushing — not by an
API call against the live spec.
A test-strategy environment can mint a fresh fsk_test_* API key — a
persona — so you (or an agent) can curl the gateway and verify metering before
going live. Personas only work in test envs.
# Mint a test key on the preview, assigned the "pro" plan.
farthershore persona bootstrap croncloud --env preview --plan pro --format json
farthershore persona list croncloud --env preview --format json
farthershore persona revoke croncloud <personaId> --env preview --format json
Use the returned key as the gateway credential to drive the product's routes —
for example CronCloud's POST /v1/cron-jobs — and watch usage accrue under the
assigned plan's limits.
A backend and its FS_RUNTIME_TOKEN can be scoped to one
environment, so a preview can point at a staging origin while production points at
the real one.
# Backend bound to the preview env.
farthershore backend create croncloud \
--name "Staging API" \
--origin-url https://staging.api.example.com \
--env preview \
--format json
# Runtime token scoped to the preview (omit --env for production).
farthershore backend tokens create croncloud --backend <backendId> --env preview --format json
Production is the main-tracked environment and the default scope. An economic
change pushed to the default branch validates and accepts, but defers its live
edge apply to a GitHub Release (see
Economic changes).
Confirm production is serving the snapshot you expect with:
farthershore product status croncloud --format json # status, latest release, live