> ## 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.

# Inspect stack status

> Check release convergence, runtime health, resource state, and condition history with the Stackdome CLI.

`stackdome status` answers two different questions: which release is serving, and whether that release is healthy now. Use structured output for automation and the table view for resource-level investigation.

## Check the current stack

```bash theme={null}
stackdome status
```

The table shows the serving release state followed by every resource, its runtime state, declared ports, and public URL. When the API reports a failure, the CLI also prints its captured details and the three most recent resource conditions.

To inspect a stack other than the current context, pass its name:

```bash theme={null}
stackdome status --stack storefront
```

<Note>
  The current CLI declares an optional `[resource]` argument, but status output remains stack-wide. Use `stackdome logs <resource>` when you need to focus on one resource.
</Note>

## Prove convergence and health

For an agent or CI job, request JSON:

```bash theme={null}
stackdome status -o json
```

The result is the Stack object. Its two embedded release summaries have different meanings:

| Field               | Meaning                                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `converged_release` | The release currently serving. It can remain on an older successful release while a newer attempt progresses or fails. |
| `latest_release`    | The newest release attempt, whether or not it became live.                                                             |

A stack is serving a healthy release when all of these are true:

* `converged_release` is present.
* `converged_release.state` is `Released`.
* `converged_release.health` is `ok`.

To verify a deployment you just created, retain `release.id` from `stackdome deploy --wait -o json` as the deployed release ID and also require `converged_release.id` to equal it. This prevents an older healthy release from satisfying the check.

To prove that this deployed release is also the **newest attempt**, require:

* `latest_release.id` equals the deployed release ID.
* `latest_release.state` is `Released`.

Do not require `latest_release.health` to be `ok`. That field is used for a newest attempt that is still `progressing` or has `failed`; once the attempt has settled successfully, runtime health belongs to `converged_release.health`.

Do not claim that a deployment succeeded from `converged_release.health == "ok"` alone. An older release can still be healthy after a newer attempt fails. Match `converged_release.id` to the retained deployed release ID; when claiming that release is newest, match `latest_release.id` to it too.

The possible runtime health values are `ok`, `progressing`, `degraded`, `unavailable`, and `failed`. `ok` is the only value that proves the serving release is healthy.

## Watch a rollout

```bash theme={null}
stackdome status --watch
```

The CLI refreshes every three seconds until interrupted. In table mode it redraws an interactive terminal. In structured mode it emits one complete Stack object per refresh:

```bash theme={null}
stackdome status --watch -o json
```

This is a stream of JSON values, not one JSON array. When watching a deployment, parse each value independently and stop only after `converged_release.id` equals the retained deployed release ID, its state is `Released`, and its health is `ok`. If the watcher also claims this remains the newest attempt, require `latest_release.id` to equal the deployed release ID and `latest_release.state` to be `Released`.

<Warning>
  Interrupting `stackdome status --watch` currently exits with code `0`. Treat that as the watch ending, not proof that the stack converged; inspect the last object yourself.
</Warning>

## Read condition history

Use the human-readable table to see every condition reported for each resource:

```bash theme={null}
stackdome status --conditions
```

Each condition includes its status, type, reason, message, and transition age. Start with the newest false or failing condition, then compare its reason and message with [runtime logs](/guides/logs).

<Warning>
  `--conditions` affects table rendering only in the current CLI. `stackdome status --conditions -o json` and `-o yaml` return the same Stack object as ordinary structured status; they do not add condition history.
</Warning>

## Choose the next diagnostic

| Status evidence                                                           | Next step                                                                                                  |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `latest_release.state` is `Pending` or `InProgress`                       | Follow its [release events](/concepts/releases#follow-release-events).                                     |
| `latest_release.state` is `Failed`                                        | Inspect release info and events; if a build failed, use the [build-failure guide](/guides/build-failures). |
| A resource is not ready or reports a captured failure                     | Run `stackdome status --conditions`, then inspect that resource's [runtime logs](/guides/logs).            |
| The newest release is serving and healthy, but the application misbehaves | Inspect application logs; status proves platform health, not application semantics.                        |