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

# Triggers Command

> Manage agent triggers — paste-anywhere URLs and SDK triggers that wake your agent on external events

## Overview

`lua triggers` manages **agent triggers**: URLs that start an agent turn when an external service POSTs to them. There are two flavours, managed with the same command:

* **URL triggers** — created entirely from the CLI with `lua triggers create`, no code required. Paste the printed URL into any service that can send a webhook; every delivery becomes an agent turn carrying the payload (optionally prefixed with an instruction you set at creation time).
* **SDK triggers** — defined in code with [`defineTrigger`](/api/luatrigger) and deployed via `lua push`. These add declarative `verify` / `filter` / `transform` shaping in front of the agent turn.

```bash theme={null}
lua triggers                              # Interactive management
lua triggers list                         # List all triggers
lua triggers create --name order-created  # Create a URL trigger (prints the pasteable URL)
lua triggers logs --trigger order-created # View execution history
```

<Note>
  For defining SDK triggers in code, see the [LuaTrigger API](/api/luatrigger). Looking for **integration triggers** (Linear, HubSpot, and other connected apps)? Those are managed with [`lua integrations webhooks`](/cli/integrations-command).
</Note>

## Subcommands

| Action         | What it does                                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list`         | List all triggers with type (URL or SDK), status, URL, and creation date.                                                                                                      |
| `create`       | Create a URL trigger and print its pasteable URL.                                                                                                                              |
| `logs`         | Show execution history for a trigger, newest first.                                                                                                                            |
| `activate`     | Enable a trigger.                                                                                                                                                              |
| `deactivate`   | Disable a trigger — its URL stops firing, but is retained.                                                                                                                     |
| `rotate-token` | Invalidate the current URL and mint a new one.                                                                                                                                 |
| `delete`       | Remove a trigger. Its URL stops working immediately. A trigger with deployed SDK versions is **deactivated instead of deleted** (its URL stops firing; versions are retained). |

Running `lua triggers` with no action opens an interactive menu covering all of the above.

## Options

| Option                 | Description                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `--name <name>`        | Trigger name (required for `create`).                                                     |
| `--description <text>` | Trigger description (optional, for `create`).                                             |
| `--instruction <text>` | Instruction sent to the agent each time this trigger fires (optional, for `create`).      |
| `--trigger <nameOrId>` | Trigger name or ID (required for `logs`/`activate`/`deactivate`/`rotate-token`/`delete`). |
| `--limit <n>`          | Max executions to show for `logs` (default: 20, max: 200).                                |
| `--json`               | Output as JSON (for `list` and `logs`).                                                   |
| `--force`              | Skip confirmation prompts (for `delete`).                                                 |

## The Paste-Anywhere URL Workflow

Create a trigger, paste its URL somewhere, and every POST to it becomes an agent turn:

```bash theme={null}
lua triggers create --name daily-time --instruction "Reply with the current date and time"
```

```
✅ Trigger "daily-time" created
📝 Instruction sent to the agent on each fire: Reply with the current date and time

============================================================
🔗 Trigger URL (paste it anywhere):

   https://trigger.heylua.ai/trigger/6978e0294d9c2007ed5cb129/9f2e6c1a-2b7d-4c03-9e88-1a2b3c4d5e6f

============================================================

Trigger is live. Fire it, then inspect executions:
  Fire:     curl -X POST https://trigger.heylua.ai/trigger/6978e0294d9c2007ed5cb129/9f2e6c1a-2b7d-4c03-9e88-1a2b3c4d5e6f -H 'Content-Type: application/json' -d '{"hello":"world"}'
  Inspect:  lua triggers logs --trigger daily-time

