> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Check fleet health

> Read per-install workflow health for an agent template, decide which installs need a re-apply, and confirm the install ledger

After this guide, you know which installs of your [agent template](/concepts/agent-templates) have a workflow that is inactive, auto-disabled, inert, or failing, and what to do about each. Health covers workflows shipped by the template; for jobs and triggers on one agent, read that agent's [logs](/ship/logs-and-debugging).

*Verified against lua-cli 3.33.0.*

**Before you begin**

* A project connected to an agent in the template's creator organization and a signed-in CLI.
* The template id, and at least one install whose version ships a [workflow](/concepts/workflows). An install without workflows appears with no rows.

<Steps>
  <Step title="Read the fleet">
    `health` prints one row per install and workflow over a look-back window.

    ```bash theme={null}
    lua marketplace template health --template-id <template-id> --window-days 30 --ci
    ```

    `--window-days` defaults to 7 and is clamped server-side to 1 through 90; the CLI rejects a value less than 1 with `--window-days must be a positive integer`. Pages are fetched until the fleet is complete. Before any install exists, the command prints one line.

    ```text Output theme={null}
    No installs (or no workflow-bearing installs) for this template yet.
    ```
  </Step>

  <Step title="Read each row">
    The columns are `INSTALL`, `AGENT`, `WORKFLOW`, `STATE`, `SCHEDULE`, `IN-FLIGHT`, `TERMINALS (<n>d)`, and `LAST FAILURE`.

    | Column             | Values                                              | Meaning                                                                                              |
    | ------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
    | `STATE`            | `active`, `inactive`, `auto-disabled`, `inert`      | The workflow on the installed agent; `inert` means a connection it depends on is missing or declined |
    | `SCHEDULE`         | `active`, `paused`, `failed`, `none`                | The workflow's schedule row; `failed` means the schedule auto-disabled after failures                |
    | `IN-FLIGHT`        | count                                               | Runs that are running, gated, or suspended                                                           |
    | `TERMINALS (<n>d)` | `<ok> ok / <failed> failed / <cancelled> cancelled` | Runs that ended in the window; `failed` adds timed-out runs                                          |
    | `LAST FAILURE`     | `<reason> (<run id>)` or `—`                        | The most recent failed run                                                                           |

    `--json` prints `{ templateId, windowDays, installs[] }`; each install carries `templateInstallId`, `agentId`, `orgId`, `installedVersion`, and `workflows[]` with `key`, `displayName`, `workflowId`, `active`, `capabilityInert`, `scheduleStatus`, `autoDisabledAt`, `runs` (`inFlight`, `gated`, `suspended`, `last`, `lastFailure`, and `terminals` with `completed`, `failed`, `timedOut`, `cancelled`, `abandoned`), and the version pins: `activeVersionId`, `versions[]` (non-terminal runs per pinned workflow version), `recallable` (`true` when parked runs, that is suspended, waiting, or gated, sit on one of those pins), and `parkedOnOldPin` (how many parked runs are pinned to a version other than `activeVersionId`; a REST install with `migrateRuns` moves them).
  </Step>

  <Step title="Decide what to do">
    Match the row to the action:

    * An `installedVersion` behind the version that fixes a failure: roll it out with `lua marketplace template apply --template-id <template-id> --agents <agent-id> --force`. The target must allow creator updates.
    * `SCHEDULE` `failed` or `STATE` `auto-disabled`: the schedule stopped after repeated failures (`autoDisabledAt` says when). Fix the cause; then the installer re-arms it from a project on that agent: `lua workflows schedules list -i <workflow-name>` prints the schedule's job id with `Status` `auto-disabled`, and `lua workflows schedules resume <jobId>` sets it active and resets the failure count (`--backfill-now` replays missed fires). An `apply` never re-arms a paused or auto-disabled schedule; it reports the key under `blockedTriggers` with `paused by the installer — not re-armed by a creator push`.
    * `STATE` `inactive`: the workflow itself is off, so nothing fires; `lua workflows activate <workflow-name>` on that agent turns it back on.
    * `STATE` `inert`: a connection the workflow depends on is missing or declined. The installer connects the [integration](/concepts/integrations) and re-runs `install` at their installed version, which reuses the connection.
    * Failed runs on a current version: inspect them on that agent with `lua workflows runs` and `lua workflows status`; see [Operate runs](/build/workflows/operate-runs).
  </Step>

  <Step title="Verify">
    Confirm the ledger after a re-apply.

    ```bash theme={null}
    lua marketplace template status --template-id <template-id> --ci
    ```

    Each row shows the install's `TEMPLATE VERSION`, the `AGENT VERSION` it promoted, `STATUS` (`installed` or `apply_failed`), and `APPLIED AT`; `--json` prints the same rows with `allowCreatorUpdates` and `lastError`. In CI, fail the job on any auto-disabled schedule or failed run in the window:

    ```bash theme={null}
    lua marketplace template health --template-id <template-id> --json --ci \
      | jq -e '[.installs[].workflows[] | select(.scheduleStatus == "failed" or .runs.terminals.failed > 0)] | length == 0'
    ```

    `jq -e` exits 1 when the expression is false.
  </Step>
</Steps>

## Next steps

<Columns cols={2}>
  <Card title="Install and apply" href="/marketplace/install-and-apply">The `apply` rollout and what a failed target means.</Card>
  <Card title="Operate runs" href="/build/workflows/operate-runs">Watch, retry, and cancel the runs behind a failing row.</Card>
  <Card title="lua marketplace" href="/reference/cli/marketplace">`health`, `status`, and their flags.</Card>
</Columns>