Skip to content
Back to skills

Lifecycle

ASecurity

Stopping, starting and deleting a HOSTED environment from the CLI — `forge env stop|start|delete`, --target and --wait, billing refusals, data retention and `forge env retained list|purge`, and why `forge env down` is not the same thing; the whole app with `forge app stop|teardown|delete`; plus the domain commands and scope errors.

  • 10 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 13, 2026
ai-agentsgoshellapidatabasefrontend

Works with

  • cli
  • api

Security analysis

A100/100

Scanned November 18, 2026

npx -y skills add reliant-labs/forge --skill lifecycle --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Lifecycle?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Lifecycle
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-lifecycle/badge)](https://www.skillsdirectory.com/skills/reliant-labs-lifecycle)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: deploy/lifecycle
description: Stopping, starting and deleting a HOSTED environment from the CLI — `forge env stop|start|delete`, --target and --wait, billing refusals, data retention and `forge env retained list|purge`, and why `forge env down` is not the same thing; the whole app with `forge app stop|teardown|delete`; plus the domain commands and scope errors.
---

# Hosted env lifecycle

Everything the Reliant UI does to a hosted env is available from the CLI. Signed
in to Reliant (running `reliant forge …`, or in a Reliant agent's shell) you are
already authenticated — do NOT run `forge login`; forge asks Reliant's
credential helper (`$FORGE_CREDENTIAL_HELPER`) for a short-lived token. Standalone
forge uses `forge login`; CI sets the env's token variable.

```
forge env stop prod [--target api] [--wait]    # suspend; never refused
forge env start prod [--target api] [--wait]   # resume; refused with the billing reason if not entitled
forge env delete preview [--yes] [--keep-data] # tear the env down, data included
```

- `--target` takes a workload name (resolved to its deployment id); without it
  the whole environment changes. After the call forge prints each deployment's
  DECLARED state; the platform converges asynchronously.
- `--wait` polls until the platform OBSERVES the new state (`--timeout`,
  default 5m) and exits non-zero on timeout.
- A refused `start` prints the server's reason and the fix; nothing is started.
- `delete` prompts you to type the env name. With no TTY or `CI=1` it fails
  fast unless you pass `--yes`. It removes EVERYTHING the env runs: its
  deployments, workloads, URLs, Flux objects, custom resources, namespaces and
  its managed databases' data (irreversible). `--keep-data` retains each
  managed database instead: it keeps running and billing as storage and is
  listed as a retained database until purged; a re-deploy creates a NEW env and
  does not reattach it. The project's registry images are kept either way.
- `delete` also removes a hosted env whose `deploy/kcl/<env>/` is gone: it is
  looked up by name on the control plane the project is bound to
  (`.forge/hosted-projects.json`), or on the one `--endpoint <url>` names when
  the project is bound to none or several. `--endpoint` must be one of those
  bindings or Reliant cloud; any other host is refused before a credential is
  sent. `--id <environment-id>` names such an env by the control plane's id
  instead (refused if the env belongs to another project, or is still
  declared). `forge env list --orphaned` lists the hosted envs this project no
  longer declares.
- Before confirming, `delete` shows the env's id, project, control plane,
  deployment count and bound custom domains. The control plane refuses to
  delete an env while a custom domain is bound to it: `forge domain unbind`
  each first. If the bound domains cannot be read, `delete` stops before
  confirming and deletes nothing.
- All three refuse an env that is not hosted. `forge env down` only stops local
  host processes and never touches a control plane.

## Retained databases

A database kept by `--keep-data` is a RETAINED database: still running, still
billing as storage, never reattached by a later deploy.

```
forge env retained list [--all]          # this app's (--all: the organization's), with size and dates
forge env retained purge <id> [--all] [--yes]  # destroy one: type its name to confirm. IRREVERSIBLE
```

`purge` takes the id `list` prints, or a database name when exactly one of
this app's retained databases has it. Either resolves among THIS app's: another
app's is refused and named; `--all` resolves among the organization's, and the
confirmation names the owning app. A control plane that purges retained
databases by itself shows the date in a `PURGE AFTER` column; an older one
does not, and its databases stay until purged. Purging needs an org owner or
admin.

## The whole app: stop, tear down, delete

The app is every hosted env of this project (forge.yaml `name`) on the control
plane the project is bound to (`.forge/hosted-projects.json`, or
`--endpoint`). Least to most destructive:

```
forge app stop [--yes]                   # suspend every env; storage keeps billing
forge app teardown [--yes] [--keep-data] # delete every env, keep the app; nothing bills
forge app delete [--yes]                 # schedule the app's deletion (7-day grace window)
forge app delete --status | --cancel     # show it / cancel it until the purge starts
```

- Each asks you to type the app name (`--yes` skips it; with no TTY or `CI=1`
  it fails fast without `--yes`), and `stop` and `teardown` print each env's
  outcome. An env the control plane refuses (`stop` needs `deploy:write` on
  it; `teardown` an org owner or admin) is reported and left as it was, the
  rest still change, and the command exits non-zero.
- `stop` keeps URLs, data, secrets and domains; `forge env start <env>`
  resumes an env. Storage keeps billing: `teardown` is the zero-cost state.
- `teardown` is `forge env delete` for every env: data destroyed unless
  `--keep-data` (then listed by `forge env retained list`). It keeps the app's
  name, release history and release images (not billed) and its custom domains
  (unbound), so `forge env deploy <env> <release>` recreates an env. Each env's
  secrets are not given back to a recreated env: set them again. It deletes
  nothing while a custom domain is bound to one of the envs (`forge domain
  unbind` it first), when the bound domains cannot be read (the domain service
  failing, or a control plane without one), or while an env this project
  declares also runs parts on a cluster you operate.
- `delete` stops every env at once and refuses new deploys, promotions and
  envs (reason `app_deletion_scheduled`). After the grace window the control
  plane purges every env and its data, retained databases, release history and
  images, domains and certificates, and secrets, and frees the name; activity,
  audit and spend history stay. `--cancel` starts again what the deletion
  stopped. `--status` also says when the purge waits on a paused secret
  destroy. It needs an org owner or admin signed in as a person (tokens are
  refused) with a live step-up on every protected env: on a `step_up_required`
  refusal, step up in the Reliant web app and re-run. A control plane that
  predates app deletion answers Unimplemented; forge says so and changes
  nothing (`teardown` still works there).

## Preview environments

Per-PR and per-branch copies of a template env, which expire:
`forge env preview create|delete`, `forge env gc`. Load `deploy/preview`.

## Domains

`forge domain add|ls|show|verify|bind|unbind|rm --env <env>` — see
`deploy/domains`.

## Missing-scope rejections

A 403 naming a scope (e.g. `domain:read`): the credential lacks it. Under
Reliant, the Reliant session it was minted from lacks it — grant it in Reliant
(Settings → Access Tokens) or sign in again with `reliant auth login`; standalone,
re-run `forge login`. If a fresh token still lacks it, your role has no grant —
ask an org admin, who can mint a token with the scope in the web app (Settings →
API tokens, https://forge.reliantlabs.io/settings/tokens); export it as the env's
declared token variable.

### Scopes for reading what a deployed app is doing

These scopes belong to the feedback loop (observe, then query). Each is its own
authority: none implies another product's, and a token is minted with them like
any other scope.

| Scope | Allows | Notes |
|---|---|---|
| `obs:read` | every telemetry read: traces, logs, metrics, issues, release health | the one an org automation token carries to gate CI on a release's health; needs no acting user |
| `obs:triage` | changing an issue's triage state (resolve, ignore, unresolve) | implies `obs:read` at the point of use; a read-only token cannot silence an issue |
| `obs:write` | authoring the org's observability workspace (dashboards: save, restore, archive, promote) | implies `obs:read` at the point of use; implies nothing else (not `obs:triage`); cannot be bound to one environment |
| `db:query` | one read-only query against an env's database | implies nothing and is implied by nothing: app data is not telemetry. A real env may restrict it further to people |
| `storage:read` | reading an env's object storage: list a bucket, read an object's metadata, preview it, mint a short-lived download URL | implies nothing and is implied by nothing, `db:query` included: uploads are not rows. May be bound to one environment; a real env may restrict it further to people (`data_access.storage`) |
| `deploy:config:read` | a release's config VALUES: a workload's plain env var values and its redacted rendered manifest (`deploy:read` sees names only) | implies nothing and is implied by nothing, `deploy:write` included: shipping a release is not reading what it carries. May be bound to one environment. Secret objects and secret refs never show a value, and a secret-looking plain value shows only as `redacted` (`release.RedactObject`), with no value-derived digest |

### A registry-only credential for filing source maps

`sourcemaps:write` files a frontend's source maps (`forge frontend sourcemaps
push`) and does nothing else. The registry grants it push and pull on
`<org>/<project>/<frontend>-sourcemaps` repositories only, and the control plane
refuses it on every RPC. It is a whole credential: a token carrying it carries
no other scope, acts as no person, is bound to nothing, and no wildcard resolves
to it. Because it cannot ask the control plane for its org, the push names the
org itself. A person mints the token in the web app (Settings → API tokens,
https://forge.reliantlabs.io/settings/tokens); `forge cloud token create` does
it from the CLI only on a control plane that admits a CLI login for token
administration (Reliant cloud refuses one: exit 9, `person_session_required`):

    forge cloud token create --env prod --name desktop-sourcemaps --scopes sourcemaps:write --expires-in 2160h
    forge frontend sourcemaps push dist --frontend desktop --build-id "$VERSION" --env <env> --org <org id>

`accesstoken.AllScopes` is the closed set; a store's `access_tokens` CHECK must
list every member (`db/closed-sets`).

## Where the credential comes from

`--token`, then the env's declared token variable (CI), then what `forge login`
stored, then the credential helper `$FORGE_CREDENTIAL_HELPER` (Reliant's
session). `forge cloud status <env>` prints which one a command will use —
never the token.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.