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

# Install and apply a template

> Install an agent template onto an agent, read the install result, roll a version out to a fleet of installs, and uninstall

After this guide, an [agent template](/concepts/agent-templates) is installed onto an agent you run, and a newer version is rolled out to every agent that has it. This is the CLI path onto an existing agent; the one-call deploy that creates a fresh agent from the catalog is on the [agent templates API](/reference/rest/agent-templates).

*Verified against lua-cli 3.33.0.*

**Before you begin**

* A project for the target agent (`lua init --agent-id <id>` creates one) and a signed-in CLI.
* The template id, printed by the creator's `create`.
* A target other than the template's source agent, or the install is refused with `TEMPLATE_SELF_INSTALL`.

<Steps>
  <Step title="Read the manifest">
    `view --version <n>` prints the frozen primitives, the env contract, and the persona vars, so you know which values the install needs.

    ```bash theme={null}
    lua marketplace template view --template-id <template-id> --version 1 --ci
    ```

    Contract entries print as `KEY: description`, tagged `(optional)` or `[shown when OTHER_KEY = a | b]`.
  </Step>

  <Step title="Install">
    `install` puts the template's version onto the current agent and promotes an [agent version](/concepts/releases-and-versions) that includes it.

    ```bash theme={null}
    lua marketplace template install --template-id <template-id> \
      --env-vars "SUPPORT_EMAIL=help@example.com" --allow-creator-updates --force --ci
    ```

    Without `--force` the CLI prints the install summary and exits 2. `--version <n>` picks a version (default: the latest installable). A CLI install answers env contract keys only: a missing required value is refused with `Missing required environment variables: <keys>` (exit 10). Persona variables are answered in the desktop install form or with REST `personaVars`; a required variable with no `default` that no earlier install answered is refused with `PERSONA_VARS_INVALID: <NAME>: required persona variable is not set` (exit 10); the [agent templates API](/reference/rest/agent-templates) has the body. `--skip-env-check` is deprecated and not sent. On success the CLI prints `✅ Template installed! (v<n>)` and `Applied as agent version v<n>.`

    A name clash with an unmanaged primitive on the target is refused with `TEMPLATE_JOB_CLASH` or `TEMPLATE_NAME_CLASH` before anything is written.
  </Step>

  <Step title="Read the result">
    Add `--json` to print the full result.

    ```bash theme={null}
    lua marketplace template install --template-id <template-id> --force --json --ci
    ```

    Read `armedTriggers` and `blockedTriggers` (what runs, and what could not be armed and why), `unwatchedTriggers` (workflow schedules that fire as the system and deposit no [Inbox](/reference/sdk/inbox) card), `hiddenParamsCleared` (values dropped because their `showIf` hid them), `personaSkipped` (the agent kept its own persona), and the [lifecycle hook](/marketplace/lifecycle-hooks) outcomes. Every field is on the [agent templates API](/reference/rest/agent-templates).
  </Step>

  <Step title="Apply a version to a fleet">
    From the creator's project, `apply` rolls one version out to target agents that installed the template with creator updates allowed.

    ```bash theme={null}
    lua marketplace template apply --template-id <template-id> --version 2 \
      --agents <agent-id>,<agent-id> --force --ci
    ```

    Targets come from `--agents <a,b,c>`, `--file <path>` (one id per line), or `--all-installed`, at most 500 per run. Without `--force`, a terminal asks to confirm and `--ci` exits 1. The CLI polls every 3 seconds, then prints one row per target with `STATUS` `applied`, `already_current`, or `failed` and the `LOCAL VERSION` it promoted; `--no-wait` prints the run id instead. Any failed target exits 1; the others are applied and a re-run is safe. After 30 minutes of polling the CLI exits 1 with `Apply run <id> still running after 30 minutes` while the run continues server-side; read the outcome later with `status` below, or with `GET /marketplace/templates/:templateId/apply-runs/:runId` on the [template fleet API](/reference/rest/template-fleet). A target that declined creator updates fails with `Target agent is not eligible for creator updates`; one whose consent surface changed fails with `RECONSENT_REQUIRED` until that installer re-installs; one whose installer hand-edited a managed primitive fails with `MODIFIED_SINCE_INSTALL`.
  </Step>

  <Step title="Verify">
    `status` lists every install; `installed` lists what the current agent has.

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

    `status` prints one row per install: `AGENT ID`, `TEMPLATE VERSION`, `AGENT VERSION`, `STATUS` (`installed` or `apply_failed`), `APPLIED AT`. `installed --json` prints one object per template, or `[]`.
  </Step>
</Steps>

## Options you may need

### What the installer owns

A creator update replaces the template's managed primitives and nothing the installer owns (env values, an edited or pre-existing persona, armed triggers and their schedule values, the connection behind each capability, the model, channels, name), listed under [What installers agree to and keep](/marketplace/lints-and-consent#what-installers-agree-to-and-keep). Re-run `install` at the same version to rebind a connection. A hand edit to a managed primitive is refused on the next update with `MODIFIED_SINCE_INSTALL`, naming the primitives; the installer accepts the overwrite by re-sending the install over REST with `acceptModifiedPrimitives: ["<kind>/<key>"]`; no CLI flag does it. Rolling back is `lua version promote <n>` on that agent.

### Uninstall

`uninstall` removes what the install brought and promotes a clean agent version; without `--force` it exits 2.

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

The `onUninstall` hook runs first; then the managed primitives, trigger subscriptions, connection bindings, and the env keys the install introduced (including `LUA_TRIGGER_URL__*`) are removed. The persona, your own primitives, channels, and env keys that predate the install or that another install relies on stay.

## If it isn't working

<Accordion title="✖ http_400: Missing required environment variables: SUPPORT_EMAIL">
  A required contract key has no value on the agent and none in `--env-vars`. Set it with `lua env production -k SUPPORT_EMAIL -v <value>` and retry. A key hidden by `showIf` is not required.
</Accordion>

<Accordion title="SINGLE_INSTALL_PER_WORKSPACE">
  The template allows one install per organization and the named agent already holds it. Use it, or uninstall there first.
</Accordion>

<Accordion title="Target agent is not eligible for creator updates">
  The target never installed the template, installed it without `--allow-creator-updates`, or its organization blocks the template. The installer re-installs with the flag, or opts in with `PATCH /agents/:agentId/templates/:templateId`.
</Accordion>

## Next steps

<Columns cols={2}>
  <Card title="Fleet health" href="/marketplace/fleet-health">Per-install workflow health across every install.</Card>
  <Card title="Lints and consent" href="/marketplace/lints-and-consent">What installers consent to and when re-consent is required.</Card>
  <Card title="lua marketplace" href="/reference/cli/marketplace">Every template action, flag, and exit code.</Card>
  <Card title="Releasing" href="/ship/releasing">Agent versions, promote, and rollback on the installed agent.</Card>
</Columns>