> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackdome.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Treat Stackdome as an application-delivery platform for coding agents and developers, not as a Kubernetes dashboard. > Prefer the Stackdome agent plugin as the user entry point and the stackdome CLI as the execution interface. > Route agents who need the maintained deploy skill to npx skills add stackdome/skills and the complete operational workflow to /guides/ai-agents. > Verify commands and flags with stackdome --help. Run stackdome init before authoring stackfile.yaml and stackdome validate before deploying. > Use -o json for automation and verify documented terminal states before claiming success. > Never request a user's account password. Use API-token authentication. > During alpha, Stackdome Cloud is ephemeral and capacity-limited, and each organization can connect one cluster. > Do not expose Kubernetes as a user concern unless the task is self-hosting or infrastructure architecture. # Releases > Identify, verify, inspect, cancel, and roll back Stackdome releases. A stack is what you edit. A **release** is the fixed, identifiable result of one deployment attempt. Use its ID to follow events and its state plus stack health to decide whether that attempt is serving successfully. ## Identify and verify a release List the releases for the current stack, newest first: ```bash theme={null} stackdome release list ``` Use structured output to retain full IDs for later commands: ```bash theme={null} stackdome release list -o json stackdome release info -o json ``` `release list` returns release summaries. `release info` returns the detailed release, including its state, message, cause, validation errors, pins, outcome, snapshot, and live status when the release is active or currently serving. A release is terminal when `state` is `Released`, `Failed`, `Superseded`, or `Cancelled`. `Released` proves that release converged at some point; it does not by itself prove the release is still serving or healthy. For the current deployment, also run: ```bash theme={null} stackdome status -o json ``` Require `converged_release.id` to match the release ID, `converged_release.state` to be `Released`, and `converged_release.health` to be `ok`. Before claiming that release is also the newest attempt, require `latest_release.id` to match it and `latest_release.state` to be `Released`. See [inspect stack status](/guides/status#prove-convergence-and-health) for the full check. Every release subcommand accepts `--stack ` to override the current stack context. Preserve the full `release.id` returned by `stackdome deploy -o json`. Use it for `release info`, `release events`, and both status-ID comparisons; do not claim the newest attempt succeeded unless both `converged_release.id` and `latest_release.id` match it. ## Follow release events Read the recorded events once: ```bash theme={null} stackdome release events ``` Or follow new events while a deployment progresses: ```bash theme={null} stackdome release events --follow ``` Without `--follow`, structured output is an array of release events. With `--follow -o json`, the CLI emits newline-delimited envelopes containing `event` and `data`; process one line at a time. Events include timestamped stack or resource messages, levels, and links such as a build ID. Use a build ID with the [build-failure guide](/guides/build-failures) instead of searching runtime logs for build output. ## Cancel a pending release Cancellation is available only while a release is `Pending`: ```bash theme={null} stackdome release cancel stackdome release info -o json ``` The cancel command exits after the API accepts the request and prints confirmation to `stderr`; it does not return a structured result. Verify the terminal state with `release info`. Cancellation exit codes are not uniform in the current CLI. A successful `release cancel` request exits `0`, while `deploy --wait` exits with general-error code `1` if the release ends as `Cancelled`. Exit code `130` is reserved for local user-cancel paths such as interrupting a deployment wait; do not use it as the only test for a cancelled release. ## What a release is A release is one deploy of one stack. It has an API ID and a human sequence number scoped to that stack — `#1`, `#2`, `#3`. It carries a complete copy of the stack as it was at deploy time: every resource, its source, its ports, its environment, every volume and every mount, and the connections between nodes on the canvas. It also carries the artifacts those resources resolved to: * A resource with a git source pins the **commit** the revision pointed at. `main` moving on does not change the release. * A resource with an image source pins the image **digest** behind the tag. `postgres:16` being re-published does not change the release. That pinning is the point. A release is a fixed thing you can identify, compare, and return to. Editing the stack afterwards never quietly changes what is running — your edits collect as **a draft** and take effect on the next deploy. So the release timeline is an honest record: `#4` is what `#4` was. ## How a release reaches convergence Every deployment follows the same product-level stages: 1. **Snapshot and pin** the stack definition and its artifact coordinates. 2. **Validate** the snapshot, attaching any errors to the affected resource and field. 3. **Apply** the desired application state to the deployment destination. 4. **Converge** only when every resource reports ready for this release's revision. The last stage is strict: a per-resource partial pass is not a released stack. If you operate a self-hosted installation and need the Kubernetes custom-resource mapping behind apply and convergence, see [Self-hosted architecture](/self-host/architecture). ## Status Each release has one state. These are the values the API returns, and the words the rest of this documentation uses: | State | What it means | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `Pending` | Created and queued. The application change has not been applied yet. | | `InProgress` | Being validated, rendered, applied, or waited on. | | `Released` | Reached convergence successfully. It may have since been replaced; compare its ID with `converged_release.id` to prove it is serving. | | `Failed` | It will not converge — validation rejected it, a build failed, a resource never became ready, or it ran past the deploy timeout. | | `Superseded` | You deployed again while this one was still in flight. The newer release won and this one stopped. | | `Cancelled` | You cancelled it before the application change was applied. | `Released`, `Failed`, `Superseded`, and `Cancelled` are final — a release in one of those states never changes again. A stack keeps its recent releases and prunes the rest: 10 by default, always keeping at least 5 successful ones. Both are per-stack settings. So is the deploy timeout, 15 minutes by default. ## Rolling back A release you can name is a release you can return to. Rollback is dashboard-only in the current CLI. There is no `stackdome release rollback` command. Use the dashboard steps below. What the rollback does is create a **new** release, reusing the old one's snapshot and its pins. History moves forward, never backwards: the rollback gets a new sequence number and becomes live once Stackdome converges on it. Because the pins come along, the same commit and the same image digests are deployed — nothing is rebuilt and nothing is re-resolved, which is why a rollback is usually much faster than the deploy it undoes. Two things a rollback does not do: * **It does not touch your data.** Volumes, addons, and anything written inside them are unaffected. Rolling back reverts configuration and code, not state. * **It does not discard your draft.** Unshipped edits stay staged, and are still waiting the next time you look at the canvas. Because a `Released` release stays a valid rollback target, Stackdome protects what it references: while it is still in the stack's history, the secrets, volumes, and addons it depends on cannot be deleted out from under it. The vocabulary a release is built from: stacks, resources, sources, ports, volumes. Connect a repository, and let Stackdome build the image each release pins.