💡 If this URL leaks, run 'lua triggers rotate-token --trigger daily-time' to invalidate it and mint a new one.
```

The URL works from anywhere that can send an HTTP POST — CI pipelines, monitoring tools, Zapier, `curl`, another agent. The agent receives the request body as its message, prefixed with `[Trigger: <name>]` and the instruction if you set one.

<Warning>
  **The URL is the credential.** The token embedded in the URL is the only thing gating a plain URL trigger. Treat trigger URLs like API keys, and rotate them if they leak. For real authentication (HMAC signatures), define an SDK trigger with a [`verify` slot](/api/luatrigger#slots-at-least-one-required).
</Warning>

## Examples

```bash theme={null}
# Interactive
lua triggers

# List everything (URL and SDK triggers)
lua triggers list
lua triggers list --json

# Create URL triggers
lua triggers create --name order-created
lua triggers create --name order-created --description "Fires on new orders"
lua triggers create --name daily-time --instruction "Reply with the current date and time"

# Execution history
lua triggers logs --trigger order-created
lua triggers logs --trigger order-created --limit 5 --json

# Pause and resume
lua triggers deactivate --trigger order-created
lua triggers activate   --trigger order-created

# Invalidate a leaked URL
lua triggers rotate-token --trigger order-created

# Delete
lua triggers delete --trigger order-created --force
```

## Output Shapes

### list

Each trigger is shown with its type — **URL** (a plain paste-anywhere trigger) or **SDK** (a deployed `defineTrigger` version owns the pipeline) — plus its status, URL, and creation date. `--json` emits the same fields as machine-readable JSON.

### logs

Executions are listed newest first, with a status per delivery:

| Status                             | Meaning                                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| ✅ `COMPLETED`                      | The agent turn finished; the agent's response text is shown with the entry.                         |
| 🔄 `ACCEPTED`                      | Slots passed; the agent turn is still in flight.                                                    |
| ⏳ `TIMED OUT`                      | Accepted long ago with no completion recorded.                                                      |
| ❌ `FAILED`                         | A slot threw, the transform returned nothing, or the agent invocation failed — the error is shown.  |
| ⛔ `REJECTED (verify failed → 401)` | The SDK trigger's `verify` slot returned false.                                                     |
| 🔇 `SKIPPED (filtered out)`        | The SDK trigger's `filter` slot returned false — delivery acknowledged with 200, agent not invoked. |
| 🚫 `SKIPPED (trigger inactive)`    | The trigger was deactivated at delivery time.                                                       |

### rotate-token

Prints the **new** URL and confirms the old one is dead:

```
✅ Token rotated for "order-created" — the old URL no longer works

🔗 New trigger URL (update it everywhere it was pasted):

   https://trigger.heylua.ai/trigger/6978e0294d9c2007ed5cb129/7c1a40d8-5e92-4f6b-a3d1-8b9c0d1e2f3a
```

## SDK Triggers and `lua push`

SDK triggers are not created with this command — they are defined in code and deployed with `lua push`, which compiles each trigger, uploads a new version, and records it in `lua.skill.yaml`:

```yaml theme={null}
triggers:
  - name: github-pr-assigned
    triggerId: 5f4c9a1e-2b7d-4c03-9e88-1a2b3c4d5e6f
    version: 1.0.1
```

Once pushed, SDK triggers appear in `lua triggers list` alongside URL triggers, and `logs`, `activate`/`deactivate`, and `rotate-token` all work the same way.

## Common Workflow

```bash theme={null}
# Edit your trigger in src/triggers/pr-assigned.trigger.ts, then:
lua push                                            # Build + deploy
lua triggers list                                   # Confirm it's live, copy the URL
# Paste the URL into the external service (GitHub, Stripe, ...)
curl -X POST <url> -H 'Content-Type: application/json' -d '{"test":true}'
lua triggers logs --trigger github-pr-assigned      # Verify the delivery pipeline
```

## Related

* [LuaTrigger API](/api/luatrigger) — defining SDK triggers with verify/filter/transform
* [LuaWebhook API](/api/luawebhook) — when you need full request/response control
* [Webhooks Command](/cli/webhooks-command) — managing webhook primitives
* [Integrations Command](/cli/integrations-command) — integration triggers for connected apps (Linear, HubSpot, ...)
* [Env Command](/cli/env-command) — secrets for verify slots