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

# Marketplace Command

> Browse, publish, and install marketplace skills and agent templates

## Overview

`lua marketplace` is the CLI surface for the Lua Marketplace. It has one shape:

```bash theme={null}
lua marketplace [noun] [action] [options]
```

`noun` is `skill` or `template`. Everything about a *skill* — a single reusable tool package — lives under `lua marketplace skill`. Everything about an *agent template* — a full, versioned agent manifest you can install or roll out across a fleet — lives under `lua marketplace template`.

```bash theme={null}
lua marketplace                 # Interactive: pick a domain (Skills / Agent templates)
lua marketplace skill           # Skill action menu
lua marketplace template        # Template action menu
```

<Note>
  Not sure which one you need? See [Marketplace Overview](/marketplace/overview#skills-vs-agent-templates) for when to publish a skill versus a template.
</Note>

<Tip>
  This replaces the older `lua marketplace create` / `lua marketplace install` role split. If you have scripts or muscle memory built on those, see [Migrating from the old command shape](#migrating-from-the-old-command-shape) below.
</Tip>

## `lua marketplace skill`

All skill-marketplace actions live in one flat namespace — publishing your own skills and installing others' both go through `lua marketplace skill <action>`.

### Actions

| Action      | What it does                                                              |
| ----------- | ------------------------------------------------------------------------- |
| `list`      | Create a marketplace listing for one of your skills.                      |
| `publish`   | Publish a specific version of a listed skill.                             |
| `edit`      | Update listing metadata (display name).                                   |
| `unlist`    | Hide the listing — no new installs, but existing installers keep working. |
| `unpublish` | Remove a specific published version.                                      |
| `mine`      | View the skills you've listed.                                            |
| `search`    | Search the marketplace by free-text query.                                |
| `view`      | Show the detail page for a specific listing.                              |
| `install`   | Install a specific version of a skill into your agent.                    |
| `update`    | Update an installed skill (e.g. to a newer version, or its env vars).     |
| `uninstall` | Remove an installed skill.                                                |
| `installed` | List skills installed on this agent.                                      |

<Note>
  `mine` and `edit` are the renamed publishing-side actions — they used to be called `view` and `update` under the old `lua marketplace create` role, but those names now belong to the installer-side actions (`view` looks up a listing by id, `update` changes an installed skill). All twelve actions support `--json`.
</Note>

### Options

| Option                           | Description                                                                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--skill-name <name>`            | Skill name (for `list`, `update`, `uninstall`).                                                                              |
| `--display-name <name>`          | Display name shown in the marketplace (for `list`/`edit`).                                                                   |
| `--visibility <public\|private>` | Who can see and install the listing (for `list`). Defaults to `public`.                                                      |
| `--marketplace-id <id>`          | Marketplace skill ID (returned after `list`).                                                                                |
| `--version-id <id>`              | Version ID (for `publish`/`install`/`update`).                                                                               |
| `--changelog <text>`             | Changelog text shown to installers (for `publish`).                                                                          |
| `--env-vars-json <json>`         | JSON array describing required env vars (for `publish`), e.g. `[{"name":"STRIPE_KEY","required":true,"description":"..."}]`. |
| `--query <text>`                 | Search query (for `search`).                                                                                                 |
| `--page <n>`                     | Page number for paginated search.                                                                                            |
| `--limit <n>`                    | Results per page.                                                                                                            |
| `--env-vars <k=v,...>`           | Comma-separated `key=value` pairs (for `install`/`update`).                                                                  |
| `--force`                        | Skip confirmation prompts.                                                                                                   |
| `--json`                         | Output as JSON.                                                                                                              |

### Examples

```bash theme={null}
# Interactive skill menu
lua marketplace skill

# View my listed skills
lua marketplace skill mine
lua marketplace skill mine --json | jq

# List a skill — public by default
lua marketplace skill list \
  --skill-name mySkill \
  --display-name "My Skill"

# List a private skill — only your org can find and install it
lua marketplace skill list \
  --skill-name internalCrmSkill \
  --display-name "Internal CRM Helper" \
  --visibility private

# Publish a specific version with a changelog
lua marketplace skill publish \
  --marketplace-id mkt_xyz \
  --version-id v1 \
  --changelog "Adds support for European VAT"

# Edit display name
lua marketplace skill edit \
  --marketplace-id mkt_xyz \
  --display-name "My Skill (Pro)"

# Unlist (existing installers unaffected)
lua marketplace skill unlist --marketplace-id mkt_xyz --force

# Unpublish a specific version
lua marketplace skill unpublish \
  --marketplace-id mkt_xyz \
  --version-id v1 \
  --force

# Search the marketplace
lua marketplace skill search --query "CRM"
lua marketplace skill search --query "CRM" --page 2 --limit 20

# View a specific listing
lua marketplace skill view --marketplace-id mkt_xyz
lua marketplace skill view --marketplace-id mkt_xyz --json

# Install a specific version
lua marketplace skill install \
  --marketplace-id mkt_xyz \
  --version-id v1 \
  --force

# Install with env vars
lua marketplace skill install \
  --marketplace-id mkt_xyz \
  --version-id v1 \
  --env-vars "STRIPE_KEY=sk_xxx,WEBHOOK_SECRET=whsec_yyy" \
  --force

# List installed skills
lua marketplace skill installed
lua marketplace skill installed --json

# Update an installed skill to a newer version
lua marketplace skill update \
  --skill-name myCRMSkill \
  --version-id v2

# Update env vars on an installed skill
lua marketplace skill update \
  --skill-name myCRMSkill \
  --env-vars "STRIPE_KEY=sk_new"

# Uninstall
lua marketplace skill uninstall --skill-name myCRMSkill --force
```

See [Publishing Skills](/marketplace/creator-guide) and [Installing Skills](/marketplace/installer-guide) for the full lifecycle, including private visibility.

## `lua marketplace template`

Agent templates are published, versioned snapshots of an agent's full deployable manifest — skills, webhooks, jobs, processors, triggers, and model — plus the authored declarations that drive the deploy experience: connections, a persona template, trigger presets, and parameter metadata. See [Agent Templates](/marketplace/agent-templates) for the concepts and [Publishing Templates](/marketplace/publishing-templates) for the creator workflow; this section is the flag reference.

### Actions

| Action      | What it does                                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create`    | Create a new template from the current agent.                                                                                                                                                                 |
| `draft`     | Compose the `template:` section of `lua.skill.yaml` — the server infers connections, persona variables, trigger presets, and parameter metadata from your agent for you to review and edit before publishing. |
| `publish`   | Freeze a new template version from a promoted agent version, together with the authored `template:` sections.                                                                                                 |
| `view`      | Show a template's detail page, or a specific version's manifest.                                                                                                                                              |
| `versions`  | List all published versions of a template.                                                                                                                                                                    |
| `install`   | Install a template's primitives onto the current agent.                                                                                                                                                       |
| `apply`     | Push a template version out to a fleet of agents that have it installed.                                                                                                                                      |
| `status`    | Show the fleet install ledger — which agent runs which version.                                                                                                                                               |
| `installed` | List templates installed on the current agent.                                                                                                                                                                |
| `uninstall` | Remove a template's managed primitives from the current agent.                                                                                                                                                |

### Options

| Option                             | Description                                                                                                                                                                                                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name <name>`                    | Internal template identifier (for `create`).                                                                                                                                                                                                                                        |
| `--display-name <name>`            | Display name (for `create`).                                                                                                                                                                                                                                                        |
| `--description <text>`             | Description (for `create`).                                                                                                                                                                                                                                                         |
| `--visibility <public\|private>`   | Who can see and install the template (for `create`). Defaults to `private`.                                                                                                                                                                                                         |
| `--template-id <id>`               | Template ID.                                                                                                                                                                                                                                                                        |
| `--source-version <n>`             | Agent version to compose or freeze from (for `draft`/`publish`). Defaults to the agent's active version.                                                                                                                                                                            |
| `--changelog <text>`               | Changelog for this template version (for `publish`).                                                                                                                                                                                                                                |
| `--env-contract <KEY=description>` | Declare an env-contract entry; repeatable. Use `KEY?=description` for an optional variable (for `publish`). Omitted entirely, the new version inherits the previous version's contract.                                                                                             |
| `--version <n>`                    | A specific template version (for `view`/`install`/`apply`). Defaults to the latest published version.                                                                                                                                                                               |
| `--env-vars <k=v,...>`             | Comma-separated `key=value` pairs to satisfy the env contract (for `install`).                                                                                                                                                                                                      |
| `--allow-creator-updates`          | Let this template's creator push future `apply` updates onto your agent (for `install`). Off by default.                                                                                                                                                                            |
| `--skip-env-check`                 | **Retired.** Still accepted so existing scripts don't break, but it no longer skips anything — the CLI prints a deprecation warning and the env-contract check is enforced server-side regardless. Satisfy the contract with [`lua env`](/cli/env-command) or `--env-vars` instead. |
| `--agents <a,b,c>`                 | Comma-separated target agent IDs (for `apply`).                                                                                                                                                                                                                                     |
| `--file <path>`                    | Path to a file with one target agent ID per line (for `apply`).                                                                                                                                                                                                                     |
| `--all-installed`                  | Target every agent that already has this template installed (for `apply`).                                                                                                                                                                                                          |
| `--no-wait`                        | Print the apply run ID immediately instead of polling for completion (for `apply`).                                                                                                                                                                                                 |
| `--yes`                            | Auto-confirm **only** the publish consequence prompt shown when a publish clears or narrows authored `template:` sections (for `publish`). Unlike `--force`, it skips no other confirmation.                                                                                        |
| `--force`                          | Skip confirmation prompts. For `draft`, it changes the merge behavior instead: the composed draft **replaces** your authored `template:` sections wholesale rather than merging additively.                                                                                         |
| `--json`                           | Output as JSON.                                                                                                                                                                                                                                                                     |

### The `template:` section of `lua.skill.yaml`

`draft` writes (and `publish` reads) a `template:` section in your project's `lua.skill.yaml` carrying the four authored declarations: `connections`, `personaTemplate`, `triggerPresets`, and `paramsMeta`. Two rules govern how it publishes:

* **All four sections always ship together.** Whenever a `template:` section exists, `publish` serializes all four sections — a section that's absent or empty is an **explicit clear** of that section, never "inherit the previous version's". (A project with no `template:` section at all sends nothing template-shaped, and the authored sections inherit from the previous version as before.)
* **Clearing or narrowing requires a confirm.** If the publish would clear a section, or remove keys, relative to the latest published version, the CLI prints a per-section consequence diff — e.g. clearing `personaTemplate` means *new installs get no persona template; installed personas are untouched* — and asks you to confirm. Pass `--yes` to auto-confirm exactly this prompt in scripts; in CI or non-interactive runs the publish proceeds with the diff printed to stdout.

Re-running `draft` never destroys your edits: it merges additively (new inferred entries are appended, your existing keys are never modified) and prints a per-section added/kept diff. Use `draft --force` only when you want the composed draft to replace your authored sections wholesale.

### Examples

```bash theme={null}
# Interactive template menu
lua marketplace template

# Create a template from the current agent — private by default
lua marketplace template create \
  --name support-bot \
  --display-name "Support Bot"

# Compose the template: section of lua.skill.yaml (additive merge; review, then publish)
lua marketplace template draft --template-id tpl_abc

# Recompose from a specific promoted agent version, replacing authored sections wholesale
lua marketplace template draft --template-id tpl_abc --source-version 12 --force

# Publish a version, declaring its env contract
lua marketplace template publish \
  --template-id tpl_abc \
  --changelog "Add refund skill" \
  --env-contract "STRIPE_KEY=Stripe secret key" \
  --env-contract "SUPPORT_EMAIL?=Fallback contact address"

# Publish in a script, auto-confirming only the section clear/narrow prompt
lua marketplace template publish --template-id tpl_abc --yes

# Inspect a template, or a specific version's manifest
lua marketplace template view --template-id tpl_abc
lua marketplace template view --template-id tpl_abc --version 2 --json

# List all published versions
lua marketplace template versions --template-id tpl_abc

# Install onto the current agent
lua marketplace template install \
  --template-id tpl_abc \
  --env-vars "STRIPE_KEY=sk_live_xxx" \
  --force

# Roll out a new version to a specific set of agents
lua marketplace template apply \
  --template-id tpl_abc \
  --agents agent_1,agent_2,agent_3 \
  --force

# Roll out to every agent that already has it installed
lua marketplace template apply --template-id tpl_abc --all-installed --force

# Check the fleet ledger
lua marketplace template status --template-id tpl_abc

# List templates installed on this agent
lua marketplace template installed

# Remove a template's primitives from this agent
lua marketplace template uninstall --template-id tpl_abc --force
```

### End to end: from project to installable template

The whole creator flow in one block, using a small standup-tracking agent (one skill that logs wins, one scheduled nudge job, a persona):

```bash theme={null}
# Build and ship the source agent
lua init                          # new project (or use an existing one)
lua compile                       # build the primitives
lua push all --force              # push them to the platform
lua version promote 1             # promote the version templates will freeze

# Turn it into a template
lua marketplace template create \
  --name standup-sidekick \
  --display-name "Standup Sidekick"          # → prints the template ID

lua marketplace template draft \
  --template-id tpl_standup                   # writes the template: section
                                              # of lua.skill.yaml for review

# Edit lua.skill.yaml: polish display names, required flags, persona {{vars}} …

lua marketplace template publish \
  --template-id tpl_standup \
  --changelog "v1: win logging + standup nudge"

# Install it onto another agent (run from that agent's project)
lua marketplace template install --template-id tpl_standup --force
```

For the full lifecycle around these commands — what `draft` infers and how to review it, and what installers experience — see [Publishing Templates](/marketplace/publishing-templates) and [Deploying Templates](/marketplace/deploying-templates).

## Migrating from the old command shape

The former `lua marketplace [create|install] [action]` role split is gone. Every invocation maps onto the new `skill` noun:

| Old                                                    | New                                   |
| ------------------------------------------------------ | ------------------------------------- |
| `lua marketplace create list ...`                      | `lua marketplace skill list ...`      |
| `lua marketplace create publish ...`                   | `lua marketplace skill publish ...`   |
| `lua marketplace create update ...` (metadata)         | `lua marketplace skill edit ...`      |
| `lua marketplace create unlist ...`                    | `lua marketplace skill unlist ...`    |
| `lua marketplace create unpublish ...`                 | `lua marketplace skill unpublish ...` |
| `lua marketplace create view ...` (my listings)        | `lua marketplace skill mine ...`      |
| `lua marketplace install search ...`                   | `lua marketplace skill search ...`    |
| `lua marketplace install view ...`                     | `lua marketplace skill view ...`      |
| `lua marketplace install install ...`                  | `lua marketplace skill install ...`   |
| `lua marketplace install update ...` (installed skill) | `lua marketplace skill update ...`    |
| `lua marketplace install uninstall ...`                | `lua marketplace skill uninstall ...` |
| `lua marketplace install installed ...`                | `lua marketplace skill installed ...` |

All flags keep their old names and meaning — only the noun/action path changed. Agent templates (`lua marketplace template ...`) are new; there's no old shape to migrate from.

## Env Var Formats

When a skill declares required env vars, two flag shapes are used:

| Flag              | Purpose                                          | Format                                                                              |
| ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `--env-vars-json` | **Publishing** — declare what your skill needs.  | JSON array of objects `[{"name":"STRIPE_KEY","required":true,"description":"..."}]` |
| `--env-vars`      | **Installing** — provide values when installing. | Comma-separated `key=value` pairs                                                   |

Agent templates use a single `--env-contract KEY=description` flag (repeatable, `KEY?=description` for optional) at publish time, and the same `--env-vars k=v,...` shape at install time. The contract is enforced server-side — a missing required variable blocks the install with a list of what's missing. See [Agent Templates: the env contract](/marketplace/agent-templates#the-env-contract).

## Related

* [Marketplace Overview](/marketplace/overview)
* [Publishing Skills](/marketplace/creator-guide)
* [Installing Skills](/marketplace/installer-guide)
* [Agent Templates](/marketplace/agent-templates)
* [Publishing Templates](/marketplace/publishing-templates)
* [Deploying Templates](/marketplace/deploying-templates)