Triggers Command

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 and deployed via lua push. These add declarative verify / filter / transform shaping in front of the agent turn.

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

For defining SDK triggers in code, see the LuaTrigger API. Looking for integration triggers (Linear, HubSpot, and other connected apps)? Those are managed with lua integrations webhooks.

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:

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.

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.

Examples

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

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

# 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

LuaTrigger API — defining SDK triggers with verify/filter/transform
LuaWebhook API — when you need full request/response control
Webhooks Command — managing webhook primitives
Integrations Command — integration triggers for connected apps (Linear, HubSpot, …)
Env Command — secrets for verify slots

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Triggers Command

Overview

Subcommands

Options

The Paste-Anywhere URL Workflow

Examples

Output Shapes

list

logs

rotate-token

SDK Triggers and `lua push`

Common Workflow

​Overview

​Subcommands

​Options

​The Paste-Anywhere URL Workflow

​Examples

​Output Shapes

​list

​logs

​rotate-token

​SDK Triggers and lua push

​Common Workflow

​Related

Overview

Subcommands

Options

The Paste-Anywhere URL Workflow

Examples

Output Shapes

list

logs

rotate-token

SDK Triggers and `lua push`

Common Workflow

Related