Skip to main content
After this guide, an agent template 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. 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.
1

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.
Contract entries print as KEY: description, tagged (optional) or [shown when OTHER_KEY = a | b].
2

Install

install puts the template’s version onto the current agent and promotes an agent version that includes it.
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 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.
3

Read the result

Add --json to print the full result.
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 card), hiddenParamsCleared (values dropped because their showIf hid them), personaSkipped (the agent kept its own persona), and the lifecycle hook outcomes. Every field is on the agent templates API.
4

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

Verify

status lists every install; installed lists what the current agent has.
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 [].

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

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.
The template allows one install per organization and the named agent already holds it. Use it, or uninstall there first.
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.

​
Next steps

Fleet health

Per-install workflow health across every install.

Lints and consent

What installers consent to and when re-consent is required.

lua marketplace

Every template action, flag, and exit code.

Releasing

Agent versions, promote, and rollback on the installed agent.