# AI Agent Building Guide
Source: https://docs.heylua.ai/ai-guide

Complete reference for AI Agents and AI Coding IDEs (Cursor, Windsurf, GitHub Copilot) to build, test, and deploy agents on the Lua platform

## Purpose

This guide is for AI agents and coding IDEs that build, test, and deploy agents on the Lua platform.

The build commands use non-interactive flags where practical. Authentication is the exception: keep emails, OTPs, and credentials out of the AI conversation.

## Prerequisites

* Node.js 18+ installed
* npm, yarn, or pnpm
* Lua CLI installed: `npm install -g lua-cli`
* Authentication configured (see below)

## High-Level Workflow

```
Authenticate → lua init → Write Code → lua test → iterate → lua chat sandbox → push → version create → version promote
                              ↓
                    (Optional) lua integrations connect → Agent gets third-party tools instantly
```

After **`lua init`**, the CLI surfaces a suggested build loop: **compile → test → chat (sandbox) → push and deploy**. Treat that sequence as your default checklist before iterating on agent code. Once the agent has release history, prefer `lua version create` + `lua version promote` as your release step instead of `lua deploy` — see [§7](#7-push-deploy-and-agent-versions) for the full distinction.

***

## 1. Authentication

<Note>
  Authenticate before you run a command that calls the Lua platform.
</Note>

### New login

Ask the user to open a private terminal outside the AI conversation and run:

```bash theme={null}
lua auth configure
```

For email login, the CLI saves a renewable first-party session. It reads the user's current organizations and agents when commands run. Agent selection belongs to each project's `lua.skill.yaml`.

Do not ask the user for their email address, OTP, or saved credential. Continue after the user confirms that setup finished.

### Existing credential

`lua auth configure` also accepts an existing scoped or non-dotted legacy API key. The CLI validates and saves the supplied value unchanged. It does not rotate or revoke the key.

If the environment already contains a working `LUA_API_KEY`, do not replace it.

### CI and unattended jobs

Create a scoped credential in **Settings → API Keys**. Store the secret in the CI provider, then expose it to the job:

```bash theme={null}
# The CI runner injects LUA_API_KEY from its secret manager.
lua push all --ci --force --auto-deploy
```

The CLI reads credentials in this order:

1. `LUA_API_KEY`; if it is not exported, the CLI loads it from the current project's `.env`
2. The renewable session for the active Lua environment
3. `~/.lua-cli/credentials`

Existing legacy credentials remain supported indefinitely. For CI and unattended jobs, use a scoped key with only the organizations, agents, and role that the job needs.

***

## 2. Initialization (`lua init`)

<Warning>
  **Run `lua init` only ONCE per project.** After initialization, you have your agent and codebase - work on it from there.
</Warning>

### Two Modes

#### New Agent (`--agent-name`)

Creates a brand new agent from scratch:

```bash theme={null}
# Create agent in existing organization
lua init --agent-name "My Agent" --org-id org_abc123

# Create agent + new organization
lua init --agent-name "My Agent" --org-name "My Company"

# With example code included
lua init --agent-name "My Agent" --org-id org_abc123 --with-examples
```

#### Existing Agent (`--agent-id`)

Links to an agent that already exists:

```bash theme={null}
lua init --agent-id agent_abc123

# Override existing project
lua init --agent-id agent_abc123 --force
```

<Note>
  **Important limitation**: Existing code/primitives on the server CANNOT be pulled down to local codebase. Bundling is one-way only (local → server). Use this mode to start fresh development on an existing agent.
</Note>

### Non-Interactive Flags

| Flag                  | Description               |
| --------------------- | ------------------------- |
| `--agent-id <id>`     | Use existing agent        |
| `--agent-name <name>` | Name for new agent        |
| `--org-id <id>`       | Existing organization ID  |
| `--org-name <name>`   | Create new organization   |
| `--with-examples`     | Include example code      |
| `--force`             | Override existing project |

### Project Structure Created

```
project/
├── lua.skill.yaml      # Config manifest (managed by CLI, don't edit manually)
├── package.json
├── tsconfig.json
├── .env                # Local environment variables
└── src/
    └── index.ts        # LuaAgent configuration
```

***

## 3. Debugging with `lua logs` (read this BEFORE you write tools)

<Note>
  **This section is promoted to the top because every AI builder needs the post-deploy loop in their head before they write a single tool.** All `console.log`, `console.error`, etc. output from your tool code shows up in `lua logs`. The CLI also prints a `✨ Tip:` line at the end of every push/deploy/chat/sync/compile/test pointing at the right `lua logs --type X --limit N` command for what you just ran. Follow it.
</Note>

The single canonical post-deploy loop is:

```
lua push --auto-deploy → lua chat -m "test" → lua logs --type X --limit 10
```

For the full canonical guide, see [Debugging your agent — the post-deploy loop](/cli/debugging).

### The "post-test-always-check" pattern

After every `lua chat -m "test"`, immediately run:

```bash theme={null}
lua logs --type agent_error --limit 5
```

If the count is **zero**, the test passed cleanly. If **non-zero**, fix the error before running another test message — most pipeline errors (billing, validation, LLM provider failures) don't surface in the chat response itself.

The CLI helps by running a quiet `agent_error` probe automatically after every `lua chat` turn — when new errors fire, you'll see:

```
⚠️  2 new agent error(s) during this turn — run `lua logs --type agent_error --limit 2` to inspect.
```

Set `LUA_NO_HINTS=1` to silence all post-action hints.

### Post-deploy verification recipe

After deploying, always run this 3-line check:

```bash theme={null}
lua push all --force --auto-deploy
lua chat -m "verify deploy" -e production -t prod-verify --clear
lua logs --type agent_error --limit 5  # should be empty
```

If step 3 returns entries timestamped after your deploy, **don't walk away** — read them and decide whether to roll back.

<Warning>
  **Important:** `lua logs` returns **zero** results right after deploy until something executes. Generate traffic first, for example:

  ```bash theme={null}
  lua chat -e production -m "test"
  ```

  Then inspect:

  ```bash theme={null}
  lua logs --type skill --limit 10
  ```
</Warning>

### `lua logs` quick reference

```bash theme={null}
# View all logs
lua logs --type all --limit 50

# Filter by type (the CLI suggests the right --type after each command)
lua logs --type skill --name mySkill --limit 10
lua logs --type job --name healthCheck --json
lua logs --type webhook --limit 20
lua logs --type agent_error --limit 10  # post-chat canary
lua logs --type mcp --limit 20
lua logs --type rag --limit 10
lua logs --type runtime --limit 20

# Filter by user (for user-reported issues)
lua logs --type all --user-id user_abc123 --limit 50
```

### Filter types

| Type             | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| `all`            | All logs                                                                 |
| `skill`          | Skill/tool executions                                                    |
| `job`            | Job executions                                                           |
| `webhook`        | Webhook executions                                                       |
| `preprocessor`   | PreProcessor executions                                                  |
| `postprocessor`  | PostProcessor executions                                                 |
| `mcp`            | MCP tool executions                                                      |
| `runtime`        | Agent runtime / LLM SDK / framework-level logs (was previously `mastra`) |
| `rag`            | Knowledge-base / RAG retrieval logs                                      |
| `device`         | Device command executions                                                |
| `device-trigger` | Device trigger handler executions                                        |
| `user_message`   | User messages                                                            |
| `agent_response` | Agent responses                                                          |
| `agent_error`    | Pipeline errors — the signal to watch after a `lua chat` test            |
| `calls`          | Voice call records                                                       |

***

## 4. Agent Configuration (LuaAgent)

The main configuration lives in `src/index.ts`:

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

export const agent = new LuaAgent({
  name: 'my-agent',
  
  persona: `You are a helpful assistant.
  
Your role:
- Help users with their tasks
- Provide accurate information

Communication style:
- Friendly and professional
- Clear and concise`,

  skills: [mySkill],
  
  // Optional components:
  // webhooks: [myWebhook],
  // jobs: [myJob],
  // preProcessors: [myPreProcessor],
  // postProcessors: [myPostProcessor],
});
```

### Key Properties

| Property         | Required | Description                                                                                                         |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`           | Yes      | Agent identifier                                                                                                    |
| `persona`        | Yes      | Personality, behavior, capabilities, limitations                                                                    |
| `model`          | No       | AI model to use — string like `'google/gemini-2.5-flash'` or a function `(request) => string` for dynamic selection |
| `skills`         | Yes      | Array of LuaSkill instances                                                                                         |
| `webhooks`       | No       | HTTP endpoints for external events                                                                                  |
| `jobs`           | No       | Scheduled cron tasks                                                                                                |
| `preProcessors`  | No       | Message filters before agent processes                                                                              |
| `postProcessors` | No       | Response formatters after agent responds                                                                            |
| `mcpServers`     | No       | External MCP tool servers (also auto-created via `lua integrations`)                                                |

***

## 5. Building Components

### Skills & Tools

A **Skill** is a collection of related tools:

```typescript theme={null}
import { LuaSkill } from 'lua-cli';

const mySkill = new LuaSkill({
  name: 'my-skill',
  description: 'Brief description of the skill',
  context: `Detailed instructions for when to use these tools.
  
  - Use tool_a when user asks about X
  - Use tool_b when user wants to do Y`,
  tools: [new ToolA(), new ToolB()]
});
```

A **Tool** is a single function the AI can call:

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

class GetWeatherTool implements LuaTool {
  name = 'get_weather';
  description = 'Get current weather for a city';
  
  inputSchema = z.object({
    city: z.string().describe('City name'),
    units: z.enum(['metric', 'imperial']).optional().default('metric')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const { city, units } = input;
    // Implementation here
    return { temperature: 22, condition: 'sunny', city };
  }
}
```

### Webhooks

HTTP endpoints for external events:

```typescript theme={null}
import { LuaWebhook } from 'lua-cli';
import { z } from 'zod';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  description: 'Handle Stripe payment events',
  
  bodySchema: z.object({
    type: z.string(),
    data: z.any()
  }),

  execute: async (event) => {
    const { body } = event;
    // Handle the webhook
    return { received: true };
  }
});
```

### Jobs

Scheduled cron tasks:

```typescript theme={null}
import { LuaJob } from 'lua-cli';

const dailyReport = new LuaJob({
  name: 'daily-report',
  description: 'Generate daily report',
  schedule: { type: 'cron', expression: '0 9 * * *' }, // 9 AM daily

  execute: async (job) => {
    // Generate report
    return { status: 'completed' };
  }
});
```

### PreProcessors & PostProcessors

```typescript theme={null}
import { PreProcessor, PostProcessor } from 'lua-cli';

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Filter inappropriate content',

  execute: async (user, messages, channel) => {
    // Return { action: 'block', response } to block, or { action: 'proceed' } to continue
    const text = messages.map(m => m.type === 'text' ? m.text : '').join(' ');
    if (containsProfanity(text)) {
      return { action: 'block', response: 'Message blocked due to inappropriate content.' };
    }
    return { action: 'proceed' };
  }
});

const addDisclaimer = new PostProcessor({
  name: 'add-disclaimer',
  description: 'Add legal disclaimer to responses',

  execute: async (user, message, response, channel) => {
    return { modifiedResponse: response + '\n\n_This is not legal advice._' };
  }
});
```

***

## 6. Testing Strategy

<Note>
  This is one of the most important sections. Understanding when to use `lua test` vs `lua chat` is critical.
</Note>

### `lua test` - Isolated Component Testing

**Purpose**: Unit test for individual blocks (tools, jobs, webhooks, processors)

**How it works**:

* Creates a local VM and executes code directly
* **No AI involved** - just runs the `execute` function
* Fast - no network latency, no AI processing time

**Use for**: Quick testing, quick debugging, building components in isolation

**Input format**: Must match the tool's `inputSchema` exactly

```bash theme={null}
# Test a tool
lua test skill --name get_weather --input '{"city": "London"}'

# Test a webhook
lua test webhook --name payment-webhook --input '{"query": {}, "headers": {}, "body": {"type": "payment.completed"}}'

# Test a job
lua test job --name daily-report

# Test a preprocessor
lua test preprocessor --name profanity-filter --input '{"message": "hello", "channel": "web"}'

# Test a postprocessor
lua test postprocessor --name add-disclaimer --input '{"message": "hi", "response": "hello", "channel": "web"}'
```

### `lua chat` - Live Agent Testing

**Purpose**: Real agent requests involving AI

**How it works**:

* HTTP requests for streaming/generating responses
* Full integration - multiple components may execute (skills, tools, pre/post-processors)

**Two modes**:

| Mode         | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `sandbox`    | Free, unbilled, can override local code without push/deploy |
| `production` | Uses pushed and deployed versions                           |

```bash theme={null}
# Test in sandbox (uses local code)
lua chat -e sandbox -m "What's the weather in London?"

# Test in production (uses deployed code)
lua chat -e production -m "What's the weather in London?"
```

### Key Difference

| Command    | What it does                         | AI involved? | Speed  |
| ---------- | ------------------------------------ | ------------ | ------ |
| `lua test` | Runs execute function directly in VM | No           | Fast   |
| `lua chat` | Full agent request with AI           | Yes          | Slower |

### Thread Isolation for Testing

<Note>
  **Recommended for AI agents running automated tests.** Use `--thread` to scope each chat session to an isolated conversation context. This prevents test state from leaking between runs — no need to call `lua chat clear` between tests.
</Note>

Each `--thread` creates a completely independent conversation context. This also means **multiple tests can run concurrently** (5-10 at a time) without interfering with each other.

```bash theme={null}
# Scope to an explicit thread ID
lua chat -e sandbox -m "Test scenario A" --thread scenario-a

# Auto-generate a UUID thread (printed at start so you can log/reuse it)
lua chat -e sandbox -m "Test scenario B" --thread

# Isolated test with automatic cleanup after response
lua chat -e sandbox -m "Test scenario C" -t scenario-c --clear

# Run 10 isolated tests sequentially, each with a clean context
for i in $(seq 1 10); do
  lua chat -e sandbox -m "test scenario $i" -t "test-$i" --clear
done
```

**`--thread` flags:**

| Flag                        | Description                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `-t, --thread [id]`         | Scope to a named thread. Omit the ID to auto-generate a UUID. Thread ID is printed at session start.                           |
| `--clear`, `--clear-thread` | Clear the thread's history when the session ends (interactive: on exit, non-interactive: after response). Requires `--thread`. |

### Concurrent Testing

Because each `--thread` is a fully isolated conversation, you can run multiple `lua chat` invocations in parallel without any state collision. This is especially useful for AI agents that need to validate multiple conversation scenarios at once:

```bash theme={null}
# Run 5 tests in parallel (background jobs)
lua chat -e sandbox -m "test flow A" -t test-a --clear &
lua chat -e sandbox -m "test flow B" -t test-b --clear &
lua chat -e sandbox -m "test flow C" -t test-c --clear &
lua chat -e sandbox -m "test flow D" -t test-d --clear &
lua chat -e sandbox -m "test flow E" -t test-e --clear &
wait  # wait for all to complete
```

### Clearing Conversation History (`lua chat clear`)

```bash theme={null}
# Clear all conversation history
lua chat clear --force

# Clear specific user's history
lua chat clear --user user@email.com --force
lua chat clear --user +1234567890 --force
lua chat clear --user user_abc123 --force

# Clear a specific thread's history
lua chat clear --thread my-test-scenario --force
```

Without `--user`, the command clears only the authenticated caller's history. `--user` requires `org:manage` for the agent. Organization-admin grants do not cascade to private agents; organization owners and sufficient explicit agent grants retain access under the shared authorization rules. Only users associated with that agent can be targeted.

**When to use `lua chat clear` vs `--thread`**:

| Approach                 | When to use                                                  |
| ------------------------ | ------------------------------------------------------------ |
| `lua chat clear --force` | Reset all history before a new development session           |
| `--thread <id>`          | Isolate individual test runs without touching other contexts |
| `--clear`                | Auto-clean up thread history at end of each automated test   |

### Recommended Development Workflow

```bash theme={null}
# 1. Write/modify component code

# 2. Quick isolated test
lua test skill --name my_tool --input '{"param": "value"}'

# 3. Check logs if issues
lua logs --type skill --name my_tool --limit 5

# 4. Iterate until component works

# 5. Test with full agent in an isolated thread (no need to clear history)
lua chat -e sandbox -m "Test message" -t dev-session

# 6. Run a suite of scenario tests concurrently
lua chat -e sandbox -m "scenario 1" -t s1 --clear &
lua chat -e sandbox -m "scenario 2" -t s2 --clear &
wait

# 7. When ready: push and deploy

# 8. Verify in production
lua chat -e production -m "Test message" -t prod-verify --clear
```

***

## 7. Push, Deploy, and Agent Versions

<Warning>
  Understanding this distinction is critical. Many users — and AI agents following this guide — confuse these commands.
</Warning>

There are three commands involved in getting code live, and they do three different things:

### `lua push` - Upload Code to Server

* Compiles local code and uploads to Lua platform server/database
* Mints a new immutable **version** of that one primitive
* Code now exists on server, not just locally
* **Activates nothing.** Does NOT make it live yet.

```bash theme={null}
# Push a specific skill with version
lua push skill --name mySkill --set-version 1.0.0 --force

# Push all components
lua push all --force

# Push and immediately deploy
lua push all --force --auto-deploy
```

### `lua version create` + `lua version promote` - Recommended Release Flow

* `lua version create` snapshots the latest **pushed** version of every primitive (skills, webhooks, jobs, processors, triggers, persona, voice, MCP config, model) into a single agent version.
* `lua version promote <N>` atomically activates that snapshot — every primitive switches at once, with no window where some are old and some are new.
* This is the recommended way to ship a release, especially when a change touches more than one primitive.

```bash theme={null}
# Push everything and snapshot in one step
lua version create --auto-push -m "checkout flow v2"

# Promote the resulting version — e.g. v2
lua version promote 2
```

See the [Version Command](/cli/version-command) page for the full command set, including `lua version status` (shows what's pushed but not yet live), `lua version diff`, and `lua version list`.

### `lua deploy` - Legacy Single-Primitive Activation

* Makes a previously pushed version of **one primitive** live/active.
* Still fully supported, and still the fastest path for a one-off, single-primitive fix.
* **Behavior depends on the agent's history:**
  * If the agent has **promoted at least one agent version already**, `lua deploy` performs a **scoped promote**: it creates and promotes a new agent version identical to the current one except for the primitive you just deployed. The change is live immediately, and it still appears in `lua version list` (tagged with a `deploy …` message) — so agent-version history stays consistent even when you use the legacy command.
  * If the agent has **never created or promoted an agent version**, `lua deploy` activates the primitive directly, as before.

```bash theme={null}
# Deploy specific version
lua deploy skill --name mySkill --set-version 1.0.5 --force

# Deploy latest version
lua deploy skill --name mySkill --set-version latest --force
```

### Key Difference

| Command                                      | What it does                                                                                                                                   |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `lua push`                                   | Upload a new version of one primitive to the server (staged, not live)                                                                         |
| `lua version create` + `lua version promote` | Snapshot every primitive, then atomically switch the whole agent to that snapshot — recommended flow                                           |
| `lua deploy`                                 | Activate one primitive's version now — scoped-promotes into version history if the agent already has versions, otherwise activates it directly |

After `lua push` **without** `--auto-deploy`, code is **staged, not live**. The CLI says so explicitly — for example:

```
✨ Staged but NOT live yet. To make it active: lua deploy skill
```

Use `lua push … --auto-deploy`, run `lua deploy` explicitly, or run `lua version create` + `lua version promote` before validating in production.

<Check>
  **Execution guarantee:** once `lua deploy` or `lua version promote` reports success, that exact code serves the very next invocation of the agent (allow up to roughly a minute for edge caches to catch up globally). Sandbox testing (`lua chat`, `lua test`) never touches what's live, and deactivating a primitive (e.g. a webhook) stops it serving immediately regardless of version history.
</Check>

***

## 8. Environment Variables

### Sandbox vs Production

| Environment | Source                                          |
| ----------- | ----------------------------------------------- |
| Sandbox     | Local `.env` file or CLI env variables          |
| Production  | Stored on server (set via `lua env production`) |

### Commands

```bash theme={null}
# List variables
lua env sandbox --list
lua env production --list

# Set variable
lua env sandbox -k API_KEY -v "sk-test-xxx"
lua env production -k API_KEY -v "sk-live-xxx"

# Delete variable
lua env production -k OLD_KEY --delete
```

Set environment variables **as needed** when code requires them.

***

## 9. Sandbox Overrides

When using `lua chat -e sandbox`, the following can be overridden with local compiled code **without needing to push/deploy**:

| Component      | How it works                                        |
| -------------- | --------------------------------------------------- |
| Skills         | Local compiled code pushed to Redis cache           |
| Persona        | Local persona overrides deployed production persona |
| PreProcessors  | Local code pushed to Redis cache                    |
| PostProcessors | Local code pushed to Redis cache                    |
| Environment    | Local `.env` file used                              |

This allows testing changes instantly without the push/deploy cycle.

***

## 10. Compilation Gotchas

The CLI uses **esbuild** to bundle each `execute` function:

### What Works

* Standard TypeScript code
* Imports from `package.json` dependencies
* Relative imports within your project

### What May Not Work

* Not all Node.js file structures are supported
* Each execute function's code is extracted and bundled separately
* `lua-cli` imports are stripped - APIs like `User`, `Products`, `Data`, `Agents` are sandbox globals

### Warning Signs

| Issue                        | Meaning                              |
| ---------------------------- | ------------------------------------ |
| Empty bundles (\< 100 bytes) | Something went wrong during bundling |
| "Could not resolve" errors   | Check imports/dependencies           |
| "Transform failed"           | TypeScript syntax issues             |

### Debug Mode

Run with `--debug` for verbose compilation output:

```bash theme={null}
lua compile --debug
```

***

## 11. Platform APIs Available at Runtime

These are available as **globals** in the VM sandbox (don't import from lua-cli):

| API            | Description                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `User`         | **Per-user persistent storage** — store onboarding state, preferences, workflow progress, or any custom data that persists across conversations |
| `Data`         | Custom data collections                                                                                                                         |
| `Products`     | Product catalog                                                                                                                                 |
| `Baskets`      | Shopping cart                                                                                                                                   |
| `Orders`       | Order management                                                                                                                                |
| `AI`           | AI generation                                                                                                                                   |
| `Lua`          | Request context (`Lua.request.channel`, `Lua.request.webhook`)                                                                                  |
| `Jobs`         | Job scheduling                                                                                                                                  |
| `Templates`    | Message templates                                                                                                                               |
| `CDN`          | File upload/retrieval                                                                                                                           |
| `BasketStatus` | Enum for basket statuses (`ACTIVE`, `CHECKED_OUT`, `ABANDONED`, `EXPIRED`)                                                                      |
| `OrderStatus`  | Enum for order statuses (`PENDING`, `CONFIRMED`, `FULFILLED`, `CANCELLED`)                                                                      |
| `env(key)`     | Environment variable access                                                                                                                     |
| `process.env`  | Environment variables as an object (alternative to `env()`)                                                                                     |
| `fetch`        | HTTP requests                                                                                                                                   |
| `console`      | Logging (appears in `lua logs`)                                                                                                                 |

### User: Per-User Persistent Storage

<Note>
  **Critical for AI agents building stateful workflows.** The `User` API is the primary way to maintain state across conversations. It is a **schemaless, persistent key-value store** scoped to each end-user — not just a profile reader.
</Note>

Any property you set on the user object **persists forever** (across conversations, sessions, days, months) until you explicitly change it. This makes it the go-to primitive for:

* **Onboarding flows** — track `user.onboardingStep`, `user.completedSteps`
* **Multi-step workflows** — accumulate data across tool calls with `user.collectedData`
* **Session state** — store `user.lastIntent`, `user.pendingAction`
* **User preferences** — persist `user.theme`, `user.language`, `user.notificationSettings`

```typescript theme={null}
// In any tool — read and write arbitrary user state
const user = await User.get();   // User is a sandbox global

// These properties persist FOREVER until you change them
user.onboardingStep = 'identity_verification';
user.collectedData = { name: 'Jane', company: 'Acme' };
user.completedSteps = ['welcome', 'personal_info'];
await user.save();

// Next conversation, next day, next month — it's still there
const user = await User.get();
console.log(user.onboardingStep); // 'identity_verification'
console.log(user.completedSteps); // ['welcome', 'personal_info']
```

**State machine pattern** — use `user.onboardingStep` (or any field) to track where the user is in a multi-step flow, then resume from that point in any future conversation:

```typescript theme={null}
const user = await User.get();
const step = user.onboardingStep || 'not_started';

if (step === 'not_started') {
  user.onboardingStep = 'collecting_info';
  await user.save();
  return { message: "Let's get started!" };
} else if (step === 'collecting_info') {
  user.companyName = input.companyName;
  user.onboardingStep = 'awaiting_verification';
  await user.save();
  return { message: 'Now let\'s verify your identity.' };
}
// ... continue for each step
```

See the full [User API reference](/api/user) for all methods (`update()`, `save()`, `send()`, `clear()`).

***

## 12. Third-Party Integrations (POWERFUL FEATURE)

<Note>
  **This is one of the most powerful features of the Lua platform.** With a single command, you can give your agent access to 250+ third-party services (Linear, Discord, Google Calendar, HubSpot, Slack, GitHub, and more) - **without writing any code**.
</Note>

### Why This Matters

Instead of:

* Writing API integration code
* Managing OAuth tokens and refresh logic
* Building tools for each third-party service
* Handling rate limits and error handling

You simply run:

```bash theme={null}
lua integrations connect --integration linear --auth-method oauth --scopes all --triggers task_task.created
```

And your agent **instantly** gets:

* Tools like `linear_create_issue`, `linear_list_projects`, `linear_update_task`, etc.
* **Triggers** that wake up your agent when events occur (e.g., when a new issue is created)

### How It Works

1. **Connect** - Authenticate with the third-party service via OAuth or API token
2. **Auto-MCP** - An MCP (Model Context Protocol) server is automatically created
3. **Instant Tools** - Your agent can immediately use tools from that integration
4. **Triggers** - Optionally enable triggers to wake up your agent on events

### Discovery Commands (For AI Agents)

Before connecting, use discovery commands to understand what's available:

```bash theme={null}
# List all available integrations
lua integrations available

# Get detailed info about an integration (scopes and triggers)
lua integrations info linear

# Get info as JSON (for parsing)
lua integrations info linear --json

# List available trigger events
lua integrations webhooks events --integration linear
lua integrations webhooks events --integration linear --json
```

**JSON output** is especially useful for AI coding assistants to programmatically discover:

* Available OAuth scopes with friendly descriptions
* Available trigger events with friendly descriptions
* Webhook types (native vs virtual)

### Connecting an Integration

```bash theme={null}
# View available integrations
lua integrations available

# Connect with OAuth and triggers (recommended)
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated

# Connect with all available triggers
lua integrations connect --integration linear --auth-method oauth --scopes all --triggers all

# Connect with specific scopes only (no triggers)
lua integrations connect --integration linear --auth-method oauth --scopes "task_task_read,task_task_write"

# Connect with API token
lua integrations connect --integration linear --auth-method token

# List connected integrations
lua integrations list

# Update scopes on existing connection
lua integrations update --integration linear --scopes all

# Disconnect
lua integrations disconnect --connection-id <id>
```

### Triggers: Event-Driven Agent Wake-Up

**Triggers** are one of the easiest ways to make your agent reactive. When enabled, your agent automatically wakes up when events occur in connected services.

```bash theme={null}
# Enable triggers during connection
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated

# Or add triggers after connection
lua integrations webhooks create --connection <id> --object task_task --event created

# List active triggers
lua integrations webhooks list

# Delete a trigger
lua integrations webhooks delete --webhook-id <id>
```

**What happens when a trigger fires:**

1. An event occurs in the connected service (e.g., a new Linear issue is created)
2. Unified.to sends a webhook to your agent
3. Your agent wakes up with the event data in `runtimeContext`
4. The agent can respond based on what happened

### Testing Integration Tools

After connecting, test immediately. Use `--thread` to keep each test isolated:

```bash theme={null}
# Test integration tools in isolated threads (can run concurrently)
lua chat -e sandbox -m "Create a Linear issue titled 'Test from Lua' in my default project" -t test-linear --clear

lua chat -e sandbox -m "List my upcoming Google Calendar events" -t test-gcal --clear

lua chat -e sandbox -m "Send a message to the #general channel on Discord" -t test-discord --clear
```

### Available Integrations (250+)

Common integrations include:

| Category            | Examples                                         |
| ------------------- | ------------------------------------------------ |
| **Task Management** | Linear, Asana, Jira, Monday.com, ClickUp, Notion |
| **Communication**   | Discord, Slack, Microsoft Teams, Telegram        |
| **Calendar**        | Google Calendar, Outlook Calendar, Calendly      |
| **CRM**             | HubSpot, Salesforce, Pipedrive, Zoho CRM         |
| **Development**     | GitHub, GitLab, Bitbucket                        |
| **Storage**         | Google Drive, Dropbox, OneDrive, Box             |
| **Support**         | Zendesk, Intercom, Freshdesk                     |
| **Email**           | Gmail, Outlook, SendGrid                         |

Run `lua integrations available` to see all available integrations for your workspace.

### Managing MCP Servers for Integrations

Each integration creates an MCP server. You can manage them:

```bash theme={null}
# List MCP servers and their status
lua integrations mcp list

# Deactivate (hide tools from agent)
lua integrations mcp deactivate --connection <id>

# Reactivate
lua integrations mcp activate --connection <id>
```

### Integration Workflow Example

```bash theme={null}
# 1. Discover available integrations and their capabilities
lua integrations available
lua integrations info linear --json

# 2. Connect Linear with triggers
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated
# (Complete OAuth in browser)

# 3. Verify connection and triggers
lua integrations list
lua integrations webhooks list

# 4. Test the integration in isolated threads
lua chat -e sandbox -m "List all Linear projects I have access to" -t test-list --clear
lua chat -e sandbox -m "Create a task in Linear: Review documentation updates" -t test-create --clear

# 5. The agent now has full Linear capabilities and reacts to events!
```

### Key Points for AI Agents

<Warning>
  **Important for AI coding assistants building Lua agents:**

  1. **Use discovery commands** to understand what's available:
     * `lua integrations available` - list integrations
     * `lua integrations info <type> --json` - get scopes and triggers
     * `lua integrations webhooks events --integration <type> --json` - get trigger events

  2. **Enable triggers** during connection for event-driven workflows:
     * `--triggers task_task.created,task_task.updated` - specific triggers
     * `--triggers all` - all available triggers

  3. **Connect integrations** before writing custom tool code - the integration might already provide what's needed

  4. **Test with `lua chat`** after connecting to verify tools are available

  5. **One connection per integration type** per agent - use `update` to change scopes
</Warning>

***

## 13. Complete Workflow Example

```bash theme={null}
# 0. Authenticate (one-time setup)
# The user runs this in a private terminal outside the AI conversation.
lua auth configure

# 1. Initialize project (one-time per agent)
lua init --agent-id agent_abc123

# 2. Set environment variables (as needed)
lua env sandbox -k OPENAI_KEY -v "sk-test-xxx"

# 3. (OPTIONAL BUT POWERFUL) Connect third-party integrations
lua integrations available                                          # See what's available
lua integrations connect --integration linear --auth-method oauth --scopes all
lua integrations connect --integration discord --auth-method oauth --scopes all
lua integrations list                                                # Verify connections

# 4. Write your code in src/

# 5. Test individual components
lua test skill --name get_order --input '{"orderId": "123"}'

# 6. Check logs if issues
lua logs --type skill --name get_order --limit 5

# 7. Test with full agent in isolated threads (sandbox)
lua chat -e sandbox -m "Get order 123" -t test-get-order --clear
lua chat -e sandbox -m "Create a Linear issue for order 123 review" -t test-linear --clear  # If Linear connected

# Or run both concurrently
lua chat -e sandbox -m "Get order 123" -t test-get-order --clear &
lua chat -e sandbox -m "Create a Linear issue" -t test-linear --clear &
wait

# 8. Push to server
lua push skill --name order-service --set-version 1.0.0 --force

# 9. Deploy to production
# (single primitive, fast path — see §7 for when to prefer
#  `lua version create --auto-push` + `lua version promote` instead)
lua deploy skill --name order-service --set-version latest --force

# 10. Set production env vars
lua env production -k OPENAI_KEY -v "sk-live-xxx"

# 11. Test production in isolated thread
lua chat -e production -m "Get order 123" -t prod-verify --clear

# 12. Monitor logs
lua logs --type skill --name order-service --limit 10 --json
```

***

## Quick Reference: Non-Interactive Commands

| Task                                               | Command                                                                                              |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| New local login                                    | User runs `lua auth configure` in a private terminal                                                 |
| CI authentication                                  | Set `LUA_API_KEY` from the CI secret manager                                                         |
| Initialize with existing agent                     | `lua init --agent-id <id>`                                                                           |
| Initialize with new agent                          | `lua init --agent-name <name> --org-id <id>`                                                         |
| Test a tool                                        | `lua test skill --name <name> --input '<json>'`                                                      |
| Test a webhook                                     | `lua test webhook --name <name> --input '<json>'`                                                    |
| Test a job                                         | `lua test job --name <name>`                                                                         |
| Chat in sandbox                                    | `lua chat -e sandbox -m "<message>"`                                                                 |
| Chat in production                                 | `lua chat -e production -m "<message>"`                                                              |
| Chat in isolated thread                            | `lua chat -e sandbox -m "<message>" -t <thread-id>`                                                  |
| Chat in auto-generated thread                      | `lua chat -e sandbox -m "<message>" -t`                                                              |
| Isolated test with auto-cleanup                    | `lua chat -e sandbox -m "<message>" -t <id> --clear`                                                 |
| Clear all conversation history                     | `lua chat clear --force`                                                                             |
| Clear another user's history (`org:manage`)        | `lua chat clear --user <email\|mobile\|userId> --force`                                              |
| Clear specific thread history                      | `lua chat clear --thread <thread-id> --force`                                                        |
| View available integrations                        | `lua integrations available`                                                                         |
| Get integration info (JSON)                        | `lua integrations info <type> --json`                                                                |
| List trigger events (JSON)                         | `lua integrations webhooks events --integration <type> --json`                                       |
| Connect with triggers                              | `lua integrations connect --integration <type> --auth-method oauth --scopes all --triggers <events>` |
| Connect integration (OAuth)                        | `lua integrations connect --integration <type> --auth-method oauth --scopes all`                     |
| Connect integration (Token)                        | `lua integrations connect --integration <type> --auth-method token`                                  |
| List connected integrations                        | `lua integrations list`                                                                              |
| Update integration scopes                          | `lua integrations update --integration <type> --scopes all`                                          |
| Disconnect integration                             | `lua integrations disconnect --connection-id <id>`                                                   |
| List triggers                                      | `lua integrations webhooks list`                                                                     |
| Create trigger                                     | `lua integrations webhooks create --connection <id> --object <type> --event <event>`                 |
| Delete trigger                                     | `lua integrations webhooks delete --webhook-id <id>`                                                 |
| List integration MCP status                        | `lua integrations mcp list`                                                                          |
| Push all                                           | `lua push all --force`                                                                               |
| Push and deploy                                    | `lua push all --force --auto-deploy`                                                                 |
| Deploy specific version (legacy, single primitive) | `lua deploy skill --name <name> --set-version <ver> --force`                                         |
| Snapshot a release candidate                       | `lua version create --auto-push -m "<message>"`                                                      |
| Promote a release atomically                       | `lua version promote <N>`                                                                            |
| Check what's pushed but not live                   | `lua version status`                                                                                 |
| Set env variable                                   | `lua env <sandbox\|production> -k <key> -v <value>`                                                  |
| View logs                                          | `lua logs --type <type> --name <name> --limit <n>`                                                   |

***

## Related Documentation

<CardGroup>
  <Card title="Debugging Loop" icon="bug" href="/cli/debugging">
    Canonical post-deploy debug loop and the active `agent_error` probe
  </Card>

  <Card title="CLI Commands Reference" icon="terminal" href="/cli/overview">
    Complete CLI command documentation
  </Card>

  <Card title="Non-Interactive Mode" icon="robot" href="/cli/non-interactive-mode">
    All non-interactive flags and CI/CD examples
  </Card>

  <Card title="Integrations Command" icon="link" href="/cli/integrations-command">
    Connect 250+ third-party services
  </Card>

  <Card title="LuaAgent API" icon="code" href="/api/luaagent">
    Complete LuaAgent configuration reference
  </Card>

  <Card title="Platform APIs" icon="plug" href="/concepts/platform-apis">
    User, Data, Products, and other runtime APIs
  </Card>

  <Card title="MCP Servers" icon="server" href="/cli/mcp-command">
    Manage MCP servers for external tools
  </Card>

  <Card title="Version Command" icon="code-branch" href="/cli/version-command">
    Atomic agent versions, promote, rollback, and version status
  </Card>
</CardGroup>


# Agents API
Source: https://docs.heylua.ai/api/agents

Invoke the current agent or another agent from Lua runtime code

## Overview

The Agents API lets Lua runtime code — tools, webhooks, jobs, preprocessors, and postprocessors — invoke the current agent or another agent through the full chat pipeline. The invocation goes through billing, message persistence, skills and tools, preprocessors, postprocessors, and governance on the target agent.

```typescript theme={null}
import { Agents } from 'lua-cli';

// Simplified: returns plain text
const reply = await Agents.invoke('sales-agent', 'Summarize the last order.');

// Full options: returns structured output
const result = await Agents.invoke('sales-agent', {
  prompt: 'Draft a reply to the latest order',
  threadId: 'order-123',
  systemPrompt: 'Be concise.',
});
console.log(result.text, result.usage);
```

<Note>
  **Full Pipeline Execution:** Unlike `AI.generate`, `Agents.invoke` routes through the target agent's complete processing stack — including its skills, tools, preprocessors, postprocessors, and governance rules.
</Note>

<Tip>
  **Use this inside agent primitives.** `/chat/generate` and `/chat/stream` are external consumption APIs for apps and services. `Agents.invoke` is the runtime API for starting an agent turn from Lua code, so it does not require an API base URL or user bearer token.
</Tip>

## Run Your Own Agent on a Schedule

Self-invocation is supported: pass the current agent's ID as `targetAgentId`. This is useful when a `LuaJob` needs the agent itself to run a scheduled prompt with its normal skills and tools.

```typescript theme={null}
import { Agents, LuaJob, env } from 'lua-cli';

export default new LuaJob({
  name: 'weekly-pipeline-review',
  description: 'Run the agent weekly against the latest pipeline data',
  schedule: { type: 'cron', expression: '0 7 * * 1', timezone: 'UTC' },
  execute: async (job) => {
    const currentAgentId = env('CURRENT_AGENT_ID');
    if (!currentAgentId) throw new Error('CURRENT_AGENT_ID is required');

    return Agents.invoke(currentAgentId, {
      prompt: 'Review the current pipeline and produce the weekly digest.',
      userId: job.metadata.userId,
      threadId: 'weekly-pipeline-review',
    });
  },
  metadata: { userId: 'user_abc123' },
});
```

<Warning>
  `Agents.invoke` currently requires an explicit `targetAgentId`; there is no `self` sentinel or ambient current-agent ID in the runtime API. A reusable template that self-invokes must still receive its deployed agent ID as configuration. It does **not** need an API URL or bearer token.
</Warning>

## Import

```typescript theme={null}
import { Agents } from 'lua-cli';
// or
import { Agents } from 'lua-cli/skill';
```

## Calling Contexts

| Context                          | User identity                    | Recommended pattern                                                      |
| -------------------------------- | -------------------------------- | ------------------------------------------------------------------------ |
| **Tool** (user turn)             | Caller's user automatically used | `Agents.invoke(id, prompt)` — no `userId` needed                         |
| **Dynamic Job** (Jobs API)       | Caller's user automatically used | `Agents.invoke(id, prompt)` — no `userId` needed                         |
| **Webhook**                      | No ambient user                  | Pass `userId` from event payload, or omit to run without a user identity |
| **Pre-defined LuaJob**           | No ambient user                  | Pass `userId` from metadata, or omit to run without a user identity      |
| **PreProcessor / PostProcessor** | Caller's user automatically used | `Agents.invoke(id, prompt)` — no `userId` needed                         |

<Note>
  **No user identity** — when no `userId` is available (e.g. a webhook with no user context), the invocation runs without a user identity and no conversation history is stored. Use `userId` from your event payload whenever you have one.
</Note>

### Execution and delivery semantics

`Agents.invoke` waits for a complete agent turn and returns that turn's response to the calling code. During the turn, the target agent's tools execute normally and their side effects are real.

The returned response is **not automatically sent to a user or channel**. Delivery only occurs if the invoked agent calls a delivery tool, or if the calling code sends `result.text` through a runtime API such as `User` or `Channels`.

* In a user-authenticated tool, dynamic job, or processor, the ambient user is used automatically.
* In a pre-defined `LuaJob` or userless webhook, pass `userId` when the invoked tools or later delivery need a user. Without it, the turn runs in system scope with no user profile or conversation history.
* `channel` sets the target turn's channel context. It does not, by itself, deliver the returned text to that channel.

## Methods

### Simplified: `Agents.invoke(targetAgentId, prompt)`

Invoke an agent with a plain text prompt. Returns the assistant's response as a plain string.

<ParamField type="string">
  The target agent's identifier (e.g. `'sales-agent'`, `'support-agent'`). Pass the current agent's own ID to self-invoke. There is currently no `self` sentinel or ambient self-ID.
</ParamField>

<ParamField type="string">
  Plain-text message to send to the target agent.
</ParamField>

**Returns:** `Promise<string>`

```typescript theme={null}
const summary = await Agents.invoke('sales-agent', 'Summarize the last order.');
console.log(summary); // "The last order was for 3 units of..."
```

### Full options: `Agents.invoke(targetAgentId, input)`

Invoke an agent with full control over the request. Returns a structured output object.

<ParamField type="string">
  The target agent's identifier. Pass the current agent's own ID to self-invoke.
</ParamField>

<ParamField type="AgentInvocationInput">
  Full invocation options — see below.
</ParamField>

**Returns:** `Promise<AgentInvocationOutput>`

## `AgentInvocationInput`

<ParamField type="string">
  Plain-text user message. Mutually exclusive with `messages`.
</ParamField>

<ParamField type="UserContent">
  AI SDK `UserContent` (array of `TextPart`, `ImagePart`, `FilePart`). Mutually exclusive with `prompt`.
</ParamField>

<ParamField type="string">
  Override the target agent's system prompt for this invocation only.
</ParamField>

<ParamField type="string">
  Additional runtime context string attached to the request (e.g. serialised metadata).
</ParamField>

<ParamField type="object">
  Client-side context for the invocation. Supports `timezone` — an IANA timezone string (e.g. `'Africa/Nairobi'`) used as the user's local timezone for date/time-aware responses. When omitted, the target agent falls back to the user's stored profile, country, or UTC.
</ParamField>

<ParamField type="string">
  Thread ID suffix for conversation scoping. When omitted, the invocation flows into the caller-user's default chat thread with the target agent — the same behaviour as a direct message. Pass a custom value to isolate this invocation in its own thread.
</ParamField>

<ParamField type="string">
  Channel context for the invoked turn. Defaults to `'agent-invocation'`. This does not automatically deliver the returned response to a channel.
</ParamField>

<ParamField type="string">
  Free-form request tag persisted on the stored message record (e.g. a UUID or external trace ID for correlation). Not a user identifier.
</ParamField>

<ParamField type="string">
  Explicit user to invoke as. Use from context-less triggers — webhooks and pre-defined jobs — where there is no ambient user. When omitted from a webhook or pre-defined job, the invocation runs without user identity and no conversation history is stored. This field is **ignored** during a user-authenticated turn; the turn's user is always used.
</ParamField>

## `AgentInvocationOutput`

| Field          | Type        | Description                                                                                                              |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `text`         | `string`    | Final response text (after the target agent's postprocessors).                                                           |
| `finishReason` | `string?`   | AI SDK `FinishReason` — `'stop'`, `'length'`, `'content-filter'`, `'preprocessor_blocked'`, `'governance_blocked'`, etc. |
| `usage`        | `object?`   | Token usage: `{ inputTokens, outputTokens, totalTokens, reasoningTokens, cachedInputTokens }`                            |
| `toolsUsed`    | `string[]?` | Names of tools invoked by the target agent during generation.                                                            |
| `threadId`     | `string?`   | Echoes back the `threadId` the caller passed in, if any.                                                                 |

## Error Handling

`Agents.invoke` throws an `Error` for any non-success response. Wrap calls in `try/catch` and inspect the message:

```typescript theme={null}
import { Agents } from 'lua-cli';

async function delegateToAgent(agentId: string, prompt: string) {
  try {
    const result = await Agents.invoke(agentId, { prompt });

    if (result.finishReason === 'preprocessor_blocked') {
      return { blocked: true, message: result.text };
    }
    if (result.finishReason === 'governance_blocked') {
      return { blocked: true, message: result.text };
    }

    return { success: true, text: result.text };
  } catch (error) {
    // Network, timeout, target disabled, insufficient credits, etc.
    return { success: false, error: error.message };
  }
}
```

**Common error causes:**

| Cause                 | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| Target agent disabled | The target agent is not available to the invoking user.                |
| Insufficient credits  | The account does not have enough credits to run the invocation.        |
| Timeout               | The target agent took longer than 120 s to respond.                    |
| Service unreachable   | The platform could not be reached (may occur during local `lua test`). |

## Complete Examples

### Tool routing to a specialist agent

```typescript theme={null}
import { LuaTool, Agents } from 'lua-cli/skill';
import { z } from 'zod';

export default class EscalateToLegalTool implements LuaTool {
  name = 'escalate_to_legal';
  description = 'Send a legal query to the dedicated legal-review agent';

  inputSchema = z.object({
    query: z.string().describe('The legal question to review'),
    contractId: z.string().optional(),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Agents.invoke('legal-review-agent', {
      prompt: input.query,
      threadId: input.contractId ? `contract-${input.contractId}` : undefined,
      systemPrompt: 'Respond in plain language suitable for a non-lawyer.',
    });

    return {
      legalAdvice: result.text,
      tokensUsed: result.usage?.totalTokens,
    };
  }
}
```

### Webhook delegating to an agent

When a webhook fires you typically have a user ID in the event payload — pass it via `userId` so the invocation runs in that user's context:

```typescript theme={null}
import { LuaWebhook, Agents } from 'lua-cli';

const orderWebhook = new LuaWebhook({
  name: 'order-shipped-webhook',
  description: 'Notify users when their order ships',

  execute: async (event) => {
    const { orderId, customerId, trackingNumber } = event.body ?? {};

    if (!customerId) {
      return { skipped: true, reason: 'no customerId in payload' };
    }

    // Pass userId so the invocation runs as that user — conversation history
    // is stored and any per-user agent rules apply.
    await Agents.invoke('notification-agent', {
      prompt: `Order ${orderId} has shipped. Tracking: ${trackingNumber}. Notify the customer.`,
      userId: customerId,
    });

    return { notified: true, customerId };
  },
});

export default orderWebhook;
```

### Pre-defined job with no user context

When no `userId` is available, omit it and the invocation runs without user identity. No conversation history is stored.

```typescript theme={null}
import { LuaJob, Agents } from 'lua-cli';

const dailyDigest = new LuaJob({
  name: 'daily-digest-generator',
  schedule: { type: 'cron', expression: '0 6 * * *' },

  execute: async (job) => {
    // No userId available — invocation runs without a user context
    const result = await Agents.invoke('digest-agent', {
      prompt: 'Generate the daily product digest for today.',
    });

    // Store the result for other processes to pick up
    return { digest: result.text, generatedAt: new Date().toISOString() };
  },
});

export default dailyDigest;
```

If the invoked agent uses `User.get()`, `User.send()`, or another user-scoped tool, include a real `userId` in the invocation. A system-scoped invocation cannot infer the template installer or a delivery recipient.

### Multi-modal input (image analysis)

```typescript theme={null}
import { LuaTool, Agents } from 'lua-cli/skill';
import { z } from 'zod';

export default class AnalyseReceiptTool implements LuaTool {
  name = 'analyse_receipt';
  description = 'Send a receipt image to the expense-processing agent';

  inputSchema = z.object({
    imageUrl: z.string().url(),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Agents.invoke('expense-agent', {
      messages: [
        { type: 'text', text: 'Extract line items and total from this receipt.' },
        { type: 'image', url: input.imageUrl },
      ],
    });

    return { extraction: result.text };
  }
}
```

## Limitations

* **No recursion guard** — avoid infinite agent-invoke loops in your code.
* **Explicit target required** — self-invocation works, but you must pass the current agent's ID. There is no `self` sentinel or ambient self-ID yet.
* **No native fire-and-forget** — `Agents.invoke` is always awaited. To run in the background, use the Jobs API to schedule a dynamic job.
* **`skillOverride` / `preprocessorOverride` not exposed** — the target agent always runs with its configured skills and preprocessors.
* **Persona override not exposed** — use `systemPrompt` to influence behaviour without replacing the full persona.
* **120 s timeout** — invocations that take longer than 120 seconds will throw a timeout error.

## Related APIs

<CardGroup>
  <Card title="AI API" href="/api/ai" icon="brain">
    Generate text outside the agent pipeline
  </Card>

  <Card title="User API" href="/api/user" icon="user">
    Get or update user context
  </Card>

  <Card title="LuaWebhook" href="/api/luawebhook" icon="webhook">
    HTTP endpoints for external events
  </Card>

  <Card title="LuaJob" href="/api/luajob" icon="clock">
    Pre-defined scheduled tasks
  </Card>

  <Card title="Jobs API" href="/api/jobs" icon="plus">
    Dynamic job creation
  </Card>

  <Card title="PostProcessor" href="/api/postprocessor" icon="paper-plane">
    Format agent responses
  </Card>
</CardGroup>

## See Also

* [HTTP API](/channels/http-api) — external `/chat/generate` and `/chat/stream` endpoints for apps and services consuming an agent
* [AI API](/api/ai) — isolated text generation without the full agent pipeline
* [LuaWebhook](/api/luawebhook) — triggering agents from external events
* [LuaJob](/api/luajob) — scheduled agent invocations


# AI API
Source: https://docs.heylua.ai/api/ai

Generate AI responses with custom context in your tools

## Overview

The AI API provides isolated text generation from within tools, aligned with [Vercel AI SDK `generateText`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text) semantics. Requests are proxied to a dedicated generation endpoint — they do **not** go through the agent chat pipeline.

```typescript theme={null}
import { AI } from 'lua-cli';

// Quick text generation
const text = await AI.generate('Summarize the latest AI news.');

// Full options with rich result
const result = await AI.generate({
  model: 'google/gemini-2.0-flash',
  system: 'You are concise.',
  prompt: 'What is the weather in London?',
});
```

<Note>
  **Powerful Tool Enhancement:** The AI API lets you embed AI generation directly in your tools with custom personas, multi-modal inputs, and rich response metadata.
</Note>

## Import

```typescript theme={null}
import { AI } from 'lua-cli';
// or
import { AI } from 'lua-cli/skill';
```

## Capabilities

<CardGroup>
  <Card title="Text Generation" icon="file-lines">
    Generate content with custom prompts and personas
  </Card>

  <Card title="Image Analysis" icon="image">
    Analyze images with AI vision capabilities
  </Card>

  <Card title="Document Processing" icon="file-pdf">
    Process and analyze documents with AI
  </Card>

  <Card title="Multi-Modal" icon="layer-group">
    Combine text, images, and files in one request
  </Card>

  <Card title="Multi-Provider" icon="server">
    Google (Vertex AI), OpenAI, and Anthropic models
  </Card>

  <Card title="Web Grounding" icon="globe">
    Google Search grounding with source URLs
  </Card>
</CardGroup>

## Methods

### Simplified: AI.generate(prompt, content?)

Quick text generation. Returns plain text as a string.

<ParamField type="string">
  When called with one argument, this is the user prompt. When called with two arguments, it becomes the system instruction.
</ParamField>

<ParamField type="UserContent">
  User message content. Accepts a string or an array of multimodal parts (`TextPart`, `ImagePart`, `FilePart`) from the AI SDK.
</ParamField>

**Returns:** `Promise<string>`

```typescript theme={null}
// Single argument: prompt is the user message
const text = await AI.generate('Summarize the latest AI news.');

// Two arguments: system instruction + user content
const text2 = await AI.generate(
  'You are a helpful assistant.',
  [{ type: 'text', text: 'What products do you recommend?' }]
);

// Multi-modal content
const analysis = await AI.generate(
  'You are an image analysis expert.',
  [
    { type: 'text', text: 'What do you see?' },
    { type: 'image', url: 'https://example.com/photo.jpg' }
  ]
);
```

### Full options: AI.generate(options)

Full control over generation parameters. Returns a rich result object.

<ParamField type="string">
  Model to use, e.g. `'google/gemini-2.0-flash'`, `'openai/gpt-4o'`, `'anthropic/claude-sonnet-4-20250514'`. Defaults to the agent's configured model.
</ParamField>

<ParamField type="string">
  System instruction.
</ParamField>

<ParamField type="string">
  User prompt (simple text).
</ParamField>

<ParamField type="array">
  Conversation messages (AI SDK `ModelMessage[]`).
</ParamField>

<ParamField type="number">
  Sampling temperature (0–2).
</ParamField>

<ParamField type="number">
  Maximum tokens to generate.
</ParamField>

<ParamField type="{ schema: JSONSchema7 }">
  Constrain the model response to a JSON Schema. The parsed object lands on
  `result.output`. Mirrors AI SDK `Output.object({ schema })`. Object-mode
  only — array / choice modes are future extensions.

  When set on a Google model, the auto-injected `google_search` tool is
  suppressed (Vertex does not allow mixing function-calling tools with
  `google_search` in one request).
</ParamField>

**Returns:** `Promise<AiGenerateOutput>`

```typescript theme={null}
const result = await AI.generate({
  model: 'google/gemini-2.0-flash',
  system: 'You are concise.',
  prompt: 'What is the weather in London?',
  temperature: 0.7,
});

result.text           // Generated text
result.finishReason   // 'stop', 'length', etc.
result.usage          // { promptTokens, completionTokens, totalTokens }
result.sources        // Google Search grounding URLs
```

### Response Shape (AiGenerateOutput)

The full-options response mirrors AI SDK `GenerateTextResult`:

| Field            | Type                     | Description                                                                                                          |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `text`           | `string`                 | Generated text                                                                                                       |
| `finishReason`   | `FinishReason`           | `'stop'`, `'length'`, `'content-filter'`, `'tool-calls'`, `'error'`, `'other'`, `'unknown'`                          |
| `usage`          | `LanguageModelUsage`     | `{ promptTokens, completionTokens, totalTokens }`                                                                    |
| `reasoning?`     | `ReasoningOutput[]`      | Model reasoning steps (e.g. Gemini thinking)                                                                         |
| `reasoningText?` | `string`                 | Concatenated reasoning text                                                                                          |
| `sources?`       | `AiGenerateSource[]`     | URL sources from Google Search grounding                                                                             |
| `toolCalls?`     | `AiGenerateToolCall[]`   | Tool calls made during generation                                                                                    |
| `toolResults?`   | `AiGenerateToolResult[]` | Tool results from generation                                                                                         |
| `output?`        | `unknown`                | Parsed structured result when `structuredOutput` was set on the request. Shape conforms to the supplied JSON Schema. |
| `warnings?`      | `CallWarning[]`          | Provider warnings                                                                                                    |

## Supported Providers

| Provider           | Prefix       | Example                              |
| ------------------ | ------------ | ------------------------------------ |
| Google (Vertex AI) | `google/`    | `google/gemini-2.0-flash`            |
| OpenAI             | `openai/`    | `openai/gpt-4o`                      |
| Anthropic          | `anthropic/` | `anthropic/claude-sonnet-4-20250514` |

If the requested provider's API key is not configured, the request falls back to the default Vertex AI model.

<Note>
  Google models automatically get **Google Search grounding** — real-time web search results appear in the `sources` field of the full-options response.
</Note>

## Content Types

### Text

```typescript theme={null}
[{ type: 'text', text: 'Your message here' }]
```

### Image

```typescript theme={null}
[
  { type: 'text', text: 'What do you see in this image?' },
  { type: 'image', url: 'https://example.com/photo.jpg' }
]
```

### File

```typescript theme={null}
[
  { type: 'text', text: 'Summarize this document' },
  { type: 'file', url: 'https://example.com/doc.pdf', mimeType: 'application/pdf' }
]
```

## Complete Examples

### Product Description Generator

```typescript theme={null}
import { LuaTool, AI, Products } from 'lua-cli/skill';
import { z } from 'zod';

export default class GenerateDescriptionTool implements LuaTool {
  name = 'generate_product_description';
  description = 'Generate compelling product descriptions using AI';
  
  inputSchema = z.object({
    productId: z.string(),
    style: z.enum(['casual', 'professional', 'luxury']).optional()
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    const product = await Products.getById(input.productId);
    if (!product) {
      return { success: false, error: 'Product not found' };
    }
    
    const style = input.style || 'professional';
    const description = await AI.generate(
      `You are a ${style} copywriter. Create a 2-3 sentence product description.`,
      [{ type: 'text', text: `Product: ${product.name}, Price: $${product.price}` }]
    );
    
    await product.update({ description });
    return { success: true, productId: input.productId, description };
  }
}
```

### Weather Search with Google Grounding

```typescript theme={null}
import { LuaTool, AI } from 'lua-cli/skill';
import { z } from 'zod';

export default class WeatherSearchTool implements LuaTool {
  name = 'search_weather';
  description = 'Search current weather using AI with Google Search grounding';
  
  inputSchema = z.object({
    location: z.string().describe('City or location')
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await AI.generate({
      model: 'google/gemini-2.0-flash',
      system: 'You report current weather conditions concisely.',
      prompt: `What is the current weather in ${input.location}?`,
    });

    return {
      weather: result.text,
      sources: result.sources?.map(s => ({ title: s.title, url: s.url })) ?? [],
      usage: result.usage,
    };
  }
}
```

### Image Analysis Tool

```typescript theme={null}
import { LuaTool, AI } from 'lua-cli/skill';
import { z } from 'zod';

export default class AnalyzeImageTool implements LuaTool {
  name = 'analyze_image';
  description = 'Analyze images using AI vision';
  
  inputSchema = z.object({
    imageUrl: z.string().url(),
    question: z.string().optional()
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    const analysis = await AI.generate(
      'You are an image analysis expert. Describe what you see in detail.',
      [
        { type: 'text', text: input.question || 'Describe this image in detail' },
        { type: 'image', url: input.imageUrl }
      ]
    );
    
    return { success: true, imageUrl: input.imageUrl, analysis };
  }
}
```

### Content Summarizer

```typescript theme={null}
import { LuaTool, AI } from 'lua-cli/skill';
import { z } from 'zod';

export default class SummarizeTool implements LuaTool {
  name = 'summarize_content';
  description = 'Summarize long text content';
  
  inputSchema = z.object({
    content: z.string(),
    maxLength: z.enum(['brief', 'medium', 'detailed']).optional()
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    const instructions = {
      brief: 'in 1-2 sentences',
      medium: 'in 1 paragraph',
      detailed: 'in 2-3 paragraphs with key points'
    };
    const length = input.maxLength || 'medium';
    
    const summary = await AI.generate(
      `You are a professional content summarizer. Create a clear summary ${instructions[length]}.`,
      [{ type: 'text', text: `Summarize:\n\n${input.content}` }]
    );
    
    return { success: true, summary, originalLength: input.content.length };
  }
}
```

### Translation Tool

```typescript theme={null}
import { LuaTool, AI } from 'lua-cli/skill';
import { z } from 'zod';

export default class TranslateTool implements LuaTool {
  name = 'translate_text';
  description = 'Translate text to different languages';
  
  inputSchema = z.object({
    text: z.string(),
    targetLanguage: z.string(),
    sourceLanguage: z.string().optional()
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    const translation = await AI.generate(
      `You are a professional translator. Translate accurately to ${input.targetLanguage}. Return ONLY the translated text.`,
      [{ type: 'text', text: input.text }]
    );
    
    return {
      success: true,
      original: input.text,
      translation,
      from: input.sourceLanguage || 'auto-detect',
      to: input.targetLanguage
    };
  }
}
```

### Sentiment Analysis (Structured Output)

Use `structuredOutput` to make the model return an object that conforms to a
JSON Schema. The parsed result lands on `result.output` — no more
`JSON.parse(...)` and no more "the model wrapped it in markdown again" bugs.

```typescript theme={null}
import { LuaTool, AI } from 'lua-cli/skill';
import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

const SentimentSchema = z.object({
  sentiment: z.enum(['positive', 'negative', 'neutral']),
  score: z.number().min(0).max(1),
  summary: z.string(),
});

export default class SentimentAnalysisTool implements LuaTool {
  name = 'analyze_sentiment';
  description = 'Analyze the sentiment of text';

  inputSchema = z.object({ text: z.string() });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await AI.generate({
      system: 'You are a sentiment analysis expert.',
      prompt: `Analyze:\n\n"${input.text}"`,
      temperature: 0,
      structuredOutput: {
        schema: zodToJsonSchema(SentimentSchema) as Record<string, unknown>,
      },
    });

    const parsed = SentimentSchema.safeParse(result.output);
    if (!parsed.success) {
      return { success: false, error: 'Schema mismatch', rawResponse: result.text };
    }

    return { success: true, ...parsed.data, originalText: input.text };
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Provide clear, specific context">
    Good context leads to better results

    ```typescript theme={null}
    // Good — specific and clear
    const context = `You are a product reviewer.
    Rate products on Quality (1-10), Value (1-10), Features (1-10).
    Return ONLY a JSON object with these ratings.`;

    // Bad — vague
    const context = `Review this product`;
    ```
  </Accordion>

  <Accordion title="Choose the right overload">
    Use simplified for quick text, full options when you need metadata

    ```typescript theme={null}
    // Simplified — just need the text
    const summary = await AI.generate('Summarize this article.', content);

    // Full options — need usage stats, sources, finish reason
    const result = await AI.generate({
      model: 'google/gemini-2.0-flash',
      prompt: 'What is happening in tech today?',
    });
    console.log(result.sources); // Google Search grounding URLs
    ```
  </Accordion>

  <Accordion title="Handle variable responses">
    AI responses may vary — always validate

    ```typescript theme={null}
    try {
      const response = await AI.generate(context, messages);
      if (!response || response.trim().length === 0) {
        return { success: false, error: 'Empty response' };
      }
      return { success: true, response };
    } catch (error) {
      return { success: false, error: error.message };
    }
    ```
  </Accordion>

  <Accordion title="Don't use AI for simple logic">
    Use regular code for deterministic tasks

    ```typescript theme={null}
    // Bad — waste of AI for simple math
    await AI.generate('Calculate 2 + 2');

    // Good — use regular code
    const result = 2 + 2;
    ```
  </Accordion>
</AccordionGroup>

## Common Use Cases

| Use Case               | Example Tool                                           |
| ---------------------- | ------------------------------------------------------ |
| **Content generation** | Product descriptions, email drafts, social media posts |
| **Analysis**           | Sentiment analysis, image recognition, document review |
| **Translation**        | Multi-language support                                 |
| **Summarization**      | Long documents, articles, conversations                |
| **Recommendations**    | Product suggestions, content curation                  |
| **Moderation**         | Content filtering, safety checks                       |
| **Q\&A**               | Document queries, knowledge retrieval                  |
| **Web search**         | Real-time information via Google Search grounding      |

## Performance Considerations

<CardGroup>
  <Card title="Response Time" icon="clock">
    AI generation typically takes 1-5 seconds. Longer/more complex requests take more time.
  </Card>

  <Card title="Context Length" icon="file">
    Maximum context length varies by model. Keep contexts focused and relevant.
  </Card>

  <Card title="Image Processing" icon="image">
    Image analysis is slower than text. Optimize image sizes when possible.
  </Card>

  <Card title="Caching" icon="database">
    Cache common AI responses. Store frequently requested generations.
  </Card>
</CardGroup>

## Limitations

* Maximum context length varies by model
* Image size limits apply (optimize before sending)
* File types supported: PDF, images, text files
* Response may vary between calls (non-deterministic)
* Some content may be filtered for safety
* Processing time increases with input complexity

## Error Handling

```typescript theme={null}
async execute(input: any) {
  try {
    const response = await AI.generate(context, messages);
    
    if (!response || response.trim().length === 0) {
      return { success: false, error: 'AI returned empty response' };
    }
    
    return { success: true, response };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'AI generation failed'
    };
  }
}
```

## Related APIs

<CardGroup>
  <Card title="User API" href="/api/user" icon="user">
    Get user context for personalization
  </Card>

  <Card title="Data API" href="/api/data" icon="database">
    Store AI-generated content
  </Card>

  <Card title="Products API" href="/api/products" icon="box">
    Enhance products with AI descriptions
  </Card>

  <Card title="Jobs API" href="/api/jobs" icon="clock">
    Schedule AI generation tasks
  </Card>
</CardGroup>

## See Also

* [LuaTool](/api/luatool) - Creating tools
* [Tool Examples](/examples/overview) - More tool patterns
* [User API](/api/user) - Accessing user data


# Baskets API
Source: https://docs.heylua.ai/api/baskets

Shopping cart management for e-commerce

## Overview

The Baskets API provides complete shopping cart functionality with item management, status tracking, and checkout capabilities. Returns **BasketInstance** objects with direct property access.

```typescript theme={null}
import { Baskets, BasketStatus } from 'lua-cli';

// Create basket - returns BasketInstance
const basket = await Baskets.create({ currency: 'USD' });

// Direct property access
console.log(basket.itemCount);    // 0
console.log(basket.totalAmount);  // 0
console.log(basket.status);       // "active"

// Add item using instance method
await basket.addItem({
  id: productId,
  price: 29.99,
  quantity: 2
});

// Access updated properties directly
console.log(basket.itemCount);    // 2
console.log(basket.totalAmount);  // 59.98

// Checkout using instance method
const order = await basket.placeOrder({
  shippingAddress: {...},
  paymentMethod: 'stripe'
});
```

<CardGroup>
  <Card title="Direct Access" icon="bolt">
    Access `basket.itemCount` not `basket.common.itemCount`
  </Card>

  <Card title="Instance Methods" icon="wrench">
    Built-in methods like `addItem()`, `placeOrder()`
  </Card>

  <Card title="Auto-Sync" icon="sync">
    Properties update after method calls
  </Card>

  <Card title="Type-Safe" icon="shield">
    Full TypeScript support
  </Card>
</CardGroup>

## Basket Statuses

```typescript theme={null}
import { BasketStatus } from 'lua-cli';
```

<Tabs>
  <Tab title="ACTIVE">
    Currently being used for shopping

    Default status for new baskets
  </Tab>

  <Tab title="CHECKED_OUT">
    Converted to an order

    Set automatically during checkout
  </Tab>

  <Tab title="ABANDONED">
    User left without completing purchase

    Can be set manually or by TTL
  </Tab>

  <Tab title="EXPIRED">
    TTL (time-to-live) exceeded

    Automatically set after expiration
  </Tab>
</Tabs>

## Methods

### create()

Create a new shopping basket.

```typescript theme={null}
Baskets.create(data: CreateBasketRequest): Promise<BasketInstance>
```

<ParamField type="string">
  Currency code (USD, EUR, GBP, etc.)
</ParamField>

<ParamField type="object">
  Custom metadata to store with basket
</ParamField>

**Returns:** `BasketInstance` with direct property access and methods

**Example:**

```typescript theme={null}
const basket = await Baskets.create({
  currency: 'USD',
  metadata: {
    source: 'web',
    campaign: 'summer_sale'
  }
});

// Direct property access
console.log(basket.id);          // "basket_abc123"
console.log(basket.itemCount);   // 0
console.log(basket.totalAmount); // 0
console.log(basket.status);      // "active"
console.log(basket.metadata.campaign); // "summer_sale"

// Instance methods available
await basket.addItem({...});
await basket.updateMetadata({...});
```

### get()

Retrieve baskets, optionally filtered by status.

```typescript theme={null}
Baskets.get(status?: BasketStatus): Promise<BasketInstance[]>
```

**Examples:**

```typescript theme={null}
// Get all baskets
const allBaskets = await Baskets.get();

// Get only active baskets
const activeBaskets = await Baskets.get(BasketStatus.ACTIVE);

// Get abandoned baskets
const abandoned = await Baskets.get(BasketStatus.ABANDONED);
```

### getById()

Get a specific basket by ID.

```typescript theme={null}
Baskets.getById(basketId: string): Promise<BasketInstance>
```

**Returns:** `BasketInstance` with direct property access

**Example:**

```typescript theme={null}
const basket = await Baskets.getById('basket_abc123');

// Direct property access (no .common needed!)
console.log(basket.totalAmount);  // 59.98
console.log(basket.itemCount);    // 2
console.log(basket.status);       // "active"
console.log(basket.items);        // Array of items

// Instance methods
await basket.addItem({...});
await basket.clear();
```

### addItem()

Add an item to a basket.

```typescript theme={null}
Baskets.addItem(basketId: string, item: BasketItem): Promise<Basket>
```

Or use instance method (recommended — returns enriched instance):

```typescript theme={null}
basket.addItem(item: BasketItem): Promise<BasketInstance>
```

<ParamField type="string">
  ID of the basket
</ParamField>

<ParamField type="string">
  Product ID
</ParamField>

<ParamField type="number">
  Item price
</ParamField>

<ParamField type="number">
  Quantity to add
</ParamField>

<ParamField type="string">
  Stock keeping unit
</ParamField>

**Returns:** Static method returns raw `Basket` data. Instance method returns `BasketInstance` with updated item count and total.

**Example:**

```typescript theme={null}
// Using static method
const basket = await Baskets.addItem('basket_abc123', {
  id: 'product_xyz',
  price: 29.99,
  quantity: 2,
  SKU: 'SHIRT-M-BLUE'
});

// Or using instance method (recommended)
await basket.addItem({
  id: 'product_xyz',
  price: 29.99,
  quantity: 2
});

// Direct property access
console.log(basket.totalAmount);  // 59.98
console.log(basket.itemCount);    // 2
console.log(basket.items);        // Array of items
```

### removeItem()

Remove an item from a basket.

```typescript theme={null}
Baskets.removeItem(basketId: string, itemId: string): Promise<Basket>
```

**Example:**

```typescript theme={null}
await Baskets.removeItem('basket_abc123', 'item_xyz');
```

### clear()

Remove all items from a basket.

```typescript theme={null}
Baskets.clear(basketId: string): Promise<Basket>
```

**Example:**

```typescript theme={null}
const emptyBasket = await Baskets.clear('basket_abc123');

console.log(emptyBasket.common.itemCount); // 0
```

### updateStatus()

Update basket status.

```typescript theme={null}
Baskets.updateStatus(basketId: string, status: BasketStatus): Promise<BasketStatus>
```

**Example:**

```typescript theme={null}
await Baskets.updateStatus('basket_abc123', BasketStatus.ABANDONED);
```

### updateMetadata()

Update basket metadata.

```typescript theme={null}
Baskets.updateMetadata(basketId: string, metadata: Record<string, any>): Promise<Record<string, any>>
```

**Example:**

```typescript theme={null}
await Baskets.updateMetadata('basket_abc123', {
  notes: 'Gift wrapping requested',
  giftMessage: 'Happy Birthday!',
  deliveryDate: '2025-12-25'
});
```

### placeOrder()

Convert basket to order (checkout).

```typescript theme={null}
Baskets.placeOrder(orderData: Record<string, any>, basketId: string): Promise<OrderInstance>
```

<ParamField type="object">
  Shipping address information
</ParamField>

<ParamField type="string">
  Payment method (e.g., 'stripe', 'paypal')
</ParamField>

<ParamField type="string">
  Basket ID to convert to order
</ParamField>

**Example:**

```typescript theme={null}
const order = await Baskets.placeOrder({
  shippingAddress: {
    street: '123 Main St',
    city: 'New York',
    state: 'NY',
    zip: '10001',
    country: 'USA'
  },
  paymentMethod: 'stripe'
}, 'basket_abc123');

console.log(order.id);     // "order_def456"
console.log(order.common.status); // "pending"
```

## BasketInstance

All basket methods return `BasketInstance` objects with:

**Direct Property Access:**

```typescript theme={null}
basket.id
basket.totalAmount    // No .common needed!
basket.itemCount      // Direct access
basket.status         // Direct access
basket.items          // Array of items
basket.currency
basket.metadata
basket.createdAt      // Via proxy
basket.updatedAt      // Via proxy
```

**Instance Methods:**

```typescript theme={null}
await basket.addItem({...});
await basket.removeItem(itemId);
await basket.updateMetadata({...});
await basket.updateStatus(status);
await basket.clear();
await basket.placeOrder({...});
```

**Backward Compatible:**

```typescript theme={null}
basket.totalAmount;         // ✅ New way
basket.common.totalAmount;  // ✅ Old way still works
```

## Complete Shopping Flow Example

```typescript theme={null}
import { LuaTool, Products, Baskets } from 'lua-cli';
import { z } from 'zod';

// Tool 1: Create Basket
export class CreateBasketTool implements LuaTool {
  name = "create_basket";
  description = "Start a new shopping session";
  inputSchema = z.object({});

  async execute(input: any) {
    const basket = await Baskets.create({
      currency: 'USD',
      metadata: { createdBy: 'chat' }
    });
    
    return {
      basketId: basket.id,
      message: "Shopping basket created! Start adding items."
    };
  }
}

// Tool 2: Add to Basket
export class AddToBasketTool implements LuaTool {
  name = "add_to_basket";
  description = "Add a product to shopping basket";
  
  inputSchema = z.object({
    basketId: z.string(),
    productId: z.string(),
    quantity: z.number().min(1).default(1)
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get product details
    const product = await Products.getById(input.productId);
    
    // Check stock
    if (!product.inStock) {
      return {
        success: false,
        message: `${product.name} is out of stock`
      };
    }
    
    // Add to basket
    const basket = await Baskets.addItem(input.basketId, {
      id: input.productId,
      price: product.price,
      quantity: input.quantity,
      SKU: product.sku
    });
    
    return {
      basketId: basket.id,
      itemCount: basket.common.itemCount,
      total: `$${basket.common.totalAmount.toFixed(2)}`,
      message: `Added ${input.quantity}x ${product.name} to basket`
    };
  }
}

// Tool 3: Checkout
export class CheckoutTool implements LuaTool {
  name = "checkout";
  description = "Complete purchase and create order";
  
  inputSchema = z.object({
    basketId: z.string(),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      state: z.string(),
      zip: z.string()
    }),
    paymentMethod: z.string().default('stripe')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get basket
    const basket = await Baskets.getById(input.basketId);
    
    // Verify basket has items
    if (basket.common.itemCount === 0) {
      return {
        success: false,
        message: "Cannot checkout empty basket"
      };
    }
    
    // Place order
    const order = await Baskets.placeOrder({
      shippingAddress: input.shippingAddress,
      paymentMethod: input.paymentMethod
    }, input.basketId);
    
    return {
      success: true,
      orderId: order.id,
      total: `$${basket.common.totalAmount.toFixed(2)}`,
      status: order.common.status,
      message: "Order placed successfully!"
    };
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Verify Basket Exists">
    ```typescript theme={null}
    const basket = await Baskets.getById(basketId);

    if (!basket) {
      throw new Error(`Basket not found: ${basketId}`);
    }
    ```
  </Accordion>

  <Accordion title="Check Items Before Checkout">
    ```typescript theme={null}
    const basket = await Baskets.getById(basketId);

    if (basket.common.itemCount === 0) {
      return {
        success: false,
        message: "Cannot checkout empty basket"
      };
    }
    ```
  </Accordion>

  <Accordion title="Store Metadata">
    Use metadata for tracking:

    ```typescript theme={null}
    await Baskets.updateMetadata(basketId, {
      source: 'mobile_app',
      promotionCode: 'SUMMER2025',
      referralSource: 'instagram'
    });
    ```
  </Accordion>

  <Accordion title="Handle Abandoned Baskets">
    ```typescript theme={null}
    // Mark as abandoned after timeout
    setTimeout(async () => {
      await Baskets.updateStatus(
        basketId,
        BasketStatus.ABANDONED
      );
    }, 30 * 60 * 1000); // 30 minutes
    ```
  </Accordion>
</AccordionGroup>

## Common Patterns

### View Cart

```typescript theme={null}
export class ViewCartTool implements LuaTool {
  async execute(input: { basketId: string }) {
    const basket = await Baskets.getById(input.basketId);
    
    return {
      items: basket.items.map(item => ({
        product: item.id,
        quantity: item.quantity,
        price: `$${item.price}`,
        subtotal: `$${(item.price * item.quantity).toFixed(2)}`
      })),
      total: `$${basket.common.totalAmount.toFixed(2)}`,
      itemCount: basket.common.itemCount
    };
  }
}
```

### Apply Discount

```typescript theme={null}
export class ApplyDiscountTool implements LuaTool {
  async execute(input: { basketId: string; code: string }) {
    const basket = await Baskets.getById(input.basketId);
    
    // Apply discount logic
    const discountPercent = getDiscountForCode(input.code);
    const discountAmount = basket.common.totalAmount * (discountPercent / 100);
    
    await Baskets.updateMetadata(input.basketId, {
      discountCode: input.code,
      discountAmount,
      originalTotal: basket.common.totalAmount
    });
    
    return {
      discount: `${discountPercent}%`,
      saved: `$${discountAmount.toFixed(2)}`,
      newTotal: `$${(basket.common.totalAmount - discountAmount).toFixed(2)}`
    };
  }
}
```

## Next Steps

<CardGroup>
  <Card title="Orders API" icon="receipt" href="/api/orders">
    Manage orders after checkout
  </Card>

  <Card title="Basket Examples" icon="layer-group" href="/examples/baskets">
    See complete workflow examples
  </Card>
</CardGroup>


# CDN
Source: https://docs.heylua.ai/api/cdn

Upload and retrieve files from the Lua CDN

## Overview

The CDN API allows you to upload and retrieve files from the Lua CDN. Files are stored securely and can be accessed by their unique file ID.

```typescript theme={null}
import { CDN } from 'lua-cli';

// Upload a file
const fileId = await CDN.upload(file);

// Retrieve a file
const file = await CDN.get(fileId);
```

## Methods

### upload

Uploads a file to the CDN.

```typescript theme={null}
const fileId = await CDN.upload(file);
```

**Parameters:**

| Parameter | Type   | Description               |
| --------- | ------ | ------------------------- |
| `file`    | `File` | The File object to upload |

**Returns:** `Promise<string>` - The unique file ID

**Example:**

```typescript theme={null}
import { CDN } from 'lua-cli';
import { readFileSync } from 'fs';

// From a buffer
const buffer = readFileSync('image.png');
const file = new File([buffer], 'image.png', { type: 'image/png' });
const fileId = await CDN.upload(file);

console.log('Uploaded:', fileId);
```

### get

Retrieves a file from the CDN by its ID.

```typescript theme={null}
const file = await CDN.get(fileId);
```

**Parameters:**

| Parameter | Type     | Description                       |
| --------- | -------- | --------------------------------- |
| `fileId`  | `string` | The unique identifier of the file |

**Returns:** `Promise<File>` - The File object with `name`, `type`, and `size` properties

**Example:**

```typescript theme={null}
import { CDN } from 'lua-cli';

const file = await CDN.get('abc123-def456');

console.log(file.name);  // filename
console.log(file.type);  // e.g., 'image/png'
console.log(file.size);  // bytes
```

## Use Cases

### Store User Uploads

```typescript theme={null}
export class SaveDocumentTool implements LuaTool {
  name = "save_document";
  description = "Save a document to storage";
  inputSchema = z.object({
    content: z.string(),
    filename: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const file = new File(
      [input.content], 
      input.filename, 
      { type: 'text/plain' }
    );
    
    const fileId = await CDN.upload(file);
    
    return {
      success: true,
      fileId,
      message: `Document saved as ${input.filename}`
    };
  }
}
```

### Retrieve and Process Files

```typescript theme={null}
export class ReadDocumentTool implements LuaTool {
  name = "read_document";
  description = "Read a document from storage";
  inputSchema = z.object({
    fileId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const file = await CDN.get(input.fileId);
    const content = await file.text();
    
    return {
      success: true,
      filename: file.name,
      content
    };
  }
}
```

### Use with AI for Image Analysis

```typescript theme={null}
export class AnalyzeImageTool implements LuaTool {
  name = "analyze_image";
  description = "Analyze an image using AI";
  inputSchema = z.object({
    fileId: z.string(),
    question: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const file = await CDN.get(input.fileId);
    const buffer = Buffer.from(await file.arrayBuffer());
    
    const analysis = await AI.generate(
      'You are an image analysis expert.',
      [
        { type: 'text', text: input.question },
        { type: 'image', image: buffer, mediaType: file.type } as any
      ]
    );
    
    return { analysis };
  }
}
```

### Re-upload Files

Since `CDN.get()` returns a `File` object, you can easily re-upload files:

```typescript theme={null}
// Get existing file
const file = await CDN.get(existingFileId);

// Re-upload (creates a new copy)
const newFileId = await CDN.upload(file);
```

## File Properties

The `File` object returned by `CDN.get()` has these properties:

| Property | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| `name`   | `string` | Original filename             |
| `type`   | `string` | MIME type (e.g., `image/png`) |
| `size`   | `number` | File size in bytes            |

And these methods:

| Method          | Returns                | Description    |
| --------------- | ---------------------- | -------------- |
| `text()`        | `Promise<string>`      | Read as text   |
| `arrayBuffer()` | `Promise<ArrayBuffer>` | Read as binary |
| `stream()`      | `ReadableStream`       | Read as stream |

## Supported File Types

The CDN supports all file types including:

* **Images**: PNG, JPEG, GIF, WebP, SVG
* **Documents**: PDF, DOC, DOCX, TXT
* **Data**: JSON, CSV, XML
* **Audio/Video**: MP3, MP4, WAV
* **Archives**: ZIP, TAR

Images are automatically optimized with WebP compression while maintaining quality.

## Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Filenames">
    Include meaningful names when creating Files:

    ```typescript theme={null}
    // Good
    new File([data], 'invoice-2024-001.pdf', { type: 'application/pdf' })

    // Avoid
    new File([data], 'file.pdf', { type: 'application/pdf' })
    ```
  </Accordion>

  <Accordion title="Set Correct MIME Types">
    Always specify the correct MIME type:

    ```typescript theme={null}
    // Images
    { type: 'image/png' }
    { type: 'image/jpeg' }

    // Documents
    { type: 'application/pdf' }
    { type: 'text/plain' }

    // Data
    { type: 'application/json' }
    ```
  </Accordion>

  <Accordion title="Store File IDs">
    Save file IDs in your data for later retrieval:

    ```typescript theme={null}
    const fileId = await CDN.upload(file);

    await Data.create('documents', {
      title: 'Contract',
      fileId: fileId,  // Store for later
      uploadedAt: new Date().toISOString()
    });
    ```
  </Accordion>

  <Accordion title="Handle Errors">
    Always handle potential errors:

    ```typescript theme={null}
    try {
      const file = await CDN.get(fileId);
      return { success: true, file };
    } catch (error) {
      return { 
        success: false, 
        error: 'File not found' 
      };
    }
    ```
  </Accordion>
</AccordionGroup>

## Complete Example

```typescript theme={null}
import { LuaTool, CDN, Data, AI } from 'lua-cli';
import { z } from 'zod';

export class DocumentManagerTool implements LuaTool {
  name = "manage_document";
  description = "Upload, retrieve, or analyze documents";
  inputSchema = z.object({
    action: z.enum(['upload', 'get', 'analyze']),
    fileId: z.string().optional(),
    content: z.string().optional(),
    filename: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    switch (input.action) {
      case 'upload': {
        if (!input.content || !input.filename) {
          return { error: 'Content and filename required' };
        }
        const file = new File([input.content], input.filename, { 
          type: 'text/plain' 
        });
        const fileId = await CDN.upload(file);
        
        // Store reference
        await Data.create('documents', {
          fileId,
          filename: input.filename,
          uploadedAt: new Date().toISOString()
        });
        
        return { success: true, fileId };
      }
      
      case 'get': {
        if (!input.fileId) {
          return { error: 'File ID required' };
        }
        const file = await CDN.get(input.fileId);
        const content = await file.text();
        return { 
          success: true, 
          filename: file.name,
          content 
        };
      }
      
      case 'analyze': {
        if (!input.fileId) {
          return { error: 'File ID required' };
        }
        const file = await CDN.get(input.fileId);
        const content = await file.text();
        
        const summary = await AI.generate(
          'Summarize this document concisely.',
          [{ type: 'text', text: content }]
        );
        
        return { success: true, summary };
      }
    }
  }
}
```

<Note title="Debugging tip">
  If a CDN upload or retrieval isn't working as expected, log file metadata to inspect what was returned:

  ```typescript theme={null}
  const file = await CDN.get(input.fileId);
  console.log('CDN file:', file.name, file.type, `${file.size} bytes`);
  ```

  Then run `lua logs --type skill --limit 5` after a test message. See the [Debugging Skills guide](/cli/debugging) for the full workflow.
</Note>


# Channels API
Source: https://docs.heylua.ai/api/channels

Send outbound messages from any execute context — tools, jobs, webhooks, and triggers

## Overview

The Channels API lets your agent **initiate** messages on the channels it's connected to — WhatsApp, SMS, email, web chat, and more — from anywhere your code runs: a tool, a [scheduled job](/api/jobs), a [webhook](/api/luawebhook), or a [trigger](/api/luatool). It's the outbound half of a two-way conversation: inbound messages wake your agent, and `Channels.*` sends messages back out.

```typescript theme={null}
import { Channels } from 'lua-cli';

// Send a free-form message on any connected channel
await Channels.send({
  channel: 'whatsapp',
  to: { userId: 'user_123' },
  text: 'Your order has shipped! 📦'
});

// Send an email
await Channels.email.send({
  to: { email: 'customer@example.com' },
  subject: 'Order confirmation',
  text: 'Thanks for your order!'
});

// Re-open a closed WhatsApp window with an approved template
await Channels.whatsapp.sendTemplate({
  to: { phoneNumber: '+14155552671' },
  templateName: 'order_update',
  languageCode: 'en_US',
  messageContext: 'Told the customer their order shipped'
});
```

<Note>
  Every `Channels.*` send addressed to a person is **recorded to the recipient's conversation thread** with your agent. When the user replies, your agent picks up with full context — the outbound message is already part of the conversation it remembers. See [Proactive Messaging](/channels/proactive-messaging) for the full model.

  Sends addressed to a shared conversation (`to: { conversationId }`, Teams only) have no single recipient to attribute the message to, so they return `persisted: false` and are not written to agent memory.
</Note>

<CardGroup>
  <Card title="Channels.send" icon="paper-plane">
    Free-form text on any connected channel
  </Card>

  <Card title="Channels.email.send" icon="envelope">
    Rich email — subject, HTML, cc/bcc, attachments
  </Card>

  <Card title="Channels.whatsapp.sendTemplate" icon="whatsapp">
    Approved templates to start or re-open a conversation
  </Card>

  <Card title="Channels.whatsapp.sendReaction" icon="whatsapp">
    React with an emoji to a specific WhatsApp message
  </Card>
</CardGroup>

## Where you can call it

`Channels.*` works in any execute context. Recipient resolution differs slightly by context:

| Context                 | Available? | Notes                                                                                          |
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------- |
| **Tools**               | ✅          | Has conversational context — you can target the current user with their `userId`, or any user. |
| **Jobs**                | ✅          | No conversational context — target an explicit `userId`, `phoneNumber`, or `email`.            |
| **Webhooks**            | ✅          | No conversational context — target an explicit recipient.                                      |
| **Triggers**            | ✅          | Same as webhooks — target an explicit recipient.                                               |
| **Pre/Post-processors** | ✅          | Available, but most sending happens in tools and jobs.                                         |

<Tip>
  Pair `Channels.send` with a [scheduled job](/api/jobs) for time-based outreach (reminders, follow-ups, digests) — see the [Proactive Send recipe](/examples/proactive-send).
</Tip>

## Channels.send()

Send a free-form text message on a connected channel.

```typescript theme={null}
Channels.send(input: ChannelSendInput): Promise<ChannelSendOutput>
```

<ParamField type="string">
  The channel to send on. One of: `'whatsapp'`, `'sms'`, `'email'`, `'webchat'`, `'teams'`, `'instagram'`, `'messenger'`.
</ParamField>

<ParamField type="object">
  The recipient. Provide **exactly one** of the fields below.
</ParamField>

<ParamField type="string">
  A Lua user ID. Works on **every** channel — the recipient's channel address is resolved from their conversation history with your agent.
</ParamField>

<ParamField type="string">
  A phone number in E.164 format (e.g. `+14155552671`). Valid for **`whatsapp`** and **`sms`** only — lets you reach a number with no prior conversation (cold start).
</ParamField>

<ParamField type="string">
  An email address. Valid for the **`email`** channel only (cold start). For richer email, prefer [`Channels.email.send`](#channels-email-send).
</ParamField>

<ParamField type="string">
  The message text. Supports the same [response formatting components](/formatting/introduction) (`:::` blocks) as inline replies, where the channel renders them.
</ParamField>

<ParamField type="object">
  Optional send options — see [Options](#options).
</ParamField>

**Returns:** [`ChannelSendOutput`](#channelsendoutput)

**Examples:**

<Tabs>
  <Tab title="To the current user">
    ```typescript theme={null}
    // In a tool — message the user you're talking to, on a specific channel
    await Channels.send({
      channel: 'whatsapp',
      to: { userId: user._luaProfile.userId },
      text: 'Here is the summary you asked for.'
    });
    ```
  </Tab>

  <Tab title="Cold start (phone)">
    ```typescript theme={null}
    // Reach a phone number with no prior conversation (WhatsApp/SMS)
    await Channels.send({
      channel: 'sms',
      to: { phoneNumber: '+14155552671' },
      text: 'Your verification code is 123456.'
    });
    ```
  </Tab>

  <Tab title="From a job">
    ```typescript theme={null}
    import { Channels } from 'lua-cli';

    // In a scheduled job (no conversation context) — target an explicit recipient
    await Channels.send({
      channel: 'email',
      to: { email: 'customer@example.com' },
      text: 'Your weekly report is ready.'
    });
    ```
  </Tab>
</Tabs>

## Channels.email.send()

Send a rich email — subject, plain-text and/or HTML body, cc/bcc, and attachments.

```typescript theme={null}
Channels.email.send(input: EmailSendInput): Promise<ChannelSendOutput>
```

<ParamField type="object">
  The recipient. Provide **exactly one** of `to.userId` or `to.email`.
</ParamField>

<ParamField type="string">
  A Lua user ID — the email address is resolved from the user's conversation history.
</ParamField>

<ParamField type="string">
  A literal email address (cold start).
</ParamField>

<ParamField type="string">
  The email subject line.
</ParamField>

<ParamField type="string">
  Plain-text body, sent as-is (the plain-text MIME part). Provide at least one of `text`, `html`, or `richBody`.
</ParamField>

<ParamField type="string">
  HTML body, sent **as-is** — your exact markup, no template wrapper. Use this for designed / transactional emails.
</ParamField>

<ParamField type="string">
  Rich body — markdown and [`:::` component blocks](/formatting/introduction) **rendered server-side** into the branded email template (the same rendering your agent's inline replies use). Use this for "send this message as a nice email." Mutually exclusive with `html`.
</ParamField>

<ParamField type="string[]">
  Carbon-copy recipients.
</ParamField>

<ParamField type="string[]">
  Blind-carbon-copy recipients.
</ParamField>

<ParamField type="EmailAttachmentInput[]">
  Files to attach. Each is `{ filename, contentType, url }` — the file is fetched from the public `url` at send time. Combined attachment size is capped at 28 MB.
</ParamField>

<ParamField type="string">
  Threads this email as a reply (standard `In-Reply-To` header). Pass the `Message-ID` of the email you're replying to and mail clients group your message into that conversation — e.g. a thread per support ticket instead of one thread per user. When your agent handles an inbound email, the original `Message-ID` is available as `webhookPayload.messageId`; store it against your record and pass it back here on each follow-up. Honoured on the branded (existing-address) email channel.
</ParamField>

<ParamField type="string[]">
  The conversation's `References` chain (standard threading header) — the accumulated `Message-ID`s of the thread. Append the latest `Message-ID` each turn so long threads stay correctly linked.
</ParamField>

<ParamField type="object">
  Optional send options — see [Options](#options).
</ParamField>

**Returns:** [`ChannelSendOutput`](#channelsendoutput) (with `messageId` set to the provider message ID where available).

**Example:**

```typescript theme={null}
await Channels.email.send({
  to: { email: 'customer@example.com' },
  subject: 'Your invoice',
  html: '<h1>Invoice #12345</h1><p>Total: $99.00</p>',
  cc: ['accounts@example.com'],
  attachments: [
    {
      filename: 'invoice-12345.pdf',
      contentType: 'application/pdf',
      url: 'https://files.example.com/invoice-12345.pdf'
    }
  ]
});
```

Or let the platform render markdown into the branded template with `richBody`:

```typescript theme={null}
await Channels.email.send({
  to: { email: 'customer@example.com' },
  subject: 'Welcome aboard',
  richBody: '# Welcome!\n\nThanks for signing up — here is what to do next…'
});
```

**Threading a reply into an existing conversation** — keep follow-ups in the same email thread (e.g. one thread per ticket) by echoing the original message's `Message-ID`:

```typescript theme={null}
// `webhookPayload.messageId` is the inbound email's Message-ID — capture it
// when the ticket's first email arrives, then reuse it on every push.
await Channels.email.send({
  to: { email: 'tenant@example.com' },
  subject: 'Re: Porch light (MT-2026-184)',
  richBody: 'Your technician is booked for Thursday 9am.',
  inReplyTo: ticket.rootMessageId,
  references: [ticket.rootMessageId]
});
```

## Channels.whatsapp.sendTemplate()

Send a **pre-approved WhatsApp template**. Use this to start a conversation, or to reach a user whose [24-hour messaging window](/channels/proactive-messaging#the-whatsapp-24-hour-window) has closed (where free-form sends aren't allowed).

```typescript theme={null}
Channels.whatsapp.sendTemplate(input: WhatsAppTemplateSendInput): Promise<ChannelSendOutput>
```

<ParamField type="object">
  The recipient — exactly one of `to.userId` or `to.phoneNumber` (E.164).
</ParamField>

<ParamField type="string">
  The name of an approved template on the agent's WhatsApp channel. List available templates with [`Templates.whatsapp.list`](/api/templates#list).
</ParamField>

<ParamField type="string">
  The template language, e.g. `'en_US'`.
</ParamField>

<ParamField type="object[]">
  Meta template component objects supplying the header / body / button parameter values — e.g. `{ type: 'BODY', parameters: [{ type: 'text', text: 'Tuesday at 3pm' }] }`. The component `type` is `'HEADER'`, `'BODY'`, or `'BUTTON'`; the parameter `type` is `'text'`, `'image'`, `'video'`, `'document'`, or `'coupon_code'`.
</ParamField>

<ParamField type="string">
  A plain-text summary of what the template said. This is the text **recorded to the conversation thread** so your agent remembers the outreach when the user replies. Recommended whenever the template body isn't self-explanatory.
</ParamField>

<ParamField type="object">
  Optional send options — see [Options](#options).
</ParamField>

**Returns:** [`ChannelSendOutput`](#channelsendoutput)

**Example:**

```typescript theme={null}
await Channels.whatsapp.sendTemplate({
  to: { phoneNumber: '+14155552671' },
  templateName: 'appointment_reminder',
  languageCode: 'en_US',
  components: [
    { type: 'BODY', parameters: [{ type: 'text', text: 'Tuesday at 3pm' }] }
  ],
  messageContext: 'Reminded the customer about their Tuesday 3pm appointment'
});
```

<Note>
  `Channels.whatsapp.sendTemplate` is the **canonical** way to send a WhatsApp template as part of a conversation — it records the send to the recipient's thread and respects the recipient resolution above. The lower-level [`Templates.whatsapp.send`](/api/templates) (batch send by channel ID and phone numbers) remains available for bulk/campaign sends.
</Note>

## Channels.whatsapp.sendReaction()

React with an emoji to a specific WhatsApp message — the same reaction a person leaves by tapping and holding a message. This is also how the [Reaction formatting component](/formatting/reaction) sends on WhatsApp; call it directly when you need to react to a message outside of a normal reply (e.g. from a job or webhook).

```typescript theme={null}
Channels.whatsapp.sendReaction(input: WhatsAppReactionSendInput): Promise<ChannelSendOutput>
```

<ParamField type="object">
  The recipient — exactly one of `to.userId` or `to.phoneNumber` (E.164).
</ParamField>

<ParamField type="string">
  The vendor message ID of the WhatsApp message to react to (a `wamid....` value). Must be no more than 30 days old. Available from the channel webhook payload or the message's entry in conversation history.
</ParamField>

<ParamField type="string">
  A single emoji to react with. Pass an empty string (`''`) to remove the agent's existing reaction from the message.
</ParamField>

<ParamField type="object">
  Optional send options — see [Options](#options).
</ParamField>

**Returns:** [`ChannelSendOutput`](#channelsendoutput)

**Example:**

```typescript theme={null}
await Channels.whatsapp.sendReaction({
  to: { userId: 'user_123' },
  messageId: 'wamid.HBgLMTU1NTU1NTU1NTUVAgARGBI5QTNDQTVCM0Q0RUQ5RTU3RgA=',
  emoji: '👍'
});

// Remove the reaction
await Channels.whatsapp.sendReaction({
  to: { userId: 'user_123' },
  messageId: 'wamid.HBgLMTU1NTU1NTU1NTUVAgARGBI5QTNDQTVCM0Q0RUQ5RTU3RgA=',
  emoji: ''
});
```

<Warning>
  **WhatsApp only, for now.** `sendReaction` isn't available on other channels — use the [Reaction formatting component](/formatting/reaction) for the broader multi-channel path (Instagram, Facebook Messenger, Slack, iMessage, web chat), which is ignored on channels without reaction support rather than throwing.
</Warning>

## Options

All three methods accept an optional `options` object:

<ParamField type="string">
  Pin the send to a specific channel configuration (for agents with more than one channel of the same type). The configuration must belong to your agent.
</ParamField>

<ParamField type="'queue' | 'fail'">
  What to do when a WhatsApp free-form send hits a closed [24-hour window](/channels/proactive-messaging#the-whatsapp-24-hour-window):

  * **`'queue'`** (default) — queue the message and deliver it after the user re-engages (the API returns `queued: true`).
  * **`'fail'`** — reject the send so you can fall back to `Channels.whatsapp.sendTemplate`.
</ParamField>

## ChannelSendOutput

Every send method resolves to the same shape:

```typescript theme={null}
interface ChannelSendOutput {
  deliveryId: string;     // the delivery record; pass it to Channels.getStatus()
  status: DeliveryStatus; // where the delivery stands as the send returns
  delivered: boolean;     // the channel accepted the message for delivery
  persisted: boolean;     // the message was recorded to the agent's conversation thread
  queued?: boolean;       // WhatsApp only: deferred until the recipient re-engages
  userId?: string;        // the Lua user the message was recorded against
  identifier?: string;    // the channel-native recipient (phone / email / etc.)
  messageId?: string;     // provider message ID, where available
  warning?: string;       // set when delivered but not persisted
}
```

<ParamField type="string">
  The delivery record for this send. It is stable for the whole life of the message, so store it if you want to answer "did that land?" later. Pass it to [`Channels.getStatus()`](#channels-getstatus).
</ParamField>

<ParamField type="DeliveryStatus">
  Where the delivery stands the moment the send returns. A live send returns `queued`, `accepted` or `sent`. Receipts move it further afterwards, which is what `Channels.getStatus()` reads.
</ParamField>

<ParamField type="boolean">
  The channel accepted the message. Independent of `persisted`.
</ParamField>

<ParamField type="boolean">
  The message was recorded to the recipient's conversation thread with your agent. A delivered-but-unpersisted send returns `delivered: true, persisted: false` plus a `warning` — it does **not** throw.
</ParamField>

<ParamField type="boolean">
  WhatsApp only. `true` means the 24-hour window was closed and the message is queued — `delivered` stays `false` until the recipient re-engages, at which point the queued text is delivered and recorded. See [Proactive Messaging](/channels/proactive-messaging#the-whatsapp-24-hour-window).
</ParamField>

## Delivery status

A send tells you the message left. It cannot tell you the phone rang. That
answer arrives later, as the provider reports back, and it lands on the delivery
record the send returned an id for.

### Channels.getStatus()

```typescript theme={null}
Channels.getStatus(deliveryId: string): Promise<DeliveryView>
```

```typescript theme={null}
const sent = await Channels.send({
  channel: 'whatsapp',
  to: { phoneNumber: '+15551234567' },
  text: 'Your order has shipped!'
});

// ...later, in a job or a follow-up turn
const delivery = await Channels.getStatus(sent.deliveryId);

if (delivery.status === 'failed') {
  console.error(delivery.error?.category, delivery.error?.title);
} else if (delivery.status === 'read') {
  console.log('Read at', delivery.readAt);
}
```

Throws if no delivery with that id belongs to your agent.

### Channels.listDeliveries()

```typescript theme={null}
Channels.listDeliveries(filter?: {
  userId?: string;
  status?: DeliveryStatus;
  channel?: string;
  since?: string | Date;
  limit?: number;      // 1–200, defaults to 50
}): Promise<DeliveryView[]>
```

Newest first.

```typescript theme={null}
const failures = await Channels.listDeliveries({
  status: 'failed',
  since: new Date(Date.now() - 24 * 60 * 60 * 1000),
  limit: 100
});

const billing = failures.filter(d => d.error?.category === 'billing');
if (billing.length) {
  console.warn(`${billing.length} sends blocked on billing`);
}
```

### Status vocabulary

Every channel reports into the same seven statuses.

| Status      | Meaning                                                                                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queued`    | WhatsApp only. The 24-hour window was closed, so the text is held and flushes when the recipient replies.                                                            |
| `accepted`  | The provider took the message and gave us an id. Receipts are still to come.                                                                                         |
| `sent`      | The provider handed it off to the recipient's network. On channels with no receipts (Slack, Teams, Front, webchat, AgentMail) this is where a successful send stops. |
| `delivered` | It reached the recipient's device.                                                                                                                                   |
| `read`      | The recipient opened it. WhatsApp only, and only when the recipient has read receipts on.                                                                            |
| `failed`    | Terminal. `error` says why.                                                                                                                                          |
| `expired`   | A `queued` WhatsApp message the recipient never re-engaged with.                                                                                                     |

Progress only moves forward. A receipt that arrives twice, or out of order, leaves
the record where it already was, so polling `getStatus` is safe. The one exception
is `failed`, which a provider may report after `sent` (a payment problem, say) but
never after `delivered`.

### Error categories

A failure carries a `DeliveryError`. `category` is ours and is the same across
every provider, so you can branch on it without learning any vendor's code list.
`code` is the vendor's own, kept for support tickets. `owner` says who has to act,
and `retryable` says whether sending again could work.

| Category          | Means                                                        | Example vendor code    |
| ----------------- | ------------------------------------------------------------ | ---------------------- |
| `window_closed`   | Outside the channel's free-form window; send a template      | Meta `131047`          |
| `unreachable`     | No such recipient, or their device cannot be reached         | Meta `131026`          |
| `billing`         | The account cannot pay for this message                      | Meta `131042`          |
| `opted_out`       | The recipient blocked or unsubscribed you                    | Meta `131050`          |
| `throttled`       | Rate limited. Retryable                                      | Meta `130429`          |
| `auth`            | The channel's credentials are rejected or expired            | Meta `190`             |
| `template`        | The template is unapproved, missing or wrongly parameterised | Meta `132000`–`133999` |
| `media`           | The attachment was rejected or could not be fetched          | Meta `131053`          |
| `invalid_request` | We sent something malformed                                  | Meta `100`             |
| `compliance`      | Blocked by policy, regulation or content rules               | SES `Reject`           |
| `experiment`      | Held back by a provider-side experiment                      | Meta `130472`          |
| `provider`        | The provider failed on its own side. Often retryable         | Meta `131000`          |
| `unknown`         | The provider reported a code we do not classify yet          | —                      |

```typescript theme={null}
const delivery = await Channels.getStatus(sent.deliveryId);

switch (delivery.error?.category) {
  case 'window_closed':
    await Channels.whatsapp.sendTemplate({ to: { phoneNumber }, templateName: 'order_update' });
    break;
  case 'opted_out':
    await markUnsubscribed(delivery.recipient);
    break;
  case 'throttled':
  case 'provider':
    // delivery.error.retryable is true here
    break;
}
```

## Idempotency

The SDK puts an `X-Idempotency-Key` on every send for you, so a retry inside one
`Channels.send()` call cannot send the message twice.

The key is what makes a *retry of your own* safe too. If your job crashes after a
send and runs again, or a queue redelivers your handler, pass the same key both
times and the second call sends nothing. It returns the first send's outcome
instead, with the same `deliveryId`. The guard is for retries, one after the
other: two calls with the same key that are in flight at the same instant can
both go out, because the key is written once the vendor has accepted the send. Set your own key through the HTTP client's
headers when you call the REST endpoint directly:

```bash theme={null}
curl -X POST https://api.heylua.ai/developer/agents/$AGENT_ID/channels/send \
  -H "Authorization: Bearer $LUA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-4471-shipped" \
  -d '{"channel":"whatsapp","to":{"phoneNumber":"+15551234567"},"text":"Your order has shipped!"}'
```

Derive the key from the thing you are messaging about, not from the attempt, or
every retry mints a fresh key and sends again.

Three rules worth knowing:

* **The window is the delivery record's lifetime**, 180 days. There is no separate expiry.
* **A key is scoped to one agent.** The same key from a different agent is a different key.
* **A key whose first attempt failed replays the failure.** It does not resend. You already got an answer; sending again would be a second message, not a retry.

## Error handling

`Channels.*` **throws** when a send is rejected (invalid recipient, unconfigured channel, provider rejection, or `onClosedWindow: 'fail'` on a closed window). Wrap calls in `try/catch` where a failure should be handled gracefully.

A successful call may still report partial success — **`delivered: true` with `persisted: false`** (plus a `warning`) means the message went out but couldn't be recorded to the conversation thread. This is **not** an error and won't throw; check the flag if recording matters to your flow.

```typescript theme={null}
try {
  const result = await Channels.send({
    channel: 'whatsapp',
    to: { userId: 'user_123' },
    text: 'Quick update for you!'
  });

  if (result.queued) {
    // Window closed — message will deliver when the user replies
    console.log('Queued; will deliver on re-engagement');
  } else if (!result.persisted) {
    console.warn('Delivered but not recorded:', result.warning);
  }
} catch (err) {
  // Rejected — e.g. unconfigured channel, invalid recipient, closed-window 'fail'
  console.error('Send failed:', err.message);
}
```

<Warning>
  **WhatsApp free-form sending is time-limited.** You can only send free-form WhatsApp messages within 24 hours of the recipient's last inbound message. Outside that window, use `Channels.whatsapp.sendTemplate` with an approved template — or rely on the default `onClosedWindow: 'queue'` behavior. See [Proactive Messaging](/channels/proactive-messaging) and [Channel Capabilities](/channels/channel-capabilities).
</Warning>

## Channels & recipients at a glance

| Channel     | Cold start (no prior conversation)                       | Warm only (`userId`)                                   |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------ |
| `whatsapp`  | ✅ via `phoneNumber` (template required if window closed) | ✅                                                      |
| `sms`       | ✅ via `phoneNumber`                                      | ✅                                                      |
| `email`     | ✅ via `email`                                            | ✅                                                      |
| `webchat`   | —                                                        | ✅                                                      |
| `teams`     | —                                                        | ✅ — also `conversationId` for group chats and channels |
| `instagram` | —                                                        | ✅                                                      |
| `messenger` | —                                                        | ✅                                                      |

See [Channel Capabilities](/channels/channel-capabilities) for per-channel limits, sender resolution, and compliance notes.

## TypeScript types

```typescript theme={null}
type ChannelSendChannel =
  | 'whatsapp' | 'sms' | 'email' | 'webchat'
  | 'teams' | 'instagram' | 'messenger';

interface ChannelSendTarget {
  userId?: string;          // any channel — the user's DIRECT conversation
  phoneNumber?: string;     // whatsapp / sms (cold start)
  email?: string;           // email (cold start)
  conversationId?: string;  // teams — a shared conversation, not a person
}

interface ChannelSendOptions {
  channelIdentifier?: string;
  whatsapp?: { onClosedWindow?: 'queue' | 'fail' };
}

interface ChannelSendInput {
  channel: ChannelSendChannel;
  to: ChannelSendTarget;
  text: string;
  options?: ChannelSendOptions;
}

interface WhatsAppTemplateSendInput {
  to: { userId?: string; phoneNumber?: string };
  templateName: string;
  languageCode?: string;
  components?: Array<Record<string, unknown>>;
  messageContext?: string;
  options?: ChannelSendOptions;
}

interface WhatsAppReactionSendInput {
  to: { userId?: string; phoneNumber?: string };
  messageId: string;
  emoji: string;
  options?: ChannelSendOptions;
}

interface EmailAttachmentInput {
  filename: string;
  contentType: string;
  url: string;
}

interface EmailSendInput {
  to: { userId?: string; email?: string };
  subject?: string;
  text?: string;
  html?: string;
  richBody?: string;
  cc?: string[];
  bcc?: string[];
  attachments?: EmailAttachmentInput[];
  inReplyTo?: string;
  references?: string[];
  options?: ChannelSendOptions;
}

interface ChannelSendOutput {
  deliveryId: string;
  status: DeliveryStatus;
  delivered: boolean;
  persisted: boolean;
  queued?: boolean;
  userId?: string;
  identifier?: string;
  messageId?: string;
  warning?: string;
}

type DeliveryStatus =
  | 'queued'
  | 'accepted'
  | 'sent'
  | 'delivered'
  | 'read'
  | 'failed'
  | 'expired';

type DeliveryErrorCategory =
  | 'window_closed'
  | 'unreachable'
  | 'billing'
  | 'opted_out'
  | 'throttled'
  | 'auth'
  | 'template'
  | 'media'
  | 'invalid_request'
  | 'compliance'
  | 'experiment'
  | 'provider'
  | 'unknown';

interface DeliveryError {
  category: DeliveryErrorCategory;
  provider: 'meta' | 'vonage' | 'bird' | 'ses' | 'agentmail' | 'slack' | 'front' | 'teams' | 'pusher';
  code: string;
  title: string;
  detail?: string;
  href?: string;
  retryable: boolean;
  owner: 'customer' | 'recipient' | 'lua' | 'vendor';
}

interface DeliveryView {
  id: string;
  agentId: string;
  userId?: string;
  channel: string;
  provider: DeliveryError['provider'];
  channelIdentifier: string;
  recipient: string;
  providerMessageId?: string;
  conversationMessageId?: string;
  origin: string;
  templateName?: string;
  status: DeliveryStatus;
  error?: DeliveryError;
  events: { status: DeliveryStatus; at: string; source: 'send' | 'callback' | 'sweep' }[];
  pricing?: { billable: boolean; category?: string; model?: string };
  createdAt: string;
  updatedAt: string;
  deliveredAt?: string;
  readAt?: string;
  failedAt?: string;
}
```

## Next steps

<CardGroup>
  <Card title="Proactive Messaging" icon="bell" href="/channels/proactive-messaging">
    The full model: Channels.send vs user.send() vs templates, and per-channel windows
  </Card>

  <Card title="Channel Capabilities" icon="table-list" href="/channels/channel-capabilities">
    Per-channel limits, sender resolution, and compliance
  </Card>

  <Card title="Proactive Send Recipe" icon="clock" href="/examples/proactive-send">
    Schedule outreach with defineJob + Channels.send
  </Card>

  <Card title="Templates API" icon="whatsapp" href="/api/templates">
    List and batch-send approved WhatsApp templates
  </Card>
</CardGroup>


# Data API
Source: https://docs.heylua.ai/api/data

Custom data storage with semantic vector search

## Overview

The Data API allows you to store custom data in collections with powerful semantic search capabilities using vector embeddings. Returns **DataEntryInstance** objects with direct property access.

<Note>
  Data is agent-owned collection storage: a collection can contain many independent entries. For one persistent record tied to a particular end user, use the [User API](/api/user) instead.
</Note>

```typescript theme={null}
import { Data } from 'lua-cli';

// Create with search indexing - returns DataEntryInstance
const entry = await Data.create('movies', {
  title: 'Inception',
  director: 'Christopher Nolan'
}, 'Inception Christopher Nolan sci-fi thriller dreams');

// Direct property access
console.log(entry.title);     // "Inception"
console.log(entry.director);  // "Christopher Nolan"
console.log(entry.id);        // "entry_abc123"

// Instance methods
await entry.update({ rating: 9.5 }, 'inception nolan 9.5 rating');
await entry.save();
await entry.delete();

// Semantic search - returns array of DataEntryInstance
const results = await Data.search('movies', 'mind-bending thriller', 10, 0.7);

// Direct array methods and property access
results.forEach(entry => {
  console.log(`${entry.title}: ${entry.score * 100}% match`);
});

const highScoring = results.filter(entry => entry.score > 0.8);
const titles = results.map(entry => entry.title);
```

<CardGroup>
  <Card title="Direct Access" icon="bolt">
    Access `entry.title` not `entry.data.title`
  </Card>

  <Card title="Search Scores" icon="chart-line">
    Results include relevance scores
  </Card>

  <Card title="Instance Methods" icon="wrench">
    Built-in `update()`, `patch()`, `unset()`, `save()`, and `delete()`
  </Card>

  <Card title="Array Methods" icon="list">
    Use `.map()`, `.filter()` on search results
  </Card>
</CardGroup>

## Return Shape Reference

<Warning>
  **Each method returns a different type.** The most common mistake is treating `Data.search()` results like `Data.get()` results — they have different shapes.
</Warning>

| Method            | Returns                                             | How to use                                                                      |
| ----------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
| `Data.create()`   | `DataEntryInstance` (Proxy)                         | `entry.fieldName` or `entry.data.fieldName`                                     |
| `Data.getEntry()` | `DataEntryInstance` (Proxy)                         | `entry.fieldName` or `entry.data.fieldName`                                     |
| `Data.search()`   | `DataEntryInstance[]` — **flat array, no envelope** | `results.map(e => e.fieldName)`, `results.length` — **no `.data`, no `.count`** |
| `Data.get()`      | `{ data: Entry[], pagination }` — **envelope**      | `result.data.map(e => e.data.fieldName)` — entries are raw, **not proxied**     |
| `Data.update()`   | `{ status, message }`                               | Check `result.status === 'success'`                                             |
| `Data.delete()`   | `{ status, message }`                               | Check `result.status === 'success'`                                             |

**Quick examples:**

```typescript theme={null}
// ✅ Data.search → flat array
const results = await Data.search('movies', 'thriller', 10, 0.7);
results.forEach(entry => console.log(entry.title, entry.score)); // Proxy works
console.log(results.length);          // ✅ count
// ❌ results.data   → undefined
// ❌ results.count  → undefined

// ✅ Data.get → { data, pagination } envelope
const page = await Data.get('movies', {}, 1, 20);
page.data.map(entry => entry.data.title); // raw entries: must use entry.data.field
console.log(page.pagination.totalPages);
// ❌ entry.title (without .data) → undefined on get() results

// ✅ Data.create / Data.getEntry → DataEntryInstance with Proxy
const entry = await Data.create('movies', { title: 'Inception' }, 'Inception Nolan');
console.log(entry.title);       // Proxy shortcut ✅
console.log(entry.data.title);  // Also works ✅
```

## Key Features

<CardGroup>
  <Card title="Custom Collections" icon="database">
    Store any JSON data in named collections
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    Semantic similarity search using AI embeddings
  </Card>

  <Card title="Flexible Schema" icon="diagram-project">
    No fixed schema - store any structure
  </Card>

  <Card title="Filtering" icon="filter">
    Query by field values with operators
  </Card>
</CardGroup>

## Methods

### create()

Create a new entry in a collection.

```typescript theme={null}
Data.create(
  collectionName: string,
  data: object,
  searchText?: string
): Promise<DataEntryInstance>
```

<ParamField type="string">
  Name of the collection (e.g., 'movies', 'customers', 'articles')
</ParamField>

<ParamField type="object">
  Any JSON-serializable object to store
</ParamField>

<ParamField type="string">
  Text to index for vector search. Include all searchable content.
</ParamField>

<Warning>
  **In a deployed agent, the third argument must be a plain string.** Passing
  an object as the third argument in a deployed agent fails with
  `searchText must be a string`. The options-object form
  (`{ searchText?, index? }`) currently works only in local development runs —
  see [Indexes](#indexes) for where index declarations stand today.
</Warning>

**Returns:**

```typescript theme={null}
{
  id: string;
  data: object;
  createdAt: number;
  updatedAt: number;
  searchText?: string;
}
```

**Example:**

```typescript theme={null}
const movie = await Data.create('movies', {
  title: 'The Matrix',
  year: 1999,
  director: 'Wachowski Sisters',
  genre: 'Sci-Fi',
  rating: 8.7
}, 'The Matrix 1999 Wachowski sci-fi action cyberpunk reality virtual');

console.log(movie.id); // "entry_abc123"
```

### search()

Semantic search using vector embeddings.

```typescript theme={null}
Data.search(
  collectionName: string,
  searchText: string,
  limit?: number,
  scoreThreshold?: number
): Promise<DataEntryInstance[]>
```

<ParamField type="string">
  Name of the collection to search
</ParamField>

<ParamField type="string">
  Search text (natural language query)
</ParamField>

<ParamField type="number">
  Maximum number of results to return
</ParamField>

<ParamField type="number">
  Minimum similarity score (0-1). Higher = more similar.
</ParamField>

**Returns:** Array of `DataEntryInstance` objects, each with a `score` property.

**Similarity Scores:**

* `1.0` = Perfect match
* `0.8-0.9` = Very similar
* `0.6-0.7` = Somewhat similar
* `<0.6` = Low similarity

**Example:**

```typescript theme={null}
// Finds movies even if query doesn't match exact words!
const results = await Data.search('movies', 'mind-bending thriller', 5, 0.7);

results.forEach(entry => {
  console.log(`${entry.title} - Relevance: ${entry.score}`);
});
// Output:
// Inception - Relevance: 0.92
// The Matrix - Relevance: 0.85
// Interstellar - Relevance: 0.78
```

### get()

<Tip>
  Filtering a **large** collection? Queries on unindexed fields slow down as
  the collection grows and eventually fail with an error naming the field.
  [Index declarations](#indexes) fix this, but they can currently be made in
  local development runs only — in a deployed agent, keep filtered
  collections small or filter through paginated reads.
</Tip>

Retrieve entries with optional filtering and pagination.

```typescript theme={null}
Data.get(
  collectionName: string,
  filter?: object,
  page?: number,
  limit?: number
): Promise<GetCustomDataResponse>
```

<ParamField type="string">
  Name of the collection
</ParamField>

<ParamField type="object">
  Bounded filter criteria for fields stored in the entry's `data` object
</ParamField>

<ParamField type="number">
  Page number (1-indexed)
</ParamField>

<ParamField type="number">
  Items per page (maximum 100)
</ParamField>

**Returns:**

```typescript theme={null}
{
  data: Entry[];
  pagination: {
    currentPage: number;
    totalPages: number;
    totalCount: number;
    limit: number;
    hasNextPage: boolean;
    hasPrevPage: boolean;
    nextPage: number | null;
    prevPage: number | null;
  };
}
```

**Examples:**

```typescript theme={null}
// Get all
const all = await Data.get('movies');

// With pagination
const page2 = await Data.get('movies', {}, 2, 20);

// With filter
const recent = await Data.get('movies', {
  year: { $gte: 2020 }
});

// Complex filter
const sciFi = await Data.get('movies', {
  genre: 'Sci-Fi',
  rating: { $gte: 8.0 },
  year: { $gte: 2000, $lte: 2020 }
});
```

### getEntry()

Retrieve a specific entry by ID.

```typescript theme={null}
Data.getEntry(
  collectionName: string,
  entryId: string
): Promise<DataEntryInstance>
```

**Example:**

```typescript theme={null}
const movie = await Data.getEntry('movies', 'entry_abc123');
console.log(movie.title); // "Inception" (direct property access via proxy)
```

### update()

Update an existing entry.

```typescript theme={null}
Data.update(
  collectionName: string,
  entryId: string,
  data: object,
  searchText?: string
): Promise<UpdateCustomDataResponse>
```

<ParamField type="string">
  Name of the collection
</ParamField>

<ParamField type="string">
  ID of the entry to update
</ParamField>

<ParamField type="object">
  Data to merge with existing entry
</ParamField>

<ParamField type="string">
  Optional new text for vector search indexing. As with `create()`, a deployed
  agent accepts only a plain string here — the options-object form is a
  local-development capability today (see [Indexes](#indexes)).
</ParamField>

**Returns:**

```typescript theme={null}
{
  status: string;   // "success"
  message: string;  // "Custom data entry updated"
}
```

**Example:**

```typescript theme={null}
// Update data and search text
const result = await Data.update('movies', 'entry_abc123', {
  rating: 8.8,      // Updated rating
  awards: ['Oscar'] // New field
}, 'Inception Christopher Nolan oscar winner');

// Update data only
await Data.update('movies', 'entry_abc123', {
  views: 1500
});
```

<Note>
  Updates merge with existing data. Only the specified fields are updated; other fields are preserved.
</Note>

## DataEntryInstance Methods

When you retrieve or create data entries, you get a `DataEntryInstance` object with convenient instance methods.

### save()

Save the current state of the data entry to the server. This is a convenience method that persists all changes made to the entry.

```typescript theme={null}
entry.save(searchText?: string): Promise<boolean>
```

<ParamField type="string">
  Optional new text for vector search indexing
</ParamField>

**Returns:** Promise resolving to `true` if successful

**Example:**

```typescript theme={null}
const entry = await Data.getEntry('movies', 'entry_abc123');

// Modify properties directly
entry.title = "Inception";
entry.rating = 9.0;
entry.year = 2010;

// Save all changes at once
await entry.save();

// Or save with updated search text
await entry.save('Inception 2010 Nolan sci-fi thriller dreams');
```

<Note>
  The `save()` method provides a simpler workflow - modify properties then save, rather than calling `Data.update()` with the collection name and entry ID.
</Note>

### update() (Instance Method)

Update the entry using the instance method.

```typescript theme={null}
entry.update(data: object, searchText?: string): Promise<object>
```

**Returns:** Promise resolving to the updated data object

**Example:**

```typescript theme={null}
const entry = await Data.getEntry('movies', 'entry_abc123');

// Update with new search text
const updatedData = await entry.update(
  { rating: 9.5, review: 'Mind-bending masterpiece' }, 
  'inception nolan 9.5 rating masterpiece'
);

console.log(updatedData.rating); // 9.5

// Update data only (keeps existing search text)
await entry.update({ views: 1000 });
```

### patch() and unset()

Atomically set and remove top-level fields from an entry. You can also replace the semantic-search text, or clear it with `null`.

```typescript theme={null}
entry.patch(mutation: {
  set?: Record<string, any>;
  unset?: string[];
  searchText?: string | null;
}): Promise<Record<string, any>>

entry.unset(...fields: string[]): Promise<Record<string, any>>
```

A field mutation must change at least one field, unless `searchText` is changed in the same request. `set` and `unset` cannot contain the same field, and field names must be non-empty and cannot start with `$` or contain `.` or a null byte.

```typescript theme={null}
const entry = await Data.getEntry('movies', 'entry_abc123');

await entry.patch({
  set: { rating: 9.5 },
  unset: ['legacyRating'],
  searchText: 'Inception Christopher Nolan acclaimed sci-fi thriller'
});

// Remove fields without replacing the entire entry
await entry.unset('temporaryNote', 'importBatch');

// Remove the search text and its semantic-search vector
await entry.patch({ searchText: null });
```

As with User data, `null` is a stored value inside `set`; use `unset` for deletion. Existing `update()` merge behavior is unchanged.

### delete() (Instance Method)

Delete the entry using the instance method.

```typescript theme={null}
entry.delete(): Promise<boolean>
```

**Example:**

```typescript theme={null}
const entry = await Data.getEntry('movies', 'entry_abc123');
await entry.delete();
```

## Static Methods

### delete()

Delete an entry using the static method.

```typescript theme={null}
Data.delete(
  collectionName: string,
  entryId: string
): Promise<DeleteCustomDataResponse>
```

**Example:**

```typescript theme={null}
await Data.delete('movies', 'entry_abc123');
```

## Use Cases

### Knowledge Base

```typescript theme={null}
export class CreateArticleTool implements LuaTool {
  async execute(input: any) {
    // Create searchable article
    const article = await Data.create('kb_articles', {
      title: input.title,
      content: input.content,
      category: input.category,
      tags: input.tags
    }, `${input.title} ${input.content} ${input.tags.join(' ')}`);
    
    return { articleId: article.id };
  }
}

export class SearchArticlesTool implements LuaTool {
  async execute(input: any) {
    // Semantic search
    const results = await Data.search(
      'kb_articles',
      input.query,
      10,
      0.7
    );
    
    return {
      articles: results.map(entry => ({
        id: entry.id,
        title: entry.title,
        content: entry.content.substring(0, 200),
        relevance: Math.round(entry.score * 100) + '%'
      }))
    };
  }
}
```

### Customer CRM

```typescript theme={null}
export class CreateCustomerTool implements LuaTool {
  async execute(input: any) {
    const customer = await Data.create('customers', {
      name: input.name,
      email: input.email,
      company: input.company,
      status: 'active',
      createdAt: new Date().toISOString()
    }, `${input.name} ${input.company} ${input.email}`);
    
    // Log interaction
    await Data.create('interactions', {
      customerId: customer.id,
      type: 'created',
      notes: 'Initial contact',
      timestamp: new Date().toISOString()
    });
    
    return { customerId: customer.id };
  }
}
```

### Task Management

```typescript theme={null}
export class CreateTaskTool implements LuaTool {
  async execute(input: any) {
    const task = await Data.create('tasks', {
      title: input.title,
      description: input.description,
      status: 'pending',
      priority: input.priority,
      createdAt: new Date().toISOString()
    }, `${input.title} ${input.description}`);
    
    return { taskId: task.id };
  }
}

export class SearchTasksTool implements LuaTool {
  async execute(input: any) {
    const results = await Data.search('tasks', input.query, 20, 0.6);
    
    return {
      tasks: results.map(entry => ({
        id: entry.id,
        title: entry.title,
        description: entry.description,
        status: entry.status,
        priority: entry.priority,
        relevance: entry.score
      }))
    };
  }
}
```

## Filter Operators

Data filters use the platform-wide [Lua Query language](/api/query). The grammar, validation, limits, and errors are identical to every other API that accepts a `filter`.

```typescript theme={null}
// Comparison
{ age: { $eq: 25 } }       // Equal
{ age: { $ne: 25 } }       // Not equal
{ age: { $gt: 25 } }       // Greater than
{ age: { $gte: 25 } }      // Greater than or equal
{ age: { $lt: 25 } }       // Less than
{ age: { $lte: 25 } }      // Less than or equal

// Logical
{ $and: [{ age: { $gte: 18 } }, { age: { $lte: 65 } }] }
{ $or: [{ status: 'active' }, { status: 'pending' }] }

// Array
{ tags: { $in: ['urgent', 'important'] } }
{ tags: { $nin: ['spam', 'archived'] } }
{ tags: ['urgent', 'important'] } // Shorthand for $in

// Existence
{ email: { $exists: true } }
```

See [Lua Query security, errors, and resource limits](/api/query#security-and-errors) for the common contract.

## Indexes

<Warning>
  **Local development only, for now.** Index declarations are accepted in
  local development runs, but the deployed runtime does not accept them yet:
  in a deployed agent, `Data.create()` and `Data.update()` take a plain
  `searchText` string as the third argument, and **passing an object as the
  third argument in a deployed agent fails with `searchText must be a
      string`**. Treat this section as a preview of the local-development
  behavior, and keep the third argument a string in code you deploy.
</Warning>

Every agent's Data collections live in shared storage. Filtered queries
(`Data.get(collection, { field: value })`) stay fast only if the filtered
field is **indexed for your agent** — without one, query time grows with your
collection until requests exceed the platform's 5-second budget and fail.

Declare the fields you filter on **where you store data**:

```typescript theme={null}
// Single fields — one index each
await Data.create('inference_cache', doc, { index: ['business_id'] });

// Compound (fields filtered TOGETHER) — nested array
await Data.create('orders', doc, { index: [['country', 'business_id']] });

// update() and patch() accept the same option and refresh your declarations
await Data.update('orders', id, changes, { index: [['country', 'business_id']] });
```

### How it works

* **Asynchronous**: the index builds within minutes of the first declaration.
  Don't judge query speed in the first moments after declaring.
* **Agent-scoped**: your index contains only your agent's rows — declaring
  costs other agents nothing.
* **Self-maintaining**: declarations are idempotent; declare on every write.
  An index stays alive while your agent *uses* it — declaring writes **or**
  matching filtered reads both count — and is removed automatically \~14 days
  after all usage stops. No cleanup code, ever.
* **Compound = leftmost prefix**: `[['country', 'business_id']]` serves
  filters on `country` and on `country + business_id`, but **not**
  `business_id` alone — declare that separately if you filter it alone.

### Limits

| Limit                 | Value |
| --------------------- | ----- |
| Fields per index      | 2     |
| Declarations per call | 3     |
| Indexes per agent     | 5     |

Over-limit or invalid declarations are **rejected, never silently trimmed** —
check status to see why.

### Checking status

The collections listing includes your declarations and their state:

```typescript theme={null}
const { data: collections } = await Data.collections();
for (const col of collections) {
  for (const idx of col.indexes ?? []) {
    console.log(col.name, idx.fields, idx.status, idx.error ?? '');
    // status: pending | building | ready | failed | rejected
    // error explains failed/rejected (e.g. "too many fields (max 2)")
  }
}
```

### When you forget

A filtered query that exceeds the time budget on an **undeclared** field
fails with an error naming the collection, the field, and the exact
declaration to add. In a local development run, copy it into your
`Data.create` call and the index builds automatically; in a deployed agent
the declaration cannot be applied yet — restructure the read (smaller
collection, tighter pagination) until deployed index support lands.

### Caveats

* Declare **scalar** fields. Indexing a field that holds arrays degrades the
  index (and a compound where *both* fields hold arrays will reject writes
  with a MongoDB "parallel arrays" error).
* Field paths may be dotted (`profile.tier`) but not numeric positions
  (`items.0.sku`), and never `$`-prefixed.

## Best Practices

<AccordionGroup>
  <Accordion title="Create Rich Search Text">
    Include all searchable content in searchText:

    ```typescript theme={null}
    const searchText = [
      item.title,
      item.description,
      item.category,
      item.tags.join(' '),
      item.author
    ].filter(Boolean).join(' ');

    await Data.create('items', item, searchText);
    ```
  </Accordion>

  <Accordion title="Use Appropriate Score Thresholds">
    * `0.8+`: High precision, few results
    * `0.7`: Balanced (recommended default)
    * `0.6`: More results, lower precision
    * `<0.6`: May return irrelevant results
  </Accordion>

  <Accordion title="Structure Data Consistently">
    Use consistent field names across entries:

    ```typescript theme={null}
    // ✅ Good - Consistent
    await Data.create('items', {
      name: 'Item 1',
      price: 10.99,
      inStock: true
    });

    // ❌ Bad - Inconsistent
    await Data.create('items', {
      title: 'Item 2',  // Different field name
      cost: 15.99,      // Different field name
      available: true   // Different field name
    });
    ```
  </Accordion>

  <Accordion title="Add Timestamps">
    Track when entries are created/modified:

    ```typescript theme={null}
    await Data.create('items', {
      ...data,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString()
    });
    ```
  </Accordion>
</AccordionGroup>

## Vector Search Tips

<Tabs>
  <Tab title="What It Is">
    Vector search uses AI to understand meaning, not just match keywords.

    **Example:**

    * Query: "affordable laptop for students"
    * Finds: "budget-friendly notebook for college"
    * Even though no words match exactly!
  </Tab>

  <Tab title="Best For">
    * Knowledge bases
    * FAQs
    * Product recommendations
    * Content discovery
    * Document search
  </Tab>

  <Tab title="Tips">
    1. Include synonyms in searchText
    2. Use natural language queries
    3. Adjust threshold based on results
    4. Test with real user queries
  </Tab>
</Tabs>

<Note title="Debugging tip">
  If your Data results don't look right, log the raw return value before transforming it:

  ```typescript theme={null}
  const results = await Data.search('collection', input.query);
  console.log('Data.search result:', JSON.stringify(results, null, 2));
  ```

  Then run `lua logs --type skill --limit 5` after sending a test message to see the actual shape at runtime. See the [Debugging Skills guide](/cli/debugging) for the full 5-step workflow.
</Note>

## Next Steps

<CardGroup>
  <Card title="Custom Data Examples" icon="layer-group" href="/examples/custom-data">
    See working examples
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Complete tutorial using Data API
  </Card>

  <Card title="Debugging Skills" icon="bug" href="/cli/debugging">
    Inspect runtime return values
  </Card>
</CardGroup>


# LuaDevices
Source: https://docs.heylua.ai/api/device-definition

Define server-side devices and device triggers with defineDevice() and defineDeviceTrigger()

## Overview

The Device Definition API gives you two helpers for declaring how your agent talks to a physical or virtual device:

* **`defineDevice(config)`** — declares a device, its commands, and (optionally) its built-in triggers.
* **`defineDeviceTrigger(config)`** — declares a standalone trigger primitive (versioned, pushed independently).

```typescript theme={null}
import { defineDevice, defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';
```

<Note>
  For the device-side **client library** (the code that runs on the device itself — Node, MQTT, MicroPython), see [Device Client](/api/luadeviceclient) and the [Devices tab](/devices/overview).
</Note>

***

## `defineDevice(config)`

Declares a device. Devices have commands (agent → device) and optionally triggers (device → agent).

```typescript theme={null}
import { defineDevice } from 'lua-cli';
import { z } from 'zod';

export const labelPrinter = defineDevice({
  name: 'label-printer',
  description: 'Warehouse label printer (Zebra GK420d)',
  commands: {
    print: {
      description: 'Print a shipping label',
      schema: z.object({
        orderId: z.string(),
        labelData: z.object({
          address: z.string(),
          tracking: z.string(),
        }),
      }),
    },
    eject: {
      description: 'Eject the current label',
      schema: z.object({}),
    },
  },
  triggers: {
    paperLow: {
      description: 'Fires when paper drops below threshold',
      payloadSchema: z.object({ level: z.number() }),
      execute: async (payload, { agent, device }) => {
        await agent.chat(`Printer ${device.name} paper low: ${payload.level}%`);
      },
    },
  },
});
```

### Configuration — `LuaDeviceConfig`

<ParamField type="string">
  Unique device name. Used in `lua devices` and addressing from agent code.
</ParamField>

<ParamField type="string">
  Human-readable description shown in the admin dashboard.
</ParamField>

<ParamField type="string">
  Optional group label for organizing devices (e.g. `'printers'`, `'sensors'`). `lua devices list --group <name>` filters by this.
</ParamField>

<ParamField type="Record<string, DeviceCommandConfig>">
  Map of command name → command config. Each command is a callable the agent can invoke on the device.
</ParamField>

<ParamField type="Record<string, DeviceTriggerConfig>">
  Map of trigger name → trigger config. Built-in triggers tied to this device. For triggers shared across devices, use [`defineDeviceTrigger`](#definedevicetrigger-config) instead.
</ParamField>

### Command Shape — `DeviceCommandConfig`

<ParamField type="string">
  What this command does. Used by the agent's LLM to decide when to invoke.
</ParamField>

<ParamField type="ZodSchema">
  Zod schema for the command's input. Validated before the command leaves the agent.
</ParamField>

<ParamField type="number">
  Per-command timeout in milliseconds. Defaults to the device-wide timeout (`30000`).
</ParamField>

### Trigger Shape — `DeviceTriggerConfig`

<ParamField type="string">
  What this trigger represents. Used in trigger discovery and admin UI.
</ParamField>

<ParamField type="ZodSchema">
  Zod schema for the trigger payload. Validated when the device fires the trigger.
</ParamField>

<ParamField type="(payload, ctx) => Promise<void>">
  Handler invoked when the trigger fires. Receives the validated payload and a context with `agent` (for invoking the agent) and `device` (the device that fired).
</ParamField>

***

## `defineDeviceTrigger(config)`

Declares a **standalone** device trigger as a first-class primitive. Use this when a trigger isn't bound to a single device — for example, a trigger that any device in a group can fire, or a trigger that's pushed/versioned independently from its associated device.

```typescript theme={null}
import { defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';

export const paperLowAlert = defineDeviceTrigger({
  name: 'paper-low-alert',
  description: 'Generic paper-low handler for any printer',
  payloadSchema: z.object({
    deviceName: z.string(),
    level: z.number(),
  }),
  execute: async (payload, { agent }) => {
    await agent.chat(`Paper low on ${payload.deviceName}: ${payload.level}%`);
  },
});
```

Standalone triggers are pushed via `lua push device-trigger` (or as part of `lua push all`) and managed through the standard CLI surfaces.

### Configuration — `LuaDeviceTriggerConfig`

<ParamField type="string">
  Unique trigger name. Allowed characters: `a-z`, `0-9`, `_`, `-`. Must start with a letter.
</ParamField>

<ParamField type="string">
  What this trigger represents.
</ParamField>

<ParamField type="ZodSchema">
  Zod schema for the trigger payload.
</ParamField>

<ParamField type="(payload, ctx) => Promise<void>">
  Handler invoked when the trigger fires.
</ParamField>

***

## Wiring Up to an Agent

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import { labelPrinter } from './devices/label-printer';
import { paperLowAlert } from './triggers/paper-low-alert';

export const agent = new LuaAgent({
  name: 'warehouse-agent',
  devices: [labelPrinter],
  deviceTriggers: [paperLowAlert],
  // ...
});
```

## Invoking Commands from Tools

Inside a skill tool, address a device by name and call its command:

```typescript theme={null}
class PrintLabelTool extends LuaTool {
  name = 'printLabel';
  description = 'Print a shipping label';
  inputSchema = z.object({ orderId: z.string() });

  async execute({ orderId }, ctx) {
    const order = await Data.get('orders', orderId);
    await ctx.devices['label-printer'].commands.print({
      orderId,
      labelData: { address: order.shipping, tracking: order.tracking },
    });
    return { printed: true };
  }
}
```

## Local Testing

Use `lua devices test` and `lua devices test-trigger` to exercise commands and triggers without involving real hardware:

```bash theme={null}
lua devices test --device-name label-printer
lua devices test-trigger --device-name label-printer --payload '{"level":15}'
```

## Related

* [Devices Overview](/devices/overview)
* [Device Client](/api/luadeviceclient) — the device-side library
* [Devices Command](/cli/devices-command)
* [Self-Describing Commands](/devices/self-describing-commands)
* [Device Triggers](/devices/triggers)


# Environment Utilities
Source: https://docs.heylua.ai/api/environment

Secure environment variable management

## env()

Safely access environment variables in your tools.

```typescript theme={null}
import { env } from 'lua-cli';

const apiKey = env('API_KEY');
const baseUrl = env('API_BASE_URL') || 'https://default.com';
```

## Function Signature

```typescript theme={null}
env(key: string): string | undefined
```

<ParamField type="string">
  Environment variable name to retrieve
</ParamField>

**Returns**: `string | undefined` - Value of the environment variable, or `undefined` if not set

## Loading Priority

Environment variables are loaded in this order (later overrides earlier):

<Steps>
  <Step title="System Environment">
    Variables from your shell/system

    ```bash theme={null}
    export API_KEY=value
    ```
  </Step>

  <Step title=".env File">
    Variables from project `.env` file

    ```bash theme={null}
    # .env
    API_KEY=value
    ```
  </Step>
</Steps>

<Note>
  For production, use `lua env` command to manage variables on the server.
</Note>

## Examples

### Basic Usage

```typescript theme={null}
import { env } from 'lua-cli';

export class MyTool implements LuaTool {
  async execute(input: any) {
    const apiKey = env('STRIPE_API_KEY');
    
    if (!apiKey) {
      throw new Error('STRIPE_API_KEY not configured');
    }
    
    // Use the API key...
    const response = await fetch('https://api.stripe.com/v1/...', {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    return await response.json();
  }
}
```

### With Default Values

```typescript theme={null}
const apiUrl = env('API_BASE_URL') || 'https://api.example.com';
const maxRetries = parseInt(env('MAX_RETRIES') || '3');
const debug = env('DEBUG') === 'true';
const timeout = Number(env('TIMEOUT') || 5000);
```

### Multiple Environment Variables

```typescript theme={null}
export class EmailTool implements LuaTool {
  async execute(input: any) {
    // Get all required variables
    const apiKey = env('SENDGRID_API_KEY');
    const fromEmail = env('FROM_EMAIL');
    const fromName = env('FROM_NAME') || 'Support Team';
    
    // Validate required variables
    if (!apiKey) {
      throw new Error('SENDGRID_API_KEY is required');
    }
    if (!fromEmail) {
      throw new Error('FROM_EMAIL is required');
    }
    
    // Use variables...
  }
}
```

### Environment-Specific Configuration

```typescript theme={null}
export class ApiTool implements LuaTool {
  async execute(input: any) {
    const environment = env('NODE_ENV') || 'development';
    
    // Use different config based on environment
    const apiKey = environment === 'production'
      ? env('PROD_API_KEY')
      : env('DEV_API_KEY');
    
    const baseUrl = environment === 'production'
      ? 'https://api.example.com'
      : 'https://api-dev.example.com';
    
    // Use environment-specific values...
  }
}
```

## Setting Variables

### Method 1: .env File (Local Development)

Create `.env` in project root:

```bash theme={null}
# .env
STRIPE_API_KEY=sk_test_abc123
SENDGRID_API_KEY=SG.xyz789
API_BASE_URL=https://api.example.com
MAX_RETRIES=3
DEBUG=true
```

<Warning>
  Add `.env` to `.gitignore` - never commit secrets!
</Warning>

Create `.env.example` for documentation:

```bash theme={null}
# .env.example
STRIPE_API_KEY=your_stripe_key_here
SENDGRID_API_KEY=your_sendgrid_key_here
API_BASE_URL=https://api.example.com
```

### Method 2: System Environment

Set in your shell:

```bash theme={null}
# Temporary (current session)
export API_KEY=value

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export API_KEY=value' >> ~/.bashrc
```

## Best Practices

<AccordionGroup>
  <Accordion title="Validate Required Variables">
    ```typescript theme={null}
    const apiKey = env('REQUIRED_KEY');

    if (!apiKey) {
      throw new Error(
        'REQUIRED_KEY environment variable is not set. ' +
        'Please add it to your .env file or use `lua env` for production'
      );
    }
    ```
  </Accordion>

  <Accordion title="Use Descriptive Names">
    ```typescript theme={null}
    // ✅ Good
    env('STRIPE_API_KEY')
    env('SENDGRID_API_KEY')
    env('WEATHER_API_KEY')

    // ❌ Bad
    env('KEY1')
    env('SECRET')
    env('TOKEN')
    ```
  </Accordion>

  <Accordion title="Provide Defaults for Non-Secrets">
    ```typescript theme={null}
    // Configuration with sensible defaults
    const apiUrl = env('API_URL') || 'https://api.example.com';
    const timeout = parseInt(env('TIMEOUT') || '5000');
    const retries = parseInt(env('MAX_RETRIES') || '3');

    // But NOT for secrets
    const apiKey = env('API_KEY'); // No default!
    if (!apiKey) throw new Error('API_KEY required');
    ```
  </Accordion>

  <Accordion title="Don't Log Sensitive Values">
    ```typescript theme={null}
    const apiKey = env('API_KEY');

    // ❌ Bad - Exposes secret
    console.log('API Key:', apiKey);

    // ✅ Good - Masked
    console.log('API Key:', apiKey ? '***' : 'not set');
    console.log('API Key configured:', !!apiKey);
    ```
  </Accordion>

  <Accordion title="Type Conversion">
    Environment variables are always strings. Convert when needed:

    ```typescript theme={null}
    // Numbers
    const port = parseInt(env('PORT') || '3000');
    const timeout = Number(env('TIMEOUT') || 5000);

    // Booleans
    const debug = env('DEBUG') === 'true';
    const enabled = env('FEATURE_ENABLED') !== 'false';

    // Arrays
    const hosts = (env('ALLOWED_HOSTS') || '').split(',');
    ```
  </Accordion>
</AccordionGroup>

## Common Patterns

### Pattern: Required Variable

```typescript theme={null}
function getRequiredEnv(key: string): string {
  const value = env(key);
  if (!value) {
    throw new Error(`${key} environment variable is required`);
  }
  return value;
}

// Usage
const apiKey = getRequiredEnv('STRIPE_API_KEY');
```

### Pattern: Validation

```typescript theme={null}
const apiKey = env('API_KEY');

if (apiKey && !apiKey.startsWith('sk_')) {
  throw new Error('API_KEY must start with sk_');
}

if (apiKey && apiKey.length < 32) {
  throw new Error('API_KEY is too short');
}
```

### Pattern: Caching

```typescript theme={null}
export class MyTool implements LuaTool {
  private static cachedApiKey: string | null = null;
  
  private getApiKey(): string {
    if (!MyTool.cachedApiKey) {
      MyTool.cachedApiKey = env('API_KEY');
      if (!MyTool.cachedApiKey) {
        throw new Error('API_KEY not configured');
      }
    }
    return MyTool.cachedApiKey;
  }
  
  async execute(input: any) {
    const apiKey = this.getApiKey();
    // Use cached key...
  }
}
```

## Security

<Warning>
  **Never commit secrets to version control!**

  * Add `.env` to `.gitignore`
  * Use `.env.example` for documentation
  * Store production secrets using `lua env` command (server-managed)
  * Rotate keys regularly
</Warning>

### .gitignore

```
# .gitignore
.env
.env.local
.env.*.local
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Variable not found">
    **Problem**: `env('MY_VAR')` returns `undefined`

    **Solutions**:

    1. Check spelling in `.env` file
    2. Ensure `.env` is in project root
    3. Restart CLI command (variables loaded at startup)
    4. For production, use `lua env` to verify variables on server
  </Accordion>

  <Accordion title="Changes not taking effect">
    **Problem**: Updated `.env` but value unchanged

    **Solution**: Restart the command:

    ```bash theme={null}
    # Stop (Ctrl+C)
    lua chat  # Start again
    ```

    Or use `lua env` to verify and update variables
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Environment Variables Guide" icon="key" href="/concepts/environment-variables">
    Complete guide to configuration
  </Card>

  <Card title="Payment Tool Example" icon="credit-card" href="/examples/payment">
    See environment variables in action
  </Card>
</CardGroup>


# Inbox API
Source: https://docs.heylua.ai/api/inbox

Push approval requests, notices, and connection-fix cards onto a user's desk from any execute context

## Overview

The Inbox API lets your agent **ask for something and wait** — instead of hoping the user is in the conversation right now. `User.Inbox.push()` puts a card on the user's desk: an approval to click, a notice to read, or a broken integration to reconnect. You get a receipt back immediately; the user deals with the card whenever they next open their inbox.

```typescript theme={null}
import { User } from 'lua-cli';

const receipt = await User.Inbox.push({
  title: 'Approve the Q3 renewal quote',
  body: 'Northstar Ltd renewal is ready to send at $48,000.',
  actions: ['approve'],
  key: 'northstar-q3-renewal',
});

// { outcome: 'deposited', kind: 'input_request', key: 'northstar-q3-renewal' }
```

<Note>
  This is the counterpart to [Channels](/api/channels). `Channels.*` sends a **message** into a conversation and expects the user to read it there. `Inbox.push` files a **task** that survives being ignored — it stays on the desk until it is acted on or expires.
</Note>

<CardGroup>
  <Card title="Approval" icon="circle-check">
    Options the user resolves in one click
  </Card>

  <Card title="Notice" icon="bell">
    A finished-work or heads-up card
  </Card>

  <Card title="Connection fix" icon="plug">
    An integration the agent needs reconnected
  </Card>
</CardGroup>

## Where you can call it

`User.Inbox.push()` takes **no recipient** — the card always goes to the user of the current execution context. That makes it available exactly where your code already has an ambient user.

| Context                                         | Available? | Who gets the card                                                                  |
| ----------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| Tool `execute`                                  | ✅          | The user in the current conversation                                               |
| [Dynamic job](/api/jobs) (`Jobs.create`)        | ✅          | The user who triggered the job                                                     |
| Local run against your agent                    | ✅          | **You** — the signed-in developer                                                  |
| Tool in a [trigger](/api/luatrigger)-fired turn | ✅          | The trigger's **bound user** — its creator, or the installer for template triggers |
| [Pre-defined `LuaJob`](/api/luajob)             | ❌          | Context-less — no ambient user                                                     |
| [Webhook `execute`](/api/luawebhook)            | ❌          | Context-less — no ambient user                                                     |

<Warning>
  The recipient is derived from the execution context or your own credentials — never from the payload, and it cannot be overridden. This is the same context split that makes `User.get()` work in a tool but require an explicit `User.get(userId)` in a webhook's `execute`: surfaces with no ambient user have nothing for `Inbox.push` to target, and a push from one fails with `no_user_context`.

  Incoming webhooks are no longer automatically context-less, though: a [trigger](/api/luatrigger)-fired agent turn runs as the trigger's **bound user** — the developer who created it, or the installer for template triggers — so pushes from tools running in that turn reach a real desk. It's only a `LuaWebhook`'s own `execute` function (and a pre-defined `LuaJob`) that has no ambient user; from there, message a specific user directly with [`user.send()`](/api/user) or [Channels](/api/channels) instead.
</Warning>

## push(input)

```typescript theme={null}
const receipt = await User.Inbox.push(input);
```

### Parameters

<ParamField type="string">
  The card's first line. Trimmed and capped at 140 characters.
</ParamField>

<ParamField type="string">
  The human explanation — the card's context line, and the prose in the detail pane. Capped at 1000 characters.
</ParamField>

<ParamField type="string">
  Longer text shown only when the user opens the card. Capped at 4000 characters.
</ParamField>

<ParamField type="string">
  A source link for the card — an issue URL, a document permalink. Must be `http://` or `https://`. Rendered as a link the user can follow; never opened automatically.
</ParamField>

<ParamField type="'urgent' | 'high' | 'normal' | 'low'">
  How loudly the card announces itself. `urgent` is rate-limited — see [Limits](#limits).
</ParamField>

<ParamField type="('approve' | 'redirect' | 'fix')[]">
  What the card offers. `'approve'` gives the user a decision to make; `'fix'` requires `connection`. See [Card kinds](#card-kinds) for how this maps to what the user sees.
</ParamField>

<ParamField type="{ label: string; description?: string }[]">
  Two to four one-click answers. Labels are capped at 60 characters, descriptions at 200. Anything past the fourth option is dropped.
</ParamField>

<ParamField type="{ type: string; name: string }">
  Required with `actions: ['fix']`. `type` is the integration's catalog slug (`'google-calendar'`), `name` is what the user should recognise (`'Google Calendar'`).
</ParamField>

<ParamField type="string">
  Your idempotency and revision handle. 1–120 characters of `A–Z`, `a–z`, `0–9`, `.`, `_`, `:`, `-`. Push the same `key` again and you land on the existing card instead of knocking a second time. Omit it for one-shot cards.
</ParamField>

<ParamField type="string">
  The conversation the card should hand off into when the user acts on it. Defaults to the current conversation.
</ParamField>

### Returns

<ResponseField name="outcome" type="'deposited' | 'updated' | 'exists' | 'capped'">
  `deposited` — a new card is on the desk.
  `updated` — an existing card with this `key` was revised in place.
  `exists` — a card with this identity was already there, unchanged.
  `capped` — the push was refused and nothing was filed: the daily limit is spent, or the user's organization has turned agent pushes off. `reason` says which.
</ResponseField>

<ResponseField name="kind" type="'input_request' | 'connection_fix' | 'agent_notice'">
  Which card kind the push routed to — echoed even on `capped`, where it reports the kind that *would* have been filed.
</ResponseField>

<ResponseField name="key" type="string">
  The key the card is filed under — your `key` if you supplied one, otherwise the generated one. Reuse it to revise the card later.
</ResponseField>

<ResponseField name="reason" type="string">
  Only present on `capped`. A short explanation you can surface to the agent author.
</ResponseField>

## Card kinds

You don't pick the kind directly — it follows from what you ask for, in this order:

<Steps>
  <Step title="Two or more options → a question card">
    Supplying `options` (2–4) files an `input_request`. So does `actions: ['approve']` **without** options — the Approve/Decline pair is synthesized for you, so the card still resolves in one click.
  </Step>

  <Step title="A fix action → a connection card">
    `actions: ['fix']` with `connection: { type, name }` files a `connection_fix` — the card that walks the user through reconnecting the integration your agent is blocked on.
  </Step>

  <Step title="Everything else → a notice">
    Anything with no options and no fix — including `actions: ['redirect']` — files an `agent_notice`: work you finished, something the user should know about.
  </Step>
</Steps>

<Note>
  If you supply both `options` and `actions: ['fix']`, the options win — the question card is checked first.
</Note>

## Limits

Inbox pushes are budgeted so an agent cannot train its user to ignore the inbox. The numbers below are platform defaults and may be tuned; the behaviors — resolve to `capped`, demote, never throw — are the contract.

| Limit                                             | Default              | Behaviour when exceeded                                                                                                                                          |
| ------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cards per agent, per user, per day                | 5 per kind           | The push resolves to `{ outcome: 'capped' }` — it does **not** throw                                                                                             |
| `priority: 'urgent'` per agent, per user, per day | 2                    | The card still lands, demoted to `high` — never dropped. Demotion also drops the urgent-only **email leg**: the third urgent push of the day is device-push only |
| Organization kill switch                          | Off (pushes allowed) | An org admin can disable agent pushes entirely — every push resolves to `{ outcome: 'capped' }` with a reason                                                    |

Budgets are shared with the agent's other inbox activity of the same class, so a question pushed from code spends the same allowance as a question the agent asks on its own.

<Warning>
  Treat `capped` as an expected outcome, not an error. Branch on it and fold the information into your run summary instead of retrying:

  ```typescript theme={null}
  const receipt = await User.Inbox.push({ title, body });

  if (receipt.outcome === 'capped') {
    return `Digest ready, but the inbox is full for today: ${receipt.reason}`;
  }
  ```
</Warning>

## Notifications and quiet hours

A **fresh** card (`outcome: 'deposited'`) notifies the user's devices; `urgent` cards also send an email. The email rule applies **after** the daily urgent clamp — a push demoted to `high` sends no email. Delivery is **best-effort**: a notification can be lost — no registered devices, an offline phone, a delivery hiccup — without affecting the card, and the receipt doesn't report delivery. Revisions (`updated`), duplicates (`exists`), and capped pushes never notify — a revision updates the card quietly.

<Warning>
  **Quiet hours drop notifications — they don't defer them.** If the user has quiet hours set and your push lands inside the window, there is **no device push and no email** — not even for `urgent`, and there is no catch-up when the window ends. The card itself always lands and is the durable record; the user sees it next time they open their desk. Rely on the card, not the notification.
</Warning>

<Note>
  Quiet hours are honored fail-open: if the platform can't read the user's preference, it delivers rather than risk silently suppressing every notification. So quiet hours are a strong promise to the user, not an absolute guarantee to your code — one more reason the card, not the notification, is the contract.
</Note>

## Revising a card

Give a card a `key` and later pushes with that same `key` revise it in place rather than filing a second one. The user is not notified again for an unchanged card.

```typescript theme={null}
// Monday — file the card
await User.Inbox.push({
  key: 'weekly-pipeline-review',
  title: 'Pipeline review ready',
  body: '12 deals need a status update.',
});

// Tuesday — same key, new numbers: the existing card updates
await User.Inbox.push({
  key: 'weekly-pipeline-review',
  title: 'Pipeline review ready',
  body: '9 deals need a status update.',
});
// → { outcome: 'updated', kind: 'agent_notice', key: 'weekly-pipeline-review' }
```

## Errors

A full inbox resolves to `capped`. Everything else throws, with a `code` you can branch on:

| `code`            | Meaning                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `invalid_input`   | Missing `title`/`body`, a non-http `deeplink`, a `key` outside the allowed charset, or `actions: ['fix']` without `connection` |
| `no_user_context` | The execution context has no user to deliver to                                                                                |
| `deposit_failed`  | The card could not be filed — safe to retry                                                                                    |

```typescript theme={null}
try {
  await User.Inbox.push({ title, body, actions: ['fix'], connection });
} catch (error: any) {
  if (error.code === 'invalid_input') {
    // Fix the payload — retrying unchanged will fail the same way
  }
  throw error;
}
```

## Examples

### Ask for an approval before acting

```typescript theme={null}
import { LuaTool, User } from 'lua-cli';
import { z } from 'zod';

export class RequestRefundApproval implements LuaTool {
  name = 'request_refund_approval';
  description = 'Ask the account owner to approve a refund above the auto-approve threshold';

  inputSchema = z.object({
    orderId: z.string(),
    amount: z.number(),
  });

  async execute({ orderId, amount }: z.infer<typeof this.inputSchema>) {
    const receipt = await User.Inbox.push({
      title: `Approve a $${amount} refund`,
      body: `Order ${orderId} is above the auto-approve limit and needs a decision.`,
      detail: 'Approving issues the refund immediately and emails the customer.',
      options: [
        { label: 'Approve refund', description: 'Issue it now' },
        { label: 'Decline', description: 'Keep the order as is' },
      ],
      key: `refund-approval:${orderId}`,
      priority: 'high',
    });

    if (receipt.outcome === 'capped') {
      return 'Could not file the approval today — the daily inbox limit was reached.';
    }

    return `Approval requested. You'll be asked in your inbox.`;
  }
}
```

### Report finished work from a recurring job

Dynamic jobs carry the user who created them, so a push inside one lands on that user's desk:

```typescript theme={null}
import { Jobs, User } from 'lua-cli';

await Jobs.create({
  name: 'nightly-digest',
  schedule: { type: 'cron', expression: '0 6 * * *' },
  execute: async () => {
    const summary = await buildDigest();

    await User.Inbox.push({
      title: 'Nightly digest ready',
      body: `${summary.count} items processed overnight.`,
      detail: summary.text,
      deeplink: summary.url,
      key: 'nightly-digest',
    });
  },
});
```

Because the `key` is stable, tomorrow's run revises today's card instead of stacking a second one.

### Ask the user to reconnect an integration

```typescript theme={null}
const receipt = await User.Inbox.push({
  title: 'Reconnect Google Calendar',
  body: "I can't read your availability — the calendar connection expired.",
  actions: ['fix'],
  connection: { type: 'google-calendar', name: 'Google Calendar' },
  key: 'calendar-reconnect',
});
// → { outcome: 'deposited', kind: 'connection_fix', key: 'calendar-reconnect' }
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use a stable key for anything recurring">
    A digest, a review, a status card — anything your agent produces on a schedule should carry the same `key` every run. Without one, each run files a new card and the inbox becomes a log.
  </Accordion>

  <Accordion title="Reserve urgent for things that are actually urgent">
    Only two urgent cards per user per day survive at that priority; the rest are demoted. Spending the allowance on routine cards means the genuinely urgent one arrives looking ordinary.
  </Accordion>

  <Accordion title="Give options when you want a decision">
    A notice asking "let me know if this is okay" needs the user to open a conversation and type. Two to four `options` turn the same ask into one click, and the answer comes back into the thread.
  </Accordion>

  <Accordion title="Handle capped, never retry it">
    `capped` means the budget is spent for the day, so an immediate retry fails identically. Put the information in your return value instead — the user still gets it, through the conversation.
  </Accordion>

  <Accordion title="Write the title as the whole message">
    Users scan the first line. `Approve the Q3 renewal quote` is actionable at a glance; `Action required` is not.
  </Accordion>
</AccordionGroup>

## TypeScript Support

The input and receipt are fully typed at the call site, so `receipt.outcome` narrows correctly without any annotation. If you need the shapes as named types, derive them from the method:

```typescript theme={null}
import { User } from 'lua-cli';

type InboxPushInput = Parameters<typeof User.Inbox.push>[0];
type InboxPushReceipt = Awaited<ReturnType<typeof User.Inbox.push>>;

async function notify(input: InboxPushInput): Promise<InboxPushReceipt> {
  return User.Inbox.push(input);
}
```

## Next Steps

<CardGroup>
  <Card title="User API" href="/api/user" icon="user">
    Read and write the user data behind the card
  </Card>

  <Card title="Channels API" href="/api/channels" icon="paper-plane">
    Send a message into the conversation instead
  </Card>

  <Card title="Jobs" href="/api/jobs" icon="clock">
    Schedule the work that files the card
  </Card>

  <Card title="Spaces" href="/overview/spaces" icon="users">
    Multi-agent delegation
  </Card>
</CardGroup>

## See also

* [Proactive Inbox recipe](/examples/proactive-inbox) — a full monitoring skill: notices that revise in place, approvals, connection fixes, and `capped` handled gracefully
* [User API](/api/user) — profile, storage, and `user.send()` for in-conversation messages


# Integrations API
Source: https://docs.heylua.ai/api/integrations

Call any connected provider's raw REST API through your agent's integrations

## Overview

`Integrations.passthrough` gives your code direct access to a provider's **raw REST API** through the integration your agent is already connected to. The platform relays the call server-side over the agent's own bound connection — your code never sees OAuth tokens or provider credentials, and what the call is allowed to do is exactly what the connection's OAuth grant allows.

Connected integrations already expose curated MCP tools to your agent. Passthrough is for everything those tools don't cover: any endpoint the provider documents, with your own query parameters, headers, and JSON bodies.

```typescript theme={null}
import { Integrations } from 'lua-cli';

// Any GitHub REST endpoint, through the agent's GitHub connection
const res = await Integrations.passthrough('github', {
  method: 'GET',
  path: 'repos/acme/app/pulls/42/files',
});

if (res.status === 200) {
  console.log(res.data); // parsed JSON: the PR's files, each with its patch
}
```

It works everywhere your code runs — tools, jobs, webhooks, and pre/post processors — and every connected integration also auto-attaches a matching agent tool (see [The auto-attached agent tool](#the-auto-attached-agent-tool) below), so the agent itself can make raw provider calls too.

<Note>
  **Scope-gated by the OAuth grant.** The provider enforces its own OAuth scopes on every raw call. A call outside the connection's granted scopes comes back as the provider's own `401`/`403` **inside the response envelope** — never as a thrown error. Reconnect the integration with the needed scopes to widen access.
</Note>

## Import

```typescript theme={null}
import { Integrations } from 'lua-cli';
```

The wire types are exported too, if you want to name them explicitly:

```typescript theme={null}
import type {
  IntegrationPassthroughRequest,
  IntegrationPassthroughResponse,
  IntegrationPassthroughMethod,
} from 'lua-cli';
```

## Method

### Integrations.passthrough(integrationType, request)

Make one raw provider API call through the agent's connected integration.

<ParamField type="string">
  The connected integration to call through, e.g. `'github'`, `'microsoft'`, `'linear'`. Must match an integration the agent is connected to (see [`lua integrations`](/cli/integrations-command)).
</ParamField>

<ParamField type="IntegrationPassthroughRequest">
  The provider call to relay — see the fields below.
</ParamField>

**Returns:** `Promise<IntegrationPassthroughResponse>` — the raw provider response envelope.

### Request fields (IntegrationPassthroughRequest)

<ParamField type="'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'">
  HTTP method of the provider call.
</ParamField>

<ParamField type="string">
  Provider API path **after the provider's base URL**, e.g. `'repos/{owner}/{repo}/pulls/42/files'` for GitHub or `'v1.0/me'` for Microsoft Graph. A leading `/` is tolerated. Relative traversal segments (`..`) are rejected.
</ParamField>

<ParamField type="Record<string, string | number | boolean>">
  Query-string parameters (pagination etc.). Forwarded to the provider as-is. A query string embedded in `path` is merged in too.
</ParamField>

<ParamField type="unknown">
  Request body. Objects and arrays are sent as JSON (with `Content-Type: application/json` set for you); a string is sent verbatim — set your own `Content-Type` header for non-JSON payloads. Ignored on `GET`/`HEAD`.
</ParamField>

<ParamField type="Record<string, string>">
  Extra request headers forwarded to the provider. `Authorization` and other auth/hop-by-hop headers are managed server-side and cannot be overridden. See the [limitation on `Accept` media-type overrides](#limitation-accept-header-media-type-overrides) below.
</ParamField>

### Response envelope (IntegrationPassthroughResponse)

| Field     | Type                     | Description                                                                                                                                                       |
| --------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`  | `number`                 | The provider's HTTP status code, relayed faithfully — including provider errors like `403` or `404`                                                               |
| `headers` | `Record<string, string>` | Provider response headers (lower-cased names; auth-related headers stripped)                                                                                      |
| `data`    | `unknown`                | Provider response body: **parsed JSON** when the provider responded with JSON, the **raw string** otherwise (e.g. `text/html` or `text/plain` round-trips intact) |

## Error model: envelope vs thrown

There are two distinct kinds of failure, and they surface differently on purpose:

**Provider errors come back in the envelope.** If the provider itself rejects the call — missing OAuth scope (`403`), not found (`404`), provider-side validation (`422`) — the envelope relays the provider's own status and body so you can see exactly what the provider said. **Nothing is thrown.** Always branch on `status`:

```typescript theme={null}
const res = await Integrations.passthrough('github', {
  method: 'GET',
  path: 'repos/acme/private-repo/pulls/42/files',
});

if (res.status === 403) {
  // The GitHub connection lacks a scope for this call — the body is
  // GitHub's own error message. Reconnect with wider scopes to fix.
  return { success: false, error: 'GitHub denied the call', detail: res.data };
}
```

**Route-level failures are thrown.** If the call never reaches the provider, `Integrations.passthrough` throws a plain `Error` with a human-readable message. The relay rejects such calls with one of these typed reasons:

| Code                          | HTTP status | When it fires                                                                                            | Remedy                                                                               |
| ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `passthrough_invalid_request` | 400         | Missing/invalid `method` or `path` (e.g. a method outside the allowed six, or a path with `..` segments) | Fix the request shape                                                                |
| `passthrough_disabled`        | 403         | An admin has switched passthrough **off** for this integration                                           | Ask a workspace admin to re-enable it, or use the integration's curated tools        |
| `passthrough_no_connection`   | 404         | The agent has no bound connection for `integrationType`                                                  | Connect the integration with [`lua integrations connect`](/cli/integrations-command) |
| `passthrough_rate_limited`    | 429         | The per-agent passthrough rate limit was exceeded                                                        | Back off and retry shortly; batch or cache calls                                     |
| `passthrough_upstream_error`  | 502         | The relay could not reach the upstream integration layer (transport failure)                             | Transient — retry with backoff                                                       |
| `passthrough_not_configured`  | 503         | The platform's server-side integration relay isn't configured for this workspace                         | Contact support                                                                      |

<Note>
  The **Code** column is the relay's typed rejection code. The `Error` thrown in sandbox code carries the corresponding human-readable message — the code token itself is not embedded in the message — so treat any throw as "the provider was never called" rather than string-matching on codes. The [auto-attached agent tool](#the-auto-attached-agent-tool) does surface the typed `code` directly on route-level failures.
</Note>

```typescript theme={null}
try {
  const res = await Integrations.passthrough('github', { method: 'GET', path: 'user' });
  return { status: res.status, user: res.data };
} catch (error) {
  // Route-level only: disabled, no connection, rate limited, transport, …
  return { success: false, error: error instanceof Error ? error.message : 'passthrough failed' };
}
```

## Guardrails

<CardGroup>
  <Card title="Admin enable switch" icon="toggle-on">
    Passthrough is enabled per integration by default, and workspace admins can switch it off for any integration. A disabled integration rejects with `passthrough_disabled`.
  </Card>

  <Card title="Every call audited" icon="clipboard-list">
    Every passthrough call — including denied ones — is audit-logged with identifiers, status, and latency. Request and response bodies are never logged.
  </Card>

  <Card title="Per-agent rate limit" icon="gauge-high">
    Calls are rate-limited per agent (default 120 calls per minute). Exceeding it rejects with `passthrough_rate_limited` — back off and retry.
  </Card>
</CardGroup>

## Limitation: Accept-header media-type overrides

<Warning>
  Custom request headers are forwarded, but **`Accept` media-type overrides do not change what the provider returns** — the relay normalizes content negotiation. For example, requesting a GitHub pull request with `Accept: application/vnd.github.diff` returns the standard JSON representation, not a unified diff.

  Use the provider's **JSON-native equivalent** instead: GitHub's `GET repos/{owner}/{repo}/pulls/{n}/files` returns each changed file with its `patch` — the per-file diff — as plain JSON. Non-JSON *response bodies* are unaffected: endpoints that natively return text or HTML (e.g. GitHub's markdown renderer) round-trip intact as strings in `data`.
</Warning>

## Examples

### Microsoft Graph: profile and files

The generic Microsoft connector exposes relatively few curated tools — passthrough opens up the whole of Microsoft Graph through it.

```typescript theme={null}
import { LuaTool, Integrations } from 'lua-cli';
import { z } from 'zod';

export default class OneDriveRecentTool implements LuaTool {
  name = 'onedrive_recent';
  description = "List the connected user's OneDrive root folder";

  inputSchema = z.object({});

  async execute() {
    // Who is connected?
    const me = await Integrations.passthrough('microsoft', {
      method: 'GET',
      path: 'v1.0/me',
    });
    if (me.status !== 200) {
      return { success: false, status: me.status, error: me.data };
    }

    // List files in the OneDrive root
    const files = await Integrations.passthrough('microsoft', {
      method: 'GET',
      path: 'v1.0/me/drive/root/children',
      query: { $top: 25, $orderby: 'lastModifiedDateTime desc' },
    });
    if (files.status !== 200) {
      return { success: false, status: files.status, error: files.data };
    }

    const items = (files.data as any).value ?? [];
    return {
      success: true,
      user: (me.data as any).displayName,
      files: items.map((f: any) => ({ name: f.name, modified: f.lastModifiedDateTime })),
    };
  }
}
```

### GitHub: review a pull request

List a PR's changed files — each carries its own `patch` (the per-file diff) as JSON — then post a review with a JSON body.

```typescript theme={null}
import { LuaTool, Integrations } from 'lua-cli';
import { z } from 'zod';

export default class ReviewPrTool implements LuaTool {
  name = 'review_pr';
  description = 'Read a pull request diff and post a review';

  inputSchema = z.object({
    owner: z.string(),
    repo: z.string(),
    pullNumber: z.number(),
    comment: z.string(),
    approve: z.boolean().default(false),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const base = `repos/${input.owner}/${input.repo}/pulls/${input.pullNumber}`;

    // 1. The diff, JSON-natively: each file entry includes its `patch`
    const files = await Integrations.passthrough('github', {
      method: 'GET',
      path: `${base}/files`,
      query: { per_page: 100 },
    });
    if (files.status !== 200) {
      // Provider error relayed in the envelope — e.g. 403 on a missing scope
      return { success: false, status: files.status, error: files.data };
    }

    const patches = (files.data as any[]).map((f) => ({
      filename: f.filename,
      additions: f.additions,
      deletions: f.deletions,
      patch: f.patch, // per-file unified diff
    }));

    // 2. Post the review (JSON body POSTs through as-is)
    const review = await Integrations.passthrough('github', {
      method: 'POST',
      path: `${base}/reviews`,
      data: {
        event: input.approve ? 'APPROVE' : 'COMMENT',
        body: input.comment,
      },
    });

    return {
      success: review.status === 200,
      reviewStatus: review.status,
      filesReviewed: patches.length,
      patches,
    };
  }
}
```

## The auto-attached agent tool

Every connected integration also attaches one synthetic tool to the agent — named `{integrationType}_passthrough`, e.g. `github_passthrough` — alongside that integration's curated tools. It takes an equivalent `method` / `path` / `query` / `body` / `headers` input (note: the tool's body field is named `body`, where the SDK's is `data`) and returns the same `{ status, headers, data }` envelope, so the agent can reach any provider endpoint its connection allows without you writing a tool for it. The same guardrails (admin switch, audit log, rate limit) apply identically.

If you'd rather the agent *not* have raw API access to an integration, a workspace admin can turn the integration's passthrough switch off — that disables both the agent tool and `Integrations.passthrough` calls for it.

## Related APIs

<CardGroup>
  <Card title="Integrations Command" href="/cli/integrations-command" icon="plug">
    Connect integrations, manage scopes, and set up triggers
  </Card>

  <Card title="LuaTrigger" href="/api/luatrigger" icon="bolt">
    Wake the agent when events fire in a connected integration
  </Card>

  <Card title="LuaWebhook" href="/api/luawebhook" icon="webhook">
    Receive external events with full control of the HTTP response
  </Card>

  <Card title="AI API" href="/api/ai" icon="wand-magic-sparkles">
    Generate AI responses from within your tools
  </Card>
</CardGroup>

## See Also

* [LuaTool](/api/luatool) - Creating tools
* [Jobs API](/api/jobs) - Schedule recurring provider calls
* [Environment API](/api/environment) - Configuration for your skill code


# Jobs API
Source: https://docs.heylua.ai/api/jobs

Dynamically create scheduled tasks from within your tools

## Overview

The Jobs API allows you to dynamically create scheduled tasks from within your tools. Use this to defer work, schedule reminders, or automate recurring tasks.

```typescript theme={null}
import { Jobs } from 'lua-cli';

// Create a one-time reminder
const job = await Jobs.create({
  name: 'user-reminder',
  metadata: { message: 'Team meeting in 10 minutes' },
  schedule: {
    type: 'once',
    executeAt: new Date(Date.now() + 600000)
  },
  execute: async (jobInstance) => {
    // ✅ Dynamic jobs automatically have user context!
    const user = await jobInstance.user();  // No userId needed
    await user.send([{
      type: 'text',
      text: jobInstance.metadata.message
    }]);
  }
});
```

<Note>
  **Automatic User Context:** Dynamic jobs created from tools automatically know which user triggered them. Use `jobInstance.user()` to get the user - no userId required! This is different from pre-defined LuaJob which requires `User.get(userId)`.
</Note>

<Note>
  Dynamically create jobs at runtime from within your tools. Pairs with the LuaJob class for pre-defined jobs.
</Note>

## Import

```typescript theme={null}
import { Jobs } from 'lua-cli';
// or
import { Jobs } from 'lua-cli/skill';
```

## Capabilities

<CardGroup>
  <Card title="Dynamic Creation" icon="plus">
    Create jobs on-demand from tools
  </Card>

  <Card title="One-time Tasks" icon="calendar-day">
    Schedule tasks for specific times
  </Card>

  <Card title="Recurring Jobs" icon="rotate">
    Set up intervals or cron patterns
  </Card>

  <Card title="Automatic User Context" icon="user">
    Jobs automatically know which user triggered them - use `jobInstance.user()`
  </Card>
</CardGroup>

## Jobs API vs LuaJob

Understanding user access in different job types:

| Feature            | Jobs API (Dynamic)   | LuaJob (Pre-defined)    |
| ------------------ | -------------------- | ----------------------- |
| **When Created**   | Runtime, from tools  | At agent setup          |
| **User Context**   | ✅ Automatic          | ❌ None                  |
| **Get User**       | `jobInstance.user()` | `User.get(userId)`      |
| **userId Needed?** | ❌ No (automatic)     | ✅ Yes (from metadata)   |
| **Best For**       | User-triggered tasks | Regular scheduled tasks |

<Note>
  **Why the difference?** Dynamic jobs are created during a user conversation, so they automatically capture that user's context. Pre-defined jobs run on a schedule with no specific user, so you must explicitly provide a userId if you want to notify someone.
</Note>

## Methods

### Jobs.create(config)

Creates a new scheduled job.

<ParamField type="JobConfig">
  Job configuration object
</ParamField>

**Returns:** `Promise<JobInstance>`

**Example:**

```typescript theme={null}
const job = await Jobs.create({
  name: 'reminder-task',
  description: 'Remind user about meeting',
  metadata: { message: 'Don\'t forget the meeting!' },
  schedule: {
    type: 'once',
    executeAt: new Date(Date.now() + 3600000)
  },
  execute: async (jobInstance) => {
    const user = await jobInstance.user();
    await user.send([{
      type: 'text',
      text: jobInstance.metadata.message
    }]);
    return { success: true };
  }
});
```

### Jobs.getJob(jobId)

Retrieves a job by ID.

<ParamField type="string">
  Job ID to retrieve
</ParamField>

**Returns:** `Promise<JobInstance>`

**Example:**

```typescript theme={null}
const job = await Jobs.getJob('job_123');
console.log(job.name);
console.log(job.activeVersion?.schedule);
```

### Jobs.getAll(options?)

Retrieves all jobs for the current agent.

<ParamField type="boolean">
  Include dynamically created jobs (default: false)
</ParamField>

**Returns:** `Promise<JobInstance[]>`

**Example:**

```typescript theme={null}
// Get all jobs including dynamically created ones
const jobs = await Jobs.getAll({ includeDynamic: true });

for (const job of jobs) {
  console.log(`${job.name}: ${job.data.active ? 'active' : 'inactive'}`);
}

// Find a specific job by name
const trackingJob = jobs.find(j => j.name.startsWith('track-game-'));
if (trackingJob) {
  await trackingJob.deactivate();
}
```

## Job Configuration

### Required Fields

<ParamField type="string">
  Unique job name
</ParamField>

<ParamField type="JobSchedule">
  When/how often to run the job
</ParamField>

<ParamField type="function">
  Function that executes when job runs

  **Signature:** `(job: JobInstance) => Promise<any>`
</ParamField>

### Optional Fields

<ParamField type="string">
  Job description for documentation
</ParamField>

<ParamField type="object">
  Data to pass to execute function

  **Important:** Use metadata to pass data - the execute function cannot access parent scope!
</ParamField>

<ParamField type="number">
  Maximum execution time in seconds

  **Default:** 300 (5 minutes)
</ParamField>

<ParamField type="object">
  Retry configuration

  ```typescript theme={null}
  retry: {
    maxAttempts: number;     // Max retry attempts
    backoffSeconds?: number; // Seconds between retries (optional)
  }
  ```
</ParamField>

<ParamField type="boolean">
  Whether to activate immediately

  **Default:** true
</ParamField>

## Schedule Types

### Once (One-time execution)

```typescript theme={null}
schedule: {
  type: 'once',
  executeAt: Date  // When to run
}
```

**Examples:**

```typescript theme={null}
// Run in 1 hour
schedule: {
  type: 'once',
  executeAt: new Date(Date.now() + 3600000)
}

// Run at specific time
schedule: {
  type: 'once',
  executeAt: new Date('2025-12-25T09:00:00Z')
}
```

### Interval (Recurring at fixed intervals)

```typescript theme={null}
schedule: {
  type: 'interval',
  seconds: number  // Seconds between executions
}
```

**Examples:**

```typescript theme={null}
// Run every 5 minutes
schedule: {
  type: 'interval',
  seconds: 300
}

// Run every hour
schedule: {
  type: 'interval',
  seconds: 3600
}
```

### Cron (Schedule with cron pattern)

```typescript theme={null}
schedule: {
  type: 'cron',
  expression: string  // Cron expression
  timezone?: string   // Optional timezone (e.g., 'America/New_York')
}
```

**Examples:**

```typescript theme={null}
// Every day at 9 AM
schedule: {
  type: 'cron',
  expression: '0 9 * * *'
}

// Every Monday at 8 AM EST
schedule: {
  type: 'cron',
  expression: '0 8 * * 1',
  timezone: 'America/New_York'
}

// Every 15 minutes
schedule: {
  type: 'cron',
  expression: '*/15 * * * *'
}
```

## Complete Examples

### Reminder Tool

```typescript theme={null}
import { LuaTool, Jobs, JobInstance } from 'lua-cli/skill';
import { z } from 'zod';

export default class ReminderTool implements LuaTool {
  name = 'set_reminder';
  description = 'Set a reminder to notify user later';
  
  inputSchema = z.object({
    message: z.string().describe('Reminder message'),
    minutes: z.number().min(1).max(10080).describe('Minutes from now')
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    // Create job to notify user later
    const job = await Jobs.create({
      name: `reminder-${Date.now()}`,
      description: 'User reminder',
      
      // ✅ Pass data via metadata (not parent scope!)
      metadata: {
        message: input.message,
        setAt: new Date().toISOString()
      },
      
      schedule: {
        type: 'once',
        executeAt: new Date(Date.now() + input.minutes * 60000)
      },
      
      execute: async (jobInstance: JobInstance) => {
        const user = await jobInstance.user();
        const message = jobInstance.metadata.message;
        
        await user.send([{
          type: 'text',
          text: `⏰ Reminder: ${message}`
        }]);
        
        return {
          success: true,
          deliveredAt: new Date().toISOString()
        };
      }
    });
    
    return {
      success: true,
      message: `Reminder set for ${input.minutes} minutes from now`,
      jobId: job.id,
      executeAt: job.activeVersion?.schedule?.executeAt
    };
  }
}
```

### Follow-up Tool

```typescript theme={null}
import { LuaTool, Jobs, JobInstance, Data } from 'lua-cli/skill';
import { z } from 'zod';

export default class ScheduleFollowupTool implements LuaTool {
  name = 'schedule_followup';
  description = 'Schedule a follow-up message for customer support';
  
  inputSchema = z.object({
    ticketId: z.string(),
    followupHours: z.number().min(1).max(168),
    message: z.string()
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    // Create job for follow-up
    const job = await Jobs.create({
      name: `followup-${input.ticketId}`,
      description: `Follow-up for ticket ${input.ticketId}`,
      
      metadata: {
        ticketId: input.ticketId,
        message: input.message
      },
      
      schedule: {
        type: 'once',
        executeAt: new Date(Date.now() + input.followupHours * 3600000)
      },
      
      execute: async (jobInstance: JobInstance) => {
        const user = await jobInstance.user();
        const { ticketId, message } = jobInstance.metadata;
        
        // Check if ticket is still open
        const tickets = await Data.search('tickets', ticketId, 1);
        
        if (tickets.length > 0 && tickets[0].status === 'open') {
          // Send follow-up
          await user.send([{
            type: 'text',
            text: `📋 Ticket #${ticketId} Follow-up:\n\n${message}`
          }]);
          
          // Update ticket
          await Data.update('tickets', tickets[0].id, {
            ...tickets[0].data,
            followupSent: true,
            followupAt: new Date().toISOString()
          });
          
          return { success: true, sent: true };
        }
        
        return { success: true, sent: false, reason: 'Ticket closed' };
      }
    });
    
    return {
      success: true,
      message: `Follow-up scheduled for ${input.followupHours} hours`,
      jobId: job.id
    };
  }
}
```

### Recurring Report

```typescript theme={null}
import { LuaTool, Jobs, JobInstance, Products } from 'lua-cli/skill';
import { z } from 'zod';

export default class DailyReportTool implements LuaTool {
  name = 'setup_daily_report';
  description = 'Set up daily sales report';
  
  inputSchema = z.object({
    timeOfDay: z.string().regex(/^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$/)
      .describe('Time in HH:MM format (24-hour)')
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    const [hour, minute] = input.timeOfDay.split(':');
    
    const job = await Jobs.create({
      name: 'daily-sales-report',
      description: 'Daily sales summary',
      
      metadata: {
        reportTime: input.timeOfDay
      },
      
      schedule: {
        type: 'cron',
        expression: `${minute} ${hour} * * *`  // Every day at specified time
      },
      
      execute: async (jobInstance: JobInstance) => {
        // Get products sold today
        const products = await Products.get(1, 100);
        const totalValue = products.reduce((sum, p) => sum + (p.price || 0), 0);
        
        const report = `📊 Daily Sales Report\n\n` +
          `Total Products: ${products.length}\n` +
          `Catalog Value: $${totalValue.toFixed(2)}\n` +
          `Report Time: ${jobInstance.metadata.reportTime}`;
        
        const user = await jobInstance.user();
        await user.send([{ type: 'text', text: report }]);
        
        return {
          success: true,
          productCount: products.length,
          totalValue
        };
      }
    });
    
    return {
      success: true,
      message: `Daily report scheduled for ${input.timeOfDay}`,
      jobId: job.id
    };
  }
}
```

## Important: Metadata Pattern

<Warning>
  **Jobs execute functions must be self-contained!** They cannot access parent scope variables.
</Warning>

```typescript theme={null}
// ❌ WRONG - Accessing parent scope
async execute(input: any) {
  const userMessage = input.message;  // This variable...
  
  await Jobs.create({
    execute: async (job) => {
      // ...is NOT available here! ❌
      await user.send(userMessage);  // Error: userMessage is not defined
    }
  });
}

// ✅ CORRECT - Using metadata
async execute(input: any) {
  await Jobs.create({
    metadata: {
      message: input.message  // ✅ Pass via metadata
    },
    execute: async (job) => {
      const message = job.metadata.message;  // ✅ Access from metadata
      const user = await job.user();
      await user.send([{ type: 'text', text: message }]);
    }
  });
}
```

**Why?** Jobs are serialized, bundled, and executed in an isolated sandbox. They can't access the parent function's scope.

## JobInstance Methods

The `JobInstance` passed to execute functions provides:

### Properties

| Property        | Type                                                     | Description                                                                                                              |
| --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id`            | `string`                                                 | Unique job identifier                                                                                                    |
| `name`          | `string`                                                 | Job name                                                                                                                 |
| `activeVersion` | `JobVersion`                                             | The active version with schedule, timeout, etc.                                                                          |
| `metadata`      | `object`                                                 | Job metadata                                                                                                             |
| `data`          | `Job`                                                    | Full job data including all versions                                                                                     |
| `execution`     | `{ executionId, attempt, occurrenceId, scheduledTime? }` | Runtime execution metadata for the current run (see [Delivery Semantics](#delivery-semantics)). Undefined in local runs. |

### jobInstance.user()

Gets the user who triggered the job.

**Returns:** `Promise<UserDataInstance>`

<Note>
  **Automatic User Context:** This method is ONLY available for dynamic jobs created via `Jobs.create()`. The user context is automatically captured when the job is created from a tool. Pre-defined LuaJob must use `User.get(userId)` instead.
</Note>

**Example:**

```typescript theme={null}
// In a tool creating a dynamic job
await Jobs.create({
  execute: async (jobInstance) => {
    // ✅ Works! User context automatically available
    const user = await jobInstance.user();
    await user.send([{ type: 'text', text: 'Job complete!' }]);
  }
});
```

**Comparison with LuaJob:**

```typescript theme={null}
// ❌ This won't work in pre-defined LuaJob
const job = new LuaJob({
  execute: async (job) => {
    const user = await job.user();  // ❌ No user() method!
  }
});

// ✅ Use this for LuaJob instead
const job = new LuaJob({
  metadata: { userId: 'user_abc123' },
  execute: async (job) => {
    const user = await User.get(job.metadata.userId);  // ✅ Works!
  }
});
```

### job.metadata

Access to the metadata passed during creation.

**Example:**

```typescript theme={null}
execute: async (job) => {
  console.log(job.metadata.customData);
}
```

### job.updateMetadata(data)

Updates job metadata.

**Example:**

```typescript theme={null}
execute: async (job) => {
  await job.updateMetadata({
    lastRun: new Date().toISOString(),
    runCount: (job.metadata.runCount || 0) + 1
  });
}
```

### job.trigger(versionId?)

Manually triggers the job execution (ignores schedule). Uses the active version by default.

**Parameters:**

* `versionId` (optional): Specific version to execute. Defaults to `activeVersion`.

**Returns:** `Promise<JobExecution>`

**Example:**

```typescript theme={null}
// Trigger with default active version
const execution = await job.trigger();
console.log('Execution ID:', execution.id);
console.log('Status:', execution.status);

// Trigger with specific version
const execution = await job.trigger('version_abc123');
```

### job.delete()

Deletes the job (or deactivates if it has versions).

**Example:**

```typescript theme={null}
execute: async (job) => {
  // Do work...
  
  // Delete one-time job after execution
  await job.delete();
}
```

### job.activate()

Activates the job, enabling it to run on schedule.

**Returns:** `Promise<JobInstance>`

**Example:**

```typescript theme={null}
// Re-enable a paused job
const job = await Jobs.getJob('job_123');
await job.activate();
console.log('Job is now active');
```

### job.deactivate()

Deactivates the job, preventing it from running on schedule. Useful for jobs that should stop themselves.

**Returns:** `Promise<JobInstance>`

**Example:**

```typescript theme={null}
// Job stops itself when work is complete
execute: async (job) => {
  const data = await fetchData();
  
  if (data.isComplete) {
    // Stop the recurring job
    await job.deactivate();
    return { action: 'completed', stopped: true };
  }
  
  return { action: 'processed', data };
}
```

## Retry Configuration

```typescript theme={null}
await Jobs.create({
  name: 'important-task',
  
  retry: {
    maxAttempts: 3,
    backoffSeconds: 60  // Wait 60s between retries
  },
  
  execute: async (job) => {
    // If this throws, will retry up to 3 times
    await criticalOperation();
  }
});
```

## Delivery Semantics

Jobs run **at least once**. Each scheduled occurrence is durably queued and executed on isolated infrastructure, and a failed attempt is retried according to your [retry configuration](#retry-configuration). A job may therefore run **more than once** for a single scheduled occurrence, so keep side effects idempotent — guard them with your own state (for example, a flag in `metadata` or a record in [Data](/api/data)).

* Retries happen **only when an attempt fails**, using your `maxAttempts` and `backoffSeconds`.
* The platform caps attempts at **10** regardless of config — a higher `maxAttempts` is clamped to 10.

Each execution receives metadata on `job.execution`:

| Field           | Description                                                                                                                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `occurrenceId`  | Stable identifier for the logical occurrence — **the same value across every retry attempt**. Use it as your idempotency key so side effects run once per occurrence, no matter how many times it retries. |
| `executionId`   | Identifier for this individual attempt. **Changes on every retry** — do not use it for idempotency.                                                                                                        |
| `attempt`       | 1-based attempt counter (`1` on the first run, `2` on the first retry, and so on).                                                                                                                         |
| `scheduledTime` | For scheduled runs, the ISO-8601 fire time of the occurrence (a schedule-slot key). Absent for manually triggered runs.                                                                                    |

```typescript theme={null}
execute: async (job) => {
  const { occurrenceId, executionId, attempt } = job.execution ?? {};

  // Re-check your own state before repeating side effects
  if (attempt > 1) {
    console.log(`Retry ${attempt} of occurrence ${occurrenceId} (attempt id ${executionId})`);
  }

  // ...
}
```

<Note>
  `job.execution` is only present when a job runs on Lua's infrastructure. It is `undefined` during local `lua test` / `lua dev` runs, which execute in-process — so always read it optionally (`job.execution?.occurrenceId`).
</Note>

### Idempotency

Because a job runs **at least once**, design your side effects to be safe to repeat. The `occurrenceId` is stable across all retries of one occurrence, so it makes a natural idempotency key: record it after the side effect succeeds, and skip the work if you've already processed it. Attempts of one occurrence never run concurrently, so a simple check-then-write guard like the one below is safe.

```typescript theme={null}
execute: async (job) => {
  const occurrenceId = job.execution?.occurrenceId;

  // Skip if this occurrence's side effect already ran on an earlier attempt
  if (occurrenceId) {
    const done = await Data.get('processed_occurrences', { occurrenceId });
    if (done.data.length > 0) return;
  }

  await chargeCustomer();       // the side effect that must happen exactly once

  // Mark it processed so a later retry is a no-op
  if (occurrenceId) {
    await Data.create('processed_occurrences', { occurrenceId });
  }
}
```

<Note>
  Prefer `occurrenceId` over `executionId` for deduplication: `executionId` is re-minted on every retry, so keying on it would let each attempt's side effect through. For scheduled jobs you can instead key on `scheduledTime` when you want one run per schedule slot.
</Note>

## Timeout Configuration

```typescript theme={null}
await Jobs.create({
  name: 'long-running-task',
  timeout: 300,  // 5 minutes (seconds; supported range: 1-600)
  
  execute: async (job) => {
    // Will be terminated if exceeds 5 minutes
    await longOperation();
  }
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Use Unique Names">
    Give each job a descriptive, unique name

    ```typescript theme={null}
    name: `reminder-${Date.now()}`
    name: `followup-ticket-${ticketId}`
    ```
  </Accordion>

  <Accordion title="✅ Pass Data via Metadata">
    Always use metadata to pass data to execute function

    ```typescript theme={null}
    metadata: {
      userId: input.userId,
      message: input.message,
      timestamp: new Date().toISOString()
    }
    ```
  </Accordion>

  <Accordion title="✅ Handle Errors Gracefully">
    Implement error handling in execute function

    ```typescript theme={null}
    execute: async (job) => {
      try {
        await doWork();
        return { success: true };
      } catch (error) {
        return { success: false, error: error.message };
      }
    }
    ```
  </Accordion>

  <Accordion title="❌ Don't Access Parent Scope">
    Execute functions are isolated - use metadata!

    ```typescript theme={null}
    // ❌ This won't work
    const data = input.value;
    execute: async (job) => {
      console.log(data); // Error!
    }

    // ✅ Use metadata instead
    metadata: { data: input.value },
    execute: async (job) => {
      console.log(job.metadata.data); // Works!
    }
    ```
  </Accordion>
</AccordionGroup>

<Note title="Debugging tip">
  If a job isn't behaving as expected, add `console.log` statements and check execution logs:

  ```typescript theme={null}
  execute: async (jobInstance) => {
    const data = await Data.get('orders', { status: 'pending' });
    console.log(`[Job] Found ${data.data.length} pending orders`);
    // ... rest of job
  }
  ```

  Then check: `lua logs --type job --name my-job-name --limit 10`. See the [Debugging Skills guide](/cli/debugging) for the full workflow.
</Note>

## Related APIs

<CardGroup>
  <Card title="LuaJob" href="/api/luajob" icon="clock">
    Pre-defined scheduled jobs
  </Card>

  <Card title="User API" href="/api/user" icon="user">
    Send messages from jobs
  </Card>

  <Card title="Data API" href="/api/data" icon="database">
    Store and retrieve data
  </Card>

  <Card title="LuaAgent" href="/api/luaagent" icon="robot">
    Agent configuration
  </Card>

  <Card title="Debugging Skills" href="/cli/debugging" icon="bug">
    Inspect runtime return values
  </Card>
</CardGroup>

## See Also

* [LuaJob Class](/api/luajob) - Pre-defined jobs
* [Tool Examples](/examples/overview)
* [Concepts: Workflows](/concepts/workflows)


# Lua API
Source: https://docs.heylua.ai/api/lua

Access request-level runtime information in your code

## Overview

The `Lua` API provides access to request-level runtime information. Use it in your tools, tool conditions, preprocessors, and postprocessors to access context about the current request.

```typescript theme={null}
import { Lua } from 'lua-cli';

// Access the current channel
const channel = Lua.request.channel;

if (channel === 'whatsapp') {
  // WhatsApp-specific logic
}
```

## Import

```typescript theme={null}
import { Lua, Channel } from 'lua-cli';
```

## Availability

The `Lua` API is available in:

| Context                     | Available |
| --------------------------- | --------- |
| **Tool `execute`**          | ✅ Yes     |
| **Tool `condition`**        | ✅ Yes     |
| **Skill `condition`**       | ✅ Yes     |
| **Preprocessor `execute`**  | ✅ Yes     |
| **Postprocessor `execute`** | ✅ Yes     |

## Lua.request

The `request` object contains information about the current request context.

### channel

The channel through which the current request originated.

```typescript theme={null}
Lua.request.channel: Channel
```

**Type:** `Channel`

```typescript theme={null}
type Channel =
  | 'web'         // Chat widget on a website
  | 'whatsapp'    // WhatsApp integration
  | 'facebook'    // Facebook Messenger integration
  | 'instagram'   // Instagram integration
  | 'slack'       // Slack integration
  | 'teams'       // Microsoft Teams integration
  | 'front'       // Front integration
  | 'messagebird' // MessageBird integration
  | 'api'         // Direct HTTP API call
  | 'dev'         // Local development / CLI testing
  | 'email'       // Email integration
  | string;       // Any other channel
```

**Example - Channel-specific behavior:**

```typescript theme={null}
import { Lua } from 'lua-cli';

const channel = Lua.request.channel;

switch (channel) {
  case 'whatsapp':
    // Keep responses concise for mobile
    return { format: 'brief' };
  case 'web':
    // Can use rich formatting
    return { format: 'rich' };
  case 'api':
    // Return structured data
    return { format: 'json' };
  default:
    return { format: 'standard' };
}
```

### webhook

The webhook object contains information about the incoming webhook request from channel integrations. This provides access to the original data sent by the channel provider (WhatsApp, Slack, Teams, etc.).

```typescript theme={null}
Lua.request.webhook: { payload: any } | undefined
```

**Type:** `{ payload: any } | undefined`

The webhook object is only available when the request originated from a webhook-based channel. For direct API calls or the web chat widget, this will be `undefined`.

#### webhook.payload

The raw, unmodified webhook payload from the channel provider.

**Available for channels:**

* `whatsapp` - Full WhatsApp Cloud API webhook payload
* `slack` - Slack Events API payload
* `teams` - Microsoft Teams activity object
* `front` - Front webhook body
* `facebook` - Facebook Messenger webhook event
* `instagram` - Instagram Messaging webhook event
* `messagebird` - MessageBird webhook body
* `email` - JMAP-aligned parsed email (headers + envelope; not raw MIME — see note below)

**Example - Accessing WhatsApp webhook data:**

```typescript theme={null}
import { Lua } from 'lua-cli';

const webhook = Lua.request.webhook;

if (Lua.request.channel === 'whatsapp' && webhook) {
  // Access WhatsApp-specific data
  const entry = webhook.payload.entry?.[0];
  const value = entry?.changes?.[0]?.value;
  const messageId = value?.messages?.[0]?.id;
  const phoneNumberId = value?.metadata?.phone_number_id;
  
  return {
    messageId,
    phoneNumberId,
    raw: webhook.payload,
  };
}
```

**Example - Slack event data:**

```typescript theme={null}
import { Lua } from 'lua-cli';

const webhook = Lua.request.webhook;

if (Lua.request.channel === 'slack' && webhook) {
  const event = webhook.payload.event;
  const teamId = webhook.payload.team_id;
  const channelId = event?.channel;
  
  return {
    teamId,
    channelId,
    eventType: event?.type,
  };
}
```

**Example - Teams activity:**

```typescript theme={null}
import { Lua } from 'lua-cli';

const webhook = Lua.request.webhook;

if (Lua.request.channel === 'teams' && webhook) {
  const activity = webhook.payload;
  const conversationId = activity.conversation?.id;
  const tenantId = activity.conversation?.tenantId;
  const serviceUrl = activity.serviceUrl;
  
  return {
    conversationId,
    tenantId,
    serviceUrl,
  };
}
```

**Example - Email metadata:**

```typescript theme={null}
import { Lua } from 'lua-cli';

const webhook = Lua.request.webhook;

if (Lua.request.channel === 'email' && webhook) {
  const {
    messageId,        // bare ID, no <angle brackets>
    inReplyTo,        // bare ID, or null
    references,       // array of bare IDs
    subject,
    from,             // [{ address, name }]
    to,
    cc,
    date,             // ISO 8601 string
    headerLines,      // [{ key, line }] — full ordered RFC 5322 header list
  } = webhook.payload;

  const isReply = !!inReplyTo;
  const threadRoot = references?.[0] ?? messageId;

  return { messageId, isReply, threadRoot, subject };
}
```

<Note>
  The `email` channel's payload differs from JSON-over-HTTP channels (WhatsApp, Slack, etc.). Email arrives over SMTP as RFC 5322 MIME — there is no JSON envelope from a provider to forward. Lua parses the message and exposes it as a [JMAP](https://datatracker.ietf.org/doc/html/rfc8621#section-4)-aligned object: typed common headers plus a `headerLines` array preserving the full RFC 5322 header order.
</Note>

<Note>
  If your email channel is backed by an AgentMail inbox, `webhook.payload` follows AgentMail's native event shape (`message_id`, `thread_id`, `inbox_id`, …) rather than the JMAP shape above. Branch on the presence of `messageId` (Lua-native) vs `message_id` (AgentMail) until the shapes are normalized.
</Note>

## Complete Examples

### Conditional Tool Availability

Make a tool available only on certain channels:

```typescript theme={null}
import { LuaTool, Lua } from 'lua-cli';
import { z } from 'zod';

export default class WhatsAppOnlyTool implements LuaTool {
  name = 'send_whatsapp_template';
  description = 'Send a WhatsApp message template';

  inputSchema = z.object({
    templateId: z.string(),
  });

  // Tool only shows up on WhatsApp
  condition = async () => {
    return Lua.request.channel === 'whatsapp';
  };

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Implementation
    return { success: true };
  }
}
```

### Channel-Aware Tool Logic

Adjust tool behavior based on channel:

```typescript theme={null}
import { LuaTool, Lua } from 'lua-cli';
import { z } from 'zod';

export default class GetSupportInfoTool implements LuaTool {
  name = 'get_support_info';
  description = 'Get customer support information';

  inputSchema = z.object({});

  async execute() {
    const channel = Lua.request.channel;

    const baseInfo = {
      email: 'support@example.com',
      hours: '9 AM - 5 PM EST',
    };

    // Add channel-specific info
    switch (channel) {
      case 'whatsapp':
        return {
          ...baseInfo,
          message: 'You can also reply here for quick support!',
        };
      case 'web':
        return {
          ...baseInfo,
          phone: '1-800-SUPPORT',
          liveChatUrl: 'https://example.com/chat',
        };
      default:
        return baseInfo;
    }
  }
}
```

### Preprocessor with Channel Context

Use channel in preprocessors:

```typescript theme={null}
import { PreProcessor, Lua } from 'lua-cli';

const channelGreeting = new PreProcessor({
  name: 'channel-greeting',
  description: 'Add channel-specific greeting context',
  priority: 1,
  execute: async (user, messages, channel) => {
    const currentChannel = Lua.request.channel;
    return { action: 'proceed' };
  },
});
```

### Postprocessor with Channel-Specific Formatting

Format responses based on channel:

```typescript theme={null}
import { PostProcessor, Lua } from 'lua-cli';

const formatForChannel = new PostProcessor({
  name: 'format-for-channel',
  description: 'Format response based on channel',
  execute: async (user, message, response, channel) => {
    const currentChannel = Lua.request.channel;

    // WhatsApp has character limits - truncate long responses
    if (currentChannel === 'whatsapp' && response.length > 4096) {
      return {
        modifiedResponse: response.substring(0, 4093) + '...',
      };
    }

    return { modifiedResponse: response };
  },
});
```

## Future Expansion

The `Lua` API will be expanded to include additional runtime information, such as:

* User profile data
* Session information
* More request metadata

<Note>
  This API is designed to grow. Check back for new properties as they become available.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Import from lua-cli">
    Always import the `Lua` API from `lua-cli`:

    ```typescript theme={null}
    import { Lua } from 'lua-cli';

    const channel = Lua.request.channel;
    ```
  </Accordion>

  <Accordion title="✅ Handle Unknown Channels">
    The channel type includes `unknown` for unrecognized values:

    ```typescript theme={null}
    const channel = Lua.request.channel;

    if (channel === 'whatsapp' || channel === 'web') {
      // Known channel handling
    } else {
      // Fallback for unknown channels
    }
    ```
  </Accordion>

  <Accordion title="✅ Keep Channel Logic Simple">
    Use channel for minor adjustments, not completely different flows:

    ```typescript theme={null}
    // ✅ Good - Minor adjustments
    const maxLength = channel === 'whatsapp' ? 4096 : 10000;

    // ❌ Avoid - Completely different tools per channel
    // Instead, use tool conditions to show/hide tools
    ```
  </Accordion>

  <Accordion title="✅ Use Tool Conditions for Availability">
    For channel-specific tools, use the `condition` function:

    ```typescript theme={null}
    condition = async () => {
      return Lua.request.channel === 'whatsapp';
    };
    ```

    `LuaSkill` accepts the same `condition` to gate a whole capability at once — see [Conditional Skills](/api/luaskill#conditional-skills).
  </Accordion>

  <Accordion title="✅ Check webhook Before Use">
    Always check if webhook exists before accessing it:

    ```typescript theme={null}
    const webhook = Lua.request.webhook;

    if (webhook) {
      // Safe to access webhook.payload properties
      const data = webhook.payload.entry?.[0]?.changes?.[0]?.value;
    }
    ```
  </Accordion>

  <Accordion title="✅ Combine Channel Check with webhook">
    For channel-specific webhook handling, always check both:

    ```typescript theme={null}
    if (Lua.request.channel === 'whatsapp' && Lua.request.webhook) {
      // WhatsApp-specific webhook handling
      const payload = Lua.request.webhook.payload;
    }
    ```
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Skills & Tools" href="/concepts/skills-and-tools" icon="wrench">
    Learn about creating tools with conditions
  </Card>

  <Card title="Preprocessors" href="/overview/preprocessors" icon="filter">
    Intercept and modify incoming messages
  </Card>

  <Card title="Postprocessors" href="/overview/postprocessors" icon="wand-magic-sparkles">
    Transform agent responses
  </Card>

  <Card title="Channels" href="/channels/introduction" icon="comments">
    Overview of available channels
  </Card>
</CardGroup>


# LuaAgent
Source: https://docs.heylua.ai/api/luaagent

Unified agent configuration combining skills, webhooks, jobs, and processors

## Overview

`LuaAgent` is the recommended way to configure your AI agent in modern lua-cli. It provides a single, intuitive configuration object that combines skills, webhooks, jobs, and message processors.

```typescript theme={null}
import { LuaAgent } from 'lua-cli';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: 'You are a helpful assistant...',
  skills: [skill1, skill2]
});
```

<Note>
  LuaAgent replaces the need to export individual skills, webhooks, and jobs separately.
</Note>

## Why LuaAgent?

<CardGroup>
  <Card title="Single Source of Truth" icon="bullseye">
    All agent components in one configuration object
  </Card>

  <Card title="Auto-Sync" icon="arrows-rotate">
    CLI auto-manages `lua.skill.yaml` (do not edit manually)
  </Card>

  <Card title="Better IDE Support" icon="code">
    Improved autocomplete and type safety
  </Card>

  <Card title="Clear Organization" icon="layer-group">
    Organized, readable agent configuration
  </Card>
</CardGroup>

## Constructor

### new LuaAgent(config)

Creates a new agent configuration.

<ParamField type="LuaAgentConfig">
  Agent configuration object
</ParamField>

## Configuration Parameters

### Required Fields

<ParamField type="string">
  Agent identifier used for organization and logging

  **Examples**: `'customer-support-agent'`, `'sales-assistant'`
</ParamField>

<ParamField type="string | { base?: string; voice?: string; text?: string }">
  Defines the agent's personality, behavior, tone, and capabilities

  **String form (recommended):**

  * Who the agent is
  * What role they play
  * How they should communicate
  * What they can and cannot do
  * Any specific behaviors or rules

  **Object form (channel-aware):** Only use when you need measurably different behavior on voice vs text channels.

  * `base` — Always rendered, on every channel
  * `voice` — Appended to `base` on voice channels, ignored on text
  * `text` — Appended to `base` on text channels (web, WhatsApp, SMS), ignored on voice

  See [Channel-aware Prompts](/concepts/channel-aware-prompts) for details.
</ParamField>

### Optional Fields

<ParamField type="string">
  Short capability summary used by [Spaces](/overview/spaces) to decide when to delegate to this agent

  One or two sentences about **what the agent can do** — around 200 characters. The persona still owns voice, tone and detailed instructions; this is only the routing signal a supervisor reads when choosing between member agents.

  **Example**: `'Handles refunds, returns and order cancellations for existing orders.'`

  Ownership is opt-in. Omit it and any description set in the admin dashboard is left untouched. Set it to an empty string to clear it.

  **Default**: unset — the platform falls back to deriving a summary from the persona
</ParamField>

<ParamField type="LuaSkill[]">
  Array of skills (tool collections) the agent can use

  **Default**: `[]`
</ParamField>

<ParamField type="LuaWebhook[]">
  HTTP endpoints that can receive external events

  **Default**: `[]`
</ParamField>

<ParamField type="LuaJob[]">
  Scheduled tasks that run automatically

  **Default**: `[]`
</ParamField>

<ParamField type="PreProcessor[]">
  Functions that process messages before they reach the agent

  **Default**: `[]`
</ParamField>

<ParamField type="PostProcessor[]">
  Functions that process agent responses before sending to users

  **Default**: `[]`
</ParamField>

<ParamField type="LuaMCPServer[]">
  MCP (Model Context Protocol) servers providing external tools

  **Default**: `[]`

  **See**: [LuaMCPServer API](/api/luamcpserver)
</ParamField>

<ParamField type="string | ((request: LuaRequest) => string | Promise<string>)">
  The LLM your agent uses. Either a static `'provider/model'` string or a resolver function
  that selects the model dynamically per request.

  **Format**: `'provider/model'` — e.g. `'google/gemini-2.5-flash'`, `'openai/gpt-4o'`

  **Default**: `'google/gemini-2.5-flash'`

  <Note>
    Lua manages the API credentials — you don't need to configure any API keys.
    Support for user-provided API keys is coming in a future release.
  </Note>

  **Static model:**

  ```typescript theme={null}
  model: 'openai/gpt-4o'
  ```

  **Dynamic resolver** — receives the full request with all platform APIs available (`User`, `Baskets`, `Products`, etc.):

  ```typescript theme={null}
  model: async (request) => {
    const user = await User.get();
    return user.data?.isPremium ? 'openai/gpt-4o' : 'google/gemini-2.5-flash';
  }
  ```

  **See**: [Model Selection](/overview/model-selection)
</ParamField>

<ParamField type="AgentModelSettings">
  Per-call sampling settings forwarded to the model on every chat turn.
  Set them once on the agent instead of overriding them in every skill via
  `AI.generate({ temperature })`. Undefined leaves provider defaults in
  place.

  ```typescript theme={null}
  import { LuaAgent, type AgentModelSettings } from 'lua-cli';

  export const agent = new LuaAgent({
    name: 'role-scorer',
    persona: '...',
    modelSettings: {
      temperature: 0.2,
      maxOutputTokens: 4096,
    },
    skills: [scoreRoleSkill],
  });
  ```

  **Supported fields:**

  | Field              | Type                 | Range / Notes                                                    |
  | ------------------ | -------------------- | ---------------------------------------------------------------- |
  | `temperature`      | `number`             | `0`–`2` (provider-dependent; typical for OpenAI / Anthropic)     |
  | `topP`             | `number`             | `0`–`1`. Set either `temperature` or `topP`, not both.           |
  | `topK`             | `number`             | Top-K sampling (advanced)                                        |
  | `maxOutputTokens`  | `number`             | Maximum tokens to generate                                       |
  | `presencePenalty`  | `number`             | `-2`–`2` (OpenAI; not all providers support)                     |
  | `frequencyPenalty` | `number`             | `-2`–`2` (OpenAI; not all providers support)                     |
  | `stopSequences`    | `string[]`           | Generation halts when the model emits one                        |
  | `seed`             | `number`             | Random seed for deterministic sampling (provider support varies) |
  | `reasoning`        | `{ effort?, show? }` | Default reasoning effort for this agent. See below.              |

  Obviously-broken values (non-finite numbers, `temperature` outside `0..2`,
  `topP` outside `0..1`, non-positive `maxOutputTokens`, non-string
  `stopSequences`, an unrecognized `reasoning.effort`, or a non-boolean
  `reasoning.show`) are rejected at construction time. Provider-specific
  range checks are deferred to the provider.

  **`reasoning` — per-agent default reasoning effort**

  Unlike the other fields, `reasoning` isn't a raw sampling parameter — it's a
  normalized setting Lua translates into each provider's own reasoning/thinking
  dialect, so the same config works whether the resolved model is Claude, GPT,
  Gemini, or another reasoning-capable model.

  ```typescript theme={null}
  export const agent = new LuaAgent({
    name: 'support-triage',
    persona: '...',
    modelSettings: {
      reasoning: { effort: 'low', show: false },
    },
    skills: [triageSkill],
  });
  ```

  | Sub-field | Type                                                         | Notes                                                                                                                                                                                                                                                                                                                                |
  | --------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `effort`  | `'off' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'max'` | How much the model reasons before responding. `'off'` disables reasoning where the provider allows it. Any of the 6 values is safe to send for any resolved model — Lua clamps it to that provider's nearest supported tier rather than erroring (e.g. a model with no "off" state falls back to its lowest supported tier instead). |
  | `show`    | `boolean`                                                    | Whether the model's reasoning trace is surfaced to the caller. Default `true`.                                                                                                                                                                                                                                                       |

  This is a **default for the agent** — a per-request `reasoning` override on
  the chat request always takes precedence over it, field by field (setting
  only `effort` on a request doesn't clear an agent-level `show: false`). If
  neither the request nor the agent sets an `effort`, Lua's platform default
  applies: **adaptive reasoning where the resolved model supports it** (Claude's
  newest generations, Gemini 2.5's dynamic thinking budget), and an **explicit
  low effort otherwise** — favoring lower cost and latency on turns that don't
  ask for deeper thinking. A few models deviate from that low default: GPT's
  top-tier reasoning variant has a medium floor (it doesn't accept anything
  lower), DeepSeek's reasoning model has no tier below high, and Qwen's
  reasoning is on/off only (no effort tiers).

  `reasoning` only affects reasoning behavior — it is not forwarded as a raw
  `modelSettings` field to the underlying call, so it never collides with
  provider-specific sampling parameters.
</ParamField>

## Basic Example

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';
import GetWeatherTool from './tools/GetWeatherTool';

const weatherSkill = new LuaSkill({
  name: 'weather-skill',
  description: 'Weather information',
  context: 'Use these tools to get weather data',
  tools: [new GetWeatherTool()]
});

export const agent = new LuaAgent({
  name: 'weather-assistant',
  persona: 'You are a friendly weather assistant. Provide weather information when asked.',
  skills: [weatherSkill]
});
```

## Complete Example

```typescript theme={null}
import { 
  LuaAgent, 
  LuaSkill, 
  LuaWebhook, 
  LuaJob,
  LuaMCPServer,
  PreProcessor,
  PostProcessor
} from 'lua-cli';

// Import your components
import { customerSupportSkill } from './skills/customer-support';
import { productSkill } from './skills/products';
import { orderSkill } from './skills/orders';
import paymentWebhook from './webhooks/payment';
import orderWebhook from './webhooks/order';
import dailyReportJob from './jobs/daily-report';
import cleanupJob from './jobs/cleanup';
import profanityFilter from './preprocessors/profanity-filter';
import addDisclaimer from './postprocessors/disclaimer';
import filesystemServer from './mcp/filesystem';

export const agent = new LuaAgent({
  name: 'ecommerce-assistant',

  description: 'Helps shoppers find products, manage carts and orders, and process returns for Acme Store.',

  persona: `You are Emma, a helpful e-commerce assistant for Acme Store.
  
Your role:
- Help customers find products
- Assist with orders and cart management
- Answer product questions
- Process returns and exchanges

Communication style:
- Friendly and professional
- Patient and understanding
- Proactive with suggestions
- Clear and concise

Capabilities:
- Search product catalog
- Manage shopping carts
- Track orders
- Process payments
- Answer product questions

Limitations:
- Cannot ship orders manually
- Cannot modify pricing (suggest contacting manager)
- Cannot issue refunds over $100 (requires manager approval)
`,

  skills: [
    customerSupportSkill,
    productSkill,
    orderSkill
  ],

  webhooks: [
    paymentWebhook,
    orderWebhook
  ],

  jobs: [
    dailyReportJob,
    cleanupJob
  ],

  preProcessors: [
    profanityFilter
  ],

  postProcessors: [
    addDisclaimer
  ],

  mcpServers: [
    filesystemServer
  ]
});
```

## Persona Best Practices

### ✅ Good Persona

```typescript theme={null}
persona: `You are Dr. Smith, a medical information assistant.

Role: Provide general health information and wellness tips.

Guidelines:
- Always clarify you're not a licensed doctor
- Recommend seeing professionals for serious concerns
- Use clear, non-technical language
- Be empathetic and supportive

Tone: Professional, caring, informative`
```

### ❌ Bad Persona

```typescript theme={null}
// Too vague
persona: `You are helpful`

// Too robotic
persona: `I am an AI assistant that answers questions.`

// Missing boundaries
persona: `You can do anything the user asks.`
```

## Persona Storage

Persona is stored in your `LuaAgent` code definition (in `src/index.ts`). The `lua.skill.yaml` file is state-only and tracks IDs and versions, not persona content.

When you edit persona using `lua persona`, it updates the persona field in your `LuaAgent` code directly.

## Multiple Skills Example

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

// Organize tools by domain
const weatherSkill = new LuaSkill({
  name: 'weather-skill',
  description: 'Weather tools',
  context: 'Use for weather queries',
  tools: [getWeatherTool, getForecastTool]
});

const calculatorSkill = new LuaSkill({
  name: 'calculator-skill',
  description: 'Math tools',
  context: 'Use for calculations',
  tools: [addTool, multiplyTool, advancedMathTool]
});

const dataSkill = new LuaSkill({
  name: 'data-skill',
  description: 'Data management',
  context: 'Use for storing and retrieving user data',
  tools: [saveDataTool, queryDataTool]
});

export const agent = new LuaAgent({
  name: 'multi-purpose-assistant',
  persona: 'You are a versatile assistant that helps with weather, calculations, and data management.',
  skills: [weatherSkill, calculatorSkill, dataSkill]
});
```

## With All Components

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import { skills } from './skills';
import { webhooks } from './webhooks';
import { jobs } from './jobs';
import { preProcessors } from './preprocessors';
import { postProcessors } from './postprocessors';
import { mcpServers } from './mcp';

export const agent = new LuaAgent({
  name: 'enterprise-assistant',
  
  persona: `You are an enterprise-grade AI assistant.
  - Professional and efficient
  - Data-driven and accurate
  - Proactive with insights
  - Security and privacy conscious`,
  
  skills: skills,
  webhooks: webhooks,
  jobs: jobs,
  preProcessors: preProcessors,
  postProcessors: postProcessors,
  mcpServers: mcpServers
});
```

## Dynamic Configuration

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import { env } from 'lua-cli';

// Load configuration from environment
const agentName = env('AGENT_NAME') || 'default-agent';
const customPersona = env('AGENT_PERSONA') || 'You are a helpful assistant';

// Conditionally add components
const skills = [coreSkill];
if (env('ENABLE_ANALYTICS') === 'true') {
  skills.push(analyticsSkill);
}

export const agent = new LuaAgent({
  name: agentName,
  persona: customPersona,
  skills: skills,
  // Add webhooks only in production
  webhooks: env('NODE_ENV') === 'production' ? productionWebhooks : []
});
```

## Migration from v2.x

**Before (v2.x):**

```typescript theme={null}
// Multiple exports
export const skill1 = new LuaSkill({...});
export const skill2 = new LuaSkill({...});
export const webhook1 = new LuaWebhook({...});
```

**After:**

```typescript theme={null}
// Single export with LuaAgent
export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [skill1, skill2],
  webhooks: [webhook1]
});
```

## Related APIs

<CardGroup>
  <Card title="LuaSkill" href="/api/luaskill" icon="puzzle-piece">
    Tool collections
  </Card>

  <Card title="LuaTool" href="/api/luatool" icon="wrench">
    Individual tools
  </Card>

  <Card title="LuaWebhook" href="/api/luawebhook" icon="webhook">
    HTTP endpoints
  </Card>

  <Card title="LuaJob" href="/api/luajob" icon="clock">
    Scheduled tasks
  </Card>

  <Card title="LuaMCPServer" href="/api/luamcpserver" icon="plug">
    External MCP tools
  </Card>
</CardGroup>

## See Also

* [Quick Start Guide](/getting-started/quick-start)
* [First Skill Tutorial](/getting-started/first-skill)
* [Skills and Tools Concept](/concepts/skills-and-tools)


# DeviceClient API
Source: https://docs.heylua.ai/api/luadeviceclient

Complete API reference for the @lua-ai-global/device-client package

## DeviceClient

The main class for connecting a device to a Lua AI agent. Extends `EventEmitter`.

```typescript theme={null}
import { DeviceClient } from '@lua-ai-global/device-client';

const client = new DeviceClient(config: DeviceClientConfig);
```

### Constructor

<ParamField type="DeviceClientConfig">
  Configuration object for the device client. See [DeviceClientConfig](#deviceclientconfig) below.
</ParamField>

## DeviceClientConfig

At least one credential field, `deviceCredential` or `apiKey`, is required.

<ParamField type="string">
  Agent ID to connect to.
</ParamField>

<ParamField type="string">
  Device credential for new provisioning. See [Device credentials](/devices/credentials).
</ParamField>

<ParamField type="string">
  Existing compatibility field, supported indefinitely. Non-dotted legacy keys also remain valid indefinitely.
</ParamField>

<ParamField type="string">
  Unique name for this device. Lowercase with hyphens.
</ParamField>

<ParamField type="DeviceCommandDefinition[]">
  Commands this device supports. Sent to the server at connect time.
</ParamField>

<ParamField type="'socketio' | 'mqtt'">
  Transport protocol.
</ParamField>

<ParamField type="string">
  Server URL for Socket.IO transport.
</ParamField>

<ParamField type="string">
  MQTT broker URL. Required when `transport` is `'mqtt'`.
</ParamField>

<ParamField type="string">
  CDN URL for file uploads and downloads.
</ParamField>

<ParamField type="string">
  Optional device group name.
</ParamField>

Provide either credential field. If you provide both, their values must match.

## Methods

### connect()

Connect to the device gateway. Resolves when the connection is established and authenticated. Automatically reconnects on disconnect unless `disconnect()` was called.

```typescript theme={null}
await client.connect(): Promise<void>
```

### disconnect()

Disconnect from the device gateway. Stops auto-reconnection.

```typescript theme={null}
await client.disconnect(): Promise<void>
```

### isConnected()

Check if the client is currently connected.

```typescript theme={null}
client.isConnected(): boolean
```

### onCommand()

Register a handler for a specific command name. The handler receives the command payload and must return a result (or throw an error).

```typescript theme={null}
client.onCommand(name: string, handler: CommandHandler): void
```

<ParamField type="string">
  Command name to handle.
</ParamField>

<ParamField type="(payload: any) => Promise<any>">
  Async function that executes the command. Return value is sent back to the agent. Thrown errors are sent as error responses.
</ParamField>

```typescript theme={null}
client.onCommand('read_temperature', async (payload) => {
  return { temperature: 22.5, unit: 'celsius' };
});
```

### trigger()

Fire a trigger event to the agent. Resolves when the server acknowledges receipt (not execution completion).

```typescript theme={null}
await client.trigger(name: string, payload: any): Promise<DeviceTriggerAckMessage>
```

<ParamField type="string">
  Trigger name.
</ParamField>

<ParamField type="any">
  Trigger payload data.
</ParamField>

```typescript theme={null}
await client.trigger('temperature_alert', {
  temperature: 42.1,
  threshold: 40,
});
```

### onTriggerResult()

Listen for trigger execution results from the agent. Optional -- triggers are fire-and-forget by default.

```typescript theme={null}
client.onTriggerResult(name: string, handler: TriggerResultHandler): void
```

<ParamField type="string">
  Trigger name to listen for.
</ParamField>

<ParamField type="(result: any) => void">
  Callback function receiving the trigger execution result.
</ParamField>

## Properties

### cdn

CDN client for uploading and downloading files. Available immediately after construction.

```typescript theme={null}
client.cdn: CDN
```

## CDN

The CDN class provides file upload and download capabilities.

### cdn.upload()

Upload a file to the Lua CDN.

```typescript theme={null}
await client.cdn.upload(
  data: Buffer | Blob,
  filename: string,
  contentType?: string
): Promise<CdnUploadResult>
```

<ParamField type="Buffer | Blob">
  File content.
</ParamField>

<ParamField type="string">
  Filename with extension.
</ParamField>

<ParamField type="string">
  MIME type. Defaults to `application/octet-stream`.
</ParamField>

**Returns:** `CdnUploadResult`

```typescript theme={null}
interface CdnUploadResult {
  fileId: string;
  mediaType: string;
  extension: string;
  url: string;
}
```

### cdn.download()

Download a file from the CDN.

```typescript theme={null}
await client.cdn.download(fileId: string): Promise<Buffer>
```

### cdn.getUrl()

Get the public URL for a file.

```typescript theme={null}
client.cdn.getUrl(fileId: string): string
```

## Events

The `DeviceClient` extends `EventEmitter` and emits the following events:

| Event           | Payload                   | Description                    |
| --------------- | ------------------------- | ------------------------------ |
| `connected`     | *(none)*                  | Initial connection established |
| `reconnected`   | *(none)*                  | Reconnected after a disconnect |
| `disconnected`  | `reason: string`          | Connection lost                |
| `error`         | `error: any`              | Connection or protocol error   |
| `trigger_ack`   | `DeviceTriggerAckMessage` | Server acknowledged a trigger  |
| `trigger_error` | `error: any`              | Trigger delivery error         |

```typescript theme={null}
client.on('connected', () => console.log('Online'));
client.on('disconnected', (reason) => console.log('Offline:', reason));
client.on('error', (err) => console.error('Error:', err));
```

## DeviceCommandDefinition

Describes a command the device supports.

<ParamField type="string">
  Command name.
</ParamField>

<ParamField type="string">
  Human-readable description shown to the AI agent.
</ParamField>

<ParamField type="Record<string, any>">
  JSON Schema for input parameters.
</ParamField>

<ParamField type="number">
  Command timeout in milliseconds.
</ParamField>

<ParamField type="{ maxAttempts: number; backoffMs: number }">
  Retry configuration for failed commands.
</ParamField>

## Type Exports

The package exports the following types:

```typescript theme={null}
import type {
  DeviceClientConfig,
  DeviceCommandDefinition,
  DeviceCommandMessage,
  DeviceResponseMessage,
  DeviceTriggerAckMessage,
  CommandHandler,
  TriggerResultHandler,
} from '@lua-ai-global/device-client';

import type { CdnUploadResult } from '@lua-ai-global/device-client';
```

## Next Steps

<CardGroup>
  <Card title="Node.js Client Guide" icon="node-js" href="/devices/node-client">
    Usage guide with examples
  </Card>

  <Card title="MicroPython Client" icon="microchip" href="/devices/micropython-client">
    API reference for the MicroPython client
  </Card>

  <Card title="Quickstart" icon="rocket" href="/devices/quickstart">
    Get started in 5 minutes
  </Card>

  <Card title="Examples" icon="layer-group" href="/devices/examples/warehouse-inventory">
    Full working examples
  </Card>
</CardGroup>


# LuaJob
Source: https://docs.heylua.ai/api/luajob

Pre-defined scheduled tasks that run automatically

## Overview

`LuaJob` allows you to define scheduled tasks that run automatically without user interaction. Unlike the Jobs API which creates jobs dynamically, LuaJob is for pre-defined jobs that are part of your agent configuration.

```typescript theme={null}
import { LuaJob, User } from 'lua-cli';

const dailyReport = new LuaJob({
  name: 'daily-sales-report',
  description: 'Generate daily sales summary',
  metadata: {
    userId: 'user_abc123'  // Store user ID to notify
  },
  schedule: {
    type: 'cron',
    expression: '0 9 * * *'  // Every day at 9 AM
  },
  execute: async (job) => {
    // Generate report
    const report = await generateSalesReport();
    
    // ⚠️ Pre-defined jobs have NO conversational context
    // Get user by ID from metadata
    const user = await User.get(job.metadata.userId);
    await user.send([{
      type: 'text',
      text: report
    }]);
  }
});
```

<Warning>
  **No Conversational Context:** LuaJob executes outside of user conversations. You MUST use `User.get(userId)` with a userId from metadata. The job does NOT have `jobInstance.user()` - that's only for dynamic jobs.
</Warning>

<Note>
  Pre-defined jobs that are part of your agent configuration. Use with LuaAgent.
</Note>

## When to Use

<CardGroup>
  <Card title="LuaJob (Pre-defined)" icon="calendar">
    For scheduled tasks defined at agent setup

    * Daily reports
    * Weekly summaries
    * Cleanup tasks
    * Monitoring jobs

    **User access:** `User.get(userId)` from metadata
  </Card>

  <Card title="Jobs API (Dynamic)" icon="plus">
    For tasks created on-demand from tools

    * User reminders
    * Follow-ups
    * One-time notifications
    * Context-specific tasks

    **User access:** `jobInstance.user()` (automatic!)
  </Card>
</CardGroup>

<Warning>
  **Key Difference:** Pre-defined LuaJob has NO user context. Use `User.get(userId)` with ID from metadata. Dynamic jobs (Jobs API) automatically have user context via `jobInstance.user()`.
</Warning>

## Comparison: LuaJob vs Jobs API

Understanding user access in different job types:

| Feature              | LuaJob (Pre-defined)    | Jobs API (Dynamic)   |
| -------------------- | ----------------------- | -------------------- |
| **When Defined**     | At agent setup          | Runtime, from tools  |
| **User Context**     | ❌ None                  | ✅ Automatic          |
| **Get User**         | `User.get(userId)`      | `jobInstance.user()` |
| **userId Required?** | ✅ Yes (from metadata)   | ❌ No (automatic)     |
| **Use Case**         | Regular scheduled tasks | User-triggered tasks |

**Example - Pre-defined LuaJob:**

```typescript theme={null}
const job = new LuaJob({
  metadata: { userId: 'user_abc123' },  // ← Store userId
  execute: async (job) => {
    const user = await User.get(job.metadata.userId);  // ← Required
  }
});
```

**Example - Dynamic Job (Jobs API):**

```typescript theme={null}
await Jobs.create({
  execute: async (jobInstance) => {
    const user = await jobInstance.user();  // ← Automatic!
  }
});
```

## Constructor

### new LuaJob(config)

Creates a new pre-defined job.

<ParamField type="LuaJobConfig">
  Job configuration object
</ParamField>

## Configuration Parameters

### Required Fields

<ParamField type="string">
  Unique job name

  **Format**: lowercase, hyphens, underscores

  **Examples**: `'daily-report'`, `'weekly-cleanup'`
</ParamField>

<ParamField type="JobSchedule">
  When and how often the job runs
</ParamField>

<ParamField type="function">
  Function that runs when the job triggers

  **Signature:** `(job: JobInstance) => Promise<any>`
</ParamField>

### Optional Fields

<ParamField type="string">
  Job description for documentation
</ParamField>

<ParamField type="object">
  Static metadata available to execute function
</ParamField>

<ParamField type="number">
  Maximum execution time in seconds

  **Default:** 300 (5 minutes)

  **Supported range:** 1–600 seconds. Values outside this range are rejected.
</ParamField>

<ParamField type="object">
  Retry configuration

  ```typescript theme={null}
  retry: {
    maxAttempts: number;
    backoffSeconds?: number;
  }
  ```
</ParamField>

<ParamField type="boolean">
  Whether job is active

  **Default:** true
</ParamField>

## Schedule Types

### Interval (Fixed intervals)

```typescript theme={null}
schedule: {
  type: 'interval',
  seconds: number
}
```

**Examples:**

```typescript theme={null}
// Every 5 minutes
schedule: {
  type: 'interval',
  seconds: 300
}

// Every hour
schedule: {
  type: 'interval',
  seconds: 3600
}

// Every day (86400 seconds)
schedule: {
  type: 'interval',
  seconds: 86400
}
```

### Cron (Cron patterns)

```typescript theme={null}
schedule: {
  type: 'cron',
  expression: string  // Standard cron expression
  timezone?: string   // Optional timezone (e.g., 'America/New_York')
}
```

**Examples:**

```typescript theme={null}
// Every day at 9 AM
schedule: {
  type: 'cron',
  expression: '0 9 * * *'
}

// Every Monday at 8 AM EST
schedule: {
  type: 'cron',
  expression: '0 8 * * 1',
  timezone: 'America/New_York'
}

// Every hour on the hour
schedule: {
  type: 'cron',
  expression: '0 * * * *'
}

// First day of every month at midnight
schedule: {
  type: 'cron',
  expression: '0 0 1 * *'
}
```

## Complete Examples

### Daily Sales Report

```typescript theme={null}
import { LuaJob, Products, User } from 'lua-cli';

const dailySalesReport = new LuaJob({
  name: 'daily-sales-report',
  description: 'Daily sales summary sent every morning',
  
  metadata: {
    userId: 'user_abc123',  // Store userId to send report to
    reportTime: '09:00',
    timezone: 'America/New_York'
  },
  
  schedule: {
    type: 'cron',
    expression: '0 9 * * *',  // Every day at 9 AM
    timezone: 'America/New_York'
  },
  
  execute: async (jobInstance) => {
    // Fetch sales data
    const products = await Products.get(1, 100);
    const totalValue = products.reduce((sum, p) => sum + (p.price || 0), 0);
    const topProducts = products.sort((a, b) => b.price - a.price).slice(0, 5);
    
    // Build report
    const report = `📊 Daily Sales Report\n\n` +
      `Date: ${new Date().toLocaleDateString()}\n` +
      `Total Products: ${products.length}\n` +
      `Catalog Value: $${totalValue.toFixed(2)}\n\n` +
      `Top 5 Products:\n` +
      topProducts.map(p => `- ${p.name}: $${p.price}`).join('\n');
    
    // ⚠️ Pre-defined jobs have NO user context
    // Get user by ID from metadata
    const user = await User.get(jobInstance.metadata.userId);
    await user.send([{
      type: 'text',
      text: report
    }]);
    
    return {
      success: true,
      productCount: products.length,
      totalValue,
      timestamp: new Date().toISOString()
    };
  }
});

export default dailySalesReport;
```

### Weekly Cleanup Job

```typescript theme={null}
import { LuaJob, Data, User } from 'lua-cli';

const weeklyCleanup = new LuaJob({
  name: 'weekly-cleanup',
  description: 'Clean up old data every Sunday',
  
  metadata: {
    adminUserId: 'user_admin123'  // Store admin userId to notify
  },
  
  schedule: {
    type: 'cron',
    expression: '0 0 * * 0'  // Every Sunday at midnight
  },
  
  execute: async (jobInstance) => {
    // Delete old entries (older than 30 days)
    const thirtyDaysAgo = new Date();
    thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
    
    const oldEntries = await Data.get('temp-data', 1000);
    let deletedCount = 0;
    
    for (const entry of oldEntries) {
      const createdAt = new Date(entry.createdAt);
      if (createdAt < thirtyDaysAgo) {
        await Data.delete('temp-data', entry.id);
        deletedCount++;
      }
    }
    
    // Send summary to admin
    // ⚠️ Pre-defined jobs have NO user context
    // Get user by ID from metadata
    const user = await User.get(jobInstance.metadata.adminUserId);
    await user.send([{
      type: 'text',
      text: `🧹 Weekly cleanup complete. Deleted ${deletedCount} old entries.`
    }]);
    
    return {
      success: true,
      deletedCount,
      timestamp: new Date().toISOString()
    };
  }
});

export default weeklyCleanup;
```

### Hourly Monitoring

```typescript theme={null}
import { LuaJob, env, User } from 'lua-cli';

const systemMonitor = new LuaJob({
  name: 'system-monitor',
  description: 'Monitor system health every hour',
  
  metadata: {
    alertThreshold: 90,
    checkInterval: 'hourly',
    adminUserId: 'user_admin123'  // Store admin userId for alerts
  },
  
  schedule: {
    type: 'interval',
    seconds: 3600  // Every hour
  },
  
  execute: async (jobInstance) => {
    // Check external API health
    try {
      const response = await fetch(`${env('API_URL')}/health`);
      const health = await response.json();
      
      // Alert if threshold exceeded
      if (health.cpuUsage > jobInstance.metadata.alertThreshold) {
        // ⚠️ Pre-defined jobs have NO user context
        // Get user by ID from metadata
        const user = await User.get(jobInstance.metadata.adminUserId);
        await user.send([{
          type: 'text',
          text: `⚠️ Alert: CPU usage is ${health.cpuUsage}%`
        }]);
      }
      
      return {
        success: true,
        cpuUsage: health.cpuUsage,
        memoryUsage: health.memoryUsage,
        timestamp: new Date().toISOString()
      };
    } catch (error) {
      // Alert on failure
      const user = await User.get(jobInstance.metadata.adminUserId);
      await user.send([{
        type: 'text',
        text: `🚨 System monitor failed: ${error.message}`
      }]);
      
      return {
        success: false,
        error: error.message,
        timestamp: new Date().toISOString()
      };
    }
  },
  
  retry: {
    maxAttempts: 3,
    backoffSeconds: 60
  }
});

export default systemMonitor;
```

### Reminders with Metadata

```typescript theme={null}
import { LuaJob, Data, User } from 'lua-cli';

const userReminders = new LuaJob({
  name: 'check-reminders',
  description: 'Check and send due reminders every 5 minutes',
  
  schedule: {
    type: 'interval',
    seconds: 300  // Every 5 minutes
  },
  
  execute: async (jobInstance) => {
    // Get reminders due now
    const now = new Date();
    const reminders = await Data.get('reminders', 100);
    let sentCount = 0;
    
    for (const reminder of reminders) {
      const dueTime = new Date(reminder.data.dueAt);
      
      if (dueTime <= now && !reminder.data.sent) {
        // ⚠️ Pre-defined jobs have NO user context
        // Each reminder must store the userId to send to
        const user = await User.get(reminder.data.userId);
        await user.send([{
          type: 'text',
          text: `⏰ Reminder: ${reminder.data.message}`
        }]);
        
        // Mark as sent
        await Data.update('reminders', reminder.id, {
          ...reminder.data,
          sent: true,
          sentAt: now.toISOString()
        });
        
        sentCount++;
      }
    }
    
    return {
      success: true,
      checked: reminders.length,
      sent: sentCount,
      timestamp: now.toISOString()
    };
  }
});

export default userReminders;
```

## Using with LuaAgent

Jobs are added to your agent configuration:

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import dailySalesReport from './jobs/daily-sales-report';
import weeklyCleanup from './jobs/weekly-cleanup';
import systemMonitor from './jobs/system-monitor';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [...],
  
  jobs: [
    dailySalesReport,
    weeklyCleanup,
    systemMonitor
  ]
});
```

## JobInstance API

The execute function receives a `JobInstance` with these properties and methods:

### Properties

| Property        | Type                                                     | Description                                                                                                              |
| --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id`            | `string`                                                 | Unique job identifier                                                                                                    |
| `name`          | `string`                                                 | Job name                                                                                                                 |
| `activeVersion` | `JobVersion`                                             | The active version with schedule, timeout, etc.                                                                          |
| `metadata`      | `object`                                                 | Job metadata                                                                                                             |
| `data`          | `Job`                                                    | Full job data including all versions                                                                                     |
| `execution`     | `{ executionId, attempt, occurrenceId, scheduledTime? }` | Runtime execution metadata for the current run (see [Delivery Semantics](#delivery-semantics)). Undefined in local runs. |

### jobInstance.user()

Get the user associated with the job.

**Returns:** `Promise<UserDataInstance>`

```typescript theme={null}
const user = await jobInstance.user();
await user.send([{ type: 'text', text: 'Message' }]);
```

### jobInstance.metadata

Access job metadata.

```typescript theme={null}
const threshold = jobInstance.metadata.alertThreshold;
```

### jobInstance.updateMetadata(data)

Update job metadata dynamically.

```typescript theme={null}
await jobInstance.updateMetadata({
  lastRun: new Date().toISOString(),
  runCount: (jobInstance.metadata.runCount || 0) + 1
});
```

### jobInstance.trigger(versionId?)

Manually triggers the job execution (ignores schedule). Uses the active version by default.

**Parameters:**

* `versionId` (optional): Specific version to execute. Defaults to `activeVersion`.

**Returns:** `Promise<JobExecution>`

```typescript theme={null}
// Trigger with default active version
const execution = await jobInstance.trigger();
console.log('Execution ID:', execution.id);

// Trigger with specific version
const execution = await jobInstance.trigger('version_abc123');
```

### jobInstance.delete()

Delete the job (or deactivates if it has versions).

```typescript theme={null}
// Self-terminate after condition met
if (conditionMet) {
  await jobInstance.delete();
}
```

## Delivery Semantics

Jobs run **at least once**. Each scheduled occurrence is durably queued and executed on isolated infrastructure, and a failed attempt is retried according to the job's `retry` configuration (`maxAttempts`, `backoffSeconds`). A job may therefore run **more than once** for a single scheduled occurrence, so keep side effects idempotent — guard them with your own state (for example, a flag in `metadata` or a record in [Data](/api/data)).

* Retries happen **only when an attempt fails**, using your `maxAttempts` and `backoffSeconds`.
* The platform caps attempts at **10** regardless of config — a higher `maxAttempts` is clamped to 10.

Each execution receives metadata on `job.execution`:

| Field           | Description                                                                                                                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `occurrenceId`  | Stable identifier for the logical occurrence — **the same value across every retry attempt**. Use it as your idempotency key so side effects run once per occurrence, no matter how many times it retries. |
| `executionId`   | Identifier for this individual attempt. **Changes on every retry** — do not use it for idempotency.                                                                                                        |
| `attempt`       | 1-based attempt counter (`1` on the first run, `2` on the first retry, and so on).                                                                                                                         |
| `scheduledTime` | For scheduled runs, the ISO-8601 fire time of the occurrence (a schedule-slot key). Absent for manually triggered runs.                                                                                    |

```typescript theme={null}
execute: async (job) => {
  const { occurrenceId, executionId, attempt } = job.execution ?? {};

  // Re-check your own state before repeating side effects
  if (attempt > 1) {
    console.log(`Retry ${attempt} of occurrence ${occurrenceId} (attempt id ${executionId})`);
  }

  // ...
}
```

<Note>
  `job.execution` is only present when a job runs on Lua's infrastructure. It is `undefined` during local `lua test` / `lua dev` runs, which execute in-process — so always read it optionally (`job.execution?.occurrenceId`).
</Note>

### Idempotency

Because a job runs **at least once**, design your side effects to be safe to repeat. The `occurrenceId` is stable across all retries of one occurrence, so it makes a natural idempotency key: record it after the side effect succeeds, and skip the work if you've already processed it. Attempts of one occurrence never run concurrently, so a simple check-then-write guard like the one below is safe.

```typescript theme={null}
execute: async (job) => {
  const occurrenceId = job.execution?.occurrenceId;

  // Skip if this occurrence's side effect already ran on an earlier attempt
  if (occurrenceId) {
    const done = await Data.get('processed_occurrences', { occurrenceId });
    if (done.data.length > 0) return;
  }

  await chargeCustomer();       // the side effect that must happen exactly once

  // Mark it processed so a later retry is a no-op
  if (occurrenceId) {
    await Data.create('processed_occurrences', { occurrenceId });
  }
}
```

<Note>
  Prefer `occurrenceId` over `executionId` for deduplication: `executionId` is re-minted on every retry, so keying on it would let each attempt's side effect through. For scheduled jobs you can instead key on `scheduledTime` when you want one run per schedule slot.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Choose Appropriate Schedule">
    Use cron for specific times, interval for regular checks

    ```typescript theme={null}
    // ✅ Cron for specific times
    schedule: { type: 'cron', expression: '0 9 * * *' }  // 9 AM daily

    // ✅ Interval for regular polling
    schedule: { type: 'interval', seconds: 300 }  // Every 5 min
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Jobs should not throw - return error status instead

    ```typescript theme={null}
    execute: async (job) => {
      try {
        await doWork();
        return { success: true };
      } catch (error) {
        console.error('Job failed:', error);
        return { success: false, error: error.message };
      }
    }
    ```
  </Accordion>

  <Accordion title="Use Retry for Critical Jobs">
    Configure retries for important operations

    ```typescript theme={null}
    retry: {
      maxAttempts: 3,
      backoffSeconds: 60  // Retry after 1 minute
    }
    ```
  </Accordion>

  <Accordion title="Keep Jobs Fast">
    Set appropriate timeouts and avoid long-running operations

    ```typescript theme={null}
    timeout: 120,  // 2 minutes max (in seconds)
    ```
  </Accordion>
</AccordionGroup>

## Cron Pattern Reference

```
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (0 = Sunday)
│ │ │ │ │
* * * * *
```

**Common Patterns:**

* `0 * * * *` - Every hour on the hour
* `0 9 * * *` - Every day at 9 AM
* `0 9 * * 1` - Every Monday at 9 AM
* `0 0 1 * *` - First day of every month at midnight
* `*/15 * * * *` - Every 15 minutes
* `0 9-17 * * 1-5` - 9 AM to 5 PM, Monday to Friday

## Invoking an Agent from a Pre-defined Job

Use `Agents.invoke` to delegate work to a conversational agent from inside a scheduled job. Pre-defined jobs have no ambient user, so pass a `userId` when you have one (e.g. from job metadata). When no `userId` is available, omit it and the invocation runs without user identity — no conversation history is stored.

<Tip>
  Use `Agents.invoke` here instead of calling `/chat/generate` or `/chat/stream` with `fetch`. The runtime handles agent invocation authentication, so a job does not need an API base URL or bearer token.
</Tip>

<Warning>
  To invoke the same agent that owns the job, pass that agent's ID as the first argument. Self-invocation is supported, but the runtime does not currently provide a `self` sentinel or ambient current-agent ID. Reusable templates must therefore still configure the deployed agent ID. If the invoked turn uses `User.get()`, `User.send()`, or another user-scoped tool, also pass a real `userId`; the job cannot infer the installer or recipient.
</Warning>

```typescript theme={null}
import { LuaJob, Agents, User } from 'lua-cli';

// With a known user — invocation runs in their context
const userReminderJob = new LuaJob({
  name: 'weekly-summary',
  schedule: { type: 'cron', expression: '0 9 * * 1' },
  metadata: { userId: 'user_abc123' },

  execute: async (job) => {
    const result = await Agents.invoke('summary-agent', {
      prompt: 'Generate the weekly activity summary for this user.',
      userId: job.metadata.userId, // conversation history stored for this user
    });

    const user = await User.get(job.metadata.userId);
    await user.send([{ type: 'text', text: result.text }]);
    return { sent: true };
  },
});

// Without a user — no conversation history stored
const dailyDigestJob = new LuaJob({
  name: 'daily-digest-generator',
  schedule: { type: 'cron', expression: '0 6 * * *' },

  execute: async (job) => {
    const result = await Agents.invoke('digest-agent', {
      prompt: 'Generate the daily digest.',
      // userId omitted — invocation runs without user identity
    });
    return { digest: result.text };
  },
});
```

<Card title="Agents API Reference" href="/api/agents" icon="robot">
  Full documentation for Agents.invoke — options, output shape, error handling, and more examples
</Card>

## Comparison: LuaJob vs Jobs API

| Feature           | LuaJob (Pre-defined)    | Jobs API (Dynamic)        |
| ----------------- | ----------------------- | ------------------------- |
| **When Defined**  | At agent setup          | Runtime, from tools       |
| **Use Case**      | Regular scheduled tasks | On-demand, user-triggered |
| **Schedule**      | Interval or Cron        | Once, Interval, or Cron   |
| **Examples**      | Daily reports, cleanup  | Reminders, follow-ups     |
| **Configuration** | Static in code          | Dynamic with tool input   |

## Related APIs

<CardGroup>
  <Card title="Jobs API" href="/api/jobs" icon="plus">
    Dynamic job creation
  </Card>

  <Card title="Agents API" href="/api/agents" icon="robot">
    Invoke another agent from a job
  </Card>

  <Card title="LuaAgent" href="/api/luaagent" icon="robot">
    Agent configuration
  </Card>

  <Card title="User API" href="/api/user" icon="user">
    Send messages
  </Card>

  <Card title="Data API" href="/api/data" icon="database">
    Store and retrieve data
  </Card>
</CardGroup>

## See Also

* [Jobs API](/api/jobs) - Dynamic job creation
* [Agents API](/api/agents) - Invoking agents from scheduled jobs
* [Workflows Concept](/concepts/workflows)
* [Tool Examples](/examples/overview)


# LuaMCPServer
Source: https://docs.heylua.ai/api/luamcpserver

Connect external tools via Model Context Protocol (MCP) servers

## Overview

`LuaMCPServer` allows you to connect external MCP (Model Context Protocol) servers to your agent. MCP servers provide additional tools that your agent can use at runtime, enabling integration with APIs, databases, documentation services, and more.

```typescript theme={null}
import { LuaMCPServer, env } from 'lua-cli';

const docsServer = new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://mcp.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("MCP_API_KEY")}`
  })
});

export default docsServer;
```

<Note>
  **What is MCP?** The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io).
</Note>

## Why MCP Servers?

<CardGroup>
  <Card title="Extend Capabilities" icon="puzzle-piece">
    Add tools without writing code - use existing MCP servers
  </Card>

  <Card title="Standard Protocol" icon="plug">
    Compatible with any MCP-compliant server
  </Card>

  <Card title="Remote Integration" icon="globe">
    Connect to hosted MCP services via HTTP
  </Card>

  <Card title="Community Ecosystem" icon="users">
    Access growing library of hosted MCP servers
  </Card>
</CardGroup>

## Transport Types

MCP servers support two HTTP-based transport methods:

<Tabs>
  <Tab title="Streamable HTTP (Recommended)">
    **Best for:** Modern MCP servers, most use cases

    The modern MCP standard (spec 2025-03-26) with bidirectional communication.

    ```typescript theme={null}
    const server = new LuaMCPServer({
      name: 'my-server',
      transport: 'streamable-http',
      url: 'https://mcp.example.com/mcp',
      headers: () => ({
        'Authorization': `Bearer ${env("API_KEY")}`
      })
    });
    ```
  </Tab>

  <Tab title="SSE (Legacy)">
    **Best for:** Older MCP servers that don't support Streamable HTTP

    Uses Server-Sent Events for server-to-client streaming.

    ```typescript theme={null}
    const server = new LuaMCPServer({
      name: 'legacy-server',
      transport: 'sse',
      url: 'https://old-mcp.example.com/sse',
      headers: () => ({
        'Authorization': `Bearer ${env("API_KEY")}`
      })
    });
    ```
  </Tab>
</Tabs>

<Warning>
  **stdio transport not supported yet**: Local MCP servers (using `npx`, `node`, etc.) are not supported yet.
  Please use remote MCP servers with `streamable-http` or `sse` transport instead.
</Warning>

## Constructor

### new LuaMCPServer(config)

Creates a new MCP server configuration.

<ParamField type="LuaMCPServerConfig">
  MCP server configuration object
</ParamField>

## Configuration Parameters

### Required Fields

<ParamField type="string">
  Unique identifier for the MCP server

  **Format**: lowercase, hyphens allowed

  **Examples**: `'docs-server'`, `'api-gateway'`, `'database'`
</ParamField>

<ParamField type="'streamable-http' | 'sse'">
  Transport protocol for communication

  * `'streamable-http'` - Modern MCP standard (recommended)
  * `'sse'` - Legacy Server-Sent Events transport
</ParamField>

<ParamField type="string | (() => string)">
  URL of the remote MCP server

  Can be a static string or a function that returns the URL at runtime using `env()`.

  **Examples**:

  * `'https://mcp.example.com/mcp'`
  * `() => env("MCP_SERVER_URL")`
</ParamField>

### Optional Fields

<ParamField type="Record<string, string> | (() => Record<string, string>)">
  HTTP headers to send with requests

  Can be a static object or a function that returns headers at runtime using `env()`.

  **Example (static)**: `{ 'X-Custom-Header': 'value' }`

  **Example (dynamic)**: `() => ({ 'Authorization': \`Bearer \$\` })\`
</ParamField>

<ParamField type="number">
  Timeout in milliseconds for server operations

  **Default**: `60000` (60 seconds)
</ParamField>

## Examples

### Documentation Server

```typescript theme={null}
import { LuaMCPServer, env } from 'lua-cli';

const docsServer = new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://docs.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("DOCS_API_KEY")}`
  }),
  timeout: 30000
});

export default docsServer;
```

### API Gateway

```typescript theme={null}
import { LuaMCPServer, env } from 'lua-cli';

const apiServer = new LuaMCPServer({
  name: 'api-gateway',
  transport: 'streamable-http',
  url: 'https://api.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("API_TOKEN")}`,
    'X-Api-Version': '2024-01'
  }),
  timeout: 45000
});

export default apiServer;
```

### Database Service

```typescript theme={null}
import { LuaMCPServer, env } from 'lua-cli';

const dbServer = new LuaMCPServer({
  name: 'database',
  transport: 'streamable-http',
  url: 'https://db-mcp.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("DB_API_KEY")}`,
    'X-Database': 'production'
  }),
  timeout: 60000
});

export default dbServer;
```

### Dynamic URL with env()

```typescript theme={null}
import { LuaMCPServer, env } from 'lua-cli';

const server = new LuaMCPServer({
  name: 'dynamic-server',
  transport: 'streamable-http',
  url: () => env("MCP_SERVER_URL"),
  headers: () => ({
    'Authorization': `Bearer ${env("API_TOKEN")}`
  })
});

export default server;
```

### Legacy SSE Server

```typescript theme={null}
import { LuaMCPServer, env } from 'lua-cli';

const legacyServer = new LuaMCPServer({
  name: 'legacy-api',
  transport: 'sse',
  url: 'https://old-mcp.example.com/sse',
  headers: () => ({
    'Authorization': `Bearer ${env("API_KEY")}`
  })
});

export default legacyServer;
```

## Using with LuaAgent

MCP servers are added to your agent configuration:

```typescript theme={null}
import { LuaAgent, LuaSkill, env } from 'lua-cli';

const docsServer = new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://docs.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("DOCS_API_KEY")}`
  })
});

const coreSkill = new LuaSkill({
  name: 'core-skill',
  description: 'Core functionality',
  tools: [...]
});

export const agent = new LuaAgent({
  name: 'docs-assistant',
  persona: 'You are an assistant with access to documentation.',
  skills: [coreSkill],
  
  // Add MCP servers
  mcpServers: [docsServer]
});
```

## Lifecycle Management

### Compile

During `lua compile`, MCP servers are:

1. Detected from your source code
2. Registered with the server (if new)
3. Assigned an ID stored in `lua.skill.yaml`
4. Configuration written to `dist/mcp-servers.json`

### Push

Push individual MCP server:

```bash theme={null}
lua push mcp
# Select server from list
```

Or push all components:

```bash theme={null}
lua push all --force
```

### Activate / Deactivate

MCP servers start inactive. Activate to make tools available:

```bash theme={null}
lua mcp activate
# Select server to activate

lua mcp deactivate
# Select server to deactivate
```

### List / Delete

```bash theme={null}
lua mcp list              # Show all MCP servers
lua mcp delete            # Remove an MCP server
```

## YAML Configuration

After compilation, `lua.skill.yaml` tracks MCP servers:

```yaml theme={null}
agent:
  agentId: your-agent-id
  persona: ...

mcpServers:
  - name: docs
    mcpServerId: mcp_abc123
  - name: api-gateway
    mcpServerId: mcp_def456
```

<Note>
  The YAML only stores `name` and `mcpServerId`. The full configuration (url, headers, etc.) lives in your source code.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Use env() for Secrets">
    Always use `env()` for API keys and tokens

    ```typescript theme={null}
    // ✅ Good - resolved at runtime
    headers: () => ({
      'Authorization': `Bearer ${env("API_KEY")}`
    })

    // ❌ Bad - hardcoded secret
    headers: {
      'Authorization': 'Bearer sk_live_xxxx'
    }
    ```
  </Accordion>

  <Accordion title="Set Appropriate Timeouts">
    Adjust timeout based on expected operation duration

    ```typescript theme={null}
    // Quick operations
    timeout: 10000  // 10 seconds

    // Database queries
    timeout: 30000  // 30 seconds

    // Heavy processing
    timeout: 120000 // 2 minutes
    ```
  </Accordion>

  <Accordion title="Use Streamable HTTP for New Integrations">
    Prefer `streamable-http` transport for new MCP server integrations

    ```typescript theme={null}
    // ✅ Recommended - modern standard
    transport: 'streamable-http'

    // Use only for legacy servers
    transport: 'sse'
    ```
  </Accordion>

  <Accordion title="Activate Only What You Need">
    Keep unused servers deactivated to reduce overhead

    ```bash theme={null}
    # Activate only when needed
    lua mcp activate docs-server

    # Deactivate when done
    lua mcp deactivate docs-server
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server not found after push">
    Make sure the server is activated:

    ```bash theme={null}
    lua mcp list      # Check status
    lua mcp activate  # Activate if needed
    ```
  </Accordion>

  <Accordion title="Connection timeout">
    Check the URL is accessible and increase timeout:

    ```typescript theme={null}
    const server = new LuaMCPServer({
      transport: 'streamable-http',
      url: 'https://...',
      timeout: 120000  // Increase timeout
    });
    ```
  </Accordion>

  <Accordion title="Authentication failed">
    Verify your API key is correct and set in environment:

    ```bash theme={null}
    # Check environment variable is set
    lua env production

    # Set the variable
    lua env production -k API_KEY -v "your-api-key"
    ```
  </Accordion>

  <Accordion title="stdio transport error">
    Local MCP servers (stdio) are no longer supported. Migrate to remote servers:

    ```typescript theme={null}
    // ❌ No longer supported
    transport: 'stdio',
    command: 'npx',
    args: [...]

    // ✅ Use remote transport instead
    transport: 'streamable-http',
    url: 'https://mcp.example.com/mcp',
    headers: () => ({ ... })
    ```
  </Accordion>
</AccordionGroup>

## Related APIs

<CardGroup>
  <Card title="LuaAgent" href="/api/luaagent" icon="robot">
    Agent configuration with MCP servers
  </Card>

  <Card title="LuaSkill" href="/api/luaskill" icon="puzzle-piece">
    Custom tool collections
  </Card>

  <Card title="Environment" href="/api/environment" icon="key">
    Managing environment variables
  </Card>

  <Card title="MCP Command" href="/cli/mcp-command" icon="terminal">
    CLI management commands
  </Card>
</CardGroup>

## See Also

* [MCP Servers Overview](/overview/mcp-servers) - Conceptual introduction
* [MCP Command](/cli/mcp-command) - CLI management
* [LuaAgent](/api/luaagent) - Adding MCP servers to your agent
* [Use Lua with Claude & Cursor](/mcp-for-builders) - Connect Lua's docs to your AI coding assistant


# LuaSkill
Source: https://docs.heylua.ai/api/luaskill

Collection of related tools that give your AI specific capabilities

## Overview

`LuaSkill` is the main class for defining a skill - a collection of related tools that your AI agent can use.

```typescript theme={null}
import { LuaSkill } from 'lua-cli';

const skill = new LuaSkill({
  name: "my-skill",
  description: "Brief description of the skill",
  context: "Detailed instructions for the AI",
  tools: [new MyTool1(), new MyTool2()]
});
```

## Constructor

### new LuaSkill(config)

Creates a new skill instance.

<ParamField type="LuaSkillConfig">
  Skill configuration object
</ParamField>

### Configuration Parameters

<ParamField type="string">
  Unique identifier for the skill

  **Format**: lowercase, alphanumeric, hyphens only

  **Examples**: `"weather-skill"`, `"product-catalog-skill"`
</ParamField>

<ParamField type="string">
  Brief description (1-2 sentences) of what the skill does

  This appears in skill listings and helps users understand the skill's purpose.
</ParamField>

<ParamField type="string | { base?: string; voice?: string; text?: string }">
  Detailed instructions for the AI on when and how to use the tools.

  **String form (recommended):**

  * Critical for proper tool selection
  * Write it like instructions to a smart assistant

  **Object form (channel-aware):** Only use when you need different instructions per channel.

  * `base` — Always rendered, on every channel
  * `voice` — Appended to `base` on voice channels, ignored on text
  * `text` — Appended to `base` on text channels (web, WhatsApp, SMS), ignored on voice

  See [Channel-aware Prompts](/concepts/channel-aware-prompts) for details.
</ParamField>

<ParamField type="LuaTool[]">
  Array of tool instances to include in the skill

  Can be empty initially and tools added later with `addTool()` or `addTools()`.
</ParamField>

<ParamField type="function">
  ```typescript theme={null}
  async condition(): Promise<boolean>
  ```

  Optional gate for the whole skill. Return `true` to expose it, `false` to hide it.

  When it returns `false` the skill disappears completely: its tools can't be called **and** its name, its context, and its tool names are left out of the agent's prompt. The agent doesn't know the capability exists.

  See [Conditional Skills](#conditional-skills).
</ParamField>

## Conditional Skills

Use `condition` when a whole capability should be invisible to some users — tiering, entitlements, per-customer features.

```typescript theme={null}
import { LuaSkill, User } from 'lua-cli';
import CheckPointsTool from './tools/CheckPointsTool';
import RedeemPointsTool from './tools/RedeemPointsTool';

const loyaltySkill = new LuaSkill({
  name: 'loyalty-rewards',
  description: 'Loyalty points balance and reward redemption',
  context: `
    This skill manages the loyalty programme.

    Tool Usage:
    - check_points: Use when the customer asks about their balance.
    - redeem_points: Use when the customer wants to spend points. Confirm the reward first.
  `,
  condition: async () => {
    const user = await User.get();
    return user.data?.loyaltyEnrolled === true;
  },
  tools: [new CheckPointsTool(), new RedeemPointsTool()],
});
```

A customer who isn't enrolled talks to an agent that has never heard of a loyalty programme. There is no `check_points` tool to refuse, and no loyalty context to leak.

How it behaves:

* **Evaluated on every message, for the current user.** Results are not cached between turns, so the gate always reflects current state.
* **Runs like your tool code.** Has access to all Platform APIs (`User`, `Data`, `Lua`, `Products`, etc.).
* **Absent condition means always on.** Existing skills are unaffected.
* **Skill-level short-circuits tool-level.** If the skill is hidden, its tools' own `condition` functions never run.

If you author a skill as a `LuaSkill` subclass rather than a config object, declare `condition` as a class field or method — the semantics are identical.

<Note>
  **Fail-closed behavior:** If your condition function throws an error or times out (30s), the skill is hidden. Design for that — a flaky third-party call inside a condition will hide the capability from users who should have it. Prefer a flag you already store on the user record over a live external lookup on every message.
</Note>

### Skill condition vs tool condition

Both gates take the same shape. They differ in what the agent still knows about.

|                                      | Tool `condition`                                              | Skill `condition`                                     |
| ------------------------------------ | ------------------------------------------------------------- | ----------------------------------------------------- |
| Scope                                | One tool                                                      | Every tool in the skill                               |
| Tool callable when `false`           | No                                                            | No                                                    |
| Tool name in the prompt              | Removed                                                       | Removed                                               |
| Skill name and context in the prompt | Still rendered                                                | Removed                                               |
| Agent can mention the capability     | Yes — the skill's context still describes it                  | No — it doesn't know it exists                        |
| Reach for it when                    | The capability is known to the user but currently unavailable | The *existence* of the capability is itself sensitive |

Gate individual tools with [`LuaTool.condition`](/api/luatool#condition) when the rest of the skill still applies — for example, hiding `cancel_order` while `track_order` stays available.

## Methods

### addTool()

Adds a single tool to the skill.

```typescript theme={null}
skill.addTool(tool: LuaTool): void
```

<ParamField type="LuaTool">
  Tool instance to add
</ParamField>

**Example:**

```typescript theme={null}
const skill = new LuaSkill({
  name: "my-skill",
  description: "My skill",
  context: "..."
});

skill.addTool(new GetWeatherTool());
skill.addTool(new CreateOrderTool());
```

**Validation:**

* Tool name must be unique within the skill
* Tool name must only contain: `a-z`, `A-Z`, `0-9`, `-`, `_`
* Throws error if validation fails

### addTools()

Adds multiple tools to the skill at once.

```typescript theme={null}
skill.addTools(tools: LuaTool[]): void
```

<ParamField type="LuaTool[]">
  Array of tool instances to add
</ParamField>

**Example:**

```typescript theme={null}
skill.addTools([
  new GetWeatherTool(),
  new CreateOrderTool(),
  new SearchProductsTool()
]);
```

**Validation:**

* All tools validated before adding
* Atomic operation (all or nothing)
* Throws error if any validation fails

## Examples

### Basic Skill

```typescript theme={null}
import { LuaSkill, LuaTool } from 'lua-cli';
import { z } from 'zod';

class HelloTool implements LuaTool {
  name = "say_hello";
  description = "Say hello to a user";
  inputSchema = z.object({
    name: z.string()
  });

  async execute(input: any) {
    return { message: `Hello, ${input.name}!` };
  }
}

const helloSkill = new LuaSkill({
  name: "hello-skill",
  description: "A simple greeting skill",
  context: "Use say_hello when users want to be greeted",
  tools: [new HelloTool()]
});
```

### Weather Skill

```typescript theme={null}
import { LuaSkill } from 'lua-cli';
import GetWeatherTool from './tools/GetWeatherTool';
import GetForecastTool from './tools/GetForecastTool';

const weatherSkill = new LuaSkill({
  name: "weather-skill",
  description: "Provides weather information for any city worldwide",
  context: `
    This skill provides weather information.
    
    - Use get_weather for current conditions
    - Use get_forecast for 7-day predictions
    
    Always include the city name in responses.
    Mention temperature in user's preferred units.
  `,
  tools: [
    new GetWeatherTool(),
    new GetForecastTool()
  ]
});
```

### E-commerce Skill

```typescript theme={null}
import { LuaSkill } from 'lua-cli';
import {
  SearchProductsTool,
  CreateProductTool,
  UpdateProductTool
} from './tools/ProductTools';

const ecommerceSkill = new LuaSkill({
  name: "ecommerce-skill",
  description: "Complete e-commerce product management",
  context: `
    This skill manages an e-commerce product catalog.
    
    Tool Usage:
    - search_products: When users describe what they're looking for
    - create_product: When adding new items (admin only)
    - update_product: When modifying prices, stock, or details
    
    Guidelines:
    - Always show prices with currency
    - Mention stock availability
    - Suggest related products when relevant
    - Confirm changes before updating
  `,
  tools: [
    new SearchProductsTool(),
    new CreateProductTool(),
    new UpdateProductTool()
  ]
});
```

### Adding Tools Dynamically

```typescript theme={null}
const skill = new LuaSkill({
  name: "dynamic-skill",
  description: "Skill with dynamically added tools",
  context: "Tools will be added based on configuration"
});

// Add tools conditionally
if (config.enableWeather) {
  skill.addTool(new GetWeatherTool());
}

if (config.enableOrders) {
  skill.addTools([
    new CreateOrderTool(),
    new TrackOrderTool()
  ]);
}
```

## Writing Good Context

The `context` field is critical for AI tool selection. Follow these guidelines:

### Structure

```typescript theme={null}
context: `
  [What this skill does - 1 sentence]
  
  Tool Usage:
  - tool_1: [When to use] [What it returns]
  - tool_2: [When to use] [What it returns]
  
  Guidelines:
  - [Important rules]
  - [Edge cases]
  - [User experience tips]
`
```

### Good Context Example

```typescript theme={null}
context: `
  This skill manages customer orders for a coffee shop.

  Tool Usage:
  - show_menu: Use when customers ask what's available. Returns drinks and food.
  - create_order: Use when taking an order. Confirm items and sizes first.
  - modify_order: Use to add/remove items. Ask which item to modify.
  - finalize_order: Use when confirmed. Returns total and estimated time.

  Guidelines:
  - Always ask about drink sizes (small/medium/large)
  - Mention daily special when showing menu
  - Confirm total before finalizing order
  - Ask about dietary restrictions for food
`
```

### Poor Context Example

```typescript theme={null}
context: "A skill with tools for stuff"  // ❌ Too vague
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Names">
    ```typescript theme={null}
    // ✅ Good
    name: "weather-skill"
    name: "product-catalog-skill"
    name: "customer-support-skill"

    // ❌ Bad
    name: "skill1"
    name: "my_skill"
    name: "test"
    ```
  </Accordion>

  <Accordion title="Write Clear Descriptions">
    ```typescript theme={null}
    // ✅ Good
    description: "Provides real-time weather information and 7-day forecasts for cities worldwide"

    // ❌ Bad
    description: "Weather stuff"
    ```
  </Accordion>

  <Accordion title="Provide Detailed Context">
    The context field should include:

    * Overview of skill purpose
    * When to use each tool
    * Important guidelines
    * Edge cases to handle

    Think of it as training documentation for the AI.
  </Accordion>

  <Accordion title="Organize Related Tools">
    Group tools that work together:

    ```typescript theme={null}
    // ✅ Good - Related tools together
    const orderSkill = new LuaSkill({
      tools: [
        new CreateOrderTool(),
        new UpdateOrderTool(),
        new CancelOrderTool(),
        new TrackOrderTool()
      ]
    });

    // ❌ Bad - Unrelated tools mixed
    const messySkill = new LuaSkill({
      tools: [
        new GetWeatherTool(),
        new CreateOrderTool(),
        new SendEmailTool()
      ]
    });
    ```
  </Accordion>
</AccordionGroup>

## Multi-Skill Projects

You can define multiple skills in one project:

```typescript theme={null}
// Product browsing
const catalogSkill = new LuaSkill({
  name: "catalog-skill",
  description: "Product browsing and search",
  tools: [new SearchProductsTool(), new GetProductTool()]
});

// Shopping cart
const cartSkill = new LuaSkill({
  name: "cart-skill",
  description: "Shopping cart management",
  tools: [new CreateBasketTool(), new AddItemTool()]
});

// Order processing
const orderSkill = new LuaSkill({
  name: "order-skill",
  description: "Order creation and tracking",
  tools: [new CreateOrderTool(), new TrackOrderTool()]
});
```

Each skill gets its own `skillId` in `lua.skill.yaml` and can be deployed independently.

## Type Definitions

```typescript theme={null}
interface LuaSkillConfig {
  name?: string;
  description: string;
  context: string;
  tools?: LuaTool[];
  condition?: () => Promise<boolean>;
}

class LuaSkill {
  constructor(config: LuaSkillConfig);
  addTool(tool: LuaTool): void;
  addTools(tools: LuaTool[]): void;
}
```

## Next Steps

<CardGroup>
  <Card title="LuaTool Interface" icon="wrench" href="/api/luatool">
    Learn how to implement tools
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Follow a complete tutorial
  </Card>

  <Card title="Template Guide" icon="layer-group" href="/template/overview">
    Explore the example project
  </Card>

  <Card title="Skills & Tools Concept" icon="book" href="/concepts/skills-and-tools">
    Understand the architecture
  </Card>
</CardGroup>


# LuaTool
Source: https://docs.heylua.ai/api/luatool

Interface for implementing individual AI tool functions

## Overview

`LuaTool` is the interface that all tools must implement. A tool is a single function that the AI can call to accomplish a specific task.

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class MyTool implements LuaTool {
  name = "my_tool";
  description = "What the tool does";
  inputSchema = z.object({ param: z.string() });
  
  async execute(input: any) {
    return { result: "success" };
  }
}
```

## Interface Definition

```typescript theme={null}
interface LuaTool<TInput extends ZodType = ZodType> {
  name: string;
  description: string;
  inputSchema: TInput;
  execute: (input: z.infer<TInput>) => Promise<any>;
  condition?: () => Promise<boolean>;
}
```

## Required Properties

### name

Unique identifier for the tool.

<ParamField type="string">
  Tool name using only: `a-z`, `A-Z`, `0-9`, `-`, `_`

  **Examples**: `"get_weather"`, `"create-order"`, `"sendEmail123"`

  **Invalid**: `"get weather"`, `"tool.name"`, `"send@email"`
</ParamField>

```typescript theme={null}
// ✅ Good
name = "get_weather";
name = "create-product";
name = "search_items";

// ❌ Bad
name = "get weather";  // No spaces
name = "tool.name";    // No dots
name = "send@email";   // No special chars
```

### description

Clear, concise description of what the tool does.

<ParamField type="string">
  One sentence describing the tool's purpose

  Helps the AI understand when to use this tool
</ParamField>

```typescript theme={null}
// ✅ Good
description = "Get current weather conditions for any city worldwide";
description = "Create a new product in the catalog with price and details";
description = "Search for products by name, category, or description";

// ❌ Bad
description = "Gets data";           // Too vague
description = "Does weather stuff";  // Unclear
```

### inputSchema

Zod schema that validates and types the input.

<ParamField type="ZodType">
  Zod schema defining valid inputs

  Provides runtime validation and TypeScript types
</ParamField>

```typescript theme={null}
import { z } from 'zod';

// Simple
inputSchema = z.object({
  city: z.string()
});

// With validation
inputSchema = z.object({
  email: z.string().email(),
  age: z.number().min(0).max(120)
});

// With descriptions
inputSchema = z.object({
  city: z.string().describe("City name (e.g., 'London', 'Tokyo')"),
  units: z.enum(['metric', 'imperial']).describe("Temperature units")
});

// With optional and default values
inputSchema = z.object({
  query: z.string(),
  limit: z.number().default(10),
  offset: z.number().optional()
});
```

### execute

Async function that implements the tool's logic.

<ParamField type="function">
  ```typescript theme={null}
  async execute(input: z.infer<typeof this.inputSchema>): Promise<any>
  ```

  * Input is automatically validated
  * Must return a JSON-serializable value
  * Can throw errors for failures
</ParamField>

## Optional Properties

### condition

Async function that determines if the tool should be available to the AI.

<ParamField type="function">
  ```typescript theme={null}
  async condition(): Promise<boolean>
  ```

  * Runs **before** the tool is offered to the AI
  * Return `true` to enable the tool, `false` to hide it
  * If the function throws an error, the tool is disabled (fail-closed)
  * Has access to all Platform APIs (User, Data, Products, etc.)
</ParamField>

Use conditions to dynamically enable/disable tools based on:

* User subscription status (premium features)
* User verification or account status
* Feature flags or A/B testing
* Region-specific functionality
* Time-based access

```typescript theme={null}
import { LuaTool, User } from 'lua-cli';
import { z } from 'zod';

export default class PremiumSearchTool implements LuaTool {
  name = "premium_search";
  description = "Advanced search with filters - premium users only";
  
  inputSchema = z.object({
    query: z.string(),
    filters: z.object({
      minPrice: z.number().optional(),
      maxPrice: z.number().optional()
    }).optional()
  });

  // Only show this tool to premium users
  condition = async () => {
    const user = await User.get();
    return user.data?.isPremium === true;
  };

  async execute(input: z.infer<typeof this.inputSchema>) {
    // This only runs if condition returned true
    return { results: [] };
  }
}
```

<Note>
  **Fail-closed behavior:** If your condition function throws an error or times out (30s), the tool is automatically disabled. This ensures tools aren't accidentally exposed when conditions can't be evaluated.
</Note>

<Tip>
  A disabled tool is left out of the prompt's tool list, but the skill's name and context stay in the agent's prompt — the agent can still say "that's a premium feature, so I can't do that". To hide the capability entirely, put the same `condition` on the skill: see [Skill condition vs tool condition](/api/luaskill#skill-condition-vs-tool-condition).
</Tip>

## Implementation Examples

### Simple Tool

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class GreetTool implements LuaTool {
  name = "greet_user";
  description = "Greet a user by name";
  
  inputSchema = z.object({
    name: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    return {
      message: `Hello, ${input.name}!`,
      timestamp: new Date().toISOString()
    };
  }
}
```

### External API Tool

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class GetWeatherTool implements LuaTool {
  name = "get_weather";
  description = "Get current weather for a city";
  
  inputSchema = z.object({
    city: z.string().describe("City name"),
    units: z.enum(['metric', 'imperial']).optional().default('metric')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const { city, units } = input;
    
    // Call external API
    const response = await fetch(
      `https://api.weather.com/v1/weather?city=${city}&units=${units}`
    );
    
    if (!response.ok) {
      throw new Error(`Weather API error: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    return {
      city: data.location,
      temperature: data.temp,
      condition: data.condition,
      humidity: data.humidity
    };
  }
}
```

### Platform API Tool

```typescript theme={null}
import { LuaTool, Products } from 'lua-cli';
import { z } from 'zod';

export default class SearchProductsTool implements LuaTool {
  name = "search_products";
  description = "Search for products by name or description";
  
  inputSchema = z.object({
    query: z.string().describe("Search query"),
    limit: z.number().min(1).max(100).default(10)
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Products.search(input.query);
    
    // Take only requested number of results
    const products = results.products.slice(0, input.limit);
    
    return {
      products: products.map(p => ({
        id: p.id,
        name: p.name,
        price: `$${p.price.toFixed(2)}`,
        inStock: p.inStock
      })),
      total: results.length,
      showing: products.length
    };
  }
}
```

### Environment Variables Tool

```typescript theme={null}
import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

export default class SendEmailTool implements LuaTool {
  name = "send_email";
  description = "Send an email via SendGrid";
  
  inputSchema = z.object({
    to: z.string().email(),
    subject: z.string(),
    body: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get API key from environment
    const apiKey = env('SENDGRID_API_KEY');
    
    if (!apiKey) {
      throw new Error('SENDGRID_API_KEY not configured');
    }
    
    // Send email
    const response = await fetch('https://api.sendgrid.com/v3/mail/send', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        personalizations: [{ to: [{ email: input.to }] }],
        from: { email: 'noreply@example.com' },
        subject: input.subject,
        content: [{ type: 'text/plain', value: input.body }]
      })
    });
    
    if (!response.ok) {
      throw new Error(`Email failed: ${response.statusText}`);
    }
    
    return {
      success: true,
      message: `Email sent to ${input.to}`
    };
  }
}
```

### Multi-Step Tool

```typescript theme={null}
import { LuaTool, Products, Baskets } from 'lua-cli';
import { z } from 'zod';

export default class QuickCheckoutTool implements LuaTool {
  name = "quick_checkout";
  description = "Search, add to cart, and checkout in one step";
  
  inputSchema = z.object({
    productName: z.string(),
    quantity: z.number().min(1).default(1),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      zip: z.string()
    })
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Step 1: Search for product
    const products = await Products.search(input.productName);
    if (products.length === 0) {
      throw new Error(`Product not found: ${input.productName}`);
    }
    const product = products.products[0];
    
    // Step 2: Create basket
    const basket = await Baskets.create({ currency: 'USD' });
    
    // Step 3: Add product
    await Baskets.addItem(basket.id, {
      id: product.id,
      price: product.price,
      quantity: input.quantity
    });
    
    // Step 4: Checkout
    const order = await Baskets.placeOrder({
      shippingAddress: input.shippingAddress,
      paymentMethod: 'stripe'
    }, basket.id);
    
    return {
      orderId: order.id,
      product: product.name,
      quantity: input.quantity,
      total: `$${(product.price * input.quantity).toFixed(2)}`,
      message: 'Order created successfully'
    };
  }
}
```

### Conditional Tool (Premium Feature)

```typescript theme={null}
import { LuaTool, User, Products } from 'lua-cli';
import { z } from 'zod';

export default class PremiumAdvancedSearchTool implements LuaTool {
  name = "premium_advanced_search";
  description = "Advanced search with filters and sorting - premium users only";
  
  inputSchema = z.object({
    query: z.string().describe("Search query"),
    filters: z.object({
      category: z.string().optional(),
      minPrice: z.number().optional(),
      maxPrice: z.number().optional()
    }).optional(),
    sortBy: z.enum(["relevance", "price_asc", "price_desc", "newest"]).optional()
  });

  // Condition: Only show to premium users
  condition = async () => {
    const user = await User.get();
    
    // Check subscription status
    const isPremium = user.data?.subscription === "premium" 
                   || user.data?.isPremium === true;
    
    return isPremium;
  };

  async execute(input: z.infer<typeof this.inputSchema>) {
    const { query, filters, sortBy } = input;
    
    const searchResult = await Products.search({ query, limit: 20 });
    let products = searchResult.products;
    
    // Apply price filters
    if (filters?.minPrice !== undefined || filters?.maxPrice !== undefined) {
      products = products.filter(p => {
        if (filters.minPrice && p.price < filters.minPrice) return false;
        if (filters.maxPrice && p.price > filters.maxPrice) return false;
        return true;
      });
    }
    
    return {
      query,
      totalResults: products.length,
      results: products.slice(0, 10),
      sortedBy: sortBy || "relevance"
    };
  }
}
```

## Reusing Tools Across Agents

When multiple agents share the same tool logic — same API, same auth, same shape — but differ on a couple of config values, declare the shared parts on an abstract base and have each agent's tool extend it. The compiler walks the full `extends` chain, so a leaf class is detected as a tool whether it extends `LuaTool` directly or through any number of intermediate bases.

```typescript theme={null}
// Shared base — published once, imported by every agent
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export abstract class SearchTool implements LuaTool {
  name = 'search';
  description = 'Search the knowledge base.';
  inputSchema = z.object({ query: z.string() });

  // Subclasses override this. The default lets the type-check pass
  // for the abstract base; concrete subclasses must set a real value.
  searchPath: string = '/default/search';

  async execute(input: { query: string }) {
    const r = await fetch(`https://api.example.com${this.searchPath}`, {
      method: 'POST',
      body: JSON.stringify({ q: input.query }),
    });
    return r.json();
  }
}
```

```typescript theme={null}
// Per-agent leaf — only what differs
import { SearchTool } from '@my-org/shared';

export class BlackshipSearchTool extends SearchTool {
  name = 'search_blackship';
  searchPath = '/blk/search';
}
```

Register the leaf class on a skill — pass the class itself, not an instance:

```typescript theme={null}
import { LuaSkill } from 'lua-cli';
import { BlackshipSearchTool } from './tools/BlackshipSearch';

export default new LuaSkill({
  name: 'support',
  description: 'Customer support tools',
  context: 'Use search_blackship to look things up.',
  tools: [BlackshipSearchTool],
});
```

Field initializers on the leaf run during construction, so `this.searchPath` inside the parent's `execute` resolves to `'/blk/search'`. The leaf inherits `inputSchema`, `description`, and `execute` from the parent unless it overrides them.

<Warning>
  Don't pass constructor arguments at the reference site:

  ```typescript theme={null}
  // ❌ The string is silently dropped — one tool artifact is shared across
  //    every reference and there's no carrier for per-reference args.
  tools: [new BlackshipSearchTool('/blk/search')]
  ```

  The compiler reports `lua/constructor-args-dropped` if it sees this. Use a subclass with a field override instead.
</Warning>

## Input Schema Patterns

### Optional Fields

```typescript theme={null}
inputSchema = z.object({
  required: z.string(),
  optional: z.string().optional(),
  withDefault: z.string().default('default value')
});
```

### Validation

```typescript theme={null}
inputSchema = z.object({
  email: z.string().email(),
  age: z.number().min(18).max(120),
  phone: z.string().regex(/^\+?[1-9]\d{1,14}$/),
  url: z.string().url(),
  password: z.string().min(8)
});
```

### Nested Objects

```typescript theme={null}
inputSchema = z.object({
  user: z.object({
    name: z.string(),
    email: z.string().email()
  }),
  preferences: z.object({
    notifications: z.boolean(),
    language: z.string()
  }).optional()
});
```

### Arrays

```typescript theme={null}
inputSchema = z.object({
  items: z.array(z.object({
    id: z.string(),
    quantity: z.number()
  })),
  tags: z.array(z.string()).optional()
});
```

### Enums

```typescript theme={null}
inputSchema = z.object({
  status: z.enum(['pending', 'active', 'completed']),
  priority: z.enum(['low', 'medium', 'high']).default('medium')
});
```

## Error Handling

### Throwing Errors

```typescript theme={null}
async execute(input: any) {
  // Validate business logic
  if (input.amount <= 0) {
    throw new Error("Amount must be positive");
  }
  
  // API errors
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`API error: ${response.statusText}`);
  }
  
  // Not found errors
  const item = await findItem(input.id);
  if (!item) {
    throw new Error(`Item not found: ${input.id}`);
  }
  
  return result;
}
```

### Try-Catch Pattern

```typescript theme={null}
async execute(input: any) {
  try {
    const result = await externalService.call(input);
    
    if (!result.success) {
      throw new Error(result.error || 'Operation failed');
    }
    
    return result.data;
  } catch (error) {
    // Add context to errors
    throw new Error(`Failed to process request: ${error.message}`);
  }
}
```

## Return Value Patterns

### Structured Data

```typescript theme={null}
// ✅ Good - Structured
return {
  success: true,
  data: { id, name, price },
  metadata: { timestamp, version }
};

// ❌ Bad - Unstructured string
return "Product created with ID 123";
```

### Lists

```typescript theme={null}
return {
  items: [...],
  total: 100,
  page: 1,
  hasMore: true
};
```

### Status Updates

```typescript theme={null}
return {
  status: 'completed',
  message: 'Order shipped successfully',
  trackingNumber: 'ABC123',
  estimatedDelivery: '2025-10-10'
};
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Type-Safe Inputs">
    ```typescript theme={null}
    async execute(input: z.infer<typeof this.inputSchema>) {
      // input is fully typed!
      const { city, units } = input;
    }
    ```
  </Accordion>

  <Accordion title="Add Input Descriptions">
    ```typescript theme={null}
    inputSchema = z.object({
      city: z.string().describe("City name (e.g., 'London', 'Tokyo')"),
      units: z.enum(['metric', 'imperial']).describe("Temperature units")
    });
    ```
  </Accordion>

  <Accordion title="Return Structured Data">
    Always return objects, not strings:

    ```typescript theme={null}
    // ✅ Good
    return { temperature: 72, condition: "sunny" };

    // ❌ Bad
    return "The temperature is 72 and sunny";
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Provide helpful error messages:

    ```typescript theme={null}
    if (!apiKey) {
      throw new Error('API_KEY environment variable is required. Set it in .env file.');
    }
    ```
  </Accordion>

  <Accordion title="Keep Tools Focused">
    One tool = one responsibility:

    ```typescript theme={null}
    // ✅ Good - Single purpose
    class CreateProductTool { ... }
    class UpdateProductTool { ... }

    // ❌ Bad - Multiple purposes
    class ProductTool {
      // Does create, update, delete, search...
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="LuaSkill Class" icon="puzzle-piece" href="/api/luaskill">
    Learn about skills
  </Card>

  <Card title="Platform APIs" icon="server" href="/concepts/platform-apis">
    Use built-in APIs
  </Card>

  <Card title="Tool Examples" icon="layer-group" href="/examples/overview">
    See working examples
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Complete tutorial
  </Card>
</CardGroup>


# LuaTrigger
Source: https://docs.heylua.ai/api/luatrigger

Declarative triggers that wake your agent on external events — verify, filter, and transform, with no execute function

## Overview

`LuaTrigger` (created with `defineTrigger`) wakes your agent when an external service posts to a trigger URL. Unlike a webhook, a trigger has **no `execute` function** — the agent turn itself does the work. Your only customisation surface is three optional, declarative slots that run server-side before the agent is invoked:

1. **`verify`** — authenticate the request (e.g. an HMAC signature check). Return `false` and the request is rejected with HTTP 401; the agent never runs.
2. **`filter`** — decide whether this event matters. Return `false` and the sender gets HTTP 200, but no agent invocation happens.
3. **`transform`** — shape what the agent receives. Return a message string (or a full invocation input) instead of the raw payload.

```typescript theme={null}
import { defineTrigger } from 'lua-cli';
import { z } from 'zod';

export default defineTrigger({
  name: 'order-created',
  description: 'Fires when the shop reports a new order',
  inputSchema: z.object({
    type: z.string(),
    data: z.object({ orderId: z.string(), total: z.number() }),
  }),
  filter: (ctx) => ctx.body.type === 'order.created',
  transform: (ctx) => `New order ${ctx.body.data.orderId} for ${ctx.body.data.total}. Confirm it and notify the customer.`,
});
```

After `lua push`, every event that passes `verify` and `filter` starts an agent turn with the transformed message. There is no handler code to maintain — the agent's persona, skills, and tools take it from there.

<Note>
  A trigger needs at least one of `verify`, `filter`, or `transform` — a trigger with none of the three is just a paste-anywhere URL trigger, which you can create without any code via [`lua triggers create`](/cli/triggers-command).
</Note>

## Triggers vs Webhooks vs Jobs

|                       | **LuaTrigger**                                | **LuaWebhook**                               | **LuaJob**                            |
| --------------------- | --------------------------------------------- | -------------------------------------------- | ------------------------------------- |
| **Purpose**           | Wake the agent on an external event           | Full request/response control                | Scheduled or queued work              |
| **Handler code**      | None — declarative slots only                 | Your `execute` function                      | Your `execute` function               |
| **Who does the work** | The agent (persona, skills, tools)            | Your code                                    | Your code                             |
| **HTTP response**     | Framework-owned (200/401/…)                   | Whatever `execute` returns                   | n/a                                   |
| **Best for**          | "When X happens, have the agent deal with it" | Custom responses, side effects, syncing data | Cron schedules, background processing |

Reach for `LuaWebhook` when the caller needs a specific response body or you want to run code without involving the agent. Reach for `LuaTrigger` when the right reaction to an event is *an agent turn* — triage this PR, answer this ticket, follow up on this order. See [LuaWebhook](/api/luawebhook) and [LuaJob](/api/luajob).

## Use Cases

<CardGroup>
  <Card title="Git Events" icon="code-branch">
    "A PR was assigned to me — triage it" with signature verification
  </Card>

  <Card title="Payment Events" icon="credit-card">
    Wake the agent on a successful Stripe payment, ignore the rest
  </Card>

  <Card title="Alerting" icon="bell">
    Point a monitoring tool at the trigger URL; the agent investigates
  </Card>

  <Card title="Automation Glue" icon="plug">
    Any service that can POST JSON can start an agent turn
  </Card>
</CardGroup>

## Defining a Trigger

Three authoring shapes are recognised — pick whichever fits your codebase:

<CodeGroup>
  ```typescript defineTrigger (recommended) theme={null}
  import { defineTrigger } from 'lua-cli';

  export default defineTrigger({
    name: 'order-created',
    description: 'Fires when the shop reports a new order',
    filter: (ctx) => ctx.body.type === 'order.created',
  });
  ```

  ```typescript new LuaTrigger theme={null}
  import { LuaTrigger } from 'lua-cli';

  export default new LuaTrigger({
    name: 'order-created',
    description: 'Fires when the shop reports a new order',
    filter: (ctx) => ctx.body.type === 'order.created',
  });
  ```

  ```typescript class extends LuaTrigger theme={null}
  import { LuaTrigger, TriggerContext } from 'lua-cli';

  export default class OrderCreatedTrigger extends LuaTrigger {
    name = 'order-created';
    description = 'Fires when the shop reports a new order';

    filter(ctx: TriggerContext) {
      return ctx.body.type === 'order.created';
    }
  }
  ```
</CodeGroup>

## Configuration Parameters

### Required Fields

<ParamField type="string">
  Unique trigger name, used as the server-side identifier.

  **Format**: URL-safe — a lowercase letter followed by lowercase letters, digits, and hyphens (e.g. `'order-created'`, `'github-pr-assigned'`). Other names compile with a warning.
</ParamField>

<ParamField type="string">
  Short description shown in trigger listings. It is a note for you — it is **not** sent to the agent.
</ParamField>

### Slots (at least one required)

<ParamField type="function">
  Authentication gate. Return `false` (or a promise of `false`) to reject the request with **HTTP 401** and skip the agent entirely. Put HMAC signature checks here.

  **Signature:** `(ctx: TriggerContext) => boolean | Promise<boolean>`
</ParamField>

<ParamField type="function">
  Relevance gate, run after `verify`. Return `false` to acknowledge the event with **HTTP 200** but skip the agent — the way to intentionally ignore events you don't care about, without making the sender think delivery failed.

  **Signature:** `(ctx: TriggerContext) => boolean | Promise<boolean>`
</ParamField>

<ParamField type="function">
  Shapes the agent input, run after `filter`. Return either:

  * a **string** — becomes the agent's message for the turn, or
  * a **full invocation input object** (`{ messages | prompt, userId?, threadId?, systemPrompt?, ... }`) — you own the whole turn.

  Returning `null`/`undefined` is an error (the delivery fails with HTTP 500) — use `filter` to skip events, not `transform`.

  **Signature:** `(ctx: TriggerContext) => string | AgentInvocationInput | Promise<string | AgentInvocationInput>`

  Omit `transform` to use the default payload-forwarding format described in [Default Agent Message](#default-agent-message).
</ParamField>

### Optional Fields

<ParamField type="'webhook'">
  Event source. Only `'webhook'` (an HTTP POST to the trigger URL) is currently supported.
</ParamField>

<ParamField type="ZodType">
  Optional Zod schema describing the event body. To type `ctx.body` in your slots, also pass the payload type as the generic: `defineTrigger<MyEvent>({ ... })`.
</ParamField>

## TriggerContext

Every slot receives the same context object:

```typescript theme={null}
interface TriggerContext<T = any> {
  body: T;                       // Parsed request body (type it via defineTrigger<T>)
  rawBody?: string;              // Exact unparsed request bytes (utf8)
  headers: Record<string, any>;  // Request headers — keys are lowercased
  query: Record<string, any>;    // Parsed query-string parameters
  triggerName: string;           // This trigger's name
  source: string;                // Event source ('webhook')
}
```

<Warning>
  **Compute HMAC signatures over `ctx.rawBody`, never over `JSON.stringify(ctx.body)`.** Providers like GitHub (`x-hub-signature-256: sha256=…`), Stripe, and Slack sign the exact bytes they send. Re-stringifying the parsed body does not reproduce those bytes (key order, whitespace, and unicode escapes all differ), so a signature computed from `ctx.body` will fail even for genuine requests. `rawBody` exists precisely for this.
</Warning>

<Note>
  Header keys arrive **lowercased** — read `ctx.headers['x-hub-signature-256']`, not `ctx.headers['X-Hub-Signature-256']`.
</Note>

## Slot Semantics

Slots run server-side, in order, on every delivery. Their outcome decides the HTTP response the sender sees:

| Outcome                                | HTTP response | Agent invoked?            | Logged status            |
| -------------------------------------- | ------------- | ------------------------- | ------------------------ |
| All slots pass                         | `200`         | ✅ Yes (in the background) | `accepted` → `completed` |
| `verify` returns `false`               | `401`         | ❌ No                      | `rejected_unverified`    |
| `filter` returns `false`               | `200`         | ❌ No                      | `skipped_filtered`       |
| Any slot throws                        | `500`         | ❌ No                      | `failed`                 |
| `transform` returns `null`/`undefined` | `500`         | ❌ No                      | `failed`                 |
| Trigger is deactivated                 | `200`         | ❌ No                      | `skipped_inactive`       |
| Unknown URL or token                   | `404`         | ❌ No                      | —                        |

A few facts worth knowing:

* **Slots run in a sandbox with a 15-second budget.** Keep them fast and computational — signature checks, field comparisons, string building. Don't make network calls from slots; if the agent needs external data, let the agent fetch it with its tools during the turn.
* **`verify` failures return 401, not 500.** Webhook providers treat a 401 as a configuration error and won't retry-storm you the way they would on a 5xx.
* **`filter` failures return 200.** The sender sees a successful delivery, so it won't retry an event you deliberately ignored.
* **Node's built-in `crypto` module is available** in slots (for `createHmac`, `timingSafeEqual`), and [`env('KEY')`](/api/environment) reads your agent's environment variables — the sanctioned way to get secrets into a `verify` check.
* **The agent turn is fire-and-forget.** Once the slots pass, the sender gets its 200 immediately; the agent runs in the background and the outcome lands in the execution log.

## Default Agent Message

When you omit `transform`, the agent receives the event in a standard format. With an **instruction** set (via `lua triggers create --instruction "..."`):

```
[Trigger: <name>] <instruction>

Payload:
<JSON-stringified body>
```

Without an instruction, the JSON payload directly follows the prefix — there is no `Payload:` label:

```
[Trigger: <name>] <JSON-stringified body>
```

* The `[Trigger: <name>]` prefix is always present, so the agent (and any follow-up turns) can tell what started the conversation.
* The instruction is the place to tell the agent what to do with the event.
* The payload is **capped at 50,000 characters**; anything longer is truncated.

Providing a `transform` overrides all of this:

* **Return a string** → the agent's message becomes `[Trigger: <name>] <your string>`. The trigger's instruction is *not* applied — your transform owns the message. This is the way to forward hand-picked fields from large payloads instead of hitting the 50k cap.
* **Return an invocation input object** → you own the entire turn: message content, `userId` (to run as a specific user with conversation history), `threadId`, `systemPrompt`, and so on. The channel is always recorded as `trigger`.

```typescript theme={null}
// Full-control transform: run the turn as a specific user
transform: (ctx) => ({
  prompt: `Order ${ctx.body.orderId} was refunded. Apologise and offer a discount code.`,
  userId: ctx.body.customerId,   // conversation history is stored for this user
})
```

A transform-supplied `userId` takes precedence over the trigger's own bound user — see [Who the trigger turn runs as](#who-the-trigger-turn-runs-as).

## Who the trigger turn runs as

Every trigger has a **bound user**, and the agent turn it fires runs as that person:

* A trigger you create yourself — `lua push` of a `LuaTrigger`, or `lua triggers create` — binds **you**, the developer who created it.
* A trigger that arrives with an installed [template](/marketplace/agent-templates) binds **the installer**.

The binding is what makes user-scoped work inside a trigger-fired turn land on the right desk: an [`Inbox.push`](/api/inbox) from a tool running in the turn reaches the bound user, `User` reads and writes act on them, and the conversation lands in their history — instead of a context-less system run.

**Identity precedence**, highest first:

1. **A transform-supplied `userId`.** A `transform` that returns a full invocation input with `userId` owns the turn's identity — the SDK author's explicit choice always wins.
2. **The trigger's bound user.** The default when the transform sets no `userId` (or there is no transform).
3. **System.** With no transform `userId` and no binding, the turn runs with a system identity and no ambient user.

Three things the binding never does:

* **It never comes from the request.** The bound user is set server-side when the trigger is created or installed — nothing in the webhook payload, headers, or URL can choose or change who the turn runs as.
* **It doesn't survive duplication.** Duplicating an agent gives the copy's triggers fresh URLs and **no bound user** — a copy must never fire as the original's owner. Its turns run with system identity until the binding is re-established (re-create the trigger, or re-install the template on the copy).
* **It doesn't outlive the user.** If the bound user's account is offboarded, the binding is cleared and the trigger falls back to system identity rather than acting for someone who left.

## Trigger URLs and Token Security

Every trigger gets a URL of the form:

```
https://trigger.heylua.ai/trigger/{agentId}/{token}
```

* The **token is the secret** — anyone who has the full URL can fire the trigger (subject to your `verify` slot). Treat the URL like a credential.
* Unknown agent, unknown token, or a mismatched pair all return the **same 404** — the URL shape leaks nothing about which part was wrong.
* If a URL leaks, rotate it: `lua triggers rotate-token --trigger <name>`. The old URL stops working immediately and the CLI prints the new one.

<Warning>
  A trigger **without** a `verify` slot accepts any request that has the URL. That is fine for low-stakes automation glue, but for anything that causes real side effects, add a `verify` slot with a proper signature check — don't rely on URL secrecy alone.
</Warning>

### Agents know their own URL

When an agent is installed from a [template](/marketplace/agent-templates), the platform writes each webhook trigger's per-install URL into the agent's environment as `LUA_TRIGGER_URL__<TRIGGER_KEY>` — the trigger key upper-snaked, so `github-pr-assigned` becomes `LUA_TRIGGER_URL__GITHUB_PR_ASSIGNED`. The variable is readable with [`env()`](/api/environment) from tools **and** from trigger slots, is rewritten if the trigger's token is rotated, and is removed when the template is uninstalled.

This is what makes **zero-input webhook setup** possible: instead of the installer copying a URL into a provider's settings screen, a setup tool in the template reads its own URL and registers it with the provider itself.

```typescript theme={null}
import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

export class SetupWebhookTool implements LuaTool {
  name = 'setup_webhook';
  description = 'Register this agent\'s trigger URL with the provider.';
  inputSchema = z.object({});

  async execute() {
    // Read at call time — the platform rewrites this on token rotation.
    const triggerUrl = env('LUA_TRIGGER_URL__ORDER_CREATED')?.trim();
    if (!triggerUrl) {
      return { ok: false, message: 'No injected trigger URL — was this agent installed from a template?' };
    }
    return registerProviderWebhook(triggerUrl); // your provider API call
  }
}
```

The `LUA_TRIGGER_URL__` prefix is **reserved**: a template's env contract cannot declare keys under it (publishing rejects them), and a hand-set variable of the same name is overwritten with the platform's URL at install. The full pattern — pairing the injected URL with a post-install setup turn — is in [Publishing Templates](/marketplace/publishing-templates#self-wiring-webhooks).

## Complete Example: GitHub Pull Request Trigger

A production-shaped trigger: HMAC signature verification over the raw bytes, a filter that only lets through PRs assigned to a configured user, and a compact transform (a raw GitHub PR payload is enormous and mostly noise for the agent).

```typescript theme={null}
import { defineTrigger, env } from 'lua-cli';
import { createHmac, timingSafeEqual } from 'crypto';

interface GitHubPullRequestEvent {
  action?: string;
  assignee?: { login?: string };
  pull_request?: {
    number?: number;
    title?: string;
    html_url?: string;
  };
  repository?: { full_name?: string };
}

/** Constant-time comparison; length mismatch short-circuits (length is not secret). */
function safeEqual(expected: string, provided: string): boolean {
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(provided, 'utf8');
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

export default defineTrigger<GitHubPullRequestEvent>({
  name: 'github-pr-assigned',
  description: 'Wakes the agent when a GitHub PR is assigned to the configured user',
  source: 'webhook',

  // GitHub signs the exact wire bytes → verify against ctx.rawBody
  verify: (ctx) => {
    const secret = env('GITHUB_WEBHOOK_SECRET');
    const signature = ctx.headers['x-hub-signature-256'];
    if (!secret || !ctx.rawBody || typeof signature !== 'string') return false;
    const expected = 'sha256=' + createHmac('sha256', secret).update(ctx.rawBody, 'utf8').digest('hex');
    return safeEqual(expected, signature);
  },

  // Only wake the agent when a PR is assigned to our user
  filter: (ctx) => {
    const body = ctx.body ?? {};
    if (body.action !== 'assigned') return false;
    const configured = (env('GITHUB_USERNAME') ?? '').trim().toLowerCase();
    return !!configured && body.assignee?.login?.toLowerCase() === configured;
  },

  // Hand-pick fields — the raw payload is huge and would just waste the
  // agent's context (and risk the ~50k default-payload cap)
  transform: (ctx) => {
    const pr = ctx.body.pull_request ?? {};
    const repo = ctx.body.repository?.full_name ?? 'unknown/unknown';
    return [
      `PR assigned on GitHub: ${repo}#${pr.number ?? '?'}`,
      `Title: ${pr.title ?? '(no title)'}`,
      `URL: ${pr.html_url ?? '(no url)'}`,
      `Review it now and post a summary of the risk areas.`,
    ].join('\n');
  },
});
```

Configure the trigger URL and the same secret in your repository's webhook settings (Repository → Settings → Webhooks, content type `application/json`), and set `GITHUB_WEBHOOK_SECRET` and `GITHUB_USERNAME` with [`lua env`](/cli/env-command).

## Minimal Example: Filter Only

The smallest useful trigger — no verification, no transform, just a relevance gate. The agent receives the default `[Trigger: …] Payload: …` message.

```typescript theme={null}
import { defineTrigger } from 'lua-cli';

export default defineTrigger({
  name: 'deployment-finished',
  description: 'Wakes the agent when a deployment completes',
  filter: (ctx) => ctx.body?.status === 'succeeded' || ctx.body?.status === 'failed',
});
```

<Warning>
  This trigger accepts any POST that has the URL — there is no `verify` slot. Acceptable for internal tooling behind URL secrecy; not acceptable for anything a third party could abuse. Rotate the token immediately if the URL leaks.
</Warning>

## Using with LuaAgent

Register triggers on your agent configuration:

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import githubPrAssigned from './triggers/pr-assigned.trigger';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [...],

  triggers: [
    githubPrAssigned,
  ],
});
```

On `lua push`, each trigger is compiled, versioned, and deployed like any other primitive, and your `lua.skill.yaml` gains a `triggers:` section tracking the deployed name, ID, and version:

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

## Observability

Every delivery — invoked, filtered, rejected, or failed — is recorded as an execution. Inspect them with the CLI:

```bash theme={null}
lua triggers logs --trigger github-pr-assigned
lua triggers logs --trigger github-pr-assigned --limit 5 --json
```

| Status                | Meaning                                                                      |
| --------------------- | ---------------------------------------------------------------------------- |
| `accepted`            | Slots passed; the agent turn is in flight                                    |
| `completed`           | The agent turn finished; the response text is stored on the execution        |
| `failed`              | A slot threw, the transform returned nothing, or the agent invocation failed |
| `rejected_unverified` | `verify` returned `false` (sender saw 401)                                   |
| `skipped_filtered`    | `filter` returned `false` (sender saw 200)                                   |
| `skipped_inactive`    | Trigger was deactivated at delivery time                                     |

See the [Triggers Command](/cli/triggers-command) for the full management workflow — listing, creating URL triggers, activating, rotating tokens, and deleting.

## Related APIs

<CardGroup>
  <Card title="Triggers Command" href="/cli/triggers-command" icon="terminal">
    Manage triggers from the CLI — list, logs, rotate-token
  </Card>

  <Card title="LuaWebhook" href="/api/luawebhook" icon="webhook">
    Full request/response control with your own execute function
  </Card>

  <Card title="LuaJob" href="/api/luajob" icon="clock">
    Scheduled and queued background work
  </Card>

  <Card title="Environment Variables" href="/api/environment">
    env('KEY') — secrets for your verify slot
  </Card>
</CardGroup>

## See Also

* [LuaAgent](/api/luaagent) - Registering triggers on your agent
* [LuaWebhook](/api/luawebhook) - When you need to own the HTTP response
* [Triggers Command](/cli/triggers-command) - CLI management and the paste-anywhere URL workflow


# LuaWebhook
Source: https://docs.heylua.ai/api/luawebhook

HTTP endpoints for receiving external events and integrations

## Overview

`LuaWebhook` allows you to create HTTP endpoints that can receive events from external services like Stripe, Shopify, GitHub, or any other webhook-enabled platform.

```typescript theme={null}
import { LuaWebhook, User } from 'lua-cli';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  description: 'Handle Stripe payment events',
  execute: async (event) => {
    const { body } = event;

    // ⚠️ Webhooks have NO conversational context
    // MUST provide userId to notify users
    
    if (body?.type === 'payment_intent.succeeded') {
      const customerId = body.data?.object?.metadata?.customerId;
      if (customerId) {
        const user = await User.get(customerId);
        await user.send([{
          type: 'text',
          text: '✅ Payment confirmed!'
        }]);
      }
    }
    return { received: true };
  }
});

export default paymentWebhook;
```

<Warning>
  **No Conversational Context:** Webhooks execute outside of user conversations. You MUST use `User.get(userId)` with an explicit userId. Always store the user ID in your payment/order metadata.
</Warning>

<Note>
  HTTP webhooks for external integrations. Use with LuaAgent.
</Note>

## Webhooks vs Triggers

A `LuaWebhook` gives you an `execute` function and full control of the HTTP response — your code does the work. A [`LuaTrigger`](/api/luatrigger) has **no** `execute` function: it declaratively verifies, filters, and transforms an incoming event, then wakes the agent to do the work itself. If the right reaction to an event is "have the agent handle it", reach for a trigger; if you need a custom response body or code-only side effects, stay here. See [LuaTrigger](/api/luatrigger) for the full comparison.

## Use Cases

<CardGroup>
  <Card title="Payment Events" icon="credit-card">
    Stripe, PayPal webhooks for payment processing
  </Card>

  <Card title="E-commerce Updates" icon="cart-shopping">
    Shopify, WooCommerce order notifications
  </Card>

  <Card title="Git Events" icon="code-branch">
    GitHub, GitLab deployment triggers
  </Card>

  <Card title="Custom Integrations" icon="plug">
    Any service that sends HTTP webhooks
  </Card>
</CardGroup>

## User Access in Webhooks

| Context      | How to Get User      | userId Required?              |
| ------------ | -------------------- | ----------------------------- |
| **Webhooks** | `User.get(userId)`   | ✅ **YES** - Store in metadata |
| **Tools**    | `User.get()`         | ❌ No - automatic context      |
| **LuaJob**   | `User.get(userId)`   | ✅ **YES** - Store in metadata |
| **Jobs API** | `jobInstance.user()` | ❌ No - automatic context      |

<Warning>
  **Webhooks are context-less:** They're triggered by external systems, not user conversations. Always store the Lua user ID in your payment/order metadata so you can notify the right user.
</Warning>

## Constructor

### new LuaWebhook(config)

Creates a new webhook endpoint.

<ParamField type="LuaWebhookConfig">
  Webhook configuration object
</ParamField>

## Configuration Parameters

### Required Fields

<ParamField type="string">
  Unique webhook name

  **Format**: lowercase, hyphens, underscores

  **Examples**: `'payment-webhook'`, `'order-update-webhook'`
</ParamField>

<ParamField type="function">
  Function that handles incoming webhook events

  **Signature:** `(event: WebhookEvent) => Promise<any>`

  ```typescript theme={null}
  execute: async (event) => {
    const { query, headers, body } = event;
    // ...
  }
  ```
</ParamField>

### Optional Fields

<ParamField type="string">
  Webhook description for documentation
</ParamField>

<ParamField type="string">
  HMAC-SHA256 signing key. When set, every request must carry `x-lua-signature: sha256=<hex HMAC-SHA256 of the raw body>` or it is rejected with **401** before `execute` runs. Must be a literal or a build-time-resolvable constant. Rotate by changing the value and re-deploying; set to `''` to turn verification off. See [Verify Requests](/overview/webhooks#verify-requests).
</ParamField>

## WebhookEvent Shape

Every webhook receives a single object with request details:

```typescript theme={null}
interface WebhookEvent {
  query: Record<string, any>;
  headers: Record<string, any>;
  body: any;
  timestamp: string;
  execution?: {
    eventId: string;      // stable idempotency key — survives retries & redeliveries
    executionId: string;  // unique per attempt
    attempt: number;      // 1-based attempt counter
  };
}
```

Destructure the pieces you need inside your handler:\
`const { query, headers, body, timestamp } = event;`

<Note>
  `execution` is present only when your handler is invoked via a durably-delivered [platform event](#event-subscriptions). It is `undefined` for synchronous requests sent directly to your webhook URL and during local `lua test` / `lua dev` runs. See [Delivery Semantics](#delivery-semantics).
</Note>

## Complete Examples

### Stripe Payment Webhook

```typescript theme={null}
import { LuaWebhook, env, Orders, User } from 'lua-cli';

const stripeWebhook = new LuaWebhook({
  name: 'stripe-payment-webhook',
  description: 'Handle Stripe payment events',
  
  execute: async (event) => {
    const { body } = event;
    console.log('Stripe event:', body?.type);
    
    switch (body?.type) {
      case 'payment_intent.succeeded':
        const paymentIntent = body.data?.object;
        
        // Update order status
        const order = await Orders.getById(paymentIntent.metadata.orderId);
        if (order) {
          await order.updateStatus('CONFIRMED');
          
          // Get user by ID from payment metadata
          const customerId = paymentIntent.metadata.customerId;
          const user = await User.get(customerId);
          
          // Notify the specific user
          await user.send([{
            type: 'text',
            text: `✅ Payment confirmed! Order #${order.id} is being processed. Amount: $${paymentIntent.amount/100}`
          }]);
        }
        
        return { success: true, orderId: order?.id };
        
      case 'payment_intent.payment_failed':
        const failed = body.data?.object;
        console.error('Payment failed:', failed);
        
        // Notify user of failure
        const failedCustomerId = failed.metadata.customerId;
        if (failedCustomerId) {
          const user = await User.get(failedCustomerId);
          await user.send([{
            type: 'text',
            text: `❌ Payment failed: ${failed.last_payment_error?.message}. Please try again.`
          }]);
        }
        
        return { success: false, reason: failed.last_payment_error?.message };
        
      default:
        console.log('Unhandled event type:', body?.type);
        return { received: true };
    }
  }
});

export default stripeWebhook;
```

<Note>
  **Important:** Always store the user ID (customerId) in your payment metadata so webhooks can notify the correct user. Example: `metadata: { customerId: user.id, orderId: order.id }`
</Note>

### Shopify Order Webhook

```typescript theme={null}
import { LuaWebhook, env, Data, User } from 'lua-cli';

const shopifyOrderWebhook = new LuaWebhook({
  name: 'shopify-order-webhook',
  description: 'Handle Shopify order events',
  
  execute: async (event) => {
    const { body } = event;
    const order = body;
    
    // Store order in custom data
    await Data.create('shopify-orders', {
      orderId: order.id,
      orderNumber: order.order_number,
      customer: order.customer,
      total: order.total_price,
      items: order.line_items,
      status: order.financial_status,
      customerId: order.customer.id,  // Store customer ID
      createdAt: order.created_at
    }, `Order #${order.order_number} ${order.customer.email} ${order.total_price}`);
    
    // Notify specific customer using their ID
    const user = await User.get(order.customer.id);
    await user.send([{
      type: 'text',
      text: `🛍️ Order #${order.order_number} confirmed!\n\nTotal: $${order.total_price}\nItems: ${order.line_items.length}\n\nWe'll send shipping updates soon!`
    }]);
    
    return {
      success: true,
      orderId: order.id,
      orderNumber: order.order_number,
      customerId: order.customer.id
    };
  }
});

export default shopifyOrderWebhook;
```

<Note>
  **Customer Identification:** Map external customer IDs (Shopify, Stripe) to Lua user IDs. Store this mapping in your order/payment metadata for webhook notifications.
</Note>

### GitHub Deployment Webhook

```typescript theme={null}
import { LuaWebhook, env, User } from 'lua-cli';

const githubWebhook = new LuaWebhook({
  name: 'github-deployment-webhook',
  description: 'Track GitHub deployment events',
  
  execute: async (event) => {
    const { body } = event;
    const payload = body;
    
    if (payload?.action === 'deployment_status') {
      const status = payload.deployment_status;
      const deployment = payload.deployment;
      
      // Notify on deployment completion
      // Note: You need to provide userId - webhooks have no conversational context
      if (status.state === 'success') {
        // In a real scenario, you'd get userId from deployment metadata
        // const user = await User.get(userId);
        // await user.send([{
        //   type: 'text',
        //   text: `🚀 Deployment successful!\n\nEnvironment: ${deployment.environment}\nRef: ${deployment.ref}\nURL: ${status.target_url}`
        // }]);
        console.log('Deployment successful:', deployment.environment);
      } else if (status.state === 'failure') {
        console.error('Deployment failed:', deployment.environment);
      }
      
      return { success: true, state: status.state };
    }
    
    return { received: true };
  }
});

export default githubWebhook;
```

### Generic Webhook Template

```typescript theme={null}
import { LuaWebhook, env } from 'lua-cli';

const genericWebhook = new LuaWebhook({
  name: 'custom-integration-webhook',
  description: 'Handle events from custom service',
  
  execute: async (event) => {
    const { query, headers, body } = event;
    try {
      // Validate event structure
      if (!body || !body.type) {
        throw new Error('Invalid event structure');
      }
      
      // Log event for debugging
      console.log('Received webhook:', {
        type: body.type,
        timestamp: new Date().toISOString(),
        dataKeys: Object.keys(body.data || {})
      });
      
      // Process event based on type
      switch (body.type) {
        case 'resource.created':
          await handleCreate(body.data);
          break;
          
        case 'resource.updated':
          await handleUpdate(body.data);
          break;
          
        case 'resource.deleted':
          await handleDelete(body.data);
          break;
          
        default:
          console.log('Unknown event type:', body.type);
      }
      
      return { success: true, processed: body.type };
      
    } catch (error) {
      console.error('Webhook processing error:', error);
      
      return {
        success: false,
        error: error.message,
        timestamp: new Date().toISOString()
      };
    }
  }
});

async function handleCreate(data: any) {
  // Handle creation logic
  console.log('Resource created:', data.id);
}

async function handleUpdate(data: any) {
  // Handle update logic
  console.log('Resource updated:', data.id);
}

async function handleDelete(data: any) {
  // Handle deletion logic
  console.log('Resource deleted:', data.id);
}

export default genericWebhook;
```

## Event Subscriptions

Webhooks can subscribe to **platform events**: delivery status updates for every outbound channel (WhatsApp, SMS, email, Messenger, Instagram, and the rest). When subscribed, your webhook's `execute` function receives the event payload automatically.

### Available Event Types

| Event               | Trigger                                                                              |
| ------------------- | ------------------------------------------------------------------------------------ |
| `message.sent`      | The provider accepted the message                                                    |
| `message.delivered` | The message reached the recipient (channels that report delivery)                    |
| `message.read`      | The recipient read the message (channels that report reads)                          |
| `message.failed`    | The message could not be delivered; `error` carries the category and provider detail |

Channels without receipts (Slack, Teams, Front, web chat) stop at `message.sent`.

### Subscribing via CLI

```bash theme={null}
lua webhooks list-events
lua webhooks subscribe --webhook-name my-webhook --event message.delivered
lua webhooks subscribe --webhook-name my-webhook --event message.read
lua webhooks unsubscribe --webhook-name my-webhook --event message.delivered
```

### Event Payload Shape

When an event fires, your webhook receives a `WebhookEvent` where `body` is the delivery record, the same object `Channels.getStatus` returns:

```typescript theme={null}
interface DeliveryEventPayload {
  id: string;                 // deliveryId, also returned by Channels.*.send
  agentId: string;
  userId?: string;
  channel: string;            // 'whatsapp' | 'sms' | 'email' | 'messenger' | ...
  provider: string;           // 'meta' | 'vonage' | 'bird' | 'ses' | ...
  channelIdentifier: string;  // the sending phone number, inbox, or page
  recipient: string;
  providerMessageId?: string;
  messageWamid?: string;      // same as providerMessageId, kept for existing WhatsApp handlers
  conversationMessageId?: string;
  origin: 'agent_reply' | 'channels_send' | 'template' | 'system_template' | 'queued_flush' | 'admin_template' | 'notification' | 'unknown';
  templateName?: string;
  idempotencyKey?: string;
  status: 'queued' | 'accepted' | 'sent' | 'delivered' | 'read' | 'failed' | 'expired';
  error?: {
    category: 'window_closed' | 'unreachable' | 'billing' | 'opted_out' | 'throttled' | 'auth' | 'template' | 'media' | 'invalid_request' | 'compliance' | 'experiment' | 'provider' | 'unknown';
    provider: string;
    code: string;       // provider's own code, e.g. Meta 131042
    title: string;
    detail?: string;
  };
  events: Array<{ status: string; at: string; source: 'send' | 'callback' | 'sweep' }>;
  pricing?: { billable: boolean; category?: string; model?: string };
  createdAt: string;
  updatedAt: string;
  deliveredAt?: string;
  readAt?: string;
  failedAt?: string;
}
```

### Delivery Semantics

Subscribed platform events are delivered **at least once**. Each event is durably queued and processed on isolated infrastructure with automatic retries — up to **3 attempts total**, a fixed 60-second wait between attempts, retried only on failure. Your handler may therefore run **more than once** for a single logical event, so keep side effects idempotent.

Each invocation receives `event.execution`:

| Field         | Description                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `eventId`     | Stable identifier for the logical event. Unchanged across retries and redeliveries — use it as your idempotency / dedup key. |
| `executionId` | Unique identifier for this individual attempt. Not a dedup key.                                                              |
| `attempt`     | 1-based attempt counter (`1` on the first delivery, `2` on the first retry, and so on).                                      |

```typescript theme={null}
execute: async (event) => {
  const { eventId } = event.execution ?? {};

  // Key side effects on eventId so a repeated delivery is a no-op
  await Data.create('delivery-events', {
    idempotencyKey: eventId,
    status: event.body.status,
  }, `${event.body.status} ${eventId}`);

  return { received: true };
}
```

<Note>
  `event.execution` is only present for durably-delivered platform events — it is `undefined` for synchronous direct requests to your webhook URL and during local `lua test` / `lua dev` runs. Very large event payloads (over 50,000 characters, which is rare) are delivered without the at-least-once retry guarantee.
</Note>

<Warning>
  **Direct requests are unchanged.** Requests sent straight to your webhook URL are still handled **synchronously** with no automatic retries — the caller receives your handler's return value and applies its own retry policy. At-least-once delivery and `event.execution` apply only to subscribed platform events.
</Warning>

### Example: Track Delivery for Analytics

```typescript theme={null}
import { LuaWebhook, Data } from 'lua-cli';

const analyticsWebhook = new LuaWebhook({
  name: 'message-analytics',
  description: 'Track message delivery for analytics',
  
  execute: async (event) => {
    const { body } = event;
    
    await Data.create('message-analytics', {
      messageId: body.messageWamid,
      recipient: body.recipientId,
      status: body.status,
      channel: body.channel,
      timestamp: body.timestamp,
      billable: body.pricing?.billable
    }, `${body.status} ${body.recipientId}`);
    
    return { tracked: true };
  }
});

export default analyticsWebhook;
```

## Using with LuaAgent

Webhooks are added to your agent configuration:

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import stripeWebhook from './webhooks/stripe';
import shopifyWebhook from './webhooks/shopify';
import githubWebhook from './webhooks/github';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [...],
  
  webhooks: [
    stripeWebhook,
    shopifyWebhook,
    githubWebhook
  ]
});
```

## Webhook URLs

After deploying, your webhooks can be called using either identifier:

```
https://webhook.heylua.ai/{agentId}/{webhookId}    // legacy + default
https://webhook.heylua.ai/{agentId}/{webhook-name} // friendly alias
```

**Notes:**

* `agentId` is your agent identifier (e.g., `agent_abc123`)
* `webhookId` is the UUID shown when you create the webhook
* `webhook-name` is the `name` you pass to `new LuaWebhook`
* You can copy both URLs after pushing: `lua push webhook`

**Examples:**

```
https://webhook.heylua.ai/agent_abc123/webhook_01JD3RZ9VX9W5
https://webhook.heylua.ai/agent_abc123/payment-webhook
```

Configure either URL in your external service (Stripe, Shopify, etc.)

## Testing Webhooks

### Local Testing

```bash theme={null}
lua test
# Select: Webhook → your-webhook-name
# Provide test payload
```

### Test Payloads

```typescript theme={null}
// Example test payload for Stripe
{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_test_123",
      "amount": 2000,
      "currency": "usd",
      "metadata": {
        "orderId": "order_456"
      }
    }
  }
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="✅ Use Environment Variables">
    Never hardcode secrets

    ```typescript theme={null}
    // ❌ Bad
    secret: 'hardcoded_secret_key'

    // ✅ Good
    secret: env('STRIPE_WEBHOOK_SECRET')
    ```
  </Accordion>

  <Accordion title="✅ Validate Webhook Structure">
    Always validate incoming data

    ```typescript theme={null}
    execute: async (event) => {
      const { body } = event;
      if (!body || !body.type) {
        throw new Error('Invalid webhook payload');
      }
      // Process webhook...
    }
    ```
  </Accordion>

  <Accordion title="✅ Return Quickly">
    Webhook handlers should return fast (\< 5 seconds)

    ```typescript theme={null}
    // ✅ Queue long-running work
    execute: async (event) => {
      const { body } = event;

      // Quick validation
      if (!isValid(body)) {
        return { error: 'Invalid' };
      }
      
      // Queue processing job
      await Jobs.create({
        execute: async () => {
          // Long-running work here
        }
      });
      
      return { received: true };
    }
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

```typescript theme={null}
const robustWebhook = new LuaWebhook({
  name: 'robust-webhook',
  
  execute: async (event) => {
    try {
      const result = await processWebhook(event);
      
      return {
        success: true,
        result,
        timestamp: new Date().toISOString()
      };
      
    } catch (error) {
      // Log error for debugging
      console.error('Webhook error:', {
        error: error.message,
        stack: error.stack
      });
      
      // Return error status (don't throw!)
      return {
        success: false,
        error: error.message,
        timestamp: new Date().toISOString()
      };
    }
  }
});
```

## Invoking an Agent from a Webhook

Use `Agents.invoke` to delegate work to a conversational agent after receiving a webhook event. Pass the user ID from the event payload so the invocation runs in that user's context (conversation history is stored). If no user ID is available, omit `userId` and the invocation runs without user identity (no conversation history).

```typescript theme={null}
import { LuaWebhook, Agents } from 'lua-cli';

const orderShippedWebhook = new LuaWebhook({
  name: 'order-shipped-webhook',
  description: 'Delegate shipment notifications to the notification agent',

  execute: async (event) => {
    const { orderId, customerId, trackingNumber } = event.body ?? {};

    if (!customerId) {
      return { skipped: true, reason: 'no customerId in payload' };
    }

    const result = await Agents.invoke('notification-agent', {
      prompt: `Order ${orderId} has shipped. Tracking: ${trackingNumber}. Notify the customer.`,
      userId: customerId, // runs as this user — history is stored
    });

    return { notified: true, agentReply: result.text };
  },
});

export default orderShippedWebhook;
```

<Card title="Agents API Reference" href="/api/agents" icon="robot">
  Full documentation for Agents.invoke — options, output shape, error handling, and more examples
</Card>

## Common Integrations

<Tabs>
  <Tab title="Stripe">
    **Webhook Events:**

    * `payment_intent.succeeded`
    * `payment_intent.payment_failed`
    * `charge.refunded`
    * `invoice.payment_succeeded`

    **Secret Location:** Stripe Dashboard → Developers → Webhooks
  </Tab>

  <Tab title="Shopify">
    **Webhook Topics:**

    * `orders/create`
    * `orders/updated`
    * `products/create`
    * `products/delete`

    **Secret Location:** Shopify Admin → Settings → Notifications
  </Tab>

  <Tab title="GitHub">
    **Webhook Events:**

    * `push`
    * `pull_request`
    * `deployment_status`
    * `release`

    **Secret Location:** Repository → Settings → Webhooks
  </Tab>

  <Tab title="Custom">
    **Requirements:**

    * POST request to webhook URL
    * JSON payload in body
    * Optional signature verification
    * Event type in payload or header

    **Best Practices:**

    * Include timestamp
    * Version your payloads
    * Support replay/retry
  </Tab>
</Tabs>

## Related APIs

<CardGroup>
  <Card title="LuaAgent" href="/api/luaagent" icon="robot">
    Agent configuration
  </Card>

  <Card title="LuaTrigger" href="/api/luatrigger" icon="bolt">
    Declarative triggers that wake the agent instead of running code
  </Card>

  <Card title="Agents API" href="/api/agents" icon="robot">
    Invoke another agent from a webhook
  </Card>

  <Card title="Jobs API" href="/api/jobs" icon="clock">
    Queue long-running work
  </Card>

  <Card title="User API" href="/api/user" icon="user">
    Send notifications
  </Card>

  <Card title="Data API" href="/api/data" icon="database">
    Store webhook data
  </Card>
</CardGroup>

## See Also

* [LuaAgent](/api/luaagent) - Adding webhooks to your agent
* [LuaTrigger](/api/luatrigger) - Wake the agent on an event, no execute function
* [Agents API](/api/agents) - Invoking agents from webhook handlers
* [Environment Variables](/api/environment) - Securely managing secrets
* [Workflows Concept](/concepts/workflows)


# Orders API
Source: https://docs.heylua.ai/api/orders

Order creation and management

## Overview

The Orders API manages order creation, status tracking, and fulfillment. Returns **OrderInstance** objects with direct property access.

```typescript theme={null}
import { Orders, OrderStatus } from 'lua-cli';

// Create order - returns OrderInstance
const order = await Orders.create({
  basketId: 'basket_abc123',
  data: { shippingAddress, paymentMethod }
});

// Direct property access
console.log(order.status);       // "pending"
console.log(order.totalAmount);  // 59.98
console.log(order.items);        // Array of items

// Instance methods
await order.updateStatus(OrderStatus.FULFILLED);
await order.update({ trackingNumber: 'ABC123' });
await order.save();

// Access updated properties
console.log(order.status);          // "fulfilled"
console.log(order.trackingNumber);  // "ABC123"
```

<CardGroup>
  <Card title="Direct Access" icon="bolt">
    Access `order.status` not `order.common.status`
  </Card>

  <Card title="Instance Methods" icon="wrench">
    Built-in `updateStatus()`, `update()`, and `save()` methods
  </Card>

  <Card title="Auto-Sync" icon="sync">
    Properties update after method calls
  </Card>

  <Card title="Type-Safe" icon="shield">
    Full TypeScript support
  </Card>
</CardGroup>

## Order Statuses

```typescript theme={null}
import { OrderStatus } from 'lua-cli';
```

<Steps>
  <Step title="PENDING">
    Order created, not yet confirmed

    Initial status for new orders
  </Step>

  <Step title="CONFIRMED">
    Order confirmed, being processed

    Payment successful, ready for fulfillment
  </Step>

  <Step title="FULFILLED">
    Order completed and delivered

    Final status for successful orders
  </Step>

  <Step title="CANCELLED">
    Order cancelled by user or system

    No further processing
  </Step>
</Steps>

## Methods

### create()

Create a new order.

```typescript theme={null}
Orders.create(orderData: CreateOrderRequest): Promise<OrderInstance>
```

<ParamField type="string">
  ID of the basket to convert to order
</ParamField>

<ParamField type="object">
  Order details (shipping, payment, etc.)
</ParamField>

**Returns:** `OrderInstance` with direct property access and methods

**Example:**

```typescript theme={null}
const order = await Orders.create({
  basketId: 'basket_abc123',
  data: {
    shippingAddress: {
      street: '123 Main St',
      city: 'New York',
      zip: '10001'
    },
    paymentMethod: 'stripe',
    customerEmail: 'customer@example.com'
  }
});

// Direct property access
console.log(order.id);          // "order_def456"
console.log(order.status);      // "pending"
console.log(order.totalAmount); // 59.98
console.log(order.items);       // Array of items
console.log(order.shippingAddress.city); // "New York"

// Instance methods available
await order.updateStatus(OrderStatus.CONFIRMED);
```

### get()

Retrieve orders, optionally filtered by status.

```typescript theme={null}
Orders.get(status?: OrderStatus): Promise<OrderInstance[]>
```

**Examples:**

```typescript theme={null}
// Get all orders
const allOrders = await Orders.get();

// Get pending orders only
const pending = await Orders.get(OrderStatus.PENDING);

// Get fulfilled orders
const fulfilled = await Orders.get(OrderStatus.FULFILLED);
```

### getById()

Get a specific order by ID.

```typescript theme={null}
Orders.getById(orderId: string): Promise<OrderInstance>
```

**Returns:** `OrderInstance` with direct property access

**Example:**

```typescript theme={null}
const order = await Orders.getById('order_def456');

// Direct property access (no .common needed!)
console.log(order.status);       // "fulfilled"
console.log(order.totalAmount);  // 59.98
console.log(order.items);        // Array of items
console.log(order.shippingAddress); // Address object

// Instance methods
await order.updateStatus(OrderStatus.FULFILLED);
await order.update({ deliveryDate: '2025-10-15' });
```

### updateStatus()

Update order status.

```typescript theme={null}
Orders.updateStatus(status: OrderStatus, orderId: string): Promise<OrderResponse>
```

Or use instance method:

```typescript theme={null}
order.updateStatus(status: OrderStatus): Promise<OrderInstance>
```

**Returns:** `OrderInstance` with updated status

**Example:**

```typescript theme={null}
// Using static method
const order = await Orders.updateStatus(OrderStatus.CONFIRMED, orderId);

// Or using instance method (recommended)
await order.updateStatus(OrderStatus.CONFIRMED);
await order.updateStatus(OrderStatus.FULFILLED);
await order.updateStatus(OrderStatus.FULFILLED);

// Access updated status directly
console.log(order.status); // "fulfilled"

// Cancel order
await order.updateStatus(OrderStatus.CANCELLED);
```

### updateData()

Update order data/metadata.

```typescript theme={null}
Orders.updateData(data: Record<string, any>, orderId: string): Promise<OrderResponse>
```

**Example:**

```typescript theme={null}
await Orders.updateData({
  trackingNumber: 'TRACK123456',
  carrier: 'UPS',
  estimatedDelivery: '2025-10-10',
  notes: 'Fragile - handle with care'
}, orderId);
```

### save() (Instance Method)

Save the current state of the order to the server. This is a convenience method that persists all changes made to the order instance.

```typescript theme={null}
order.save(): Promise<boolean>
```

**Returns:** Promise resolving to `true` if successful

**Example:**

```typescript theme={null}
const order = await Orders.getById('order_def456');

// Modify order data properties
order.trackingNumber = 'TRACK123456';
order.carrier = 'UPS';
order.estimatedDelivery = '2025-10-10';

// Save all changes at once
await order.save();

// Much cleaner workflow!
```

<Note>
  **New in Latest Version:** The `save()` method provides a simpler workflow - modify properties then save, rather than calling `Orders.updateData()` with the order ID.
</Note>

## OrderInstance

All order methods return `OrderInstance` objects with:

**Direct Property Access:**

```typescript theme={null}
order.id
order.status          // No .common needed!
order.totalAmount     // Direct access
order.itemCount       // Direct access
order.items           // Array of items
order.currency
order.shippingAddress // Data property via proxy
order.paymentMethod   // Data property via proxy
order.createdAt       // Via proxy (from OrderData)
```

**Instance Methods:**

```typescript theme={null}
await order.updateStatus(OrderStatus.FULFILLED);
await order.update({ trackingNumber: 'ABC123' });
await order.save();
```

**Backward Compatible:**

```typescript theme={null}
order.status;         // ✅ New way
order.common.status;  // ✅ Old way still works
```

## Complete Examples

### Create Order Tool

```typescript theme={null}
import { LuaTool, Orders } from 'lua-cli';
import { z } from 'zod';

export class CreateOrderTool implements LuaTool {
  name = "create_order";
  description = "Create order from basket";
  
  inputSchema = z.object({
    basketId: z.string(),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      zip: z.string()
    }),
    paymentMethod: z.string().default('stripe')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const order = await Orders.create({
      basketId: input.basketId,
      data: {
        shippingAddress: input.shippingAddress,
        paymentMethod: input.paymentMethod
      }
    });
    
    return {
      orderId: order.id,
      status: order.common.status,
      total: `$${order.common.totalAmount.toFixed(2)}`,
      message: "Order created successfully!"
    };
  }
}
```

### Track Order Tool

```typescript theme={null}
export class TrackOrderTool implements LuaTool {
  name = "track_order";
  description = "Get order status and tracking info";
  
  inputSchema = z.object({
    orderId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const order = await Orders.getById(input.orderId);
    
    return {
      orderId: order.id,
      status: order.common.status,
      total: `$${order.common.totalAmount.toFixed(2)}`,
      itemCount: order.common.itemCount,
      trackingNumber: order.data?.trackingNumber,
      estimatedDelivery: order.data?.estimatedDelivery,
      message: this.getStatusMessage(order.common.status)
    };
  }
  
  private getStatusMessage(status: string): string {
    switch (status) {
      case 'pending': return 'Order is being processed';
      case 'confirmed': return 'Order confirmed and being prepared';
      case 'fulfilled': return 'Order delivered!';
      case 'cancelled': return 'Order was cancelled';
      default: return 'Unknown status';
    }
  }
}
```

### Update Order Status Tool

```typescript theme={null}
export class UpdateOrderStatusTool implements LuaTool {
  name = "update_order_status";
  description = "Update order fulfillment status";
  
  inputSchema = z.object({
    orderId: z.string(),
    status: z.enum(['pending', 'confirmed', 'fulfilled', 'cancelled'])
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const statusMap = {
      'pending': OrderStatus.PENDING,
      'confirmed': OrderStatus.CONFIRMED,
      'fulfilled': OrderStatus.FULFILLED,
      'cancelled': OrderStatus.CANCELLED
    };
    
    await Orders.updateStatus(statusMap[input.status], input.orderId);
    
    return {
      success: true,
      message: `Order status updated to ${input.status}`
    };
  }
}
```

## Use Cases

### Order Fulfillment Workflow

```typescript theme={null}
// 1. Create order
const order = await Orders.create({ basketId, data });

// 2. Confirm payment
await Orders.updateStatus(OrderStatus.CONFIRMED, order.id);

// 3. Add tracking info
await Orders.updateData({
  trackingNumber: 'TRACK123',
  carrier: 'UPS',
  shippedAt: new Date().toISOString()
}, order.id);

// 4. Mark as delivered
await Orders.updateStatus(OrderStatus.FULFILLED, order.id);
```

### Customer Service Lookup

```typescript theme={null}
// Find customer's orders
const userOrders = await Orders.get();

// Filter recent orders
const recent = userOrders.filter(order => {
  const orderDate = new Date(order.createdAt);
  const thirtyDaysAgo = new Date();
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
  return orderDate > thirtyDaysAgo;
});
```

### Order Analytics

```typescript theme={null}
// Get all orders
const orders = await Orders.get();

// Calculate metrics
const totalRevenue = orders.reduce((sum, order) => 
  sum + order.common.totalAmount, 0
);

const avgOrderValue = totalRevenue / orders.length;

const fulfillmentRate = orders.filter(o => 
  o.common.status === OrderStatus.FULFILLED
).length / orders.length;
```

## Best Practices

<AccordionGroup>
  <Accordion title="Store Tracking Information">
    ```typescript theme={null}
    await Orders.updateData({
      trackingNumber: 'TRACK123456',
      carrier: 'UPS',
      trackingUrl: 'https://track.ups.com/...',
      estimatedDelivery: '2025-10-10'
    }, orderId);
    ```
  </Accordion>

  <Accordion title="Send Status Notifications">
    ```typescript theme={null}
    async updateOrderStatus(orderId: string, status: OrderStatus) {
      // Update status
      await Orders.updateStatus(status, orderId);
      
      // Send notification
      const order = await Orders.getById(orderId);
      await sendEmail(order.data.customerEmail, {
        subject: `Order ${orderId} - ${status}`,
        body: getEmailTemplate(status, order)
      });
    }
    ```
  </Accordion>

  <Accordion title="Handle Cancellations Gracefully">
    ```typescript theme={null}
    async cancelOrder(orderId: string, reason: string) {
      const order = await Orders.getById(orderId);
      
      // Can only cancel if not fulfilled
      if (order.common.status === OrderStatus.FULFILLED) {
        throw new Error('Cannot cancel fulfilled order');
      }
      
      // Update status and add reason
      await Orders.updateStatus(OrderStatus.CANCELLED, orderId);
      await Orders.updateData({
        cancellationReason: reason,
        cancelledAt: new Date().toISOString()
      }, orderId);
    }
    ```
  </Accordion>

  <Accordion title="Validate Order Exists">
    ```typescript theme={null}
    const order = await Orders.getById(orderId);

    if (!order) {
      throw new Error(`Order not found: ${orderId}`);
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Baskets API" icon="cart-shopping" href="/api/baskets">
    Create baskets before orders
  </Card>

  <Card title="Order Examples" icon="layer-group" href="/examples/baskets">
    See complete order workflows
  </Card>
</CardGroup>


# API Overview
Source: https://docs.heylua.ai/api/overview

Complete API reference for building Lua AI skills

## Available APIs

Lua CLI provides a comprehensive set of APIs for building AI agents:

<CardGroup>
  <Card title="Core Classes" icon="puzzle-piece">
    **LuaAgent, LuaSkill, LuaTool** - Agent configuration and building blocks
  </Card>

  <Card title="Automation" icon="clock">
    **LuaJob, LuaWebhook** - Scheduled tasks and HTTP endpoints
  </Card>

  <Card title="Message Processing" icon="filter">
    **PreProcessor, PostProcessor** - Filter and format messages
  </Card>

  <Card title="External Tools" icon="plug">
    **LuaMCPServer** - Connect MCP servers for external tool integrations
  </Card>

  <Card title="Platform APIs" icon="server">
    **AI, Agents, User, Data, CDN, Products, Baskets, Orders, Jobs, Templates, Channels** - Built-in services
  </Card>

  <Card title="Environment" icon="key">
    **env()** - Secure configuration management
  </Card>
</CardGroup>

<Note>
  LuaAgent, LuaJob, LuaWebhook, PreProcessor, PostProcessor, and Jobs API for comprehensive agent development.
</Note>

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install lua-cli zod
  ```

  ```bash yarn theme={null}
  yarn add lua-cli zod
  ```

  ```bash pnpm theme={null}
  pnpm add lua-cli zod
  ```
</CodeGroup>

<Note>
  `zod` is a peer dependency required for schema validation
</Note>

## Quick Start

### Import APIs

```typescript theme={null}
// Core classes
import { 
  LuaAgent, 
  LuaSkill, 
  LuaTool, 
  LuaWebhook, 
  LuaJob,
  LuaMCPServer,
  PreProcessor,
  PostProcessor
} from 'lua-cli';

// Platform APIs
import { AI, Agents, User, Data, CDN, Products, Baskets, Orders, Jobs, Templates, Channels } from 'lua-cli';

// Utilities
import { env } from 'lua-cli';

// Type definitions
import { BasketStatus, OrderStatus } from 'lua-cli';

// Schema validation
import { z } from 'zod';
```

### Create an Agent

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaTool } from 'lua-cli';
import { z } from 'zod';

// Define a tool
class MyTool implements LuaTool {
  name = "my_tool";
  description = "What the tool does";
  inputSchema = z.object({
    param: z.string()
  });

  async execute(input: any) {
    return { result: "success" };
  }
}

// Create a skill
const skill = new LuaSkill({
  name: "my-skill",
  description: "My custom skill",
  context: "When to use this skill and its tools",
  tools: [new MyTool()]
});

// Create agent
export const agent = new LuaAgent({
  name: "my-agent",
  persona: "You are a helpful assistant...",
  skills: [skill]
});
```

## Core Classes

### Agent Configuration

<CardGroup>
  <Card title="LuaAgent" icon="robot" href="/api/luaagent">
    Unified agent configuration

    ```typescript theme={null}
    new LuaAgent({
      name: "my-agent",
      persona: "...",
      skills: [...],
      webhooks: [...],
      jobs: [...]
    })
    ```
  </Card>
</CardGroup>

### Building Blocks

<CardGroup>
  <Card title="LuaSkill" icon="puzzle-piece" href="/api/luaskill">
    Collection of related tools

    ```typescript theme={null}
    new LuaSkill({
      name: "skill-name",
      tools: [...]
    })
    ```
  </Card>

  <Card title="LuaTool" icon="wrench" href="/api/luatool">
    Individual function the AI can call

    ```typescript theme={null}
    class MyTool implements LuaTool {
      name = "tool_name"
      execute(input) { ... }
    }
    ```
  </Card>
</CardGroup>

### Automation

<CardGroup>
  <Card title="LuaWebhook" icon="webhook" href="/api/luawebhook">
    HTTP endpoints for external events

    ```typescript theme={null}
    new LuaWebhook({
      name: "payment-webhook",
      execute: async (event) => { ... }
    })
    ```
  </Card>

  <Card title="LuaJob" icon="clock" href="/api/luajob">
    Scheduled tasks

    ```typescript theme={null}
    new LuaJob({
      name: "daily-report",
      schedule: { type: "cron", pattern: "0 9 * * *" },
      execute: async (job) => { ... }
    })
    ```
  </Card>
</CardGroup>

### Message Processing

<CardGroup>
  <Card title="PreProcessor" icon="filter" href="/api/preprocessor">
    Filter messages before agent

    ```typescript theme={null}
    new PreProcessor({
      name: "profanity-filter",
      execute: async (message, user) => { ... }
    })
    ```
  </Card>

  <Card title="PostProcessor" icon="paper-plane" href="/api/postprocessor">
    Format responses after agent

    ```typescript theme={null}
    new PostProcessor({
      name: "add-disclaimer",
      execute: async (user, message, response, channel) => { ... }
    })
    ```
  </Card>
</CardGroup>

## Platform APIs

### AI API

**New!** Generate AI responses with custom context in your tools:

```typescript theme={null}
import { AI } from 'lua-cli';

const response = await AI.generate(
  'You are a helpful sales assistant.',
  [{ type: 'text', text: 'What products do you recommend?' }]
);
```

**Use cases:**

* Product descriptions
* Image analysis
* Content summarization
* Translation
* Recommendations
* Document Q\&A

<Card title="Full Documentation" href="/api/ai" />

### Agents API

Invoke the current agent or another agent from within your tool, webhook, job, or processor. Use `Agents.invoke` inside Lua runtime code; `/chat/generate` and `/chat/stream` are for external clients consuming an agent:

```typescript theme={null}
import { Agents } from 'lua-cli';

// Simplified — returns plain text
const reply = await Agents.invoke('support-agent', 'What is the refund policy?');

// Full options — returns structured output
const result = await Agents.invoke('legal-agent', {
  prompt: 'Review this clause.',
  threadId: 'contract-456',
});
console.log(result.text, result.usage);
```

**Use cases:**

* Route requests to specialist agents
* Build multi-agent pipelines
* Run the current agent from a scheduled job
* Delegate from webhooks/jobs to conversational agents

<Card title="Full Documentation" href="/api/agents" />

### User API

Access user information:

```typescript theme={null}
import { User } from 'lua-cli';

// Get current user (from conversation context)
const user = await User.get();

// Get specific user by ID (useful in webhooks/jobs)
const specificUser = await User.get(userId);

// Direct property access
console.log(user.name);
console.log(user.email);
```

**Use cases:**

* Get current user in tools
* Get specific user in webhooks (payment notifications)
* Send messages to specific users in jobs
* Update user profiles

<Card title="Full Documentation" href="/api/user" />

### Data API

Custom data storage with vector search:

```typescript theme={null}
import { Data } from 'lua-cli';

// Create
await Data.create('collection', data, searchText);

// Search semantically
const results = await Data.search('collection', 'query', 10, 0.7);

// Get/Update/Delete
await Data.get('collection', filter);

// Declare indexes for fields you filter on (large collections)
await Data.create('collection', data, { index: ['field'] });
await Data.update('collection', id, data);
await Data.delete('collection', id);
```

<Card title="Full Documentation" href="/api/data" />

### CDN API

Upload and retrieve files from the CDN:

```typescript theme={null}
import { CDN } from 'lua-cli';

// Upload a file
const file = new File([buffer], 'image.png', { type: 'image/png' });
const fileId = await CDN.upload(file);

// Get file by ID
const retrievedFile = await CDN.get(fileId);
console.log(retrievedFile.name, retrievedFile.type);
```

**Use cases:**

* Store user uploads
* Image storage for AI analysis
* Document management
* Asset management

<Card title="Full Documentation" href="/api/cdn" />

### Products API

E-commerce product catalog:

```typescript theme={null}
import { Products } from 'lua-cli';

// Search
const products = await Products.search('laptop');

// CRUD
await Products.create({ name, price });
await Products.update({ price }, id);
await Products.getById(id);
await Products.delete(id);
```

<Card title="Full Documentation" href="/api/products" />

### Baskets API

Shopping cart management:

```typescript theme={null}
import { Baskets, BasketStatus } from 'lua-cli';

// Create basket
const basket = await Baskets.create({ currency: 'USD' });

// Add items
await Baskets.addItem(basket.id, {
  id: productId,
  price: 29.99,
  quantity: 2
});

// Checkout
const order = await Baskets.placeOrder(orderData, basket.id);
```

<Card title="Full Documentation" href="/api/baskets" />

### Orders API

Order processing and tracking:

```typescript theme={null}
import { Orders, OrderStatus } from 'lua-cli';

// Create order
const order = await Orders.create({
  basketId,
  data: { shippingAddress, paymentMethod }
});

// Update status
await Orders.updateStatus(OrderStatus.FULFILLED, orderId);
```

<Card title="Full Documentation" href="/api/orders" />

### Jobs API

Dynamically create scheduled tasks from tools:

```typescript theme={null}
import { Jobs } from 'lua-cli';

// Create a reminder job
const job = await Jobs.create({
  name: 'user-reminder',
  metadata: { message: 'Meeting in 10 minutes' },
  schedule: {
    type: 'once',
    executeAt: new Date(Date.now() + 600000)
  },
  execute: async (jobInstance) => {
    const user = await jobInstance.user();
    await user.send([{
      type: 'text',
      text: jobInstance.metadata.message
    }]);
  }
});
```

<Card title="Full Documentation" href="/api/jobs" />

### Templates API

Send template messages across different channels:

```typescript theme={null}
import { Templates } from 'lua-cli';

// List WhatsApp templates
const result = await Templates.whatsapp.list(channelId);

// Send template message
await Templates.whatsapp.send(channelId, templateId, {
  phoneNumbers: ['+447551166594'],
  values: {
    body: { name: 'John', order_number: '12345' }
  }
});
```

**Supported template types:**

* `Templates.whatsapp` - WhatsApp Business templates

<Card title="Full Documentation" href="/api/templates" />

### Channels API

Send outbound messages on any connected channel — from tools, jobs, webhooks, and triggers:

```typescript theme={null}
import { Channels } from 'lua-cli';

// Free-form message on a connected channel
await Channels.send({
  channel: 'whatsapp',
  to: { userId: 'user_123' },
  text: 'Your order has shipped!'
});

// Rich email
await Channels.email.send({
  to: { email: 'customer@example.com' },
  subject: 'Receipt',
  text: 'Thanks for your order!'
});

// Approved WhatsApp template (start or re-open a conversation)
await Channels.whatsapp.sendTemplate({
  to: { phoneNumber: '+14155552671' },
  templateName: 'order_update',
  languageCode: 'en_US'
});
```

**Use cases:**

* Proactive notifications and reminders (with [Jobs](/api/jobs))
* Confirmations from webhooks
* Agent-initiated follow-ups

<Card title="Full Documentation" href="/api/channels" />

## Environment Variables

Secure configuration management:

```typescript theme={null}
import { env } from 'lua-cli';

const apiKey = env('EXTERNAL_API_KEY');
const baseUrl = env('API_BASE_URL') || 'https://default.com';
```

<Card title="Full Documentation" href="/api/environment" />

## Type Definitions

All APIs are fully typed for TypeScript:

```typescript theme={null}
import { 
  LuaSkill, 
  LuaTool, 
  BasketStatus, 
  OrderStatus 
} from 'lua-cli';

// Autocomplete and type checking work everywhere
const user = await User.get();  // user is typed
const products = await Products.get(); // products is typed
```

## Common Patterns

### External API Integration

```typescript theme={null}
export class WeatherTool implements LuaTool {
  name = "get_weather";
  description = "Get current weather";
  inputSchema = z.object({ city: z.string() });

  async execute(input: any) {
    const response = await fetch(
      `https://api.weather.com?city=${input.city}`
    );
    return await response.json();
  }
}
```

### Using Platform APIs

```typescript theme={null}
export class ShoppingTool implements LuaTool {
  async execute(input: any) {
    // Search products
    const products = await Products.search(input.query);
    
    // Create basket
    const basket = await Baskets.create({ currency: 'USD' });
    
    // Add item
    await Baskets.addItem(basket.id, {
      id: products.products[0].id,
      price: products.products[0].price,
      quantity: 1
    });
    
    return { basketId: basket.id };
  }
}
```

### Custom Data with Search

```typescript theme={null}
export class CreateNoteTool implements LuaTool {
  async execute(input: any) {
    // Create with search indexing
    const note = await Data.create('notes', {
      title: input.title,
      content: input.content
    }, `${input.title} ${input.content}`);
    
    return { noteId: note.id };
  }
}

export class SearchNotesTool implements LuaTool {
  async execute(input: any) {
    // Semantic search
    const results = await Data.search(
      'notes',
      input.query,
      10,
      0.7
    );
    
    return {
      notes: results.map(entry => ({
        id: entry.id,
        title: entry.title,
        content: entry.content,
        relevance: entry.score
      }))
    };
  }
}
```

## API Reference Pages

### Core Classes

<CardGroup>
  <Card title="LuaAgent" href="/api/luaagent" icon="robot">
    Agent configuration
  </Card>

  <Card title="LuaSkill" href="/api/luaskill" icon="puzzle-piece">
    Skill class API
  </Card>

  <Card title="LuaTool" href="/api/luatool" icon="wrench">
    Tool interface
  </Card>

  <Card title="LuaWebhook" href="/api/luawebhook" icon="webhook">
    HTTP webhooks
  </Card>

  <Card title="LuaJob" href="/api/luajob" icon="clock">
    Scheduled tasks
  </Card>

  <Card title="LuaMCPServer" href="/api/luamcpserver" icon="plug">
    MCP external tools
  </Card>

  <Card title="PreProcessor" href="/api/preprocessor" icon="filter">
    Message filtering
  </Card>

  <Card title="PostProcessor" href="/api/postprocessor" icon="paper-plane">
    Response formatting
  </Card>

  <Card title="defineDevice" href="/api/device-definition" icon="microchip">
    Server-side device + trigger definitions
  </Card>

  <Card title="LuaVoice" href="/api/voice" icon="microphone">
    Voice agent definition
  </Card>
</CardGroup>

### Runtime APIs

<CardGroup>
  <Card title="Lua" href="/api/lua" icon="moon">
    Request context API
  </Card>

  <Card title="AI" href="/api/ai" icon="brain">
    AI generation API
  </Card>

  <Card title="Agents" href="/api/agents" icon="robot">
    Agent invocation API
  </Card>

  <Card title="User" href="/api/user" icon="user">
    User data API
  </Card>

  <Card title="Data" href="/api/data" icon="database">
    Custom data API
  </Card>

  <Card title="CDN" href="/api/cdn" icon="cloud">
    File storage API
  </Card>

  <Card title="Products" href="/api/products" icon="box">
    Products API
  </Card>

  <Card title="Baskets" href="/api/baskets" icon="cart-shopping">
    Baskets API
  </Card>

  <Card title="Orders" href="/api/orders" icon="receipt">
    Orders API
  </Card>

  <Card title="Jobs" href="/api/jobs" icon="plus">
    Jobs API
  </Card>

  <Card title="Templates" href="/api/templates" icon="message">
    Template messaging
  </Card>

  <Card title="Channels" href="/api/channels" icon="paper-plane">
    Outbound messaging
  </Card>

  <Card title="Inbox" href="/api/inbox" icon="inbox">
    Approval and notice cards
  </Card>
</CardGroup>

### Voice

<CardGroup>
  <Card title="LuaVoice" href="/api/voice" icon="microphone">
    Define voices in code — STT, TTS, LLM, plus plugin & realtime engines
  </Card>
</CardGroup>

### Utilities

<CardGroup>
  <Card title="Environment" href="/api/environment" icon="key">
    Environment utilities
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Use TypeScript">
    All APIs are fully typed. Use TypeScript for:

    * Autocomplete
    * Type checking
    * Better IDE support
  </Accordion>

  <Accordion title="Validate Inputs">
    Always use Zod schemas for input validation:

    ```typescript theme={null}
    inputSchema = z.object({
      email: z.string().email(),
      age: z.number().min(0)
    });
    ```
  </Accordion>

  <Accordion title="Handle Errors">
    Implement proper error handling:

    ```typescript theme={null}
    try {
      const result = await api.call();
      return result;
    } catch (error) {
      throw new Error(`Operation failed: ${error.message}`);
    }
    ```
  </Accordion>

  <Accordion title="Use Environment Variables">
    Never hardcode secrets:

    ```typescript theme={null}
    const apiKey = env('API_KEY');
    if (!apiKey) {
      throw new Error('API_KEY not configured');
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<Steps>
  <Step title="Explore Core Classes">
    Learn about [LuaSkill](/api/luaskill) and [LuaTool](/api/luatool)
  </Step>

  <Step title="Study Platform APIs">
    Explore [User](/api/user), [Data](/api/data), [Products](/api/products), etc.
  </Step>

  <Step title="See Examples">
    Check out [Tool Examples](/examples/overview) for working code
  </Step>

  <Step title="Build Something">
    Follow the [First Skill tutorial](/getting-started/first-skill)
  </Step>
</Steps>


# PostProcessor
Source: https://docs.heylua.ai/api/postprocessor

Transform and format AI responses before sending to users

## Overview

`PostProcessor` allows you to modify or enhance AI-generated responses before they're sent to users. Use postprocessors to add disclaimers, format output, inject dynamic content, or apply branding.

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const addDisclaimer = new PostProcessor({
  name: 'add-disclaimer',
  description: 'Add legal disclaimer to responses',
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    return {
      modifiedResponse: response + "\n\n_Disclaimer: This is AI-generated content for informational purposes only._"
    };
  }
});

export default addDisclaimer;
```

<Note>
  Response postprocessing for formatting, branding, and enhancement. Use with LuaAgent.
</Note>

<Note>
  **Streaming Support:** PostProcessors now execute on both streaming and non-streaming requests. For streaming, post-processors run after the stream completes and emit a `postprocess-complete` event. See [Channel Compatibility](/overview/postprocessors#channel-compatibility) for details.
</Note>

## Use Cases

<CardGroup>
  <Card title="Disclaimers" icon="triangle-exclamation">
    Add legal or informational disclaimers
  </Card>

  <Card title="Formatting" icon="paintbrush">
    Apply consistent formatting and styling
  </Card>

  <Card title="Branding" icon="palette">
    Add company branding or signatures
  </Card>

  <Card title="Dynamic Content" icon="bolt">
    Inject user-specific information
  </Card>
</CardGroup>

## Constructor

### new PostProcessor(config)

Creates a new response postprocessor.

<ParamField type="PostProcessorConfig">
  Postprocessor configuration object
</ParamField>

## Configuration Parameters

### Required Fields

<ParamField type="string">
  Postprocessor description for documentation
</ParamField>

<ParamField type="function">
  Function that processes AI responses

  **Signature:** `(user: UserDataInstance, message: string, response: string, channel: string) => Promise<PostProcessorResponse>`

  **Parameters:**

  * `user` - User data instance with profile and custom data
  * `message` - Original user message (string)
  * `response` - AI-generated response to modify
  * `channel` - Channel identifier (e.g., 'whatsapp', 'web', 'api')
</ParamField>

<Note>
  **Recommended:** Use the [Lua Runtime API](/api/lua) instead of the function parameters:

  * **User:** `User.get()` to retrieve the current user
  * **Channel:** `Lua.request.channel` for the current channel
  * **Webhook:** `Lua.request.webhook?.payload` for raw webhook data (WhatsApp, Slack, Teams, etc.)

  The function parameters may be removed in a future version.
</Note>

### Optional Fields

<ParamField type="string">
  Unique postprocessor name. Defaults to `'unnamed-postprocessor'` if not provided.

  **Examples**: `'add-disclaimer'`, `'format-response'`
</ParamField>

<ParamField type="number">
  Execution priority. **Lower numbers run first.** Use this to control the order when you have multiple postprocessors (e.g. translate before adding disclaimers).
</ParamField>

<ParamField type="boolean">
  When `true`, the postprocessor runs **asynchronously** — the agent's response is sent to the user immediately and the postprocessor runs in the background. Use for non-blocking side effects (analytics, audit logs) where the user shouldn't wait.

  When `false` (default), the response is held until the postprocessor returns, allowing it to mutate the text before delivery.
</ParamField>

## PostProcessorResponse

Your execute function must return:

```typescript theme={null}
interface PostProcessorResponse {
  // Modified response text (required)
  modifiedResponse: string;
}
```

<Note>
  The response object only contains `modifiedResponse`. The modified response becomes the input for the next postprocessor in the chain.
</Note>

## Complete Examples

### Add Legal Disclaimer

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const legalDisclaimer = new PostProcessor({
  name: 'legal-disclaimer',
  description: 'Add legal disclaimer to medical advice',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    // Check if response contains medical information
    const medicalKeywords = ['symptom', 'diagnosis', 'treatment', 'medication', 'doctor'];
    const hasMedicalContent = medicalKeywords.some(keyword => 
      response.toLowerCase().includes(keyword)
    );
    
    if (hasMedicalContent) {
      return {
        modifiedResponse: response + 
          "\n\n⚠️ **Medical Disclaimer:** This information is for educational purposes only and should not be considered medical advice. Please consult with a qualified healthcare professional for medical concerns."
      };
    }
    
    return { modifiedResponse: response };
  }
});

export default legalDisclaimer;
```

### Add Company Branding

```typescript theme={null}
import { PostProcessor, UserDataInstance, env } from 'lua-cli';

const brandingFooter = new PostProcessor({
  name: 'branding-footer',
  description: 'Add company branding to responses',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    const companyName = env('COMPANY_NAME') || 'Our Company';
    const supportEmail = env('SUPPORT_EMAIL') || 'support@example.com';
    
    const footer = `\n\n---\n` +
      `_Powered by ${companyName}_\n` +
      `Need help? Contact us at ${supportEmail}`;
    
    return {
      modifiedResponse: response + footer
    };
  }
});

export default brandingFooter;
```

### Format Response

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const responseFormatter = new PostProcessor({
  name: 'response-formatter',
  description: 'Apply consistent formatting to responses',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    let formatted = response;
    
    // Capitalize first letter of sentences
    formatted = formatted.replace(/(^|\. )(\w)/g, (match, p1, p2) => {
      return p1 + p2.toUpperCase();
    });
    
    // Add proper spacing after punctuation
    formatted = formatted.replace(/([.!?])(\w)/g, '$1 $2');
    
    // Format numbers with commas
    formatted = formatted.replace(/\b(\d{1,3}(?:,?\d{3})*)\b/g, (match) => {
      return match.replace(/,/g, '').replace(/\B(?=(\d{3})+(?!\d))/g, ',');
    });
    
    // Highlight important terms (example)
    const importantTerms = ['important', 'urgent', 'required', 'deadline'];
    importantTerms.forEach(term => {
      const regex = new RegExp(`\\b(${term})\\b`, 'gi');
      formatted = formatted.replace(regex, '**$1**');
    });
    
    return { modifiedResponse: formatted };
  }
});

export default responseFormatter;
```

### Add User-Specific Context

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const personalizer = new PostProcessor({
  name: 'personalizer',
  description: 'Add personalized greeting and context',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    const userName = user.name || 'there';
    const userData = await user.data;
    const isVIP = userData.vipStatus === true;
    
    // Add personalized greeting
    let personalized = `Hi ${userName}! ${response}`;
    
    // Add VIP note if applicable
    if (isVIP) {
      personalized += `\n\n✨ As a VIP member, you have priority support and exclusive benefits.`;
    }
    
    return { modifiedResponse: personalized };
  }
});

export default personalizer;
```

### Add Call-to-Action

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const ctaInjector = new PostProcessor({
  name: 'cta-injector',
  description: 'Add contextual call-to-action based on response content',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    let cta = '';
    
    // Product-related response
    if (response.toLowerCase().includes('product') || response.toLowerCase().includes('price')) {
      cta = '\n\n📦 [View Our Products](https://example.com/products)';
    }
    
    // Support-related response
    else if (response.toLowerCase().includes('issue') || response.toLowerCase().includes('problem')) {
      cta = '\n\n🎫 [Create Support Ticket](https://example.com/support)';
    }
    
    // General information
    else {
      cta = '\n\n💬 Have more questions? Just ask!';
    }
    
    return { modifiedResponse: response + cta };
  }
});

export default ctaInjector;
```

### Translation Wrapper

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const translator = new PostProcessor({
  name: 'translator',
  description: 'Translate responses based on user language preference',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    const userData = await user.data;
    const userLanguage = userData.language || 'en';
    
    // Skip if already in user's language
    if (userLanguage === 'en') {
      return { modifiedResponse: response };
    }
    
    // Translate response (using external translation API)
    try {
      const translated = await translateText(response, userLanguage);
      return { modifiedResponse: translated };
    } catch (error) {
      console.error('Translation failed:', error);
      // Fall back to original
      return { modifiedResponse: response };
    }
  }
});

async function translateText(text: string, targetLanguage: string): Promise<string> {
  // Implementation using translation API (Google Translate, DeepL, etc.)
  // This is a placeholder
  return text;
}

export default translator;
```

### Sentiment Adjuster

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const sentimentAdjuster = new PostProcessor({
  name: 'sentiment-adjuster',
  description: 'Adjust tone based on user message content',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    // Check if user message indicates frustration
    const frustrationKeywords = ['frustrated', 'annoyed', 'angry', 'not working', 'broken'];
    const isFrustrated = frustrationKeywords.some(keyword => 
      message.toLowerCase().includes(keyword)
    );
    
    if (isFrustrated) {
      // Add empathetic phrasing
      const empathetic = "I understand this can be frustrating. " + response;
      return { modifiedResponse: empathetic };
    }
    
    return { modifiedResponse: response };
  }
});

export default sentimentAdjuster;
```

### Link Enricher

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const linkEnricher = new PostProcessor({
  name: 'link-enricher',
  description: 'Convert plain URLs to formatted links',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    // Convert URLs to markdown links
    const urlRegex = /(https?:\/\/[^\s]+)/g;
    const enriched = response.replace(urlRegex, (url) => {
      const domain = new URL(url).hostname.replace('www.', '');
      return `[${domain}](${url})`;
    });
    
    // Add tracking parameters to links
    const trackedLinks = enriched.replace(/\((https?:\/\/[^\)]+)\)/g, (match, url) => {
      const tracked = `${url}${url.includes('?') ? '&' : '?'}utm_source=ai_agent&utm_medium=chat`;
      return `(${tracked})`;
    });
    
    return { modifiedResponse: trackedLinks };
  }
});

export default linkEnricher;
```

## Using with LuaAgent

Postprocessors are added to your agent configuration:

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import translator from './postprocessors/translator';
import responseFormatter from './postprocessors/formatter';
import legalDisclaimer from './postprocessors/disclaimer';
import brandingFooter from './postprocessors/branding';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [...],
  
  postProcessors: [
    translator,
    responseFormatter,
    legalDisclaimer,
    brandingFooter
  ]
});
```

<Note>
  Postprocessors execute in order of their **priority** value (lowest first). Priority is set when creating the postprocessor via the API. If not specified, default priority is 100.
</Note>

## Execution Flow

```
AI Agent Response
    ↓
PostProcessor 1 (priority: 1)
    ↓
PostProcessor 2 (priority: 10)
    ↓
PostProcessor 3 (priority: 90)
    ↓
PostProcessor 4 (priority: 100)
    ↓
Final Response to User
```

Each postprocessor receives the output of the previous one in the chain.

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Chain Postprocessors Thoughtfully">
    Order matters - structure flows logically

    ```typescript theme={null}
    priority: 1,   // Translation (first)
    priority: 10,  // Formatting
    priority: 50,  // Content injection
    priority: 100, // Disclaimer/branding (last)
    ```
  </Accordion>

  <Accordion title="✅ Preserve Original Meaning">
    Don't alter the core message

    ```typescript theme={null}
    // ✅ Add to response
    return {
      modifiedResponse: response + "\n\nAdditional info..."
    };

    // ❌ Don't completely replace
    return {
      modifiedResponse: "Something completely different"
    };
    ```
  </Accordion>

  <Accordion title="✅ Handle Errors Gracefully">
    Fall back to original response on errors

    ```typescript theme={null}
    execute: async (user, message, response, channel) => {
      try {
        return { modifiedResponse: processResponse(response) };
      } catch (error) {
        console.error('Postprocessor error:', error);
        return { modifiedResponse: response };  // Return original
      }
    }
    ```
  </Accordion>

  <Accordion title="✅ Keep Processing Fast">
    Postprocessors should be quick (\< 50ms)

    Avoid heavy computations or external API calls when possible.
  </Accordion>
</AccordionGroup>

## Testing Postprocessors

```bash theme={null}
lua test
# Select: PostProcessor → your-postprocessor-name
# Provide test response
```

## Common Patterns

### Conditional Processing

```typescript theme={null}
execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
  const userData = await user.data;
  
  // Only apply to certain user types
  if (userData.accountType === 'enterprise') {
    return {
      modifiedResponse: response + "\n\n*Enterprise Support Available 24/7*"
    };
  }
  
  return { modifiedResponse: response };
}
```

### Regex Replacements

```typescript theme={null}
execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
  // Replace placeholders
  let modified = response
    .replace(/{{user_name}}/g, user.name || 'User')
    .replace(/{{company}}/g, env('COMPANY_NAME'))
    .replace(/{{date}}/g, new Date().toLocaleDateString());
  
  return { modifiedResponse: modified };
}
```

### Markdown Formatting

```typescript theme={null}
execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
  // Add markdown formatting
  let formatted = response
    .replace(/\*\*([^*]+)\*\*/g, '**$1**')  // Bold
    .replace(/_([^_]+)_/g, '_$1_')          // Italic
    .replace(/`([^`]+)`/g, '`$1`');         // Code
  
  return { modifiedResponse: formatted };
}
```

## Related APIs

<CardGroup>
  <Card title="PreProcessor" href="/api/preprocessor" icon="filter">
    Process messages before agent
  </Card>

  <Card title="LuaAgent" href="/api/luaagent" icon="robot">
    Agent configuration
  </Card>

  <Card title="User API" href="/api/user" icon="user">
    Access user data
  </Card>

  <Card title="Data API" href="/api/data" icon="database">
    Store and retrieve data
  </Card>
</CardGroup>

## See Also

* [PreProcessor](/api/preprocessor) - Processing incoming messages
* [LuaAgent](/api/luaagent) - Adding postprocessors to your agent
* [Workflows Concept](/concepts/workflows)


# PreProcessor
Source: https://docs.heylua.ai/api/preprocessor

Filter and route messages before they reach your AI agent

## Overview

`PreProcessor` allows you to intercept and process user messages before they reach your AI agent. Use preprocessors to filter spam, route messages, validate inputs, or modify messages before the agent sees them.

```typescript theme={null}
import { PreProcessor } from 'lua-cli';

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Filter inappropriate content',
  priority: 10,
  execute: async (user, messages, channel) => {
    const hasProfanity = messages.some(msg => 
      msg.type === 'text' && msg.text.includes('badword')
    );
    
    if (hasProfanity) {
      // Block message and respond
      return {
        action: 'block',
        response: "Please keep the conversation respectful."
      };
    }
    
    // Allow messages to proceed
    return { action: 'proceed' };
  }
});

export default profanityFilter;
```

<Note>
  Message preprocessing for filtering, routing, and validation. Use with LuaAgent.
</Note>

## Use Cases

<CardGroup>
  <Card title="Content Filtering" icon="filter">
    Block spam, profanity, or inappropriate content
  </Card>

  <Card title="Message Routing" icon="route">
    Route messages to different agents or handlers
  </Card>

  <Card title="Input Validation" icon="check">
    Validate message format or required information
  </Card>

  <Card title="Analytics" icon="chart-line">
    Track message metrics before processing
  </Card>
</CardGroup>

## Constructor

### new PreProcessor(config)

Creates a new message preprocessor.

<ParamField type="PreProcessorConfig">
  Preprocessor configuration object
</ParamField>

## Configuration Parameters

### Required Fields

<ParamField type="string">
  Preprocessor description for documentation
</ParamField>

<ParamField type="function">
  Function that processes incoming messages

  **Signature:** `(user: UserDataInstance, messages: ChatMessage[], channel: string) => Promise<PreProcessorBlockResponse | PreProcessorProceedResponse>`

  **Arguments:**

  * `user`: The [UserDataInstance](#userdata-object) representing the current user.
  * `messages`: Array of [ChatMessage](#message-structure) objects sent by the user.
  * `channel`: The channel identifier (e.g., `'whatsapp'`, `'web'`, `'api'`).
</ParamField>

<Note>
  **Recommended:** Use the [Lua Runtime API](/api/lua) instead of the function parameters:

  * **User:** `User.get()` to retrieve the current user
  * **Channel:** `Lua.request.channel` for the current channel
  * **Webhook:** `Lua.request.webhook?.payload` for raw webhook data (WhatsApp, Slack, Teams, etc.)

  The function parameters may be removed in a future version.
</Note>

### Optional Fields

<ParamField type="string">
  Unique preprocessor name. Defaults to `'unnamed-preprocessor'` if not provided.

  **Examples**: `'profanity-filter'`, `'message-router'`
</ParamField>

<ParamField type="number">
  Execution priority (lower runs first). Default: `100`
</ParamField>

<ParamField type="boolean">
  Run this preprocessor asynchronously on the server. When `true`, the preprocessor executes in a non-blocking mode. Default: `false`
</ParamField>

## UserData Object

The `user` argument passed to `execute` provides access to the current user's data and methods.

```typescript theme={null}
interface UserDataInstance {
  // Direct access to user data properties
  uid: string;
  name?: string;
  email?: string;
  [key: string]: any;

  // Helper methods
  getChatHistory(): Promise<ChatHistoryMessage[]>;
  // ... other user management methods
}
```

## Message Structure

The `messages` array passed to your execute function contains `ChatMessage` objects:

```typescript theme={null}
type ChatMessage = TextMessage | ImageMessage | FileMessage;

interface TextMessage {
  type: 'text';
  text: string;
}

interface ImageMessage {
  type: 'image';
  image: string;      // URL or base64
  mimeType: string;   // e.g. "image/png", "image/jpeg"
}

interface FileMessage {
  type: 'file';
  data: string;       // URL or base64
  mimeType: string;   // e.g. "application/pdf"
}
```

## Return Type

Your execute function must return a `PreProcessorBlockResponse` or `PreProcessorProceedResponse` object indicating whether to proceed or block.

### 1. Proceed

To allow the message to continue to the next preprocessor or the agent:

```typescript theme={null}
// Proceed with original message
return { action: 'proceed' };

// OR proceed with a modified message
return {
  action: 'proceed',
  modifiedMessage: [{ type: 'text', text: 'Modified content' }],
  metadata: { reason: 'message-modified' }  // optional metadata
};
```

### 2. Block

To stop processing immediately and respond to the user:

```typescript theme={null}
return {
  action: 'block',
  response: "This message was blocked.",
  metadata: { reason: 'profanity' }  // optional metadata
};
```

## Complete Examples

### Profanity Filter

```typescript theme={null}
import { PreProcessor } from 'lua-cli';

const profanityWords = ['badword1', 'badword2', 'badword3'];

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Block messages containing inappropriate language',
  priority: 10, // Run early
  
  execute: async (user, messages, channel) => {
    // Check all text messages
    const hasProfanity = messages.some(msg => {
      if (msg.type === 'text') {
        return profanityWords.some(word => msg.text.toLowerCase().includes(word));
      }
      return false;
    });
    
    if (hasProfanity) {
      console.log(`Blocked profanity from user ${user.uid}`);
      return {
        action: 'block',
        response: "Please keep the conversation respectful. Inappropriate language is not allowed."
      };
    }
    
    return { action: 'proceed' };
  }
});

export default profanityFilter;
```

### Business Hours Filter

```typescript theme={null}
import { PreProcessor } from 'lua-cli';

const businessHoursFilter = new PreProcessor({
  name: 'business-hours-filter',
  description: 'Block messages outside business hours',
  
  execute: async (user, messages, channel) => {
    const now = new Date();
    const hour = now.getHours();
    const day = now.getDay();
    
    // Business hours: Mon-Fri, 9 AM - 5 PM
    const isWeekday = day >= 1 && day <= 5;
    const isBusinessHours = hour >= 9 && hour < 17;
    
    if (!isWeekday || !isBusinessHours) {
      return {
        action: 'block',
        response: "Thank you for contacting us. Our business hours are Monday-Friday, 9 AM - 5 PM. We'll respond to your message during our next business day."
      };
    }
    
    return { action: 'proceed' };
  }
});

export default businessHoursFilter;
```

### Message Enrichment

```typescript theme={null}
import { PreProcessor } from 'lua-cli';

const messageEnricher = new PreProcessor({
  name: 'message-enricher',
  description: 'Add context to messages before processing',
  priority: 50,
  
  execute: async (user, messages, channel) => {
    // Enrich message with user info
    const enrichedMessages = messages.map(msg => {
      if (msg.type === 'text') {
        return {
          ...msg,
          text: `${msg.text}\n\n[Context: User ID ${user.uid}]`
        };
      }
      return msg;
    });
    
    return {
      action: 'proceed',
      modifiedMessage: enrichedMessages
    };
  }
});

export default messageEnricher;
```

## Execution Flow

Preprocessors are executed in a **pipeline**:

1. **Sequential Execution**: Preprocessors run one after another, sorted by `priority`.
2. **Modifications**: If a preprocessor modifies a message, the *next* preprocessor receives the modified version.
3. **Blocking**: If any preprocessor returns `action: 'block'`, execution stops immediately, and the response is sent to the user. The agent is not called.

## Testing Preprocessors

```bash theme={null}
lua test
# Select: PreProcessor → your-preprocessor-name
# Provide test message
```

## See Also

* [PostProcessor](/api/postprocessor) - Processing responses
* [LuaAgent](/api/luaagent) - Adding preprocessors to your agent


# Products API
Source: https://docs.heylua.ai/api/products

Manage e-commerce product catalog

## Overview

The Products API provides complete CRUD operations for managing an e-commerce product catalog. Returns **ProductInstance** objects with direct property access.

```typescript theme={null}
import { Products } from 'lua-cli';

// Search products - returns ProductSearchInstance
const results = await Products.search('laptop');

// Direct property access on results
const names = results.map(p => p.name);
const prices = results.map(p => p.price);

// Create product - returns ProductInstance
const product = await Products.create({
  name: 'MacBook Pro',
  price: 1999.99
});

// Direct property access
console.log(product.name);   // "MacBook Pro"
console.log(product.price);  // 1999.99

// Instance methods
await product.update({ price: 1799.99 });
await product.save();
await product.delete();
```

<CardGroup>
  <Card title="Direct Access" icon="bolt">
    Access properties with `product.name` not `product.data.name`
  </Card>

  <Card title="Array Methods" icon="list">
    Use `.map()`, `.filter()` on search results
  </Card>

  <Card title="Instance Methods" icon="wrench">
    Built-in `update()`, `save()`, and `delete()`
  </Card>

  <Card title="Iteration" icon="arrows-rotate">
    Use `for...of` loops
  </Card>
</CardGroup>

## Return Shape Reference

<Warning>
  **`Products.search()` and `Products.get()` do NOT return arrays with a `.data` property.** They return instance wrappers that are directly iterable.
</Warning>

| Method                                                                 | Returns                                                                           | How to use                                                                        |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `Products.search(q, limit?)`                                           | `ProductSearchInstance` — iterable, has `.products`, `.length`                    | `results.map(p => p.name)`, `results.products`, `results.length` — **no `.data`** |
| `Products.get(page?, limit?)` or `Products.get({page, limit, filter})` | `ProductPaginationInstance` — iterable, has `.products`, `.pagination`, `.length` | `results.map(p => p.name)`, `results.pagination.totalPages` — **no `.data`**      |
| `Products.create(product)`                                             | `ProductInstance`                                                                 | `product.name`, `product.price`, `await product.update({...})`                    |
| `Products.getById(id)`                                                 | `ProductInstance`                                                                 | Direct property access                                                            |
| `Products.update(data, id)`                                            | `UpdateProductResponse`                                                           | `{ product }`                                                                     |
| `Products.delete(id)`                                                  | `DeleteProductResponse`                                                           | `{ success }`                                                                     |

**Quick examples:**

```typescript theme={null}
// ✅ Products.search → ProductSearchInstance (iterable)
const results = await Products.search('laptop');
results.forEach(p => console.log(p.name, p.price));  // iterate directly
const names = results.map(p => p.name);              // array methods work
console.log(results.length);                          // ✅ count
// ❌ results.data   → does not exist

// ✅ Products.get → ProductPaginationInstance
const page = await Products.get({ page: 1, limit: 20, filter: { inStock: true } });
page.map(p => p.name);                               // iterate directly
console.log(page.pagination.totalPages);             // ✅ pagination
// ❌ page.data      → does not exist
```

## Methods

### search()

Search products by name or description using semantic search.

```typescript theme={null}
Products.search(query: string): Promise<ProductSearchInstance>
```

<ParamField type="string">
  Search query to match against product names and descriptions
</ParamField>

**Returns:** `ProductSearchInstance` - Array-like collection with direct access to products via `.products` property

**Example:**

```typescript theme={null}
// Search with default limit (5)
const results = await Products.search('laptop');

// Search with custom limit
const moreResults = await Products.search('laptop', 10);

// Direct array methods
results.forEach(product => {
  console.log(`${product.name} - $${product.price}`);
});

// Or use .map()
const names = results.map(p => p.name);
const prices = results.map(p => p.price);

// Filter
const affordable = results.filter(p => p.price < 1000);

// Find
const specific = results.find(p => p.sku === 'LAP-001');

// Check length
console.log(`Found ${results.length} products`);

// For...of iteration
for (const product of results) {
  console.log(product.name);
}
```

### get()

Retrieve products with pagination and optional filtering.

```typescript theme={null}
// Simple pagination (backward compatible)
Products.get(page?: number, limit?: number): Promise<ProductPaginationInstance>

// With filter options (recommended)
Products.get(options?: ProductFilterOptions): Promise<ProductPaginationInstance>
```

**ProductFilterOptions:**

```typescript theme={null}
interface ProductFilterOptions {
  page?: number;      // Page number (1-indexed), default: 1
  limit?: number;     // Items per page, default: 10
  filter?: object;    // Bounded filter for product data
}
```

<ParamField type="number">
  Page number (1-indexed)
</ParamField>

<ParamField type="number">
  Number of products per page (maximum 100)
</ParamField>

<ParamField type="object">
  Bounded filter object to query product data fields
</ParamField>

**Returns:** `ProductPaginationInstance` - Array-like collection with pagination support

**Examples:**

```typescript theme={null}
// Simple pagination (backward compatible)
const page = await Products.get(1, 20);

// Using options object (recommended)
const page = await Products.get({ page: 1, limit: 20 });

// With filters - exact match
const electronics = await Products.get({
  page: 1,
  limit: 20,
  filter: { category: 'Electronics' }
});

// With filters - price range
const affordable = await Products.get({
  filter: {
    price: { $lte: 100 }
  }
});

// With filters - multiple conditions
const inStockLaptops = await Products.get({
  filter: {
    category: 'Laptops',
    inStock: true,
    price: { $gte: 500, $lte: 1500 }
  }
});

// Direct array methods
page.forEach(product => {
  console.log(`${product.name} - $${product.price}`);
});

// Access pagination info
console.log(`Page ${page.pagination.currentPage} of ${page.pagination.totalPages}`);
console.log(`Showing ${page.length} of ${page.pagination.totalCount} products`);

// Navigate pages
if (page.pagination.hasNextPage) {
  const nextPage = await page.nextPage();
}

if (page.pagination.hasPrevPage) {
  const prevPage = await page.prevPage();
}

// Use array methods
const names = page.map(p => p.name);
const inStock = page.filter(p => p.inStock);
```

**Filter Operators:**

Product filters use the platform-wide [Lua Query language](/api/query). The grammar, validation, limits, and errors are identical to Data and every other API that accepts a `filter`.

```typescript theme={null}
// Comparison
{ price: { $eq: 99.99 } }      // Equal
{ price: { $ne: 99.99 } }      // Not equal
{ price: { $gt: 50 } }         // Greater than
{ price: { $gte: 50 } }        // Greater than or equal
{ price: { $lt: 100 } }        // Less than
{ price: { $lte: 100 } }       // Less than or equal

// Array matching
{ category: { $in: ['Electronics', 'Computers'] } }
{ category: { $nin: ['Discontinued'] } }
{ category: ['Electronics', 'Computers'] } // Shorthand for $in

// Existence
{ inventory: { $exists: true } }

// Logical
{ $and: [{ inStock: true }, { price: { $lte: 100 } }] }
{ $or: [{ category: 'Computers' }, { category: 'Tablets' }] }

// Nested fields (dot notation)
{ 'specs.color': 'black' }
{ 'metadata.brand': 'Apple' }
```

See [Lua Query security, errors, and resource limits](/api/query#security-and-errors) for the common contract.

### getById()

Get a specific product by ID.

```typescript theme={null}
Products.getById(id: string): Promise<ProductInstance>
```

**Returns:** `ProductInstance` with direct property access and methods

**Example:**

```typescript theme={null}
const product = await Products.getById('product_abc123');

// Direct property access
console.log(product.name);   // "MacBook Pro"
console.log(product.price);  // 1999.99
console.log(product.sku);    // "MBP-14"

// Instance methods
await product.update({ price: 1799.99 });
await product.delete();
```

### create()

Create a new product.

```typescript theme={null}
Products.create(product: Product): Promise<ProductInstance>
```

<ParamField type="string">
  Product name
</ParamField>

<ParamField type="number">
  Product price
</ParamField>

<ParamField type="string">
  Product category
</ParamField>

<ParamField type="string">
  Stock keeping unit
</ParamField>

<ParamField type="boolean">
  Whether product is in stock
</ParamField>

<ParamField type="string">
  Product description
</ParamField>

**Returns:** `ProductInstance` with direct property access and methods

**Example:**

```typescript theme={null}
const product = await Products.create({
  name: 'Wireless Mouse',
  price: 29.99,
  category: 'Electronics',
  sku: 'MOUSE-001',
  inStock: true,
  description: 'Ergonomic wireless mouse'
});

// Direct property access
console.log(product.id);      // "product_xyz789"
console.log(product.name);    // "Wireless Mouse"
console.log(product.price);   // 29.99

// Instance methods available
await product.update({ price: 24.99 });
```

### update() (Instance Method)

Update an existing product via an instance. Use `product.update()` on a retrieved product — there is no static `Products.update()` method.

```typescript theme={null}
product.update(data: Record<string, any>): Promise<Product>
```

<ParamField type="object">
  Partial product data to update
</ParamField>

**Example:**

```typescript theme={null}
const product = await Products.getById('product_xyz789');

// Update via instance method
await product.update({
  price: 24.99,
  inStock: false
});

// Access updated properties
console.log(product.price);   // 24.99
console.log(product.inStock); // false
```

### save() (Instance Method)

Save the current state of the product to the server. This is a convenience method that persists all changes made to the product instance.

```typescript theme={null}
product.save(): Promise<boolean>
```

**Returns:** Promise resolving to `true` if successful

**Example:**

```typescript theme={null}
const product = await Products.getById('product_xyz789');

// Modify product properties directly
product.price = 24.99;
product.inStock = false;
product.description = "Updated description";

// Save all changes at once
await product.save();

// Much cleaner workflow!
```

<Note>
  **New in Latest Version:** The `save()` method provides a simpler workflow - modify properties then save, rather than calling `Products.update()` with the product ID.
</Note>

### delete()

Delete a product.

```typescript theme={null}
Products.delete(id: string): Promise<DeleteProductResponse>
```

**Example:**

```typescript theme={null}
await Products.delete('product_xyz789');
```

## ProductInstance

All product methods return `ProductInstance` objects with:

**Direct Property Access:**

```typescript theme={null}
product.name
product.price
product.sku
product.inStock
product.category
product.description
// Any custom fields
```

**Instance Methods:**

```typescript theme={null}
await product.update({ price: 999.99 });
await product.save();
await product.delete();
```

**Backward Compatible:**

```typescript theme={null}
product.name;        // ✅ New way
product.data.name;   // ✅ Old way still works
```

## Complete Examples

### Search Tool

```typescript theme={null}
import { LuaTool, Products } from 'lua-cli';
import { z } from 'zod';

export class SearchProductsTool implements LuaTool {
  name = "search_products";
  description = "Search for products by name or description";
  
  inputSchema = z.object({
    query: z.string().describe("Search query"),
    maxPrice: z.number().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Products.search(input.query);
    
    // Filter by price if specified
    let products = results.products;
    if (input.maxPrice) {
      products = products.filter(p => p.price <= input.maxPrice);
    }
    
    return {
      products: products.map(p => ({
        id: p.id,
        name: p.name,
        price: `$${p.price.toFixed(2)}`,
        inStock: p.inStock ? '✅ In Stock' : '❌ Out of Stock'
      })),
      total: products.length
    };
  }
}
```

### Create Product Tool

```typescript theme={null}
export class CreateProductTool implements LuaTool {
  name = "create_product";
  description = "Add a new product to the catalog";
  
  inputSchema = z.object({
    name: z.string(),
    price: z.number().positive(),
    category: z.string().optional(),
    sku: z.string().optional(),
    description: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Products.create({
      ...input,
      inStock: true
    });
    
    return {
      success: true,
      productId: result.id,
      message: `Product "${input.name}" created successfully`
    };
  }
}
```

### Update Stock Tool

```typescript theme={null}
export class UpdateStockTool implements LuaTool {
  name = "update_stock";
  description = "Update product stock status";
  
  inputSchema = z.object({
    productId: z.string(),
    inStock: z.boolean()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    await Products.update(
      { inStock: input.inStock },
      input.productId
    );
    
    return {
      success: true,
      message: `Stock status updated to ${input.inStock ? 'in stock' : 'out of stock'}`
    };
  }
}
```

## Use Cases

### E-commerce Catalog

```typescript theme={null}
// Browse products with pagination
const products = await Products.get({ page: 1, limit: 20 });

// Search specific items (semantic search)
const laptops = await Products.search('laptop');

// Filter by category
const electronics = await Products.get({
  filter: { category: 'Electronics' }
});

// Get product details
const product = await Products.getById(laptops.products[0].id);
```

### Inventory Management

```typescript theme={null}
// Update product price
await Products.update({ price: 899.99 }, productId);

// Mark as out of stock
await Products.update({ inStock: false }, productId);

// Update multiple fields
await Products.update({
  price: 799.99,
  inStock: true,
  category: 'Electronics - Sale'
}, productId);

// Get all out-of-stock products
const outOfStock = await Products.get({
  filter: { inStock: false }
});
```

### Filtering Products

```typescript theme={null}
// By price range
const affordable = await Products.get({
  filter: {
    price: { $gte: 50, $lte: 200 }
  }
});

// By category and availability
const availablePhones = await Products.get({
  filter: {
    category: 'Phones',
    inStock: true
  }
});

// By nested properties
const appleProducts = await Products.get({
  filter: {
    'metadata.brand': 'Apple'
  }
});

// Multiple categories
const gadgets = await Products.get({
  filter: {
    category: { $in: ['Phones', 'Tablets', 'Watches'] }
  }
});
```

### Product Recommendations

```typescript theme={null}
// Search similar products
const similar = await Products.search(product.category);

// Or filter by same category
const sameCategory = await Products.get({
  filter: {
    category: product.category,
    price: {
      $gte: product.price * 0.8,
      $lte: product.price * 1.2
    }
  }
});
```

### Search vs Filter

<Tabs>
  <Tab title="When to Use Search">
    **Use `Products.search()`** for semantic/fuzzy matching:

    * "laptop for students"
    * "wireless headphones"
    * Natural language queries

    ```typescript theme={null}
    // Finds products by meaning, not exact match
    const results = await Products.search('affordable gaming laptop');
    ```
  </Tab>

  <Tab title="When to Use Filter">
    **Use `Products.get()` with filter** for structured queries:

    * Exact category matches
    * Price ranges
    * Stock status
    * Attribute combinations

    ```typescript theme={null}
    // Finds products matching exact criteria
    const results = await Products.get({
      filter: {
        category: 'Laptops',
        price: { $lte: 1000 },
        inStock: true
      }
    });
    ```
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Validate Products Exist">
    Always check if product exists:

    ```typescript theme={null}
    const product = await Products.getById(input.productId);

    if (!product) {
      throw new Error(`Product not found: ${input.productId}`);
    }
    ```
  </Accordion>

  <Accordion title="Check Stock Before Adding to Cart">
    ```typescript theme={null}
    const product = await Products.getById(productId);

    if (!product.inStock) {
      return {
        success: false,
        message: `${product.name} is currently out of stock`
      };
    }
    ```
  </Accordion>

  <Accordion title="Format Prices for Display">
    ```typescript theme={null}
    return {
      products: products.map(p => ({
        ...p,
        price: `$${p.price.toFixed(2)}`,
        formattedPrice: new Intl.NumberFormat('en-US', {
          style: 'currency',
          currency: 'USD'
        }).format(p.price)
      }))
    };
    ```
  </Accordion>

  <Accordion title="Handle Search with No Results">
    ```typescript theme={null}
    const results = await Products.search(query);

    if (results.products.length === 0) {
      return {
        products: [],
        message: `No products found for "${query}". Try different search terms.`
      };
    }
    ```
  </Accordion>
</AccordionGroup>

<Note title="Debugging tip">
  If product results don't look right, log the raw return to see the actual shape:

  ```typescript theme={null}
  const results = await Products.search(input.query);
  console.log('Products.search result:', JSON.stringify(results, null, 2));
  ```

  Then run `lua logs --type skill --limit 5` after a test message to inspect the output. See the [Debugging Skills guide](/cli/debugging) for the full workflow.
</Note>

## Next Steps

<CardGroup>
  <Card title="Baskets API" icon="cart-shopping" href="/api/baskets">
    Add products to shopping carts
  </Card>

  <Card title="Product Examples" icon="layer-group" href="/examples/products">
    See complete tool examples
  </Card>

  <Card title="Debugging Skills" icon="bug" href="/cli/debugging">
    Inspect runtime return values
  </Card>
</CardGroup>


# Lua Query
Source: https://docs.heylua.ai/api/query

The common bounded Mongo-style query language used across Lua platform APIs

## Overview

Lua Query is the single filter language for every Lua platform API that exposes a `filter` parameter. It behaves the same for Data, Products, and any other Mongo-backed entity: the entity changes, but the supported syntax, validation rules, limits, and errors do not.

API implementations scope the compiled query to the entity's data and immutable ownership fields. Filter input cannot replace an agent, collection, user, or organization predicate.

<Note>
  Methods without a `filter` parameter do not interpret their input as Lua Query. For example, `User.get()` selects one record by an exact user and agent identity; custom properties stored on that record remain ordinary data.
</Note>

## Supported syntax

Comparison operands must be JSON scalars. Membership operands must be arrays of JSON scalars. Logical operators are allowed only at the root of a filter or one of its logical branches.

```typescript theme={null}
// Equality and comparison
{ status: 'active' }
{ age: { $eq: 25 } }
{ age: { $ne: 25 } }
{ age: { $gt: 25, $lte: 65 } }

// Membership and array shorthand
{ tags: { $in: ['urgent', 'important'] } }
{ tags: { $nin: ['spam', 'archived'] } }
{ tags: ['urgent', 'important'] } // Shorthand for $in

// Existence
{ email: { $exists: true } }

// Root logical operators
{ $and: [{ age: { $gte: 18 } }, { age: { $lte: 65 } }] }
{ $or: [{ status: 'active' }, { status: 'pending' }] }

// Nested fields
{ 'metadata.brand': 'Lua' }
{ metadata: { brand: 'Lua' } }
```

The complete operator set is `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, root `$and`, and root `$or`.

## Security and errors

Lua Query is deliberately smaller than the complete MongoDB query language. Unknown or dangerous operators—including `$where`, `$expr`, `$function`, `$regex`, `$text`, and geospatial operators—are rejected with a `400` error and a stable `FILTER_*` code. They are never executed, silently removed, or allowed to widen the query.

Field paths cannot contain `$` segments, null bytes, empty segments, or prototype-related names. Invalid operands and misplaced operators also fail closed.

```text theme={null}
API request failed with status 400
(FILTER_UNSUPPORTED_OPERATOR at $.name.$regex):
Invalid filter: $regex is not supported
```

## Resource limits

The same limits apply on every API surface:

| Limit                           |       Maximum |
| ------------------------------- | ------------: |
| Encoded filter size             |         8 KiB |
| Nesting depth                   |      8 levels |
| Total nodes                     |           128 |
| Branches per logical operator   |            20 |
| Values per `$in` or `$nin` list |           100 |
| Field path size                 |     256 bytes |
| String operand size             |         4 KiB |
| Page size                       |     100 items |
| Pagination offset               | 100,000 items |
| Database execution time         |     5 seconds |

These limits protect shared database capacity while keeping common application queries expressive and predictable.


# Templates API
Source: https://docs.heylua.ai/api/templates

Send template messages programmatically

## Overview

The Templates API allows you to list, retrieve, and send template messages programmatically. Templates are pre-approved message formats for proactive communication across different channels.

<Note>
  Not to be confused with **[Agent Templates](/marketplace/agent-templates)** — full agent blueprints published and installed via `lua marketplace template`. This page is the runtime API for *message* templates.
</Note>

<Note>
  **Sending a template as part of a conversation?** [`Channels.whatsapp.sendTemplate`](/api/channels#channels-whatsapp-sendtemplate) is the canonical way to send a WhatsApp template to a specific user — it resolves the recipient by `userId` or phone number and records the send to the conversation thread, so your agent remembers the outreach. Use the `Templates.whatsapp.send` below for **bulk / campaign** sends by channel ID and a list of phone numbers. Both are supported; pick by use case.
</Note>

## Supported Template Types

<CardGroup>
  <Card title="WhatsApp Templates" icon="whatsapp">
    Pre-approved message formats for WhatsApp Business Accounts. Required for initiating conversations outside the 24-hour messaging window.
  </Card>
</CardGroup>

<Note>
  Additional template types may be added in the future. The API is designed to work consistently across different template types.
</Note>

## Quick Start

```typescript theme={null}
import { Templates } from 'lua-cli';

// List all WhatsApp templates for a channel
const result = await Templates.whatsapp.list(channelId);
console.log(result.templates);  // Array of templates
console.log(result.total);      // Total count

// Get a specific template
const template = await Templates.whatsapp.get(channelId, 'template_123');
console.log(template.name);   // Template name
console.log(template.status); // 'APPROVED', 'PENDING', etc.

// Send a WhatsApp template message
const response = await Templates.whatsapp.send(channelId, 'template_123', {
  phoneNumbers: ['+447551166594'],
  values: {
    body: { first_name: 'John', order_number: '12345' }
  }
});
```

<CardGroup>
  <Card title="Template Listing" icon="list">
    List and search templates with pagination
  </Card>

  <Card title="Template Retrieval" icon="magnifying-glass">
    Get template details including components
  </Card>

  <Card title="Batch Sending" icon="paper-plane">
    Send to multiple recipients at once
  </Card>

  <Card title="Dynamic Values" icon="wand-magic-sparkles">
    Fill template parameters dynamically
  </Card>
</CardGroup>

## WhatsApp Templates

Use `Templates.whatsapp` for WhatsApp Business templates.

### list()

List WhatsApp templates for a channel with optional pagination and search.

```typescript theme={null}
Templates.whatsapp.list(
  channelId: string,
  options?: ListTemplatesOptions
): Promise<PaginatedTemplatesResponse>
```

<ParamField type="string">
  The WhatsApp channel identifier
</ParamField>

<ParamField type="object">
  Optional pagination and search options
</ParamField>

<ParamField type="number">
  Page number (1-indexed)
</ParamField>

<ParamField type="number">
  Items per page
</ParamField>

<ParamField type="string">
  Search query to filter templates by name
</ParamField>

**Returns:**

```typescript theme={null}
{
  templates: Template[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}
```

**Examples:**

```typescript theme={null}
// List all templates (first page)
const result = await Templates.whatsapp.list(channelId);

// With pagination
const page2 = await Templates.whatsapp.list(channelId, { page: 2, limit: 20 });

// Search by name
const orderTemplates = await Templates.whatsapp.list(channelId, { search: 'order' });

// Combine options
const filtered = await Templates.whatsapp.list(channelId, {
  page: 1,
  limit: 5,
  search: 'welcome'
});
```

### get()

Retrieve a specific WhatsApp template by ID.

```typescript theme={null}
Templates.whatsapp.get(
  channelId: string,
  templateId: string
): Promise<WhatsAppTemplate>
```

<ParamField type="string">
  The WhatsApp channel identifier
</ParamField>

<ParamField type="string">
  The template identifier
</ParamField>

**Returns:** `WhatsAppTemplate` object

**Example:**

```typescript theme={null}
const template = await Templates.whatsapp.get(channelId, 'template_123');

console.log(template.name);       // "order_confirmation"
console.log(template.status);     // "APPROVED"
console.log(template.category);   // "UTILITY"
console.log(template.language);   // "en"
console.log(template.components); // Array of components
```

### send()

Send a WhatsApp template message to one or more phone numbers.

```typescript theme={null}
Templates.whatsapp.send(
  channelId: string,
  templateId: string,
  data: SendTemplateData
): Promise<SendTemplateResponse>
```

<ParamField type="string">
  The WhatsApp channel identifier
</ParamField>

<ParamField type="string">
  The template identifier
</ParamField>

<ParamField type="object">
  Send data including recipients and template values
</ParamField>

<ParamField type="string[]">
  Array of recipients. For WhatsApp: phone numbers in E.164 format (e.g., +447551166594)
</ParamField>

<ParamField type="object">
  Template parameter values
</ParamField>

<ParamField type="object">
  Header component parameter values. For media headers, either use `image_url` (IMAGE format), `video_url` (VIDEO format), or `document_url` + optional `document_filename` (DOCUMENT format) — or pass a Meta media ID instead via `image_id`, `video_id`, or `document_id`. A media ID takes precedence if both are given.
</ParamField>

<ParamField type="object">
  Body component parameter values
</ParamField>

<ParamField type="SendTemplateButtonValue[]">
  Array of button parameter values. Each entry has `sub_type` (`'QUICK_REPLY'` | `'URL'` | `'PHONE_NUMBER'` | `'COPY_CODE'`), `index`, and optional `text` or `coupon_code`.
</ParamField>

**Returns:**

```typescript theme={null}
{
  results: Array<{
    phoneNumber: string;
    success: boolean;
    messageId?: string;
  }>;
  errors: Array<{
    phoneNumber: string;
    error: string;
  }>;
}
```

**Examples:**

```typescript theme={null}
// Simple send to one recipient
const result = await Templates.whatsapp.send(channelId, 'welcome_template', {
  phoneNumbers: ['+447551166594']
});

// Send with body parameters
const orderResult = await Templates.whatsapp.send(channelId, 'order_confirmation', {
  phoneNumbers: ['+447551166594'],
  values: {
    body: {
      first_name: 'John',
      order_number: '12345',
      delivery_date: 'December 25, 2025'
    }
  }
});

// Send to multiple recipients (batch)
const batchResult = await Templates.whatsapp.send(channelId, 'promotion', {
  phoneNumbers: ['+447551166594', '+447551166595', '+447551166596'],
  values: {
    header: { image_url: 'https://example.com/promo.jpg' },
    body: { discount: '20%' }
  }
});

// Send with video header
const videoResult = await Templates.whatsapp.send(channelId, 'product_demo', {
  phoneNumbers: ['+447551166594'],
  values: {
    header: { video_url: 'https://example.com/product-demo.mp4' },
    body: { product_name: 'Acme Widget' }
  }
});

// Send with document header
const docResult = await Templates.whatsapp.send(channelId, 'invoice', {
  phoneNumbers: ['+447551166594'],
  values: {
    header: {
      document_url: 'https://example.com/invoice-12345.pdf',
      document_filename: 'invoice-12345.pdf'
    },
    body: { order_number: '12345', total: '$99.99' }
  }
});

// Handle response
batchResult.results.forEach(r => {
  if (r.success) {
    console.log(`Sent to ${r.phoneNumber}: ${r.messageId}`);
  }
});

batchResult.errors.forEach(e => {
  console.error(`Failed for ${e.phoneNumber}: ${e.error}`);
});
```

## Template Structure

### WhatsApp Templates

WhatsApp templates have the following structure:

```typescript theme={null}
interface Template {
  id: string;
  name: string;
  status: 'APPROVED' | 'PENDING' | 'REJECTED';
  category: 'UTILITY' | 'MARKETING' | 'AUTHENTICATION';
  language: string;
  components: TemplateComponent[];
}

interface TemplateComponent {
  type: 'HEADER' | 'BODY' | 'FOOTER' | 'BUTTONS';
  format?: 'TEXT' | 'IMAGE' | 'VIDEO' | 'DOCUMENT';
  text?: string;
  buttons?: TemplateButton[];
}

interface TemplateButton {
  type: 'QUICK_REPLY' | 'URL' | 'PHONE_NUMBER' | 'COPY_CODE';
  text: string;
  url?: string;
  phone_number?: string;
  example?: string[];
}
```

<Note>
  Template structure may vary by template type. The above shows the WhatsApp template structure.
</Note>

### Media Headers

WhatsApp templates support media headers in addition to text headers. Headers can contain an image, video, or document:

* **IMAGE**: Static image (`format: 'IMAGE'`)
* **VIDEO**: Playable video clip (`format: 'VIDEO'`)
* **DOCUMENT**: Downloadable document like a PDF (`format: 'DOCUMENT'`)

When creating a template with a media header, you provide:

* **`format`** — one of `'IMAGE'`, `'VIDEO'`, or `'DOCUMENT'`
* **`mediaUrl`** — a publicly-reachable HTTPS URL to a sample file for approval. This URL must:
  * Be accessible over HTTPS
  * Match the format's MIME type requirements:
    * IMAGE: `.jpg`, `.png`, `.webp`
    * VIDEO: `.mp4`, `.3gp`
    * DOCUMENT: `.pdf`, `.docx`, `.xlsx`, `.pptx` (up to 10 MB)
  * Be within Meta's size limits (images ≤ 5 MB, videos ≤ 16 MB, documents ≤ 10 MB)

Once the template is approved, when you send it via the `Templates.whatsapp.send()` API, you provide the actual media URL in the `values.header` object:

* `image_url` for IMAGE format templates
* `video_url` for VIDEO format templates
* `document_url` (and optionally `document_filename`) for DOCUMENT format templates

The media URL provided at send time must also be publicly reachable over HTTPS.

### Sending by media ID instead of URL

WhatsApp re-downloads the URL on **every** send. For bulk campaigns you can upload the asset to Meta once and reuse the returned media ID across every recipient, which skips that per-send fetch entirely:

```typescript theme={null}
const response = await Templates.whatsapp.send('channel_123', 'promo_template', {
  phoneNumbers: ['+1234567890', '+0987654321'],
  values: {
    header: { image_id: '1234567890123456' },
    body: { discount: '20%' },
  },
});
```

Use `image_id`, `video_id`, or `document_id` to match the template's header format. `document_filename` still applies. If you pass both a media ID and a URL, the media ID wins.

<Warning>
  Three constraints decide whether a media ID resolves at send time:

  * **Upload it via `POST /{phone-number-id}/media`.** The Resumable Upload API (`POST /{app-id}/uploads`) returns an `h:...` file handle instead, which is only valid for *creating* a template — it will never work as a send-time media ID.
  * **Media IDs are scoped to the business phone number they were uploaded on.** That must be the phone number behind the channel you're sending from, or Meta won't resolve the ID.
  * **Meta expires media IDs after 30 days.** Plan on re-uploading per campaign rather than once forever.
</Warning>

## Template Parameters

Templates use named parameters in the format `{{parameter_name}}`. When sending, provide values for each parameter:

```typescript theme={null}
// Template body: "Hello {{first_name}}, your order {{order_number}} is ready!"

await Templates.whatsapp.send(channelId, templateId, {
  phoneNumbers: ['+447551166594'],
  values: {
    body: {
      first_name: 'John',
      order_number: 'ORD-12345'
    }
  }
});
```

<Warning>
  All required parameters must be provided when sending a template. Missing parameters will cause the send to fail.
</Warning>

## WhatsApp Examples

The following examples demonstrate using the Templates API with WhatsApp templates.

### Order Confirmation Tool

```typescript theme={null}
import { LuaTool, Templates } from 'lua-cli';
import { z } from 'zod';

export default class SendOrderConfirmationTool implements LuaTool {
  name = "send_order_confirmation";
  description = "Send order confirmation via WhatsApp template";
  
  inputSchema = z.object({
    channelId: z.string().describe("WhatsApp channel ID"),
    phoneNumber: z.string().describe("Customer phone number"),
    orderNumber: z.string().describe("Order number"),
    customerName: z.string().describe("Customer name"),
    deliveryDate: z.string().describe("Expected delivery date")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Templates.whatsapp.send(input.channelId, 'order_confirmation', {
      phoneNumbers: [input.phoneNumber],
      values: {
        body: {
          customer_name: input.customerName,
          order_number: input.orderNumber,
          delivery_date: input.deliveryDate
        }
      }
    });
    
    if (result.errors.length > 0) {
      return {
        success: false,
        error: result.errors[0].error
      };
    }
    
    return {
      success: true,
      messageId: result.results[0].messageId,
      message: `Order confirmation sent to ${input.phoneNumber}`
    };
  }
}
```

### Webhook: Send Welcome Template on New User

```typescript theme={null}
import { LuaWebhook, LuaWebhookConfig, Templates } from 'lua-cli';

const config: LuaWebhookConfig = {
  name: 'new-user-welcome',
  description: 'Send welcome template when a new user signs up'
};

const webhook: LuaWebhook = {
  config,
  execute: async (event) => {
    const { channelId, phoneNumber, firstName } = event.data;
    
    // Find welcome template
    const listResult = await Templates.whatsapp.list(channelId, { search: 'welcome' });
    const welcomeTemplate = listResult.templates.find(t => t.name === 'welcome_message');
    
    if (!welcomeTemplate) {
      return { error: 'Welcome template not found' };
    }
    
    // Send welcome message
    const sendResult = await Templates.whatsapp.send(channelId, welcomeTemplate.id, {
      phoneNumbers: [phoneNumber],
      values: {
        body: { first_name: firstName }
      }
    });
    
    return {
      sent: sendResult.results.length > 0,
      messageId: sendResult.results[0]?.messageId
    };
  }
};

export default webhook;
```

### List Templates Tool

```typescript theme={null}
import { LuaTool, Templates } from 'lua-cli';
import { z } from 'zod';

export default class ListTemplatesTools implements LuaTool {
  name = "list_whatsapp_templates";
  description = "List available WhatsApp templates";
  
  inputSchema = z.object({
    channelId: z.string().describe("WhatsApp channel ID"),
    search: z.string().optional().describe("Search query to filter templates"),
    page: z.number().optional().describe("Page number")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Templates.whatsapp.list(input.channelId, {
      search: input.search,
      page: input.page || 1,
      limit: 10
    });
    
    return {
      templates: result.templates.map(t => ({
        id: t.id,
        name: t.name,
        status: t.status,
        category: t.category,
        language: t.language
      })),
      total: result.total,
      page: result.page,
      totalPages: result.totalPages
    };
  }
}
```

## Use Cases (WhatsApp)

### Transactional Notifications

```typescript theme={null}
// Order shipped
await Templates.whatsapp.send(channelId, 'order_shipped', {
  phoneNumbers: [customerPhone],
  values: {
    body: {
      order_number: order.id,
      tracking_number: shipment.trackingNumber,
      carrier: shipment.carrier
    }
  }
});

// Appointment reminder
await Templates.whatsapp.send(channelId, 'appointment_reminder', {
  phoneNumbers: [patientPhone],
  values: {
    body: {
      patient_name: patient.name,
      appointment_date: appointment.date,
      doctor_name: appointment.doctor
    }
  }
});
```

### Marketing Campaigns

```typescript theme={null}
// Get all customers who opted in
const customers = await getOptedInCustomers();

// Send promotion to all
const result = await Templates.whatsapp.send(channelId, 'holiday_sale', {
  phoneNumbers: customers.map(c => c.phone),
  values: {
    header: { image_url: 'https://example.com/sale-banner.jpg' },
    body: { discount_code: 'HOLIDAY25' }
  }
});

console.log(`Sent: ${result.results.length}, Failed: ${result.errors.length}`);
```

### Authentication / OTP

```typescript theme={null}
// Send OTP
const otp = generateOTP();
await Templates.whatsapp.send(channelId, 'otp_verification', {
  phoneNumbers: [userPhone],
  values: {
    body: { otp_code: otp }
  }
});
```

## Tracking Delivery Status

After sending template messages, you can track whether they were delivered, read, or failed using webhook event subscriptions.

### Setup

1. Create a webhook to handle delivery events
2. Subscribe it to the status events you care about

```bash theme={null}
lua webhooks subscribe --webhook-name campaign-tracker --event message.sent
lua webhooks subscribe --webhook-name campaign-tracker --event message.delivered
lua webhooks subscribe --webhook-name campaign-tracker --event message.read
lua webhooks subscribe --webhook-name campaign-tracker --event message.failed
```

### Example: Campaign Analytics

```typescript theme={null}
import { LuaWebhook, Data, Templates } from 'lua-cli';

const campaignTracker = new LuaWebhook({
  name: 'campaign-tracker',
  description: 'Track template message delivery for campaigns',
  
  execute: async (event) => {
    const { body } = event;
    
    await Data.create('campaign-metrics', {
      messageId: body.messageWamid,
      recipient: body.recipientId,
      status: body.status,
      timestamp: body.timestamp,
      billable: body.pricing?.billable
    }, `${body.status} ${body.recipientId}`);
    
    return { tracked: true };
  }
});

export default campaignTracker;
```

After sending a batch of templates, your webhook receives individual status updates for each recipient as messages are sent, delivered, and read. Use this data to measure open rates, delivery rates, and catch failures.

<Note>
  The `messageId` returned by `Templates.whatsapp.send()` corresponds to `messageWamid` in the status event payload, allowing you to correlate sends with delivery outcomes.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Handle Batch Send Results">
    When sending to multiple recipients, always check for partial failures:

    ```typescript theme={null}
    const result = await Templates.whatsapp.send(channelId, templateId, {
      phoneNumbers: phoneNumbers
    });

    // Log successes
    result.results.forEach(r => {
      console.log(`✓ Sent to ${r.phoneNumber}`);
    });

    // Handle failures
    if (result.errors.length > 0) {
      result.errors.forEach(e => {
        console.error(`✗ Failed for ${e.phoneNumber}: ${e.error}`);
      });
    }
    ```
  </Accordion>

  <Accordion title="Validate Phone Numbers">
    Use E.164 format for phone numbers:

    ```typescript theme={null}
    // ✅ Good
    phoneNumbers: ['+447551166594', '+14155552671']

    // ❌ May cause issues
    phoneNumbers: ['07551166594', '(415) 555-2671']
    ```
  </Accordion>

  <Accordion title="Check Template Status">
    Only send approved templates:

    ```typescript theme={null}
    const template = await Templates.whatsapp.get(channelId, templateId);

    if (template.status !== 'APPROVED') {
      throw new Error(`Template ${template.name} is not approved (status: ${template.status})`);
    }
    ```
  </Accordion>

  <Accordion title="Match Parameter Names Exactly">
    Parameter names in `values` must match template parameters exactly:

    ```typescript theme={null}
    // If template has: "Hello {{first_name}}, order {{order_id}} is ready"

    // ✅ Correct
    values: {
      body: {
        first_name: 'John',
        order_id: '12345'
      }
    }

    // ❌ Wrong parameter names
    values: {
      body: {
        name: 'John',      // Should be 'first_name'
        orderId: '12345'   // Should be 'order_id'
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## TypeScript Types

```typescript theme={null}
interface ListTemplatesOptions {
  page?: number;
  limit?: number;
  search?: string;
}

interface PaginatedTemplatesResponse {
  templates: Template[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

// WhatsApp template structure
interface WhatsAppTemplate {
  id: string;
  name: string;
  status: 'APPROVED' | 'PENDING' | 'REJECTED';
  category: 'UTILITY' | 'MARKETING' | 'AUTHENTICATION';
  language: string;
  components: TemplateComponent[];
  correct_category?: string;
  message_send_ttl_seconds?: number;
  parameter_format?: 'NAMED' | 'POSITIONAL';
  previous_category?: string;
  rejected_reason?: string;
}

interface SendTemplateData {
  phoneNumbers: string[];  // Recipients (phone numbers for WhatsApp)
  values?: {
    header?: Record<string, string>;
    body?: Record<string, string>;
    buttons?: SendTemplateButtonValue[];
  };
}

interface SendTemplateButtonValue {
  sub_type: 'QUICK_REPLY' | 'URL' | 'PHONE_NUMBER' | 'COPY_CODE';
  index: string;
  text?: string;
  coupon_code?: string;
}

interface SendTemplateResponse {
  results: Array<{
    phoneNumber: string;
    success: boolean;
    messageId?: string;
  }>;
  errors: Array<{
    phoneNumber: string;
    error: string;
  }>;
  totalProcessed: number;
  totalErrors: number;
}
```

## Next Steps

<CardGroup>
  <Card title="User API" icon="user" href="/api/user">
    Send messages to users
  </Card>

  <Card title="Jobs API" icon="clock" href="/api/jobs">
    Schedule template sends
  </Card>
</CardGroup>


# User API
Source: https://docs.heylua.ai/api/user

Persistent per-user storage for state, preferences, and custom data

## Overview

The User API is a **persistent, per-user key-value store** that survives across conversations and sessions. Use it to store any data tied to a user — onboarding progress, workflow state, preferences, cart contents, verification status, or any custom fields your agent needs.

Think of it as a **schemaless user database**: read and write any property, and it persists automatically. This makes it ideal for **multi-step flows** where your agent needs to remember where a user left off.

<Note>
  User data is one record per user and agent. It is different from the [Data API](/api/data), which stores many entries in named, agent-owned collections and can index those entries for semantic search.
</Note>

<Note>
  `User.get()` is an exact identity lookup and does not accept a `filter`. APIs that do expose filters all use the same entity-independent [Lua Query language](/api/query); stored `user.*` properties are ordinary data and are never interpreted as query operators.
</Note>

```typescript theme={null}
import { User } from 'lua-cli';

// Get user instance
const user = await User.get();

// Access the read-only user profile (system-provided identity)
console.log(user._luaProfile.fullName);
console.log(user._luaProfile.emailAddresses); // A simple array of strings

// Store ANY custom data — it persists across conversations and sessions
user.onboardingStep = 'verified';
user.lastProductViewed = 'SKU-123';
user.collectedData = { company: 'Acme', plan: 'enterprise' };
await user.save();
```

## Read-Only User Profile (`_luaProfile`)

A new, read-only property `user._luaProfile` is now available on the user object. This provides a secure and reliable way to access core user identity information.

* **`_luaProfile`** (Read-Only): Contains essential user data like `userId`, `fullName`, `mobileNumbers`, and `emailAddresses`.
  * The `_lua` prefix indicates this is a special, system-provided property.
  * This data is **immutable**; any attempts to change it will be silently ignored.
* **`user.*`** (Mutable): Continue to use the main `user` object to store and manage any custom data your agent needs, such as preferences, shopping carts, or game scores.

<Note>
  The Lua profile and your custom User data are independent. `User.get()` is a read-only operation: it returns `_luaProfile` even when this user has not stored any custom data for the agent, and it does not create an empty data record. The first `update()` or `save()` creates that record when needed.
</Note>

<CardGroup>
  <Card title="Core User Identity" icon="lock">
    Access read-only data like `user._luaProfile.userId` and `user._luaProfile.fullName`.
  </Card>

  <Card title="Persistent Storage" icon="database">
    Store any data on the user object — onboarding state, workflow progress, preferences, cart contents. Persists across all conversations and sessions.
  </Card>
</CardGroup>

### Deprecated `user.userId`

To centralize core user information, `user.userId` is now deprecated. Please update your code to use `user._luaProfile.userId`. The old property will be removed in a future version.

```typescript theme={null}
// ✅ New & Recommended
const userId = user._luaProfile.userId;

// ⚠️ Deprecated
const oldUserId = user.userId;
```

## User as a State Store

The User object is not just for profile data — it is a **persistent state store** for building multi-step, stateful agent workflows. Any property you write to the user object persists across conversations, sessions, and even days or months.

<Note>
  **Key insight for AI agents and developers:** The User object is the primary way to maintain state across conversations. Use it to track onboarding progress, accumulate data across tool calls, and resume workflows exactly where the user left off.
</Note>

### Onboarding State Machine Example

```typescript theme={null}
import { LuaTool, User } from 'lua-cli';
import { z } from 'zod';

export class OnboardingTool implements LuaTool {
  name = 'handle_onboarding';
  description = 'Guide user through onboarding steps, resuming where they left off';

  inputSchema = z.object({
    data: z.record(z.any()).optional().describe('Data collected in this step')
  });

  async execute(input: any) {
    const user = await User.get();

    // Read persisted state — survives across conversations!
    const step = user.onboardingStep || 'not_started';

    switch (step) {
      case 'not_started':
        user.onboardingStep = 'collecting_info';
        user.onboardingStartedAt = new Date().toISOString();
        await user.save();
        return { message: "Let's get you set up! What's your company name?" };

      case 'collecting_info':
        user.companyName = input.data?.companyName;
        user.onboardingStep = 'awaiting_verification';
        user.completedSteps = ['welcome', 'personal_info'];
        await user.save();
        return { message: 'Great! Now let\'s verify your identity.' };

      case 'awaiting_verification':
        user.verified = true;
        user.onboardingStep = 'choosing_plan';
        user.completedSteps = [...(user.completedSteps || []), 'verification'];
        await user.save();
        return { message: 'Verified! Which plan works best for you?' };

      case 'choosing_plan':
        user.plan = input.data?.plan;
        user.onboardingStep = 'complete';
        user.onboardingCompletedAt = new Date().toISOString();
        user.completedSteps = [...(user.completedSteps || []), 'plan_selection'];
        await user.save();
        return { message: `You're all set on the ${user.plan} plan!` };

      case 'complete':
        return {
          message: `Welcome back! You completed onboarding on ${user.onboardingCompletedAt}.`,
          plan: user.plan,
          company: user.companyName
        };
    }
  }
}
```

### Common State Storage Patterns

| Pattern                   | What to store on `user.*`                               | Example                                                 |
| ------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
| **Onboarding flow**       | `onboardingStep`, `completedSteps`, `collectedData`     | Track which step the user is on, resume across sessions |
| **Multi-step form**       | `formData`, `currentSection`, `validationErrors`        | Accumulate form data across multiple tool calls         |
| **Verification workflow** | `verificationStatus`, `documentsUploaded`, `verifiedAt` | Track identity/document verification progress           |
| **Feature adoption**      | `featuresUsed`, `tutorialStep`, `firstActionAt`         | Guide users through product discovery                   |
| **Conversation context**  | `lastIntent`, `pendingAction`, `conversationTopic`      | Help the agent maintain context between sessions        |

## Features

<CardGroup>
  <Card title="Direct Access" icon="bolt">
    Access properties with `user.name` instead of `user.data.name`
  </Card>

  <Card title="Auto Sanitization" icon="shield">
    Removes sensitive fields automatically
  </Card>

  <Card title="Built-in Methods" icon="wrench">
    `update()`, `save()`, `send()`, and `clear()` included
  </Card>

  <Card title="Messaging" icon="message">
    Send text, images, and files to users
  </Card>

  <Card title="Inbox" icon="inbox">
    File approval and notice cards with `User.Inbox.push()`
  </Card>
</CardGroup>

## Inbox (`User.Inbox`)

`User.Inbox.push()` puts a card on the current user's desk — an approval to click, a notice to read, or an integration to reconnect — and returns a receipt straight away:

```typescript theme={null}
import { User } from 'lua-cli';

const receipt = await User.Inbox.push({
  title: 'Approve the Q3 renewal quote',
  body: 'Northstar Ltd renewal is ready to send at $48,000.',
  actions: ['approve'],
  key: 'northstar-q3-renewal',
});
```

Unlike `User.get(userId)`, it takes no recipient — the card always goes to the user of the current execution context, so it works in tools and dynamic jobs but not in context-less webhooks or pre-defined jobs.

See the [Inbox API reference](/api/inbox) for card kinds, daily limits, revision keys, and the full receipt contract.

## get(identifier?)

Retrieve user data as a UserDataInstance. Supports lookup by userId, email, or phone number.

```typescript theme={null}
User.get(identifier?: string | UserLookupOptions): Promise<UserDataInstance | null>
```

<ParamField type="string | UserLookupOptions">
  One of:

  * **No parameter**: Returns current user from conversation context
  * **string (userId)**: Retrieve a specific user by ID
  * **`{ email: string }`**: Look up user by email address
  * **`{ phone: string }`**: Look up user by phone number (with or without `+` prefix)

  **Required in:** Webhooks, pre-defined LuaJob (no conversational context)

  **Optional in:** Tools, dynamic jobs (has conversational context)
</ParamField>

**Returns:** `UserDataInstance` with proxy-based property access, or `null` if user not found (for email/phone lookup)

<Note>
  Look up users by email or phone — especially useful in webhooks where you receive contact info from external systems but don't have the internal userId.
</Note>

<Warning>
  Compiled voice does not currently resolve `{ email }` or `{ phone }` identifiers. In that runtime they may fall back to the current voice user, so use `User.get(userId)` for a portable explicit target before any write, including `update()`, `save()`, `patch()`, `unset()`, or `clear()`.
</Warning>

### Shortcut: `User.getChatHistory()`

If you only need chat history for the **current** user (in a tool with conversational context), the top-level static `User.getChatHistory()` skips the `User.get()` step:

```typescript theme={null}
import { User } from 'lua-cli';

const history = await User.getChatHistory();
```

This is equivalent to `(await User.get()).getChatHistory()` — see the [instance method](#getchathistory) below for the full return shape and examples.

## When to Use userId Parameter

Understanding when userId is required vs optional:

| Context      | Method                                      | Identifier Required? | Why                        |
| ------------ | ------------------------------------------- | -------------------- | -------------------------- |
| **Tools**    | `User.get()`                                | ❌ Optional           | Has conversational context |
| **Webhooks** | `User.get(userId)` or `User.get({ email })` | ✅ **REQUIRED**       | No conversational context  |
| **LuaJob**   | `User.get(userId)` or `User.get({ phone })` | ✅ **REQUIRED**       | No conversational context  |
| **Jobs API** | `jobInstance.user()`                        | ❌ N/A                | Automatic user context     |

<Warning>
  **Context Matters:**

  * **Tools:** identifier is optional - defaults to current user in conversation
  * **Webhooks:** identifier is REQUIRED - use userId, email, or phone lookup
  * **LuaJob (pre-defined):** identifier is REQUIRED - use userId, email, or phone lookup
  * **Jobs API (dynamic):** Use `jobInstance.user()` instead - automatic context captured!
</Warning>

<Tip>
  **New!** In webhooks, you can now look up users by email or phone if you don't have the userId:

  ```typescript theme={null}
  const user = await User.get({ email: 'customer@example.com' });
  const user = await User.get({ phone: '+1234567890' });
  ```
</Tip>

**Examples:**

<Tabs>
  <Tab title="Current User">
    **Get the current user from conversation context:**

    ```typescript theme={null}
    import { User } from 'lua-cli';

    // In your tool
    async execute(input: any) {
      const user = await User.get();
      
      // Direct property access
      console.log(user.name);    // "John Doe"
      console.log(user.email);   // "john@example.com"
      console.log(user.phone);   // "555-0123"
      
      return { userName: user.name };
    }
    ```
  </Tab>

  <Tab title="Specific User (Webhooks/LuaJob)">
    **Get a specific user by ID (REQUIRED in webhooks and pre-defined jobs):**

    ```typescript theme={null}
    import { User } from 'lua-cli';

    // In a webhook (NO conversational context)
    execute: async (event) => {
      // ⚠️ MUST provide userId in webhooks
      const customerId = event.data.object.metadata?.customerId;
      
      if (!customerId) {
        return { error: 'No customer ID provided' };
      }
      
      const user = await User.get(customerId);
      
      // Send message to that specific user
      await user.send([{
        type: 'text',
        text: `✅ Payment received: $${event.data.object.amount/100}`
      }]);
      
      return { notified: true };
    }
    ```

    **Required in:**

    * ✅ **Webhooks** - No conversational context
    * ✅ **LuaJob (pre-defined)** - No conversational context
    * ✅ **Admin tools** - Managing other users

    **NOT needed in:**

    * ❌ **Tools** - Use `User.get()` without userId
    * ❌ **Jobs API (dynamic)** - Use `jobInstance.user()` instead
  </Tab>

  <Tab title="Dynamic Jobs (Special Case)">
    **Dynamic jobs have automatic user context:**

    ```typescript theme={null}
    import { Jobs } from 'lua-cli';

    // Creating a dynamic job from a tool
    await Jobs.create({
      name: 'user-reminder',
      execute: async (jobInstance) => {
        // ✅ Use jobInstance.user() - automatic context!
        const user = await jobInstance.user();
        
        await user.send([{
          type: 'text',
          text: 'Reminder: Your meeting starts in 5 minutes!'
        }]);
      }
    });
    ```

    **Why it works:** Dynamic jobs created from tools automatically capture the user context, so you don't need to provide a userId.
  </Tab>

  <Tab title="Email/Phone Lookup">
    **Look up a user by email or phone number:**

    ```typescript theme={null}
    import { User } from 'lua-cli';

    // In a webhook receiving customer contact info
    execute: async (event) => {
      const { email, phone } = event.body;
      
      // Look up by email
      const userByEmail = await User.get({ email: 'customer@example.com' });
      
      // Look up by phone (both formats work)
      const userByPhone = await User.get({ phone: '+1234567890' });
      const userByPhone2 = await User.get({ phone: '1234567890' });
      
      // Handle not found gracefully
      if (!userByEmail) {
        return { error: 'User not found' };
      }
      
      // Update the user's data
      userByEmail.routingEnabled = true;
      await userByEmail.save();
      
      return { 
        success: true, 
        userId: userByEmail._luaProfile.userId 
      };
    }
    ```

    **Use cases:**

    * ✅ **Webhooks** - External systems send email/phone, not userId
    * ✅ **Admin tools** - Operators search by contact info
    * ✅ **Integrations** - Third-party systems don't have Lua user IDs

    <Warning>
      **Returns `null` if not found:** Email/phone lookup returns `null` when resolution fails. A string user ID returns a target-bound instance even when its User-data record does not exist yet, and a later write can create that record. Use explicit IDs only from a trusted, validated source, and always null-check email/phone results.
    </Warning>
  </Tab>
</Tabs>

## UserDataInstance API

### Property Access (Direct)

Access any user property directly:

```typescript theme={null}
// Reading properties
const name = user.name;
const email = user.email;
const preferences = user.preferences;
const customField = user.customField;

// Setting properties (local only - call update() to persist)
user.name = "Jane Doe";
user.email = "jane@example.com";
user.preferences = { theme: "dark" };

// Checking existence
if ('name' in user) {
  console.log('User has a name');
}
```

### update()

Update user data on the server and locally.

```typescript theme={null}
user.update(data: Record<string, any>): Promise<any>
```

<ParamField type="object">
  Object containing fields to update or add
</ParamField>

**Returns:** Promise resolving to updated sanitized user data

**Examples:**

```typescript theme={null}
// Update single field
await user.update({ name: "John Doe" });

// Update multiple fields
await user.update({
  name: "John Doe",
  email: "john@example.com",
  phone: "555-1234"
});

// Update nested objects
await user.update({
  preferences: {
    theme: "dark",
    notifications: true,
    language: "en"
  }
});

// Access updated data immediately
console.log(user.name);  // "John Doe"
console.log(user.preferences.theme);  // "dark"
```

When the instance came from `User.get(identifier)`, `update()` writes to that same user. Existing code using `User.get()` without an identifier keeps the current-session behavior.

```typescript theme={null}
const reassignedUser = await User.get('user_123');
if (!reassignedUser) throw new Error('User not found');
await reassignedUser.update({ rep_code: 'NEW_REP' });
```

### patch()

Atomically set and remove top-level fields in one request. Setting a field to `null` stores `null`; only `unset` removes it.

```typescript theme={null}
user.patch(mutation: {
  set?: Record<string, any>;
  unset?: string[];
}): Promise<any>
```

```typescript theme={null}
const user = await User.get('user_123');
if (!user) throw new Error('User not found');

await user.patch({
  set: { roster_version: 12, status: null },
  unset: ['rep_code']
});
```

The mutation is atomic, so concurrent writers cannot observe a half-applied `set`/`unset` pair. A mutation must change at least one field, `set` and `unset` cannot contain the same field, and field names must be non-empty and cannot start with `$` or contain `.` or a null byte.

### unset()

Remove one or more top-level fields. This is a convenience wrapper around `patch({ unset: fields })`.

```typescript theme={null}
user.unset(...fields: string[]): Promise<any>
```

```typescript theme={null}
const user = await User.get('user_123');
if (!user) throw new Error('User not found');
await user.unset('rep_code', 'legacy_assignment');
```

<Note>
  In compiled voice, use a user ID (`User.get(userId)`) for an explicit cross-user target. Email and phone lookup require lua-auth resolution and are not currently supported in that runtime.
</Note>

### save()

Save the current state of user data to the server. This is a convenience method that persists all changes made to the user instance.

```typescript theme={null}
user.save(): Promise<boolean>
```

**Returns:** Promise resolving to `true` if successful

**Examples:**

```typescript theme={null}
const user = await User.get();

// Modify properties
user.name = "John Doe";
user.email = "john@example.com";
user.phone = "555-1234";

// Save all changes at once
await user.save();

// Much cleaner than multiple update calls!
```

<Note>
  **Tip:** The `save()` method provides a simpler workflow - modify properties then save, rather than passing data to `update()`.
</Note>

### send()

Send messages to the user conversation. Supports text, images, and file attachments.

```typescript theme={null}
user.send(messages: Message[]): Promise<any>
```

<ParamField type="Message[]">
  Array of messages to send (text, image, or file)
</ParamField>

**Message Types:**

```typescript theme={null}
// Text message
type TextMessage = {
  type: "text";
  text: string;
};

// Image message
type ImageMessage = {
  type: "image";
  image: string;      // Base64 encoded image data
  mediaType: string;   // e.g., "image/png", "image/jpeg"
};

// File message
type FileMessage = {
  type: "file";
  data: string;       // Base64 encoded file data
  mediaType: string;   // e.g., "application/pdf"
};
```

**Examples:**

```typescript theme={null}
const user = await User.get();

// Send a text message
await user.send([
  { type: "text", text: "Your order has been shipped!" }
]);

// Send multiple messages
await user.send([
  { type: "text", text: "Here is your receipt:" },
  { 
    type: "image", 
    image: base64ImageData, 
    mediaType: "image/png" 
  }
]);

// Send a file
await user.send([
  { type: "text", text: "Your invoice is attached:" },
  {
    type: "file",
    data: base64PdfData,
    mediaType: "application/pdf"
  }
]);
```

<Note>
  **`user.send()` vs [`Channels.send`](/api/channels):** `user.send()` delivers to the user on the channel they're **already active on** — simplest when you have a `User` and just want to reach them. Use [`Channels.send`](/api/channels) when you need to **choose a specific channel** (e.g. always WhatsApp), reach a **cold** phone number or email with no prior conversation, or send an approved WhatsApp template. Both record the message to the user's conversation thread. See [Proactive Messaging](/channels/proactive-messaging#three-ways-to-send).
</Note>

### getChatHistory()

Retrieve the conversation history for the current user with the active agent. Returns the last 40 user/assistant messages, transformed for display: hidden text is filtered out and embedded media (audio, video, files) is surfaced as structured `content` parts you can render directly.

```typescript theme={null}
user.getChatHistory(): Promise<ChatHistoryMessage[]>
```

**Return shape:**

```typescript theme={null}
interface ChatHistoryMessage {
  id: string;
  role: 'user' | 'assistant';
  createdAt: string; // ISO-8601
  content: ChatHistoryContent[];
}

interface ChatHistoryContent {
  type: 'text' | 'image' | 'video' | 'audio' | 'file';
  // For text:
  text?: string;
  // For media (depending on type):
  image?: string;       // image URL or base64
  video?: string;       // video URL or base64
  data?: string;        // file/audio URL or base64
  mediaType?: string;   // e.g. "image/png", "audio/mpeg", "application/pdf"
}
```

**Example:**

```typescript theme={null}
const user = await User.get();
const history = await user.getChatHistory();

console.log(history.length); // Number of messages

for (const msg of history) {
  for (const part of msg.content) {
    if (part.type === 'text') {
      console.log(`${msg.role}: ${part.text}`);
    } else if (part.type === 'image') {
      console.log(`${msg.role} sent image (${part.mediaType})`);
    }
  }
}
```

### clear()

Clear all User data for the user represented by this instance. An instance returned by `User.get(target)` remains bound to that target.

```typescript theme={null}
user.clear(): Promise<boolean>
```

**Returns:** Promise resolving to `true` if successful

<Note>
  The VM sandbox retains its legacy return shape `{ success: true }`; direct `lua-cli` and compiled voice return the boolean `true`. Both shapes are truthy. This difference is preserved for backward compatibility, so avoid strict equality checks when code must run in every runtime.
</Note>

**Example:**

```typescript theme={null}
try {
  const user = await User.get('user_123');
  if (!user) throw new Error('User not found');
  const success = await user.clear();
  if (success) {
    console.log('User data cleared successfully');
  }
} catch (error) {
  console.error('Failed to clear user data:', error);
}
```

<Warning>
  **Destructive operation!** This removes the complete custom-data record for the user represented by this instance. It does not delete their Lua profile or chat history. Use with caution.
</Warning>

After `clear()`, a later `User.get()` can still read `_luaProfile`; the read does not recreate the deleted custom-data record.

<Note>
  `lua chat clear` clears conversation history; it does not clear User data. Use `user.clear()` for the complete User-data record or `user.unset(...)` for selected fields.
</Note>

## Data Sanitization

UserDataInstance separates system identity from custom data:

**System identity (read-only via `_luaProfile`):**

* `userId`, `fullName`, `mobileNumbers`, `emailAddresses`
* Extracted from response and made immutable — access via `user._luaProfile`

**Custom data (read/write via direct properties):**

* `name`, `email`, `phone`
* Custom fields you set
* Preferences, settings, and any other data

```typescript theme={null}
const user = await User.get();

// System identity — read-only
user._luaProfile.userId;        // "12345"
user._luaProfile.fullName;      // "John Doe"

// Custom data — read/write
user.name;                      // "John Doe"
user.email;                     // "john@example.com"
user.preferences;               // { theme: "dark" }
```

## Complete Examples

### Example 1: User Preferences

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export class ManagePreferencesTool implements LuaTool {
  name = "manage_preferences";
  description = "Manage user preferences";
  
  inputSchema = z.object({
    theme: z.enum(['light', 'dark']).optional(),
    notifications: z.boolean().optional(),
    language: z.string().optional()
  });

  async execute(input: any) {
    const user = await User.get();

    // Direct property access
    const currentPrefs = user.preferences || {};
    
    // Merge with new preferences
    const newPrefs = {
      ...currentPrefs,
      ...input
    };
    
    // Update on server
    await user.update({ preferences: newPrefs });
    
    return {
      message: 'Preferences updated successfully',
      preferences: user.preferences  // Direct access to updated data
    };
  }
}
```

### Example 2: Shopping Cart Persistence

```typescript theme={null}
export class CartTool implements LuaTool {
  name = "manage_cart";
  description = "Manage shopping cart";
  
  inputSchema = z.object({
    action: z.enum(['add', 'remove', 'get']),
    productId: z.string().optional(),
    quantity: z.number().optional()
  });

  async execute(input: any) {
    const user = await User.get();

    // Get current cart (direct access)
    let cart = user.cart || [];
    
    if (input.action === 'add') {
      cart.push({
        productId: input.productId,
        quantity: input.quantity
      });
      await user.update({ cart });
    }
    
    if (input.action === 'remove') {
      cart = cart.filter(item => item.productId !== input.productId);
      await user.update({ cart });
    }
    
    return {
      cart: user.cart,  // Direct access
      itemCount: cart.length
    };
  }
}
```

### Example 3: User Profile Management

```typescript theme={null}
export class ProfileTool implements LuaTool {
  name = "update_profile";
  description = "Update user profile information";
  
  inputSchema = z.object({
    firstName: z.string().optional(),
    lastName: z.string().optional(),
    phone: z.string().optional(),
    bio: z.string().optional()
  });

  async execute(input: any) {
    const user = await User.get();

    // Update user data
    await user.update(input);
    
    // Return updated profile (direct access)
    return {
      success: true,
      profile: {
        firstName: user.firstName,
        lastName: user.lastName,
        phone: user.phone,
        bio: user.bio
      },
      message: 'Profile updated successfully'
    };
  }
}
```

### Example 4: Personalized Greeting

```typescript theme={null}
export class GreetUserTool implements LuaTool {
  name = "greet_user";
  description = "Greet user with personalized message";
  
  inputSchema = z.object({});

  async execute(input: any) {
    const user = await User.get();

    // Direct property access
    const hour = new Date().getHours();
    const timeGreeting = hour < 12 ? 'Good morning'
      : hour < 18 ? 'Good afternoon'
      : 'Good evening';
    
    return {
      message: `${timeGreeting}, ${user.name}! How can I help you today?`
    };
  }
}
```

### Example 5: Order Notification with Messaging

```typescript theme={null}
export class SendOrderNotificationTool implements LuaTool {
  name = "send_order_notification";
  description = "Send order status notification to user";
  
  inputSchema = z.object({
    orderId: z.string(),
    status: z.enum(['shipped', 'delivered']),
    trackingNumber: z.string().optional(),
    receiptUrl: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const user = await User.get();

    // Build notification message
    const messages = [
      {
        type: "text" as const,
        text: `Hi ${user.name}! Your order #${input.orderId} has been ${input.status}.`
      }
    ];
    
    // Add tracking info if shipped
    if (input.status === 'shipped' && input.trackingNumber) {
      messages.push({
        type: "text" as const,
        text: `Tracking number: ${input.trackingNumber}`
      });
    }
    
    // Send messages to user
    await user.send(messages);
    
    // Update user's notification preferences
    user.lastNotificationSent = new Date().toISOString();
    await user.save();
    
    return {
      success: true,
      message: "Notification sent successfully"
    };
  }
}
```

### Example 6: Send Receipt with Image

```typescript theme={null}
export class SendReceiptTool implements LuaTool {
  name = "send_receipt";
  description = "Send order receipt with QR code";
  
  inputSchema = z.object({
    orderId: z.string(),
    amount: z.number(),
    qrCodeBase64: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const user = await User.get();

    // Send receipt with QR code
    await user.send([
      {
        type: "text",
        text: `Thank you for your order! Total: $${input.amount.toFixed(2)}`
      },
      {
        type: "text",
        text: "Here's your receipt QR code for easy access:"
      },
      {
        type: "image",
        image: input.qrCodeBase64,
        mediaType: "image/png"
      }
    ]);
    
    return {
      success: true,
      message: "Receipt sent to user"
    };
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Use Direct Property Access">
    ```typescript theme={null}
    // ✅ Recommended
    const name = user.name;
    const email = user.email;

    // 🟡 Still works but verbose
    const name = user.data.name;
    const email = user.data.email;
    ```
  </Accordion>

  <Accordion title="✅ Batch Updates">
    Combine multiple updates into one call:

    ```typescript theme={null}
    // ✅ Good - Single update call
    await user.update({
      name: "John Doe",
      email: "john@example.com",
      phone: "555-1234"
    });

    // ❌ Bad - Multiple update calls
    await user.update({ name: "John Doe" });
    await user.update({ email: "john@example.com" });
    await user.update({ phone: "555-1234" });
    ```
  </Accordion>

  <Accordion title="✅ Handle Missing Fields">
    Not all fields may be present:

    ```typescript theme={null}
    const phone = user.phone || 'Not provided';
    const name = user.name || 'Guest';
    const preferences = user.preferences || {};
    ```
  </Accordion>

  <Accordion title="✅ Use for Personalization">
    ```typescript theme={null}
    // Personalized responses
    return {
      message: `Welcome back, ${user.name}!`,
      savedItems: user.cart?.length || 0,
      lastVisit: user.lastSeen
    };
    ```
  </Accordion>

  <Accordion title="✅ Use save() for Multiple Changes">
    The new `save()` method is perfect for multiple changes:

    ```typescript theme={null}
    // ✅ Recommended - Modify then save
    user.name = "John Doe";
    user.email = "john@example.com";
    user.preferences = { theme: "dark" };
    await user.save();

    // 🟡 Still works - Update method
    await user.update({
      name: "John Doe",
      email: "john@example.com",
      preferences: { theme: "dark" }
    });
    ```
  </Accordion>

  <Accordion title="✅ Use send() for Proactive Notifications">
    Send messages to users for order updates, alerts, and more:

    ```typescript theme={null}
    // Send order shipped notification
    await user.send([
      { type: "text", text: "Your order has been shipped!" },
      { type: "text", text: "Tracking: TRACK123456" }
    ]);

    // Send with image
    await user.send([
      { type: "text", text: "Your boarding pass:" },
      { type: "image", image: qrCodeBase64, mediaType: "image/png" }
    ]);
    ```
  </Accordion>

  <Accordion title="⚠️ Message Format Requirements">
    Ensure correct message format:

    ```typescript theme={null}
    // ✅ Correct
    await user.send([
      { type: "text", text: "Hello!" }
    ]);

    // ✅ Multiple messages
    await user.send([
      { type: "text", text: "Message 1" },
      { type: "text", text: "Message 2" }
    ]);

    // ❌ Wrong - Must be array
    await user.send({ type: "text", text: "Hello!" });
    ```
  </Accordion>
</AccordionGroup>

## TypeScript Support

```typescript theme={null}
// User lookup options for email/phone lookup
interface UserLookupOptions {
  /** Email address to look up */
  email?: string;
  /** Phone number to look up (with or without + prefix) */
  phone?: string;
}

interface UserDataInstance {
  // Properties (dynamic based on stored data)
  name?: string;
  email?: string;
  phone?: string;
  [key: string]: any;
  
  // Methods
  update(data: Record<string, any>): Promise<any>;
  patch(mutation: { set?: Record<string, any>; unset?: string[] }): Promise<any>;
  unset(...fields: string[]): Promise<any>;
  save(): Promise<boolean>;
  send(messages: Message[]): Promise<any>;
  clear(): Promise<boolean>;
  toJSON(): Record<string, any>;
}

// Message types
type TextMessage = {
  type: "text";
  text: string;
};

type ImageMessage = {
  type: "image";
  image: string;
  mediaType: string;
};

type FileMessage = {
  type: "file";
  data: string;
  mediaType: string;
};

type Message = TextMessage | ImageMessage | FileMessage;
```

### Usage with Types

```typescript theme={null}
// Define your user data shape
interface MyUserData {
  name: string;
  email: string;
  preferences: {
    theme: 'light' | 'dark';
    notifications: boolean;
  };
}

// Access with type safety
const user = await User.get();
const name: string = user.name;
const theme = user.preferences?.theme || 'light';
```

<Note title="Debugging tip">
  If user properties aren't what you expect, log the user object to see what's actually stored:

  ```typescript theme={null}
  const user = await User.get();
  console.log('User data:', JSON.stringify(user.data, null, 2));
  console.log('User profile fields:', JSON.stringify({ name: user.name, email: user.email }, null, 2));
  ```

  Then run `lua logs --type skill --limit 5` after a test message. See the [Debugging Skills guide](/cli/debugging) for the full workflow.
</Note>

## Next Steps

<CardGroup>
  <Card title="Data API" icon="database" href="/api/data">
    Store agent-owned collection entries
  </Card>

  <Card title="User Data Examples" icon="layer-group" href="/examples/user-data">
    See working examples
  </Card>

  <Card title="Debugging Skills" icon="bug" href="/cli/debugging">
    Inspect runtime return values
  </Card>

  <Card title="Inbox API" icon="inbox" href="/api/inbox">
    File approval and notice cards
  </Card>
</CardGroup>


# LuaVoice
Source: https://docs.heylua.ai/api/voice

Define voice agents in code with LuaVoice — STT, TTS, LLM, lifecycle hooks, and voice tools

## Overview

`LuaVoice` is the class-based primitive you define in code to declare a voice-enabled agent — its speech-to-text engine, text-to-speech engine, LLM, turn detection, and any voice-specific tools.

```typescript theme={null}
import { LuaVoice } from 'lua-cli';

export default new LuaVoice({
  name: 'support-line',
  llm: 'openai/gpt-5.1-chat-latest',
  stt: 'deepgram/nova-3',
  tts: 'elevenlabs/eleven_turbo_v2_5:pwMBn0SsmN1220Aorv15',
  greeting: 'Hi, this is your support line. How can I help?',
});
```

<Note>
  For testing voice agents live or running automated voice tests, see the [Voice Command](/cli/voice-command). For the direct plugin route (when string descriptors aren't enough), see [Plugin and Realtime Engines](#plugin-and-realtime-engines) below.
</Note>

<Note>
  **Persona is configured on the parent `LuaAgent`, not on `LuaVoice`.** Use the channel-aware persona shape `{ base, voice, text }` on the agent to give a voice its own prompt — see [Channel-Aware Personas](/cli/persona-command#channel-aware-personas).
</Note>

***

## String Descriptors (recommended)

`llm`, `stt`, and `tts` all accept a provider-prefixed string descriptor. This is the canonical form — it routes through Lua's inference layer so you don't manage provider credentials yourself.

```typescript theme={null}
new LuaVoice({
  name: 'support-line',
  llm: 'openai/gpt-5.1-chat-latest',                  // LLM
  stt: 'deepgram/nova-3',                              // STT
  tts: 'elevenlabs/eleven_turbo_v2_5:<voiceId>',      // TTS — colon-separated voiceId
});
```

<Note>
  The model and voice catalogs below are a **living list** — your descriptor is forwarded straight to Lua's inference layer, so newer provider models may work before they're listed here and retired ones may drop off. Treat these tables as a starting point, not an exhaustive allowlist.
</Note>

### LLM options

Provider-prefixed model id. Grouped by tier — pick a tier based on the latency/cost/quality trade-off you need.

**Fast tier** — lowest latency, lowest cost:

| Descriptor                        | Notes                 |
| --------------------------------- | --------------------- |
| `openai/gpt-5-mini`               | Fast & cheap OpenAI.  |
| `openai/gpt-5-nano`               | Cheapest OpenAI tier. |
| `openai/gpt-4.1-mini`             | Stable, fast.         |
| `google/gemini-2.5-flash-lite`    | Fastest Gemini.       |
| `google/gemini-2.5-flash`         | Fast multimodal.      |
| `xai/grok-4-1-fast-non-reasoning` | Fast xAI tier.        |

**Balanced tier** — good default for most voice agents:

| Descriptor                    | Notes                                     |
| ----------------------------- | ----------------------------------------- |
| `openai/gpt-5`                | Balanced quality and speed.               |
| `openai/gpt-5.1-chat-latest`  | Balanced, chat-tuned. **Common default.** |
| `openai/gpt-4.1`              | Stable, balanced.                         |
| `google/gemini-3-flash`       | Newest Flash multimodal.                  |
| `xai/grok-4-1-fast-reasoning` | Reasoning at fast tier.                   |
| `deepseek-ai/deepseek-v3.2`   | Cost-efficient reasoning.                 |
| `moonshotai/kimi-k2-instruct` | Long-context instruct.                    |

**Quality tier** — best capability, higher latency/cost:

| Descriptor                     | Notes                   |
| ------------------------------ | ----------------------- |
| `openai/gpt-5.4`               | Top-tier OpenAI.        |
| `openai/gpt-5.3-chat-latest`   | Top-tier chat-tuned.    |
| `google/gemini-3-pro`          | Long context, top tier. |
| `google/gemini-2.5-pro`        | Stable Pro tier.        |
| `xai/grok-4.20-0309-reasoning` | Top-tier xAI reasoning. |

<Note>
  **Anthropic / Claude is intentionally absent** — Lua's inference layer does not carry Anthropic models for voice as of this writing. Use OpenAI, Google, xAI, DeepSeek, or Kimi for voice LLMs.
</Note>

### STT options

#### Deepgram (recommended)

Deepgram is the recommended STT provider, and `deepgram/nova-3` is the standard choice. `stt` is **required** for cascaded LLMs — omit it only when the `llm` is a realtime speech-to-speech model (which handles audio directly).

```typescript theme={null}
new LuaVoice({
  // ...
  stt: 'deepgram/nova-3',
  sttLanguage: 'en',        // BCP-47 code, or 'multi' for multilingual
});
```

| Descriptor                  | Notes                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `deepgram/nova-3`           | Latest Nova series. Best accuracy + low latency. **Recommended default.**                                          |
| `deepgram/nova-2`           | Previous generation. Still solid.                                                                                  |
| `deepgram/nova-2-phonecall` | Tuned for narrowband (8 kHz) phone audio. Use when call quality is poor or when you want extra robustness on PSTN. |

Combine with `sttLanguage` to pin the spoken language:

* BCP-47 code (`'en'`, `'es'`, `'pt-BR'`, etc.) — pins recognition to that language.
* `'multi'` — multilingual transcription. Applies to both the Inference route and the direct Deepgram plugin.

<Tip>
  Want non-default Deepgram options (smart formatting, filler-word filtering, custom keywords)? Use the plugin class form: `stt: new deepgram.STT({ model: 'nova-3', smartFormat: true })`. See [Plugin and Realtime Engines](#plugin-and-realtime-engines) for the full plugin route.
</Tip>

#### ElevenLabs Scribe

ElevenLabs has an STT model called Scribe, available via the Inference route:

```typescript theme={null}
stt: 'elevenlabs/scribe_v2_realtime'
```

Useful when you want STT and TTS from the same provider, or when Scribe's behavior on a specific language outperforms Deepgram in your testing.

### TTS options

**Recommended:** Deepgram and Fish Audio give the best balance of quality and latency. All providers below are fully supported.

#### ElevenLabs

ElevenLabs voices use the descriptor format `elevenlabs/<model>:<voiceId>`.

```typescript theme={null}
new LuaVoice({
  // ...
  tts: 'elevenlabs/eleven_turbo_v2_5:pwMBn0SsmN1220Aorv15',
});
```

**Models:**

| Model                    | Latency | Languages    | Best for                                                     |
| ------------------------ | ------- | ------------ | ------------------------------------------------------------ |
| `eleven_v3`              | \~250ms | 70+          | Most expressive. Use when quality matters more than latency. |
| `eleven_turbo_v2_5`      | Low     | Multilingual | **Common default** — balanced latency + quality.             |
| `eleven_flash_v2_5`      | \~75ms  | Multilingual | Ultra-low latency. Use for fast, interactive turns.          |
| `eleven_multilingual_v2` | \~200ms | 29           | Lifelike emotion across many languages.                      |
| `eleven_flash_v2`        | \~75ms  | English only | Ultra-low latency, English-only.                             |

**Curated voice IDs:**

Lua maintains a curated list with metadata (gender, accent, style) the raw ElevenLabs API doesn't expose:

| Voice ID               | Name      | Accent     | Style                             |
| ---------------------- | --------- | ---------- | --------------------------------- |
| `pwMBn0SsmN1220Aorv15` | Matt      | American   | Male, Hyper-Conversational        |
| `ZTho75k1M56OV0k9XtSC` | Spence    | American   | Male, Soft-Spoken                 |
| `kdmDKE6EkgrWrrykO9Qt` | Alexandra | American   | Female, Conversational            |
| `h2sm0NbeIZXHBzJOMYcQ` | Natasha   | American   | Female, Calm Narrative            |
| `lUTamkMw7gOzZbFIwmq4` | James     | British    | Male, Professional                |
| `4BWwbsA70lmV7RMG0Acs` | Blondie   | British    | Female, Relaxed Casual            |
| `lcMyyd2HUfFzxdCaC4Ta` | Lucy      | British    | Female, Fresh Casual              |
| `4CrZuIW9am7gYAxgo2Af` | Shelley   | British    | Female, Clear Confident           |
| `56bWURjYFHyYyVf490Dp` | Emma      | Australian | Female, Warm Conversational       |
| `aCChyB4P5WEomwRsOKRh` | Salma     | Arabic     | Female, Conversational Expressive |
| `2zRM7PkgwBPiau2jvVXc` | Monika    | Indian     | Female, Deep and Natural          |
| `ecp3DWciuUyW7BYM7II1` | Anika     | Indian     | Female, Sweet and Lively          |
| `pzxut4zZz4GImZNlqQ3H` | Raju      | Indian     | Male, Natural Conversationalist   |

You can also use any ElevenLabs voice ID from your own ElevenLabs account — these are just the curated defaults.

**Alternative: object form**

If you'd rather not concatenate model and voice with a colon, the object form works too:

```typescript theme={null}
tts: { model: 'elevenlabs/eleven_turbo_v2_5', voice: 'pwMBn0SsmN1220Aorv15' }
```

#### Deepgram Aura (recommended)

Deepgram offers TTS via the Aura family. The voice id is encoded inside the model id as `aura-2-<name>-<lang>`:

```typescript theme={null}
tts: 'deepgram/aura-2-thalia-en'
```

**Common Aura 2 voices (English):**

| ID                  | Name    | Gender            | Style              |
| ------------------- | ------- | ----------------- | ------------------ |
| `aura-2-thalia-en`  | Thalia  | Female (American) | Conversational     |
| `aura-2-asteria-en` | Asteria | Female (American) | Friendly           |
| `aura-2-luna-en`    | Luna    | Female (American) | Warm               |
| `aura-2-stella-en`  | Stella  | Female (American) | Professional       |
| `aura-2-athena-en`  | Athena  | Female (British)  | Authoritative      |
| `aura-2-hera-en`    | Hera    | Female (American) | Calm Narrative     |
| `aura-2-orion-en`   | Orion   | Male (American)   | Confident          |
| `aura-2-arcas-en`   | Arcas   | Male (American)   | Conversational     |
| `aura-2-perseus-en` | Perseus | Male (American)   | Engaging           |
| `aura-2-angus-en`   | Angus   | Male (Irish)      | Storyteller        |
| `aura-2-helios-en`  | Helios  | Male (British)    | Professional       |
| `aura-2-zeus-en`    | Zeus    | Male (American)   | Deep Authoritative |

Spanish voices are also available: `aura-2-celeste-es`, `aura-2-estrella-es`.

#### Other TTS providers (via Inference)

Lua's inference layer also exposes Fish Audio, Gradium, Cartesia, Inworld, Rime, and xAI TTS. The descriptors follow the same `provider/model` shape:

| Descriptor                    | Provider   | Notes                                                                 |
| ----------------------------- | ---------- | --------------------------------------------------------------------- |
| `fishaudio/s2.1-pro`          | Fish Audio | **Recommended** — expressive, multilingual, ElevenLabs-grade quality. |
| `gradium/default`             | Gradium    | Natural and warm across English, French, German, Spanish, Portuguese. |
| `cartesia/sonic-3`            | Cartesia   | Newest, expressive.                                                   |
| `cartesia/sonic-turbo`        | Cartesia   | Ultra-low latency.                                                    |
| `inworld/inworld-tts-1.5-max` | Inworld    | High-quality multilingual.                                            |
| `rime/coda`                   | Rime       | Multilingual, expressive.                                             |
| `xai/tts-1`                   | xAI        | 21 languages.                                                         |

***

## Plugin and Realtime Engines

For most voice agents the [string-descriptor form](#string-descriptors-recommended) above is all you need. Reach for the plugin/class forms here in two cases: (1) you need provider-specific options the descriptor route doesn't expose, or (2) you're using a realtime (speech-to-speech) model in the `llm` slot.

`lua-cli/voice` re-exports the LiveKit plugin namespaces that `LuaVoice` accepts as class instances — importing through it means you don't add the underlying plugin packages as direct dependencies:

```typescript theme={null}
import { LuaVoice } from 'lua-cli';
import { deepgram, elevenlabs, openai, google, xai, inference } from 'lua-cli/voice';
```

### What's allowed where

The compiler enforces two separate allowlists:

| Form                                           | Allowed in `llm` / `stt` / `tts`                                                                                                                           |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `'<provider>/<model>'` string descriptor       | **Any** provider supported by Lua's inference layer. The descriptor route handles credentials.                                                             |
| `new deepgram.<Class>({...})`                  | Plugin route. Only `deepgram` and `elevenlabs` are allowlisted.                                                                                            |
| `new elevenlabs.<Class>({...})`                | Plugin route. Only `deepgram` and `elevenlabs` are allowlisted.                                                                                            |
| `new inference.<Class>({ model, ... })`        | Typed shortcut for the descriptor route — same semantics as a string descriptor, just with autocomplete on the options.                                    |
| `new <provider>.realtime.RealtimeModel({...})` | Realtime route. `openai`, `google` (via `google.beta.realtime.*`), `xai` are allowlisted **for realtime only** (goes in the `llm` slot, replaces STT+TTS). |

<Warning>
  **`new openai.LLM(...)`, `new google.LLM(...)`, `new xai.LLM(...)` and similar class forms fail compile-time validation.** These providers are not on the plugin allowlist. Use string descriptors (`'openai/gpt-5'`) or — for speech-to-speech — the realtime form (`new openai.realtime.RealtimeModel({...})`).
</Warning>

### Plugin route: Deepgram + ElevenLabs

The two allowlisted plugin providers. Use these class forms when you need provider-specific options not exposed by the string-descriptor route.

#### Deepgram STT (plugin form)

```typescript theme={null}
import { LuaVoice } from 'lua-cli';
import { deepgram, elevenlabs } from 'lua-cli/voice';

export default new LuaVoice({
  name: 'support-line',
  llm: 'openai/gpt-5.1-chat-latest',
  stt: new deepgram.STT({
    model: 'nova-3',
    smartFormat: true,
    fillerWords: false,
  }),
  tts: new elevenlabs.TTS({
    voiceId: 'pwMBn0SsmN1220Aorv15',
    model: 'eleven_flash_v2_5',
  }),
});
```

Deepgram exposes two STT classes:

* **`new deepgram.STT({...})`** — Deepgram's v1 WebSocket endpoint. Use this for `nova-3`, `nova-2`, etc.
* **`new deepgram.STTv2({...})`** — Deepgram's v2 endpoint. Required for **Flux** models that use semantic endpointing (`eotThreshold`, `eagerEotThreshold`, `eotTimeoutMs`).

The compiler routes each to the correct underlying plugin based on which class you used.

#### ElevenLabs TTS (plugin form)

```typescript theme={null}
tts: new elevenlabs.TTS({
  voiceId: 'pwMBn0SsmN1220Aorv15',
  model: 'eleven_v3',
  stability: 0.5,
  similarityBoost: 0.75,
});
```

The plugin route lets you pass advanced ElevenLabs options (stability, similarity boost, style, speaker boost, etc.) that the descriptor route doesn't surface.

### Inference route (typed shortcut)

`inference.LLM`, `inference.STT`, `inference.TTS` are typed wrappers for the string-descriptor route. The compiler normalizes both forms to the same wire shape; the class form just gives you better TypeScript autocomplete on the options.

```typescript theme={null}
import { LuaVoice } from 'lua-cli';
import { inference } from 'lua-cli/voice';

export default new LuaVoice({
  name: 'support-line',
  llm: new inference.LLM({ model: 'openai/gpt-5.1-chat-latest' }),
  stt: new inference.STT({ model: 'deepgram/nova-3' }),
  tts: new inference.TTS({
    model: 'elevenlabs/eleven_turbo_v2_5',
    voice: 'pwMBn0SsmN1220Aorv15',
  }),
});
```

The `model` option is required — it's the same provider-prefixed string you'd pass directly. For TTS, pass `voice` separately.

This is the **only** way to use class syntax for providers that aren't on the plugin allowlist (OpenAI, Google, xAI, Cartesia, etc.).

### Realtime route (speech-to-speech)

The realtime route puts a speech-to-speech model in the `llm` slot, replacing the cascaded STT → LLM → TTS pipeline. The class-construction path differs by provider:

* **OpenAI**: `new openai.realtime.RealtimeModel({...})`
* **Google (Gemini)**: `new google.beta.realtime.RealtimeModel({...})` — note the `.beta.` prefix (matches Google's Node SDK shape)

```typescript theme={null}
import { LuaVoice } from 'lua-cli';
import { openai } from 'lua-cli/voice';

export default new LuaVoice({
  name: 'realtime-line',
  llm: new openai.realtime.RealtimeModel({
    model: 'gpt-realtime-1.5',
    voice: 'alloy',
  }),
  // stt and tts are NOT specified — realtime handles audio directly.
});
```

```typescript theme={null}
import { LuaVoice } from 'lua-cli';
import { google } from 'lua-cli/voice';

export default new LuaVoice({
  name: 'realtime-gemini',
  llm: new google.beta.realtime.RealtimeModel({
    model: 'gemini-3.1-flash-live-preview',
  }),
});
```

#### Available realtime models

| Class form                                                                           | Model id                        | Notes                                |
| ------------------------------------------------------------------------------------ | ------------------------------- | ------------------------------------ |
| `new openai.realtime.RealtimeModel({ model: 'gpt-realtime-1.5' })`                   | `gpt-realtime-1.5`              | OpenAI flagship realtime. GA.        |
| `new openai.realtime.RealtimeModel({ model: 'gpt-realtime-mini' })`                  | `gpt-realtime-mini`             | Cost-efficient OpenAI realtime. GA.  |
| `new google.beta.realtime.RealtimeModel({ model: 'gemini-3.1-flash-live-preview' })` | `gemini-3.1-flash-live-preview` | Newest Gemini realtime. Preview.     |
| `new google.beta.realtime.RealtimeModel({ model: 'gemini-2.5-flash-live-preview' })` | `gemini-2.5-flash-live-preview` | Cheaper Gemini alternative. Preview. |

<Note>
  `xai` is reserved in the realtime allowlist but no xAI realtime models are currently published.
</Note>

#### Half-cascade mode

You can keep a separate `tts` with a realtime LLM — the worker injects `modalities: ['text']` so the realtime model emits text and `tts` handles synthesis. Useful when you want realtime's low-latency reasoning but ElevenLabs' voice quality:

```typescript theme={null}
new LuaVoice({
  name: 'hybrid-line',
  llm: new openai.realtime.RealtimeModel({ model: 'gpt-realtime-mini' }),
  // stt omitted — realtime handles input audio.
  tts: 'elevenlabs/eleven_turbo_v2_5:pwMBn0SsmN1220Aorv15',
});
```

You **cannot** combine a realtime `llm` with a custom `stt` — the compiler rejects it. Realtime models handle audio input directly.

### Credentials

Plugin class instances rely on credentials provisioned by the Lua platform — you do **not** need to set `DEEPGRAM_API_KEY`, `ELEVENLABS_API_KEY`, etc. in your project's `.env`. Lua manages the provider credentials for you; your code just references the class form and the platform constructs the actual engine at runtime.

### When to use which form

| Goal                                                  | Recommended form                                                                             |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Quick start, sensible defaults                        | **String descriptor** — `stt: 'deepgram/nova-3'`                                             |
| TypeScript autocomplete on options                    | **`inference.X`** — `stt: new inference.STT({ model: 'deepgram/nova-3' })`                   |
| Deepgram or ElevenLabs with provider-specific options | **Plugin class** — `stt: new deepgram.STT({ model: 'nova-3', smartFormat: true })`           |
| Speech-to-speech (OpenAI/Google/xAI realtime)         | **Realtime class** — `llm: new openai.realtime.RealtimeModel({ model: 'gpt-realtime-1.5' })` |

***

## Configuration Reference

```typescript theme={null}
new LuaVoice({
  // Required
  name: 'support-line',
  llm: 'openai/gpt-5.1-chat-latest',
  stt: 'deepgram/nova-3',
  tts: 'elevenlabs/eleven_turbo_v2_5:pwMBn0SsmN1220Aorv15',

  // Recommended
  description: 'Inbound phone voice for the support assistant',
  greeting: "Hi, this is your support line. How can I help?",
  sttLanguage: 'en',
  turnDetection: 'vad',
  krispEnabled: true,

  // Optional tuning
  maxToolSteps: 6,
  userAwayTimeout: 20,
  preemptiveGeneration: true,
  interruption: { mode: 'adaptive', falseInterruptionTimeout: 2.0 },

  // Optional polish
  pronunciations: { 'HVAC': 'H V A C', 'CFM': 'C F M' },
  persistTranscript: true,
  onToolFailureSay: 'Sorry, let me try that another way.',
  backgroundAudio: { ambient: 'office-ambience', thinking: 'keyboard-typing' },

  // Tools + lifecycle hooks
  tools: [/* ... */],
  onEnter: async (ctx) => {/* ... */},
  onUserTurnCompleted: async (turnCtx, message) => {/* ... */},
  onExit: async (ctx) => {/* ... */},
});
```

### Required fields

<ParamField type="string">
  Unique name for this voice. Used to address the voice in `lua voice --voice <name>` and as the server-side identifier. Allowed characters: `a-zA-Z0-9_-`, 1–64 chars.
</ParamField>

<ParamField type="string | LLMConfig">
  The LLM that drives the conversation. String descriptor (e.g. `'openai/gpt-5.1-chat-latest'`) is the canonical form. See [LLM options](#llm-options) above for the catalog.
</ParamField>

<ParamField type="string | STTConfig">
  Speech-to-text engine. String descriptor (e.g. `'deepgram/nova-3'`) is canonical. Required for cascaded LLMs; omit only when using a realtime speech-to-speech model in the `llm` slot.
</ParamField>

<ParamField type="string | TTSConfig">
  Text-to-speech engine. String descriptor with colon-separated voice id (e.g. `'elevenlabs/eleven_turbo_v2_5:<voiceId>'`), or object form `{ model, voice }`. Required for cascaded LLMs.
</ParamField>

### Optional fields

<ParamField type="string">
  Human-readable description. Surfaced in the compiled manifest and admin listings.
</ParamField>

<ParamField type="string">
  Opening line spoken at session start. Empty string means no greeting. Generated through the LLM at session connect, so it can be dynamic if `onEnter` sets up context first.
</ParamField>

<ParamField type="string">
  BCP-47 language code (e.g. `'en'`, `'es'`, `'pt-BR'`) or `'multi'` for multilingual transcription. Applies to both Inference STT and the Deepgram plugin.
</ParamField>

<ParamField type="'multilingual' | 'english' | 'vad' | 'stt' | 'manual'">
  How the agent decides when the user has finished speaking. `'vad'` is the safest choice for most setups. `'multilingual'` and `'english'` use LiveKit's turn-detector model; `'manual'` defers to your own logic.
</ParamField>

<ParamField type="string">
  Voice activity detection engine. `'silero'` is the only currently-supported value.
</ParamField>

<ParamField type="object">
  Silero VAD tuning. Useful when the default endpointing clips quiet callers or fires too eagerly mid-thought.

  * `minSpeechDuration` (ms, 0–5000) — speech required before a turn starts. Default: 50.
  * `minSilenceDuration` (ms, 0–5000) — silence required to end a turn. Default: 550.
  * `prefixPaddingDuration` (ms, 0–2000) — audio captured before detected speech start, forwarded into STT. Default: 500.
  * `activationThreshold` (0–1) — lower = more sensitive to speech onset.
</ParamField>

<ParamField type="boolean">
  Krisp BVC background noise cancellation. Recommended for inbound phone calls — it removes background chatter, traffic, and other ambient noise. Billed separately, so opt-in.
</ParamField>

<ParamField type="number">
  Maximum sequential tool calls per turn (1–20). Higher values let the agent chain more tools before responding.
</ParamField>

<ParamField type="number">
  Seconds of silence before the agent considers the user "away" and ends the session. Useful for cleanly handling abandoned calls.
</ParamField>

<ParamField type="boolean">
  Generate the assistant's response speculatively as the user is still speaking. Reduces perceived latency for predictable turns but can be wasted on highly interruptive callers.
</ParamField>

<ParamField type="InterruptionOptions">
  How the agent handles being interrupted mid-response.

  * `enabled` — whether interruption is allowed.
  * `mode` — `'adaptive'` (recommended) or `'vad'`.
  * `falseInterruptionTimeout` (seconds) — how long to wait before treating a brief noise as a false interruption.
  * `resumeFalseInterruption` (boolean) — resume the cut-off response after a false interruption.
  * `minDelay` / `maxDelay` (seconds) — bounds on the interruption response window.
</ParamField>

<ParamField type="Record<string, string>">
  Word-boundary text replacements applied before TTS synthesis. Keys are matched case-insensitively as whole words. Use for acronyms and proper nouns the TTS mispronounces.

  ```typescript theme={null}
  pronunciations: { 'HVAC': 'H V A C', 'kubectl': 'kube control' }
  ```

  Cascaded path only. Setting `pronunciations` on a **full-realtime** voice (realtime `llm` with no `tts`) is rejected at compile time — pair with a half-cascade `tts`, or drop the field.
</ParamField>

<ParamField type="{ ambient?, thinking? }">
  Background audio layered onto the agent's output. Pass a built-in clip name, a `{ source, volume, probability }` config, or an array (probabilistic mix).

  Built-in clips: `'office-ambience'`, `'keyboard-typing'`, `'keyboard-typing-2'`.

  ```typescript theme={null}
  backgroundAudio: {
    ambient: 'office-ambience',
    thinking: 'keyboard-typing',
  }
  ```
</ParamField>

<ParamField type="number">
  Output speech volume, 0–100. Applied as a per-frame multiplier. Omit to pass the TTS provider's native level through unchanged.
</ParamField>

<ParamField type="boolean">
  When `true`, the worker writes `session.history` to `Data.set('call:<sessionId>')` after the call ends. Read it back from a job or webhook with `Data.get('call:<sessionId>')` for post-call analytics, follow-ups, or QA.
</ParamField>

<ParamField type="string">
  Short line spoken to the caller when a tool call fails (throws, times out, or returns an unsupported result) — fills the 2–3s gap before the LLM's own recovery response. Spoken once per failed call, then the error is surfaced to the LLM. Keep it short and on-brand (e.g. `'Sorry, let me try that another way.'`); omit for no spoken fallback.
</ParamField>

<ParamField type="Array<LuaTool | LuaVoiceTool>">
  Voice-specific tools in addition to skills attached to the owning agent. See [Defining Voice Tools](#defining-voice-tools).
</ParamField>

***

## Lifecycle Hooks

Three hooks let you wire up per-session state, RAG injection, and post-call work.

<ParamField type="(ctx: LuaVoiceHookContext) => Promise<void>">
  Fires after the session connects to the room and **before** the greeting. Use it to hydrate `session.userdata` from `User`, `Data`, etc., or to set up any per-call state.

  ```typescript theme={null}
  onEnter: async (ctx) => {
    if (ctx.caller?.phoneNumber) {
      const user = await User.get({ phone: ctx.caller.phoneNumber });
      ctx.session.userdata = { user, returning: !!user };
    }
  },
  ```
</ParamField>

<ParamField type="(turnCtx, message) => Promise<void>">
  Fires after the user finishes a turn, **before** the LLM is invoked. This is the canonical RAG-injection point — `turnCtx.addMessage(...)` adds context messages the LLM sees on this turn.

  ```typescript theme={null}
  onUserTurnCompleted: async (turnCtx, message) => {
    const docs = await Data.search('kb', message.content, 3);
    for (const doc of docs) {
      turnCtx.addMessage({ role: 'system', content: doc.text });
    }
  },
  ```
</ParamField>

<ParamField type="(ctx: LuaVoiceHookContext) => Promise<void>">
  Fires when the session is closing. Use for transcript persistence, outcome reporting, CRM updates, etc.
</ParamField>

***

## Defining Voice Tools

Voice tools run during a voice conversation. `LuaVoiceTool` is a concrete class — **instantiate** it with a config object:

```typescript theme={null}
import { LuaVoiceTool } from 'lua-cli';
import { z } from 'zod';

export const getOrderStatusTool = new LuaVoiceTool({
  name: 'getOrderStatus',
  description: 'Look up the status of an order by ID',
  inputSchema: z.object({ orderId: z.string() }),
  execute: async (input, ctx) => {
    const order = await Data.get('orders', input.orderId);
    return { status: order.status, eta: order.eta };
  },
});
```

### Config fields

<ParamField type="string">
  Tool name. Used by the LLM to identify and call the tool.
</ParamField>

<ParamField type="string">
  What the tool does. Action-oriented description the LLM reads when deciding to invoke.
</ParamField>

<ParamField type="ZodType">
  Zod schema for the tool's input. Validated before `execute` is called.
</ParamField>

<ParamField type="(input, ctx?: LuaVoiceToolCtx) => Promise<any>">
  Tool body. Receives the validated input and an optional voice-specific context.
</ParamField>

<ParamField type="() => Promise<boolean>">
  Optional gate. When provided, the tool is only exposed to the LLM if `condition()` returns `true`. Use for feature flags or runtime availability checks.
</ParamField>

<ParamField type="ToolFlag[]">
  Voice-specific tool flags (e.g. controlling barge-in behavior).
</ParamField>

### ctx — `LuaVoiceToolCtx`

<ParamField type="string">
  Identifier for this specific tool invocation.
</ParamField>

<ParamField type="(text: string) => Promise<void>">
  Speak `text` to the caller via the active LiveKit session. Useful for status updates during long-running tool work ("Looking that up — one moment.").
</ParamField>

<ParamField type="(msisdn, opts?) => Promise<void>">
  Transfer the live caller to a human at `msisdn`. Two mechanisms:

  * **`mode: 'refer'`** (default) — SIP REFER on the inbound leg. Cheap (one billed leg) but depends on the inbound carrier accepting REFER end-to-end.
  * **`mode: 'bridge'`** — dial the human as a second SIP participant into the same room. Two billed legs but works regardless of carrier REFER support. Use for high-stakes transfers.

  `announce` is spoken before the transfer fires.

  ```typescript theme={null}
  await ctx.voice?.transferToHuman('+32477123456', {
    mode: 'bridge',
    announce: 'Transferring you to our sales team — one moment.',
  });
  ```
</ParamField>

You can also share regular `LuaTool` instances between chat skills and voice tools — just pass them in the same `tools` array. The `tools` field accepts both `LuaTool` and `LuaVoiceTool` instances.

***

## Function-style: `defineVoice`

Equivalent to `new LuaVoice(config)` if you prefer a function call:

```typescript theme={null}
import { defineVoice } from 'lua-cli';

export default defineVoice({
  name: 'support-line',
  llm: 'openai/gpt-5.1-chat-latest',
  stt: 'deepgram/nova-3',
  tts: 'elevenlabs/eleven_turbo_v2_5:pwMBn0SsmN1220Aorv15',
});
```

***

## Wiring Up to an Agent

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import supportLine from './voices/support-line.voice';
import supportSkill from './skills/support.skill';

export const agent = new LuaAgent({
  name: 'support-agent',
  persona: {
    base: 'You are a helpful support agent for Acme Corp.',
    voice: `Speak conversationally in two sentences or fewer. No markdown. Never output digits — spell numbers and prices in full English words ("one hundred twenty-nine dollars", "nine o'clock", "fifty miles").`,
    text: 'Use markdown headers and bullet lists where helpful.',
  },
  voices: [supportLine],
  skills: [supportSkill],
});
```

The agent's `persona.voice` branch is what gives `supportLine` its voice-specific prompt.

<Tip>
  **Voice persona tips:**

  * Keep replies short (1–2 sentences). Voice users can't skim.
  * No markdown — TTS reads it literally.
  * Spell out numbers and prices ("nine o'clock", "twenty dollars") — TTS reads digits robotically otherwise.
</Tip>

### Connect a phone number

Attaching the voice in code makes it *available*; to make the agent **answer phone calls**, bind a number to it. Push your voice first, then run the channels flow and choose **"☎️ Manage phone numbers"**:

```bash theme={null}
lua push        # publish the agent + its LuaVoice
lua channels    # → choose "☎️  Manage phone numbers"
```

From there you can **search** available numbers, **purchase** one, and **bind** it to this agent. During bind you pick **which LuaVoice answers inbound calls** on that number:

```text theme={null}
📞 Your agent is now reachable at +1 (415) 555-0142 via voice "support-line"
```

<Note>
  Binding requires a code-defined LuaVoice that has been pushed. Without one, inbound calls fall through to platform-default STT/LLM/TTS — no greeting, lifecycle hooks, or voice-only tools. Author the voice, `lua push`, then bind.
</Note>

When purchasing, answering **"Allow customers to text this number too?"** with **yes** provisions a voice **+ SMS** number; **no** provisions a voice-only number with lower-latency inbound. See [Channels Command](/cli/channels-command) for the full phone-number flow (list, unbind, release).

***

## Related

* [Voice Command](/cli/voice-command) — live testing and voice test suites
* [Plugin and Realtime Engines](#plugin-and-realtime-engines) — Deepgram/ElevenLabs class forms, realtime speech-to-speech
* [Persona Command](/cli/persona-command#channel-aware-personas) — voice-specific personas on the parent agent
* [LuaAgent API](/api/luaagent)


# Changelog
Source: https://docs.heylua.ai/changelog

Release notes and version history for lua-cli

## v3.30.0

**Released:** September 2, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Know whether your message arrived">
    Every `Channels.send`, template, reaction and email send now returns a `deliveryId` and a `status` (`queued`, `accepted`, `sent`, `delivered`, `read`, `failed`). Read the current state later, and the reason category for a failure:

    ```typescript theme={null}
    const sent = await Channels.send({ channel: 'whatsapp', to: { userId }, text: 'Your order shipped.' });
    const delivery = await Channels.getStatus(sent.deliveryId);
    // delivery.status === 'failed' && delivery.error.category === 'window_closed'
    ```
  </Accordion>

  <Accordion title="Delivery events on every channel">
    Webhooks subscribed to `message.sent`, `message.delivered`, `message.read` and `message.failed` now receive them for SMS, email, Messenger, Instagram and the other channels, not only WhatsApp, with the full delivery in the payload.
  </Accordion>

  <Accordion title="Safe retries">
    Sends carry an idempotency key. Retrying a send with the same key returns the original outcome instead of sending twice.
  </Accordion>

  <Accordion title="Model picker for template parameters">
    Template env params can declare `type: model` so installers pick a model instead of typing a code.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="delivered stays for compatibility">
    Send results keep the `delivered` flag; prefer `status`, which keeps updating as receipts arrive.
  </Accordion>
</AccordionGroup>

***

## v3.29.1

**Released:** August 31, 2026

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Email sign-in completes successfully">
    Email OTP setup now saves the renewable session instead of failing after verification.
  </Accordion>

  <Accordion title="Large accounts can list and select agents">
    Renewable sessions now load all current organizations and agents, including accounts with more than 100 organizations.
  </Accordion>
</AccordionGroup>

***

## v3.29.0

**Released:** August 31, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Sign in once with email">
    Email sign-in now creates a renewable user session that follows your current organizations and agents. Login no longer asks you to choose an organization, agents, or role.
  </Accordion>

  <Accordion title="Choose the agent for each project">
    Run `lua init` to select an agent for a project. The selection stays in that project's `lua.skill.yaml`.
  </Accordion>

  <Accordion title="Create or duplicate agents from the CLI">
    Signed-in users can create or duplicate agents when their current Lua permissions allow it.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Moving from the v3.28.0 login flow">
    Email login no longer creates an agent-scoped API key. Existing API keys remain valid. Create and manage scoped keys in **Settings → API Keys**, or supply an existing key with direct API-key setup.
  </Accordion>

  <Accordion title="Keep using API keys for automation">
    Scoped and legacy API keys remain supported for CI, plugins, integrations, and automation through `LUA_API_KEY`, `.env`, or direct API-key setup.
  </Accordion>
</AccordionGroup>

***

## Scoped API keys

**Released:** August 27, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Scoped API keys, alongside your existing keys">
    Create personal API keys with an explicit role on specific organizations or agents, from **Settings → API Keys** in the admin dashboard — instead of a key that always carries your full account permissions.

    A scoped key can never do more than its owner can: its role on a resource is capped at the owner's current role there, and it loses access if the owner does (in that organization only — it keeps working in the owner's other organizations). An org admin can create a scoped key for another member, capped at that member's role.

    Existing keys are unaffected — they keep working exactly as before, with your full account permissions and no expiry. This is additive, not a migration.

    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    See [API Keys](/concepts/api-keys) for the full picture: roles, expiry, rotate/suspend/revoke, and the new `403` response for a valid key whose role doesn't cover the action.
  </Accordion>
</AccordionGroup>

***

## v3.28.0

**Released:** August 30, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Create scoped CLI credentials">
    Email OTP setup can now create a credential limited to a selected organization, one or more agents, and an assignable role.

    ```bash theme={null}
    lua auth configure \
      --email user@example.com \
      --otp 123456 \
      --org-id org_123 \
      --agent-id agent_123 \
      --role builder \
      --name "local laptop"
    ```
  </Accordion>

  <Accordion title="Require signed webhook requests">
    Add an optional signing key to `LuaWebhook`. When configured, Lua verifies an HMAC-SHA256 signature over the exact request body before running the webhook. Existing webhooks without a key behave as before.

    ```typescript theme={null}
    export default new LuaWebhook({
      name: 'order-updated',
      secret: 'replace-with-a-long-random-secret',
      execute: async (event) => ({ received: true }),
    });
    ```
  </Accordion>

  <Accordion title="Run tools and instructions during template lifecycle events">
    Templates can run a bundled skill tool, an agent instruction, or both after installation and before uninstall cleanup. Installed trigger callback URLs are also available through `LUA_TRIGGER_URL__<KEY>`.
  </Accordion>

  <Accordion title="Execute a skill tool directly from a trigger">
    A webhook trigger can run a named skill tool after verification and filtering without starting an agent conversation. Existing transform-only triggers continue to work unchanged.
  </Accordion>

  <Accordion title="Manage marketplace skills by organization">
    Organization administrators can list skills owned by their organization and transfer a skill to another organization they administer.

    ```bash theme={null}
    lua marketplace skill org
    lua marketplace skill transfer --marketplace-id skill_123 --new-org-id org_456 --force
    ```
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Reauthorize integrations without disconnecting them">
    `lua integrations update` now replaces credentials only after authorization succeeds. Existing triggers, tool access, labels, attachments, and memory settings remain intact. Personal connections support the same flow with `--scope user`.
  </Accordion>

  <Accordion title="Send messages as the authenticated user">
    `User.send()` now targets the authenticated user without a separate profile lookup. Existing code needs no changes.
  </Accordion>

  <Accordion title="Reuse connections during template installation">
    An existing connected account can satisfy a template requirement without another selection step. Template-installed agents can also use active attached connections consistently.
  </Accordion>

  <Accordion title="Use scoped credentials across the CLI">
    Project initialization, agent listing, status, dashboard, and integration commands work cleanly with scoped credentials. CLI telemetry no longer stores account email or name.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Reliable compiled-bundle uploads">
    Fixed an upload compatibility issue that could make `lua push` fail while uploading compiled bundles.
  </Accordion>

  <Accordion title="Failed reauthorization leaves the current connection intact">
    Cancelling or failing an integration reauthorization no longer disconnects the working account.
  </Accordion>

  <Accordion title="Webhook turns reach the bound user">
    Webhook-triggered turns now use the trigger's bound user, so user-specific actions reach the intended inbox.
  </Accordion>
</AccordionGroup>

***

## v3.27.0

**Released:** August 25, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Connect an integration once, as yourself">
    `lua integrations connect` now asks who should own the connection.

    ```bash theme={null}
    # Interactive — asks, with "this agent only" pre-selected
    lua integrations connect

    # Non-interactive
    lua integrations connect --scope user --integration github --auth-method oauth --scopes all
    ```

    **This agent only** is what the command has always done: the agent holds the credential and loses it when the agent goes.

    **Me** makes it yours. Every *private* agent you own can use it — including agents you create later, which are added automatically. Publishing an agent removes its access.

    A non-interactive run without `--scope` still connects to the agent, so existing scripts keep their meaning.
  </Accordion>

  <Accordion title="See and manage your personal connections">
    ```bash theme={null}
    lua integrations list --scope user   # yours, and how many agents each reaches
    lua integrations list --scope all    # yours and this agent's
    lua integrations disconnect --scope user --connection-id <id>
    ```

    Disconnecting removes it from every agent at once. What it already added to memory is **kept** unless you choose to forget it — disconnecting and forgetting are separate decisions.
  </Accordion>

  <Accordion title="Re-home a connection you already made">
    Already connected something to an agent and want it available everywhere? Convert it instead of reconnecting:

    ```bash theme={null}
    lua integrations convert --connection-id <id>
    lua integrations convert --connection-id <id> --force   # skip the prompt, for scripts
    ```

    The agent you connected it to keeps access and its triggers keep firing. It asks for confirmation first, because there is no way to convert back.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Options that cannot apply are refused up front">
    Connecting as yourself has no wake-up triggers, no account name and no sensitive-data toggle. Passing `--triggers`, `--custom-webhook`, `--hook-url`, `--account-label` or `--hide-sensitive` with `--scope user` now fails immediately, naming the flags — rather than partway through a browser sign-in. The interactive prompts for those steps are skipped in that scope too.
  </Accordion>

  <Accordion title="The personal catalog only offers what can be yours">
    Integrations that connect for a whole workspace, memory-source connectors, and types you have already connected are left out of the list. If the current agent already has its own connection of that type, you are warned before a second one is created — it adds a credential, it does not replace the first.
  </Accordion>

  <Accordion title="Channels.send documents conversationId">
    The `Channels.send` typings now describe addressing a shared Teams conversation with `conversationId`, alongside the existing per-person options.
  </Accordion>
</AccordionGroup>

***

## v3.26.0

**Released:** August 24, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="lua marketplace template draft — compose your template's manifest instead of hand-writing it">
    One command writes a reviewable `template:` section into `lua.skill.yaml`, inferred from your agent: the connections its skills use, `{{variable}}` slots detected in the persona, trigger presets with their current on/off state as recommended defaults, and display metadata for install-time parameters.

    ```bash theme={null}
    lua marketplace template draft --template-id tpl_abc
    # review & edit lua.skill.yaml, then:
    lua marketplace template publish --template-id tpl_abc
    ```

    Re-running `draft` merges additively — newly inferred entries are appended and your hand-edits are never modified — and prints a per-section added/kept diff. Pass `--force` to replace the authored sections wholesale, and `--source-version <n>` to compose from a specific promoted agent version. See [Publishing Templates](/marketplace/publishing-templates).
  </Accordion>

  <Accordion title="Authored template sections publish with explicit semantics — plus a --yes flag for scripts">
    When `lua.skill.yaml` carries a `template:` section, `publish` always serializes all four authored sections (`connections`, `personaTemplate`, `triggerPresets`, `paramsMeta`) — an empty or absent section is an **explicit clear**, never "inherit the previous version's". A publish that would clear or narrow a section prints a per-section consequence diff and asks for confirmation:

    ```bash theme={null}
    # Auto-confirm only the clear/narrow consequence prompt (nothing else)
    lua marketplace template publish --template-id tpl_abc --yes
    ```
  </Accordion>

  <Accordion title="Publishes are linted before a version number is spent">
    Template versions are validated server-side at publish: undeclared persona `{{variables}}`, invalid schedule intervals, unknown connection platforms or scopes, duplicate keys, and secrets in frozen code all reject with actionable per-field errors — and a rejected publish burns no version number. Publishing from a source agent with voices or device triggers is rejected with a message saying why (voice agents can't be templated yet).
  </Accordion>

  <Accordion title="Deploy a template as a brand-new agent">
    A template can now be deployed from the marketplace straight into a fresh agent: the persona template's `{{variables}}` are filled in from your answers, connections you've already granted are reused automatically, and automations only arm after an explicit confirmation. See [Deploying Templates](/marketplace/deploying-templates).
  </Accordion>

  <Accordion title="Integrations.passthrough — raw provider API through your connected integrations">
    Call any endpoint a provider documents through the integration your agent is already connected to — from tools, jobs, webhooks, and processors. The call is relayed server-side over the agent's own connection (your code never sees credentials), and the response comes back as a raw `{ status, headers, data }` envelope: provider errors such as a `403` on a missing OAuth scope are relayed faithfully in `status`, never thrown. Every connected integration also gains a matching `{integration}_passthrough` agent tool.

    ```typescript theme={null}
    import { Integrations } from 'lua-cli';

    const res = await Integrations.passthrough('github', {
      method: 'GET',
      path: 'repos/acme/app/pulls/42/files',
    });
    if (res.status === 200) console.log(res.data); // files with per-file patches
    ```

    Guardrails are built in: a per-integration enable switch admins can turn off, an audit log entry for every call, and a per-agent rate limit. See the [Integrations API](/api/integrations) for the full request/response reference, the typed error codes, and Microsoft Graph + GitHub examples.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="--skip-env-check retired">
    The env-contract check on template install and apply is enforced server-side and can no longer be bypassed. The flag is still accepted so existing scripts don't break, but it does nothing beyond printing a deprecation warning — satisfy the contract with [`lua env`](/cli/env-command) or `--env-vars` instead.
  </Accordion>
</AccordionGroup>

## v3.25.0

**Released:** August 19, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Declare what your agent does, in code">
    `LuaAgent` accepts an optional `description` — a short capability summary that [Spaces](/overview/spaces) read when deciding which member agent to hand a request to:

    ```typescript theme={null}
    import { LuaAgent } from 'lua-cli';

    export default new LuaAgent({
      name: 'refunds-agent',
      description: 'Handles refunds, returns and order cancellations for existing orders.',
      persona: 'You are a refunds specialist...',
      skills: [refundsSkill],
    });
    ```

    Keep it to one or two sentences about **what the agent can do**. The persona still owns voice, tone and detailed instructions — the description is only the routing signal.

    It travels with the rest of your configuration on `lua push`:

    ```bash theme={null}
    lua push
    # 🧭 Pushing routing description...
    #   ✅ Routing description pushed
    ```

    Ownership is opt-in. Omit `description` and a value set in the dashboard is left untouched, so existing projects are unaffected. Set it to an empty string to clear it.
  </Accordion>

  <Accordion title="Put a card on a user's desk with User.Inbox.push()">
    Your agent can ask for an approval, flag a broken integration, or leave a notice in a user's inbox — from a tool, a [job](/api/luajob), a [webhook](/api/luawebhook), or a local run:

    ```typescript theme={null}
    import { User } from 'lua-cli';

    const receipt = await User.Inbox.push({
      title: 'Approve the Q3 renewal quote',
      body: 'Northstar Ltd renewal is ready to send at $48,000.',
      actions: ['approve'],
      key: 'northstar-q3-renewal',
    });

    if (receipt.outcome === 'capped') {
      // Daily limit reached — fold it into your run summary instead.
    }
    ```

    Cards with options resolve in one click, reusing the same `key` lands on the existing card instead of knocking twice, and reaching the daily limit returns `{ outcome: 'capped' }` rather than throwing.

    See the [Inbox API reference](/api/inbox) for card kinds, limits and the full receipt contract.
  </Accordion>
</AccordionGroup>

***

## v3.24.0

### ✨ New Features

**Declared indexes for the Data primitive** — filtered queries on large
collections no longer degrade silently. Declare the fields you filter on
where you store data, and the platform builds and maintains an agent-scoped
database index for them:

```typescript theme={null}
await Data.create('inference_cache', doc, { index: ['business_id'] });
// compound (filtered together — note the nested array):
await Data.create('orders', doc, { index: [['country', 'business_id']] });
```

* `Data.create()` / `Data.update()` / `patch()` accept `{ searchText?, index? }`
  (the legacy positional `searchText` string still works)
* **New `Data.collections()`** lists your collections with entry counts and
  index status (`pending | building | ready | failed | rejected` + reasons)
* Indexes build within minutes, stay alive while your agent uses them
  (writes or filtered reads), and are removed automatically \~14 days after
  all usage stops — no cleanup code
* Limits: 2 fields per index, 3 declarations per call, 5 indexes per agent;
  invalid declarations are rejected visibly, never silently trimmed
* Filtered queries that exceed the time budget on an **undeclared** field now
  fail with an error naming the collection, the field, and the exact
  declaration to add — instead of an opaque 502

See the [Data API — Indexes](/api/data#indexes) section for the full guide.

<Note>
  **Correction (August 26, 2026):** the options-object third argument
  (`{ searchText?, index? }`) described above currently works in **local
  development runs only**. In a deployed agent, `Data.create()` and
  `Data.update()` accept a plain `searchText` string as the third argument, and
  passing an object fails with `searchText must be a string`. Keep deployed
  code on the string form until index declarations are supported in the
  deployed runtime — the [Data API — Indexes](/api/data#indexes) section
  tracks the current state.
</Note>

## v3.23.2

**Released:** August 14, 2026

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Administrators can clear another user's agent conversation again">
    Use `--user` with a user ID, email address, or mobile number when you have organization management permission for the agent:

    ```bash theme={null}
    lua chat clear --user user@example.com --force
    ```

    The target must be a user associated with that agent. Without `--user`, the command continues to clear only your own conversation history.
  </Accordion>
</AccordionGroup>

***

## v3.23.0

**Released:** August 7, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Target and update another user's stored data safely">
    A user resolved by ID, email, or phone now stays attached to that instance for every mutation:

    ```typescript theme={null}
    const user = await User.get({ email: 'customer@example.com' });

    await user.patch({
      set: { onboardingStep: 'verified' },
      unset: ['rep_code'],
    });

    await user.unset('temporaryFlag');
    ```

    `update()`, `save()`, and `clear()` are target-bound too. Existing `User.get()` calls without an identifier still use the current conversation user, and `update()` keeps its merge behavior.
  </Accordion>

  <Accordion title="Patch or delete Custom Data entries">
    Change and remove top-level fields without replacing an entire entry:

    ```typescript theme={null}
    const entry = await Data.getEntry('customers', entryId);

    await entry.patch({
      set: { status: 'active' },
      unset: ['legacyCode'],
      searchText: null,
    });

    await entry.delete();
    ```

    `searchText: null` also removes the entry's semantic-search text.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Targeted User writes update the selected user">
    User instances resolved by user ID, email, or phone no longer fall back to the calling session's record when you update, save, patch, unset, or clear them.
  </Accordion>

  <Accordion title="Job timeouts are validated and honored consistently">
    `LuaJob.timeout` accepts whole seconds from 1 through 600 and defaults to 300 seconds.
  </Accordion>

  <Accordion title="Integration authorization callbacks are safer">
    Connection and reconnection attempts now verify that the browser callback belongs to the authorization attempt and intended agent.
  </Accordion>
</AccordionGroup>

***

## v3.22.0

**Released:** July 28, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Skill-level condition — hide a whole capability">
    `LuaSkill` now accepts the same optional `condition` as `LuaTool`, one level up:

    ```typescript theme={null}
    export default new LuaSkill({
      name: 'loyalty-rewards',
      description: 'Loyalty points balance and reward redemption',
      context: `
        - check_points: Use when the customer asks about their balance.
        - redeem_points: Use when the customer wants to spend points.
      `,
      condition: async () => {
        const user = await User.get();
        return user.data?.loyaltyEnrolled === true;
      },
      tools: [new CheckPointsTool(), new RedeemPointsTool()],
    });
    ```

    When it returns `false`, the skill's tools can't be called **and** the skill's name, context, and tool names are left out of the agent's prompt entirely — the agent doesn't know the capability exists. A tool-level condition only makes a tool uncallable; the skill's name and context stay in the prompt, so the agent can still say "…but you're not enrolled, so I can't do that". Reach for the skill-level gate when the existence of a feature is itself sensitive: tiering, entitlements, per-customer capabilities.

    Evaluated per message, per user, with the full Platform API available. Fail-closed — a condition that throws or times out hides the skill. Skills without a condition are unaffected. See [Conditional Skills](/api/luaskill#conditional-skills).
  </Accordion>

  <Accordion title="Send a template media header by Meta media id">
    Template header values now accept a Meta media id as well as a public URL:

    ```typescript theme={null}
    await Templates.send({
      to: { phoneNumber: "+15551234567" },
      templateName: "spring_promo",
      values: { header: { image_id: "1234567890" } },
    });
    ```

    Upload the asset to Meta once and reuse the id across a campaign, instead of having the image re-fetched for every recipient. `image_id`, `video_id` and `document_id` sit alongside the existing `image_url` / `video_url` / `document_url` keys — an id is used in preference to a URL when both are given, and `document_filename` still applies either way.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Skills written with method shorthand keep their condition">
    `async condition() { ... }` now behaves the same as `condition: async () => { ... }`. Previously the condition was dropped and the skill failed to build.
  </Accordion>

  <Accordion title="Skill bundles no longer pull in unrelated tool code">
    A skill defined as a class alongside its tools now builds correctly and stays small — tool code no longer runs when the skill's condition is evaluated.
  </Accordion>
</AccordionGroup>

***

## v3.21.0

**Released:** July 24, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Agent templates on the marketplace">
    Publish a versioned snapshot of an agent's entire configuration (skills, webhooks, jobs, processors, triggers, model, plus a declared env-var contract) and install or roll it out to other agents. Includes fleet rollout across many agents with a per-target result table, an install ledger, consent-based creator updates, rollback via `lua version promote`, and manifest inspection.

    ```bash theme={null}
    lua marketplace template apply --template-id my-template-123 --agents agent-a,agent-b,agent-c --force
    ```

    Templates never touch a target agent's persona, environment variable values, or channels.
  </Accordion>

  <Accordion title="Private marketplace skills">
    List a skill with `--visibility private` to make it visible and installable only within your organization.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Unified marketplace command">
    `lua marketplace [skill|template] <action>` replaces the previous `create`/`install` role menus with one flat action namespace per domain. Two actions were renamed: viewing your own listings is now `mine`, and editing listing metadata is now `edit`. See the marketplace command reference for the full old → new migration table.
  </Accordion>

  <Accordion title="Subcommand --version flags fixed">
    Flags like `lua marketplace template view --version 2` previously printed the CLI's own version instead of selecting a version. The CLI's version flag is now `-V` / `--cli-version` (bare `lua --version` still works).
  </Accordion>
</AccordionGroup>

### 🔄 Changes

<AccordionGroup>
  <Accordion title="lua chat clear --user removed">
    Clearing another user's conversation history is no longer supported. The command now clears only your own history and fails with a clear message if `--user` is passed.
  </Accordion>
</AccordionGroup>

***

## v3.20.0

**Released:** July 21, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="lua version status — what's live vs what's local">
    See, per primitive, which version is pinned by the active agent version versus what's in your local project.

    ```bash theme={null}
    lua version status
    ```

    Mismatches are flagged with direction-aware guidance: primitives that are pushed but not yet live point you to `lua version create` + `lua version promote` (or `lua deploy <type>` for a single primitive), while local files older than what's live get a `lua sync` recommendation — with a warning that deploying older files would roll production back.
  </Accordion>

  <Accordion title="WhatsApp message reactions">
    React to a WhatsApp message with an emoji from your agent code:

    ```typescript theme={null}
    await Channels.whatsapp.sendReaction({
      to: { phoneNumber: '+15551234567' },
      messageId: 'wamid.HBgL...',
      emoji: '👍',
    });
    ```
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="lua deploy always takes effect for versioned agents">
    For agents using agent versioning, `lua deploy` now automatically creates and promotes a new agent version scoped to the deployed primitive — the deploy is live immediately and shows up in `lua version list`. The success output includes the promoted version, and if the live version can't be updated the deploy fails with a clear message instead of reporting success.
  </Accordion>

  <Accordion title="Integration connections show paused state">
    Connection listings now indicate when a connection has been paused.
  </Accordion>
</AccordionGroup>

***

## v3.19.0

**Released:** July 3, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Per-request timezone on chat requests (PRO-258)">
    Chat requests now accept an optional `clientContext.timezone` field — an IANA timezone string. When provided, the agent uses it as the user's local timezone for date/time-aware responses; when omitted it falls back to the user's stored profile, country, or UTC.

    ```bash theme={null}
    curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "messages": [
          { "type": "text", "text": "What time should I schedule my call for tomorrow morning?" }
        ],
        "clientContext": { "timezone": "Africa/Nairobi" }
      }'
    ```

    Also available on `Agents.invoke`. See [HTTP API](/channels/http-api) and [Agents API](/api/agents).
  </Accordion>

  <Accordion title="LuaAgent({ modelSettings: { reasoning } }) — per-agent reasoning effort">
    Set a default reasoning effort for your agent, normalized across every reasoning-capable provider (Claude, GPT/o-series, Gemini, Groq, DeepSeek, xAI, Qwen).

    ```typescript theme={null}
    import { LuaAgent } from 'lua-cli';

    export const agent = new LuaAgent({
      name: 'support-triage',
      persona: '...',
      modelSettings: {
        reasoning: { effort: 'low', show: false },
      },
      skills: [triageSkill],
    });
    ```

    `effort` is one of `'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'`. Left unset, it defaults to adaptive reasoning where the model supports it and an explicit low effort otherwise, favoring lower cost/latency on turns that don't ask for deeper thinking. `show` controls whether the reasoning trace is surfaced to the caller (default `true`). A per-request reasoning override always takes precedence over this agent-level default. See [LuaAgent → modelSettings](/api/luaagent) and [Model Selection → Reasoning Effort](/overview/model-selection#reasoning-effort).
  </Accordion>

  <Accordion title="Team.findMember() — reach a teammate without their number">
    Resolve a colleague by name within your organization and get back the channel handles (WhatsApp, SMS, email) they've chosen to share. Pair it with `Channels.send` to message them directly — no hard-coded phone numbers.

    ```typescript theme={null}
    import { Team, Channels } from 'lua-cli';

    const { matches } = await Team.findMember('Stefan');
    const whatsapp = matches[0]?.targets.find((t) => t.channel === 'whatsapp');

    if (whatsapp) {
      await Channels.send({
        channel: 'whatsapp',
        to: { phoneNumber: whatsapp.value },
        text: 'Hi Stefan!'
      });
    }
    ```

    Returns a list of matches so an ambiguous name can be disambiguated — each match includes its shareable `targets[]` (empty if the teammate hasn't opted in to sharing anything).
  </Accordion>

  <Accordion title="browser switch on LuaAgent — give your agent a browser">
    Turn on `browser: true` to give your agent browser tools like `searchWeb`, routed to the user's connected desktop browser when available, or a cloud fallback otherwise.

    ```typescript theme={null}
    import { LuaAgent } from 'lua-cli';

    export const agent = new LuaAgent({
      name: 'research-assistant',
      persona: '...',
      browser: true,
    });
    ```

    Pass an object instead of `true` for policy: `engine` (`'auto'` default, `'agent-browser'` for local-only, `'browser-use'` for cloud-only), `allowedDomains`, `credentials` (named vault entries — never raw secrets), and `maxSessionMinutes`. Off by default — a browser session costs money and carries risk, so it's opt-in.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="lua version create no longer false-blocks on a no-op counter">
    `version create` could previously refuse with "no staged changes" even when you had real changes to snapshot, or silently accept a run with nothing to snapshot. It now diffs the actual content against the previous version — including a rename with no other change. When there's genuinely nothing new, it now tells you so plainly instead of throwing an error. `lua version diff` also shows voice changes, and the "--auto-deploy was ignored" notice now appears in the final push summary, not just at the very top.
  </Accordion>
</AccordionGroup>

***

## v3.18.0

**Released:** June 22, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Channels API — agent-initiated messaging">
    Your agent can now **reach out first** — send messages on any connected channel from tools, jobs, webhooks, and triggers. Every send is recorded to the user's conversation thread, so the agent picks up with full context when they reply.

    ```typescript theme={null}
    import { Channels } from 'lua-cli';

    // Free-form message on a connected channel
    await Channels.send({
      channel: 'whatsapp',
      to: { userId: 'user_123' },
      text: 'Your order has shipped! 📦'
    });

    // Rich email
    await Channels.email.send({
      to: { email: 'customer@example.com' },
      subject: 'Receipt',
      html: '<p>Thanks for your order!</p>'
    });

    // Approved WhatsApp template (start or re-open a conversation)
    await Channels.whatsapp.sendTemplate({
      to: { phoneNumber: '+14155552671' },
      templateName: 'order_update',
      languageCode: 'en_US'
    });
    ```

    See [Channels API](/api/channels) and [Proactive Messaging](/channels/proactive-messaging).
  </Accordion>

  <Accordion title="Triggers — paste-anywhere URLs that invoke your agent">
    Define a trigger with a `verify` → `filter` → `transform` pipeline and get a pasteable URL that wakes your agent on any external event — no `execute` function required.

    ```typescript theme={null}
    import { defineTrigger } from 'lua-cli';
    import { z } from 'zod';

    export const orderCreated = defineTrigger({
      name: 'order-created',
      description: 'Fires when a new order is created',
      inputSchema: z.object({ orderId: z.string() }),
      transform: (ctx) => `New order received: ${ctx.body.orderId}`
    });
    ```

    Manage triggers from the CLI:

    ```bash theme={null}
    lua triggers create --name order-created     # prints the pasteable URL
    lua triggers list
    lua triggers logs --trigger order-created
    lua triggers rotate-token --trigger order-created
    ```

    Prefer no code? `lua triggers create --name daily --instruction "Reply with today's date"` creates a URL trigger with no SDK.
  </Accordion>

  <Accordion title="Agent-native outbound messaging">
    Let your agent send messages on its connected channels as part of a conversation by enabling the `outboundChannels` feature:

    ```bash theme={null}
    lua features configure --feature-name outboundChannels --recipient-scope anyone
    ```

    Scope it to `current_user` (message only the person it's talking to) or `anyone` (message recipients it specifies).
  </Accordion>

  <Accordion title="Voice: exclude tools and hand off calls">
    Drop specific tools from a voice agent, and transfer a live call to another in-room agent.

    ```typescript theme={null}
    // Exclude a tool from the voice agent
    excludeTools: ['place_order']

    // Hand the live call to another agent
    await ctx.voice?.handoff('billing-agent');
    ```
  </Accordion>

  <Accordion title="WhatsApp template image/video/document headers">
    Send templates with media-rich headers. Create a template with `format: 'IMAGE'`, `'VIDEO'`, or `'DOCUMENT'` and provide a sample media URL for approval (must be publicly reachable HTTPS and within Meta's size/MIME limits).

    When sending, use `values.header.image_url` for IMAGE templates, `values.header.video_url` for VIDEO templates, or `values.header.document_url` (with optional `document_filename`) for DOCUMENT templates:

    ```typescript theme={null}
    // Send with video header
    await Templates.whatsapp.send(channelId, 'product_demo', {
      phoneNumbers: ['+447551166594'],
      values: {
        header: { video_url: 'https://example.com/product-demo.mp4' },
        body: { product_name: 'Acme Widget' }
      }
    });

    // Send with document header
    await Templates.whatsapp.send(channelId, 'invoice', {
      phoneNumbers: ['+447551166594'],
      values: {
        header: {
          document_url: 'https://example.com/invoice-12345.pdf',
          document_filename: 'invoice-12345.pdf'
        },
        body: { order_number: '12345' }
      }
    });
    ```

    See the [Templates API](/api/templates#media-headers) for creation details and size limits.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Pasted and dragged images in emails now reach your agent">
    Images embedded in an email body — for example pasted or dragged into Gmail compose — previously arrived as just a `[image: …]` text placeholder, with no image part. They are now forwarded to your agent as image parts, the same way paperclip attachments are.

    The rules:

    * The embedded image must be referenced in the email's HTML body and be at least 1 KB (spacer pixels are filtered out)
    * Up to 10 embedded images per email are forwarded; regular attachments are unaffected
    * Remote-hosted images (e.g. Gmail signature images, which are hosted rather than embedded) are not fetched
    * Attachments mislabeled as embedded content by some clients are detected and forwarded as normal attachments

    The `[image: …]` placeholder still appears in the message text — use the image part, not the placeholder. See [Email Channel → Attachments and Embedded Images](/channels/email#attachments-and-embedded-images).
  </Accordion>
</AccordionGroup>

## v3.17.2

**Released:** June 1, 2026

### 🐛 Fixes

<AccordionGroup>
  <Accordion title="GitHub account linking now works">
    `lua git auth github` now links your GitHub account reliably using GitHub's
    device flow — a code is shown in your terminal that you enter at
    [github.com/login/device](https://github.com/login/device).

    ```bash theme={null}
    lua git auth github
    # Open https://github.com/login/device and enter the code: WDJB-MJHT
    # ✓ Logged in to GitHub as @your-username.
    ```

    See the [Git Command](/cli/git-command) documentation for the full
    workflow.
  </Accordion>
</AccordionGroup>

### ✨ New Features

<AccordionGroup>
  <Accordion title="Enable auto-push with one command">
    `lua git connect --auto-push` enables pushing each auto-commit to your
    linked GitHub repository. It checks that a GitHub account is linked and that
    your `origin` is a GitHub HTTPS remote before turning auto-push on, so a
    missing link or remote is reported immediately.

    ```bash theme={null}
    lua git auth github                   # link GitHub (once)
    git remote add origin https://github.com/<owner>/<repo>.git
    lua git connect --auto-push           # enable auto-commit + auto-push
    ```

    The `git` block in `lua.skill.yaml` is managed by these commands — you no
    longer need to edit it by hand. See the [Git Command](/cli/git-command)
    documentation for details.
  </Accordion>
</AccordionGroup>

## v3.17.1

**Released:** May 29, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="LuaAgent({ modelSettings }) — per-call sampling settings">
    Set sampling settings once on the agent instead of overriding them in every skill. Supports `temperature`, `topP`, `topK`, `maxOutputTokens`, `presencePenalty`, `frequencyPenalty`, `stopSequences`, and `seed` — forwarded to the model on every chat turn.

    ```typescript theme={null}
    import { LuaAgent, type AgentModelSettings } from 'lua-cli';

    export const agent = new LuaAgent({
      name: 'role-scorer',
      persona: SCORING_PERSONA,
      modelSettings: {
        temperature: 0.2,
        maxOutputTokens: 4096,
      },
      skills: [scoreRoleSkill],
    });
    ```

    Obviously-broken values (non-finite numbers, `temperature` outside `0..2`, `topP` outside `0..1`, non-positive `maxOutputTokens`, non-string `stopSequences`) are rejected at construction time. Provider-specific range checks are deferred to the provider.
  </Accordion>

  <Accordion title="AI.generate({ structuredOutput }) — JSON Schema-constrained output">
    Constrain the model response to a JSON Schema. The parsed object lands on `result.output`. No more "respond with JSON only" prompts and no more `JSON.parse` boilerplate.

    ```typescript theme={null}
    import { AI } from 'lua-cli';
    import { z } from 'zod';
    import { zodToJsonSchema } from 'zod-to-json-schema';

    const Sentiment = z.object({
      sentiment: z.enum(['positive', 'negative', 'neutral']),
      score: z.number().min(0).max(1),
    });

    const result = await AI.generate({
      prompt: 'Analyze: "the food was incredible"',
      temperature: 0,
      structuredOutput: {
        schema: zodToJsonSchema(Sentiment) as Record<string, unknown>,
      },
    });

    const parsed = Sentiment.parse(result.output);
    ```

    On Google models, the auto-injected `google_search` tool is suppressed when `structuredOutput` is set (Vertex does not allow mixing function-calling tools with `google_search`).
  </Accordion>

  <Accordion title="Named type exports for AI and LuaAgent">
    `AiGenerateInput`, `AiGenerateOutput`, `AiGenerateStructuredOutput`, `AgentModelSettings`, and sub-shapes (`AiGenerateJsonSchema`, `AiGenerateSource`, `AiGenerateToolCall`, `AiGenerateToolResult`) are now importable directly from `lua-cli`.

    ```typescript theme={null}
    import {
      AI,
      LuaAgent,
      type AiGenerateInput,
      type AiGenerateOutput,
      type AgentModelSettings,
    } from 'lua-cli';

    const opts: AiGenerateInput = {
      prompt: 'Score this JD',
      structuredOutput: { schema: jdScoreSchema },
    };

    const result: AiGenerateOutput = await AI.generate(opts);
    ```
  </Accordion>
</AccordionGroup>

## v3.5.0-alpha.2

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Email channel now exposes parsed message metadata">
    `Lua.request.webhook.payload` is now populated for inbound emails with a JMAP-aligned object containing parsed message metadata.

    ```typescript theme={null}
    import { Lua } from 'lua-cli';

    const webhook = Lua.request.webhook;

    if (Lua.request.channel === 'email' && webhook) {
      const { messageId, inReplyTo, references, subject, from, to } = webhook.payload;

      // Use metadata to build threaded replies
      const replySubject = subject?.startsWith('Re:') ? subject : `Re: ${subject}`;
      const threadId = inReplyTo ?? messageId;

      return { threadId, replySubject };
    }
    ```

    Access the Message-ID for deduplication, full RFC 5322 header list via `headerLines`, and all threading metadata (`messageId`, `inReplyTo`, `references`). See the [API reference](/api/lua#email-metadata) for the complete shape and AgentMail divergence note.
  </Accordion>
</AccordionGroup>

## v3.16.0

**Released:** May 19, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Voice agents via LuaVoice">
    Define voice agents in TypeScript alongside your `LuaAgent`. Supports cascaded (STT/LLM/TTS) and realtime (speech-to-speech) shapes, with hooks for `onEnter`, `onUserTurnCompleted`, `onExit`, and voice-only tools.

    ```typescript theme={null}
    import { LuaVoice } from 'lua-cli';

    export default new LuaVoice({
      name: 'support-line',
      llm: 'openai/gpt-5.1-chat-latest',
      stt: 'deepgram/nova-3',
      tts: 'elevenlabs/eleven_turbo_v2_5:pwMBn0SsmN1220Aorv15',
      turnDetection: 'vad',
      greeting: "Hi, this is your support line — how can I help?",
    });
    ```

    Reference the voice from your `LuaAgent`'s `voices: [supportVoice]`. `lua push` ships it through the same versioned-primitive flow as skills and webhooks.
  </Accordion>

  <Accordion title="lua channels phone — interactive phone-number provisioning">
    Buy, bind, list, and release phone numbers from the CLI:

    ```bash theme={null}
    lua channels
    # → ☎️ Manage phone numbers
    # → Search available numbers / Purchase / Bind / List / Release
    ```

    SMS-capable numbers route through Vonage; voice-only routes through LiveKit-native PSTN. The bind action wires the number directly to your agent for inbound calls.
  </Accordion>

  <Accordion title="lua voice test — deterministic voice-agent testing">
    Test voice agents with text input and event-stream assertions, runnable in CI:

    ```typescript theme={null}
    import { runVoice, expectContainsMessage, expectCalledTool } from 'lua-cli/voice/test';
    import supportVoice from '../src/voices/support.voice';

    test('greets and books appointment', async () => {
      const result = await runVoice(supportVoice, {
        turns: ['I need to book an appointment', 'Tomorrow at 2pm'],
      });
      expectContainsMessage(result, 'appointment');
      expectCalledTool(result, 'create_booking');
    });
    ```
  </Accordion>

  <Accordion title="lua voice terminal / lua voice browser — local dev">
    Talk to your voice agent during development without going through a phone number:

    ```bash theme={null}
    lua voice terminal   # CLI mode
    lua voice browser    # Opens an embedded UI in your browser
    ```
  </Accordion>

  <Accordion title="lua logs --type calls — voice call logs">
    View voice call logs from the CLI:

    ```bash theme={null}
    lua logs --type calls
    ```

    Also available as a choice in the interactive `lua logs` picker.
  </Accordion>

  <Accordion title="lua-cli/voice — LiveKit plugin namespaces">
    Re-exports of LiveKit's plugin namespaces from `lua-cli` so you don't need a direct LiveKit dependency in your project:

    ```typescript theme={null}
    import { LuaVoice } from 'lua-cli';
    import { deepgram, elevenlabs, inference } from 'lua-cli/voice';

    export default new LuaVoice({
      stt: new deepgram.STT({ model: 'nova-3', language: 'en' }),
      tts: new elevenlabs.TTS({ model: 'eleven_turbo_v2_5', voice: '...' }),
      llm: new inference.LLM({ model: 'openai/gpt-5.1-chat-latest' }),
    });
    ```
  </Accordion>

  <Accordion title="Subclass-with-field-override — share logic across agents">
    Factor shared tool / skill / webhook / etc. logic into a base class in a workspace package, then extend per-agent with field initializers:

    ```typescript theme={null}
    // shared/SharedSearchTool.ts
    export abstract class SharedSearchTool implements LuaTool {
      name = 'search';
      ragSearchPath: string = '/default';
      async execute(input: { query: string }) {
        return { results: await fetch(this.ragSearchPath, /* ... */) };
      }
    }

    // agents/customer-a/src/tools/SearchTool.ts
    export class CustomerASearchTool extends SharedSearchTool {
      ragSearchPath = '/customer-a';
    }
    ```

    Works for every primitive type. The compiler walks the full `extends` chain, including transitive extends through shared intermediates.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Voice version updates take effect immediately">
    Publishing a new voice version with `lua push voice` is enough — the next
    call uses the new version. No need to re-push the agent.
  </Accordion>
</AccordionGroup>

### 📝 Notes

<AccordionGroup>
  <Accordion title="Server compatibility">
    Voice agents require the latest server-side endpoints. Self-hosted Lua
    deployments must deploy the latest server before publishing voice agents via
    `lua push`.
  </Accordion>
</AccordionGroup>

***

## v3.15.3

**Released:** May 12, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="lua push --include-source / --no-include-source">
    After a primitive push, the CLI now also attaches the gzipped workspace archive to each skill's per-skill source store, so the Builder UI's source panel stays in sync with your CLI edits.

    ```bash theme={null}
    lua push skill                       # default: source attach included
    lua push skill --no-include-source   # skip the attach (CI loops, etc.)
    lua push all                         # same default behavior
    ```

    The attach is non-fatal — if it fails, the push is still considered successful, because the primitive is already deployed and the agent-level backup already succeeded. The per-skill store is a denormalized projection for the Builder UI, not the canonical source store.
  </Accordion>
</AccordionGroup>

***

## v3.15.2

**Released:** May 8, 2026

<Warning>
  If you're upgrading from v3.15.1, upgrade directly to v3.15.2 (or later).
  v3.15.1 has a startup crash on fresh installs from npm.
</Warning>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="lua-cli no longer crashes on startup with Cannot find package 'axios'">
    v3.15.1 shipped with a missing runtime dependency that crashed **every** CLI command on a fresh `npm install lua-cli@3.15.1`, not just the new `lua source` subcommands. v3.15.2 removes the dependency entirely — the affected paths now use the same HTTP layer as the rest of the CLI, so install size and dependency footprint are unchanged from v3.15.0.

    If you were stuck on v3.15.0 because of this, you can upgrade safely now:

    ```bash theme={null}
    npm install -g lua-cli@latest
    ```
  </Accordion>
</AccordionGroup>

***

## v3.15.1

**Released:** May 7, 2026

<Warning>
  This release has a startup crash on fresh installs from npm. Upgrade directly
  to v3.15.2 or later.
</Warning>

### ✨ New Features

<AccordionGroup>
  <Accordion title="lua source list and lua source rollback">
    Two new subcommands for working with your agent's backup version history.

    **List versions:**

    ```bash theme={null}
    lua source list                # most recent 50 versions
    lua source list --all          # full history
    lua source list --limit 100    # custom cap
    ```

    The currently active version is starred in the output.

    **Roll back to a past version:**

    ```bash theme={null}
    lua source rollback --version 12          # confirms before applying
    lua source rollback --version 12 --force  # skip the confirmation
    ```

    Rollback downloads the chosen version's files into your local workspace and then auto-pushes the rolled-back state as the next version. History is append-only — the original `v12` is never overwritten. After a rollback you have an explicit new version at the head representing "we returned to v12 on this date."
  </Accordion>

  <Accordion title="Auto-backup-push after every primitive push">
    `lua push <primitive>` now always runs a fresh-from-disk backup-push as the final step. If the backup fails, the command exits non-zero.

    No more silent partial success where the primitive landed on the server but your local source never reached the canonical store. This makes the CLI a reliable single source of truth for "this version was pushed from this machine in this state."
  </Accordion>

  <Accordion title="--fresh flag on lua push backup">
    Builds the backup manifest by walking your project directory directly from disk, instead of reading the compiled manifest.

    ```bash theme={null}
    lua push backup --fresh
    ```

    Always-on for the auto-backup hook; opt-in for explicit `lua push backup` calls. Use this when files have been written by the Builder or by any other out-of-band path that bypassed `lua compile`.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="lua init restores from the latest active backup">
    Init's restore step now hits the active manifest endpoint, which reflects every successful push from any platform — CLI, Builder chat, dashboard edits.

    Previously, `lua init` against a Builder-managed agent could restore a backup days or weeks behind the actual runtime state because the Builder's writes weren't reaching the legacy backup manifest reliably.
  </Accordion>

  <Accordion title="activeVersion tracked in lua.skill.yaml">
    After `lua init` and after every successful `lua push`, the CLI records the
    server's active backup version into your local `lua.skill.yaml`. Foundation
    for future staleness warnings ("local is behind server") and for cross-machine
    drift recovery.
  </Accordion>

  <Accordion title="Fresh backups now include Builder-written files">
    The new fresh-from-disk walker enumerates source files directly, so files written by the Builder (or any out-of-band edit) make it into your backup. Per-file cap: 256 KB. Skipped: `node_modules`, `.git`, `dist`, `dist-v2`, `.env`, and lockfiles.

    Previously, the reconcile-only path re-hashed files already in the compiled manifest, missing anything written outside `lua compile`.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="lua init no longer crashes on transient restore failures">
    Network timeouts or missing blobs during the post-init backup restore are now caught and logged. `lua init` continues with an empty workspace and tells you what failed, instead of aborting with an unhandled exception.
  </Accordion>

  <Accordion title="Compiled output excluded from fresh backups">
    The `dist-v2` directory is no longer accidentally pulled into fresh backups. Previously, every fresh backup included the entire compiled tree (bundles, per-file source copies, the manifest), inflating per-push size and contradicting the intent that compiled artifacts stay separate.
  </Accordion>
</AccordionGroup>

***

## v3.15.0

**Released:** May 6, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Duplicate an existing agent">
    Clone an entire agent into a new one in a single command:

    ```bash theme={null}
    lua init --from-agent-id <existing-agent-id>
    ```

    The duplicated agent includes its persona, skills, MCP servers, env vars, and a full project backup that is restored locally so you can `lua push` immediately. The new agent inherits its source's LLM model — `lua init` no longer prompts for a model.

    Opt-in flags add more buckets to the copy:

    ```bash theme={null}
    lua init --from-agent-id <id> \
      --include-resources \
      --include-custom-data \
      --include-inquiry-form \
      --include-devices \
      --include-ecommerce-catalog
    ```

    Cross-org duplicates are supported by adding `--org-id <target-org-id>`.

    The interactive `lua init` flow (no flags) now offers "Duplicate an existing agent" as a third choice alongside "Create a new agent" and "Use one of your existing agents".
  </Accordion>

  <Accordion title="Channel-aware personas">
    Persona and skill context can now be split per channel using an object form. The previous string form keeps working — adopt the object form only where you need it.

    ```ts theme={null}
    new LuaAgent({
      // string form (still works)
      persona: 'You are a helpful assistant…',

      // or split per channel
      persona: {
        base: 'Shared persona for all channels',
        voice: 'Speak naturally, no markdown, no bullet lists',
        text: 'Use markdown headers and bullet lists where helpful'
      },
    });
    ```

    Useful when a voice agent needs different phrasing than the same agent's chat surface. The CLI pushes voice-only personas correctly (previously they could be skipped as empty), and `lua sync --pull` round-trips the object form back to your source file with all channel branches preserved.

    The new `PersonaText` type is exported from `lua-cli` for use in your own typings.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Clearer authentication errors">
    When a command hits a 401 from the server, `lua-cli` now distinguishes between two very different conditions and tailors the remediation hint accordingly:

    * **API key invalid or expired** — `Authentication failed. Run \`lua auth configure\` to set a new API key.\`
    * **API key valid, but no access to this agent** — `Access denied for this agent. Run \`lua agents\` to list agents you can access, or \`lua init\` to switch projects.\`

    Previous versions printed a single generic message for both, sending users to a dead-end remediation flow when their key was actually fine.
  </Accordion>

  <Accordion title="Postprocessor priority is preserved on push">
    Setting `priority` on a `LuaPostprocessor` now correctly ships to production. In previous versions, the field was silently dropped during compile, so postprocessors always ran in their default order regardless of declared priority.

    No code change needed — re-run `lua push` and your existing `priority` declarations now take effect.
  </Accordion>

  <Accordion title="More resilient backup restore">
    Restoring a project backup from an older agent no longer aborts mid-restore with `incorrect header check` when one of its stored blobs was archived without compression. Uncompressed blobs are now passed through verbatim.

    Affects `lua init --restore-sources`, `lua init --from-agent-id`, and any other path that restores a project backup.
  </Accordion>

  <Accordion title="Object personas round-trip faithfully">
    Two related fixes for the new channel-aware persona shape:

    * **Voice-only personas now push.** A persona of just `{ voice: '...' }` (no `base`, no `text`) is correctly applied. Earlier this was silently skipped as empty.
    * **`lua sync --pull` preserves all channel branches.** Pulling an object-form persona from the server and writing it back to local source no longer drops `voice` or `text`.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="lua production no longer prints [object Object] for channel-aware personas">
    `lua production` now correctly displays personas using the new object form, instead of crashing on `.length` / `.substring()` calls or printing the literal string `[object Object]`.
  </Accordion>

  <Accordion title="Skills without a context push correctly under stricter validation">
    Skills that don't define a `context` now push without error. Previously the
    CLI would send an empty string and the server would reject it under the new
    stricter persona/context validator.
  </Accordion>

  <Accordion title="lua init writes valid TypeScript for string-form personas">
    The source-write path for string-form personas now produces a properly-quoted literal under all edit paths, instead of occasionally emitting unquoted text that broke compilation.
  </Accordion>
</AccordionGroup>

***

## v3.14.0

**Released:** May 5, 2026

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Reliable push for large agents">
    `lua push` now reliably uploads agents of any size, including those with many tools or large code bundles.

    Previously, agents that exceeded the upload size limit would fail mid-push with a "request too large" error. This no longer happens — pushes succeed regardless of total bundle size.

    Applies to every primitive type:

    * skills (and their tools)
    * webhooks
    * jobs
    * preprocessors / postprocessors
    * devices and device triggers

    No configuration or command change required. Just run `lua push` as usual.
  </Accordion>

  <Accordion title="Faster, leaner pushes">
    Duplicate copies of code bundles have been removed from the push payload across all primitive types. Each push is now hundreds of KB to several MB smaller, which makes pushes faster — especially on slow connections.

    Sandbox sessions launched by `lua chat` benefit from the same reduction.

    No action needed; the change is automatic with this release.
  </Accordion>
</AccordionGroup>

***

## v3.13.0

**Released:** April 29, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="lua status / lua describe — full agent state at a glance">
    A new `lua status` command (alias: `lua describe`) dumps the full state of your agent in one shot — no more running five separate commands to understand what's going on.

    ```bash theme={null}
    lua status           # human-readable table
    lua describe         # same output via alias
    lua status --json    # machine-readable JSON (schemaVersion: 1)
    ```

    What it shows:

    * **Environment** — CLI version, install method, Node version, API base, env overrides
    * **Updates** — current vs latest published version
    * **Auth** — key source, email, user ID, org list, server reachability
    * **Project** — config path, agent name/ID, manifest primitive count
    * **Primitives** — per-type sync table: local version, server version, status (synced / ahead / behind / not deployed) for skills, webhooks, jobs, preprocessors, postprocessors, MCP servers, devices, device triggers
    * **Persona** — synced / drifted
    * **Backup** — synced / out-of-sync
    * **Telemetry** — enabled/disabled
    * **Next steps** — actionable hints based on current state

    The `--json` flag outputs a stable JSON document (`schemaVersion: 1`) suitable for LLM agent consumption or CI dashboards. All progress output is suppressed in JSON mode.
  </Accordion>

  <Accordion title="Fuzzy command suggestions">
    Mistyped commands now show a "Did you mean X?" suggestion instead of a bare error:

    ```bash theme={null}
    lua stauts   # → error: unknown command 'stauts' (Did you mean: status?)
    lua pish     # → error: unknown command 'pish' (Did you mean: push?)
    lua logss    # → error: unknown command 'logss' (Did you mean: logs?)
    ```

    Works for top-level commands and constrained argument values (log types, primitive kinds, environments) across all 22 commands.
  </Accordion>

  <Accordion title="Alias shorthands for common CLI arguments">
    Common aliases are now accepted everywhere constrained argument values are expected:

    | Alias      | Expands to         |
    | ---------- | ------------------ |
    | `pp`       | `postprocessor`    |
    | `pre`      | `preprocessor`     |
    | `prod`     | `production`       |
    | `skills`   | `skill` (plural)   |
    | `webhooks` | `webhook` (plural) |
    | `jobs`     | `job` (plural)     |

    For example: `lua logs --type pp` is equivalent to `lua logs --type postprocessor`.
  </Accordion>

  <Accordion title="Post-deploy debug coaching">
    Every push, deploy, chat, compile, sync, and test surface now provides contextual guidance after the operation:

    * **Error paths** — `💡 Diagnose: run \`lua logs --type X --name Y --limit 10\`\` pointing at the right log stream for what just failed.
    * **Success paths** — `✨ Tip: run \`lua logs --limit 10\`\` nudges you to verify production execution.
    * **`lua chat`** — after each conversation turn, silently probes for `agent_error` logs. If any fired during that turn, prints: `⚠️ N new agent error(s) — run \`lua logs --type agent\_error\` to inspect.\`
    * **`lua compile`** — tip to run `lua test` after a successful compile.
    * **`lua sync --push`** — tip to verify with `lua logs` after pushing.

    To suppress all hints (for CI scripts): `LUA_NO_HINTS=1 lua push all`
  </Accordion>

  <Accordion title="lua test --json and shape headers">
    Two improvements to `lua test` output:

    **Shape headers** — the tool return value is now prefixed with its type and field names:

    ```
    Tool returned: Object — fields: success, message, data
    Tool returned: Array[3] of UserDataInstance — fields: id, name, email
    ```

    **`--json` flag** — outputs pure JSON on stdout, with all progress and compile output redirected to stderr. Enables clean piping:

    ```bash theme={null}
    lua test skill --name myTool --input '{"userId":"123"}' --json | jq '.data'
    ```
  </Accordion>
</AccordionGroup>

***

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Compiler: variable reference resolution (major fix)">
    Primitive arrays defined outside the agent config object previously caused primitives to be silently dropped from the compiled manifest. All of the following patterns now resolve correctly:

    ```typescript theme={null}
    // Variable reference
    const myTools = [new GetUserTool(), new UpdateUserTool()];
    export default new LuaAgent({ tools: myTools });

    // Spread
    export default new LuaAgent({ tools: [...baseTools, new CustomTool()] });

    // Cross-file import
    import { sharedTools } from './shared/tools';
    export default new LuaAgent({ tools: sharedTools });

    // new ImportedClass() pattern
    import { GetUserTool } from './tools/GetUserTool';
    export default new LuaAgent({ tools: [new GetUserTool()] });
    ```

    Previously, using any of these patterns would cause the compile to succeed (`✅ Compiled N primitives`) but with the primitives silently absent from the manifest — resulting in a broken agent after push.
  </Accordion>

  <Accordion title="Version collision auto-retry">
    `lua push all` now automatically retries once when it encounters an "already exists" version collision. It re-fetches the current highest server version, bumps to the next one, and retries — resolving the most common `lua push all` failure without any user intervention.

    Additionally, sandbox versions (e.g. `1.0.21-sandbox`) are now correctly excluded when calculating the next production version bump.
  </Accordion>

  <Accordion title="Orphaned primitives: delete and trigger">
    Primitives that exist on the server but not in your local YAML are now shown in interactive delete and trigger menus, clearly marked as `[server only]`. Previously these orphaned primitives were invisible in menus, making them impossible to delete or trigger interactively.

    Non-interactive delete (`lua preprocessors delete --preprocessor-name X`) also now falls back to server data for all primitive types.

    The orphan warning message now shows the exact delete command to use:

    ```
    ⚠️  Found preprocessors on server not in your local code:
       - user-context
       To remove from server: lua preprocessors delete --preprocessor-name user-context
       To restore source from backup: lua sync --accept
    ```
  </Accordion>

  <Accordion title="lua compile: tools no longer get empty schemas on corrupted installs">
    `zod` is now bundled with the CLI. Previously, if your `node_modules/zod` was corrupted — by a partial install, a dependency conflict, or switching branches mid-install — every tool got an empty `inputSchema: {}` and the compile printed `✅ Compiled N primitives` anyway, shipping a broken agent silently.

    Now:

    * The bundled copy is used first and is immune to `node_modules` corruption.
    * A local `node_modules` fallback is tried second.
    * If both fail, compile aborts immediately with a clear reinstall hint before any primitive is processed.
  </Accordion>

  <Accordion title="Monorepo backup, log types, and other fixes">
    * **Monorepo backup** — `lua push backup` now captures source files imported from cross-package paths in a monorepo and restores them to `.lua/external/` on `lua sync --accept`.
    * **Log type `runtime`** — The log source previously called `mastra` is now `runtime`. Use `lua logs --type runtime` (was `--type mastra`).
    * **New log types** — `lua logs --type rag` and `lua logs --type device-trigger` are now valid filter values.
    * **Startup warnings eliminated** — Extraneous warnings that appeared on every CLI command have been removed.
    * **Skill sandbox stale ID** — Sandbox sessions that expire after 24 hours no longer show a misleading "run lua push first" message. The CLI now recovers automatically.
    * **`lua init` template fixes** — `Data.update` and `Products.search` usage in the scaffolded template was corrected.
  </Accordion>
</AccordionGroup>

***

## v3.12.3

**Released:** April 24, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="heylua and lua-ai as additional CLI aliases">
    lua-cli now installs three binary aliases pointing to the same entry point:
    `lua`, `heylua`, and `lua-ai`. Users who have the Lua programming language
    interpreter installed (which also claims the `lua` command) can run `heylua`
    or `lua-ai` without any conflict or post-install workaround. Existing
    scripts using `lua` continue to work unchanged.
  </Accordion>
</AccordionGroup>

***

## v3.12.2

**Released:** April 23, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="@filepath attachments in lua chat">
    Attach images and documents to any chat message using `@<path>` syntax — in both interactive and non-interactive mode.

    ```bash theme={null}
    # Interactive mode
    @screenshot.png what's wrong with this UI?
    check @report.pdf and tell me what you see

    # Non-interactive mode
    lua chat -m "@screenshot.png what do you see?" -e production
    lua chat -m "compare @before.png and @after.png" -e sandbox
    ```

    Images are sent as vision inputs; documents and text files are sent as file parts. The `@` token is stripped from the message text — only the file is forwarded alongside any remaining text.

    Supported types include: `.png`, `.jpg`, `.gif`, `.webp`, `.heic`, `.pdf`, `.docx`, `.xlsx`, `.ppt`, `.csv`, `.json`, `.html`, `.txt`, `.md`, `.eml`, and more. Files with unsupported extensions are left in your message as plain text. Email addresses (`user@example.com`) are never mistaken for file paths.

    Maximum attachment size: **10 MB** per file. Multiple attachments per message are supported.
  </Accordion>
</AccordionGroup>

***

## v3.12.1

**Released:** April 22, 2026

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="lua init no longer waits 30 seconds after creating an agent">
    Agent creation previously ended with a 30-second blind sleep. That wait has been removed — `lua init` now completes immediately after the server responds. The agent persona is read directly from the create API response.
  </Accordion>

  <Accordion title="Model set at agent creation time">
    The chosen model is now sent in the initial create request instead of a follow-up PATCH call, eliminating a window where the agent could briefly exist without a model.
  </Accordion>
</AccordionGroup>

***

## v3.12.0

**Released:** April 22, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="lua triggers — pause and resume integration triggers">
    `lua triggers` is now a top-level command (alias for `lua integrations webhooks`) that lets you manage your integration triggers directly from the CLI.

    New `pause` and `resume` subcommands let you suspend or restore triggers individually or for an entire connection:

    ```bash theme={null}
    lua triggers                               # interactive menu
    lua triggers list                          # list all triggers with status
    lua triggers pause   --webhook-id <id>     # pause a single trigger
    lua triggers resume  --webhook-id <id>     # resume a single trigger
    lua triggers pause   --connection-id <id>  # pause all triggers on a connection
    lua triggers resume  --connection-id <id>  # resume all triggers on a connection
    lua triggers pause   --webhook-id <id> --reason "Maintenance window"
    ```

    The trigger list now displays rich status icons — ✅ active, ⏸️ paused, 💳 credit-suspended, 🔴 unhealthy — so you can see trigger health at a glance.

    The connect flow is also updated: triggers are opt-in by default (none pre-selected), giving you explicit control over which events wake your agent.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Skills compilation — skills now push correctly">
    Skills (`defineSkill`) were silently dropped from the compiled manifest because they were fed through esbuild like tools and webhooks. Skills are metadata-only (name, description, context, tool refs) and do not contain executable code. They now produce a JSON metadata artifact and flow through the full pipeline. Resolves the circular failure: `lua push skill` → "no server ID, run lua compile" → "not found in manifest".
  </Accordion>

  <Accordion title="MCP server ID tracking in lua.skill.yaml">
    MCP server IDs are now written back to `lua.skill.yaml` immediately after a successful push, so the server is never treated as an orphan on its first deploy. Re-pushes are fully idempotent.
  </Accordion>
</AccordionGroup>

***

## v3.11.0

**Released:** April 21, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Agents.invoke API for agent-to-agent calls (BAC-107)">
    Added a reusable agent invocation surface callable from within a LuaSkill, LuaWebhook, LuaJob, or any other primitive:

    ```typescript theme={null}
    await Agents.invoke(targetAgentId, prompt)
    await Agents.invoke(targetAgentId, { messages, systemPrompt })
    ```
  </Accordion>

  <Accordion title="Standalone defineDeviceTrigger primitive">
    Added support for device triggers as a first-class primitive decoupled from
    defineDevice, compiled and pushed like webhooks.
  </Accordion>

  <Accordion title="Governance SDK Integration">
    Added `lua governance add` and `lua governance remove` commands to configure runtime enforcement of governance policies for your agents.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Device Trigger Names">
    Allowed underscores in device trigger names.
  </Accordion>

  <Accordion title="Push Backup Refusal">
    Push-backup refusal message now shows project hashes instead of misleading timestamps.
  </Accordion>
</AccordionGroup>

***

## v3.10.0

**Released:** April 16, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="lua models command — manage your agent's LLM model (LUA-268)">
    Manage the LLM model for your agent directly from the CLI.

    ```bash theme={null}
    lua models                           # list all approved models
    lua models set                       # interactive model picker
    lua models set --model openai/gpt-4o # non-interactive
    lua models unset                     # revert to platform default
    lua models list --json               # machine-readable output
    ```

    `lua models list` shows all approved models grouped by provider, with the current model highlighted. `lua models set` writes the chosen model into your `src/index.ts` and syncs it to the server. `lua models unset` removes the model property and clears it on the server.
  </Accordion>

  <Accordion title="lua devices command — bidirectional agent-device communication">
    Full CLI for managing devices connected to your agent. Devices are a new first-class primitive type that enables your agent to send commands to physical or virtual hardware and receive trigger payloads from them.

    ```bash theme={null}
    lua devices list [--group <name>]
    lua devices status --device-name <name>
    lua devices enable --device-name <name>
    lua devices disable --device-name <name>
    lua devices remove --device-name <name> [--force]
    lua devices test --device-name <name> [--payload <json>] [--timeout <ms>]
    lua devices test-trigger --device-name <name> [--payload <json>]
    ```

    Push device definitions with `lua push device` or include them in `lua push all`. Connect hardware or virtual devices using `@lua/device-client`.

    All actions support interactive mode — omit `--device-name` to choose from a picker.
  </Accordion>

  <Accordion title="Sync pull conflict guard">
    `lua sync --accept` now detects files you have modified locally since the last `lua push backup` and refuses to overwrite them.

    ```bash theme={null}
    lua sync --accept          # guarded pull — fails if local changes detected
    lua sync --accept --force  # bypass the guard and overwrite local changes
    ```

    After every successful `lua push backup`, a local cache of file hashes is stored in `.lua/backup-manifest.json`. The guard compares this cache against your current files and only flags files that were actually modified.

    If no backup has been run yet, the pull proceeds with a warning rather than failing.
  </Accordion>

  <Accordion title="Persona guide template for new agents (LUA-271)">
    New agents created via `lua init` now receive a structured persona template instead of `"Placeholder persona"`. The template includes suggested sections — identity, tone, audience, capabilities, boundaries, and guidelines — each with guidance notes to help you write an effective persona. It is designed to be reshaped or replaced entirely.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Sync conflict detection always triggered even with no local changes">
    The backup conflict detector used full 64-character SHA-256 hashes when reading files from disk, while the backup manifest stored 16-character truncated hashes (matching the compiler format). Every comparison failed, so every file appeared as a conflict regardless of whether anything had actually changed. Fixed by aligning the detector to use the same 16-char hash as the manifest.
  </Accordion>

  <Accordion title="lua sync --accept exited 0 in CI even when restore failed">
    When a backup restore failed (network error, missing manifest), the CLI printed "Sync complete" and exited with code 0 — silently masking the failure. When drift included source-bearing primitives but no backup was available, the missing count was also never incremented. Both failure paths now correctly propagate the error so CI/CD pipelines can detect a failed pull.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="--force flag for lua sync to bypass conflict guard">
    Use `lua sync --accept --force` (or `lua sync --force`) to intentionally
    overwrite local changes when pulling from the server.
  </Accordion>
</AccordionGroup>

***

## v3.9.3

**Released:** April 15, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Model selection in lua init (LUA-262)">
    Choose your agent's LLM model during `lua init`.

    **Interactive mode:** a searchable, provider-grouped model list appears after org and name selection. Select a model or skip to use the server default.

    **Non-interactive mode:**

    ```bash theme={null}
    lua init --model openai/gpt-4o
    lua init --agent-name "My Bot" --org-id org123 --model anthropic/claude-3-5-sonnet
    ```

    The selected model is written into your generated `src/index.ts` and synced to the server. Works correctly across fresh init, re-init, backup restore, and agent-switch flows.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="MCP sync pull now works">
    `lua sync --accept` and interactive pull for MCP servers were silently no-ops — servers created via the dashboard were never written to local YAML even when drift was detected. Fixed: MCP servers missing locally are now correctly added to YAML on pull.
  </Accordion>

  <Accordion title="lua push mcp suggestion fix">
    During `lua sync`, the push suggestion for MCP servers was `lua push mcpServer --name "X"` (invalid command). Fixed to `lua push mcp --name "X"`.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="lua init wording clarity">
    The option to use an existing agent now reads "Use one of your existing
    agents" instead of "Extend one of your existing agents". The word "extend"
    implied inheritance; the actual behavior is source restore or template
    scaffold.
  </Accordion>
</AccordionGroup>

***

## v3.9.0

**Released:** April 13, 2026

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="CI/CD-friendly authentication — no keychain required (LUA-258)">
    `keytar` (OS keychain) has been removed. The CLI now works on headless Debian, Docker, and VMs without any native system dependencies.

    API key resolution order:

    1. `LUA_API_KEY` environment variable
    2. `~/.lua-cli/credentials` file (written by `lua auth configure`)
    3. `.env` file values

    ```bash theme={null}
    # Option 1 — environment variable (CI/CD, Docker)
    export LUA_API_KEY=your-api-key

    # Option 2 — interactive setup (local dev)
    lua auth configure

    # Option 3 — .env file
    echo "LUA_API_KEY=your-api-key" >> .env
    ```

    <Note>
      **Upgrading from v3.8.x or earlier?** Run `lua auth configure` once to store your key in the new location. Your previous key stored in the OS keychain is not migrated automatically.
    </Note>
  </Accordion>
</AccordionGroup>

***

## v3.8.0

**Released:** April 8, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Webhook event subscriptions (BAC-131)">
    Subscribe your webhooks to WhatsApp message lifecycle events dispatched when Meta sends status callbacks.

    ```bash theme={null}
    lua webhooks events list-events               # See all subscribable event types
    lua webhooks events subscribe <webhook-id>    # Subscribe to events
    lua webhooks events unsubscribe <webhook-id>  # Remove subscriptions
    ```

    Supported events: `sent`, `delivered`, `read`, `failed`, `played`.
  </Accordion>

  <Accordion title="Generic multi-primitive deploy (BAC-137)">
    `lua deploy` now mirrors `lua push [type]` — deploy any primitive interactively or directly:

    ```bash theme={null}
    lua deploy                    # Interactive type selection
    lua deploy skill              # Deploy a skill version
    lua deploy webhook            # Deploy a webhook version
    lua deploy job                # Deploy a job version
    lua deploy preprocessor       # Deploy a preprocessor version
    lua deploy postprocessor      # Deploy a postprocessor version
    lua deploy persona            # Deploy a persona version
    lua deploy all --force        # Deploy latest of everything
    ```

    New generic flags: `--name` (replaces `--skill-name`) and `--set-version` (replaces `--skill-version`). Deprecated aliases kept for backwards compatibility.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Jobs short flags and live status (BAC-94)">
    `lua jobs deploy -i myJob -v latest` now works correctly — `-i` and `-v` are registered as short flags for `--job-name` and `--job-version`. The activate/deactivate selection list now shows the live server status badge next to each job.
  </Accordion>

  <Accordion title="Active version comparison for all primitives">
    Jobs, preprocessors, and postprocessors were comparing the wrong ID against
    `activeVersionId`, causing the active version to not be highlighted correctly.
    Fixed to use the version's own ID in all cases.
  </Accordion>

  <Accordion title="Webhook unsubscribe event type validation">
    Invalid event types passed to `lua webhooks events unsubscribe` now show a clear validation error instead of a misleading "not subscribed" message.
  </Accordion>
</AccordionGroup>

***

## v3.7.5

**Released:** March 30, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Per-agent message batching (BAC-113)">
    Agents can now have individual batching configuration for message debouncing. New `lua chat` flags for testing:

    ```bash theme={null}
    lua chat --batch           # Enable message batching in chat session
    lua chat --delay 2000      # Set first-message delay (ms)
    ```

    Batching config is set per-agent with fallback to environment variables.
  </Accordion>
</AccordionGroup>

***

## v3.7.4

**Released:** March 27, 2026

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Keychain authentication reliability">
    Fixed several issues that could cause API key saves to silently fail on macOS. The auth flow now correctly reports errors and clears stale data on re-authentication.
  </Accordion>

  <Accordion title="Inline comment stripping in .env files">
    `.env` parsing now correctly strips inline comments: `LUA_API_KEY=abc # my comment` resolves to `abc`.
  </Accordion>
</AccordionGroup>

***

## v3.7.3

**Released:** March 24, 2026

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="HTTP retry with exponential backoff">
    Automatic retries with backoff for transient server failures (429, 500–504). Max 3 retries, never retries client errors. Improves reliability for flaky network conditions.
  </Accordion>

  <Accordion title="Reduced package size">
    Removed the `lua dev` web UI command and unused dependencies, significantly reducing install size.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Chat stream timeout">
    Chat sessions now have a 5-minute timeout instead of hanging indefinitely on
    unresponsive connections.
  </Accordion>
</AccordionGroup>

***

## v3.7.2

**Released:** March 24, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Isolated AI text generation — AI.generate (BAC-14)">
    New `AI.generate` API for running text generation from within tools, aligned with Vercel AI SDK `generateText` semantics.

    **Simplified — returns plain text:**

    ```typescript theme={null}
    // Single argument: prompt is the user message
    const text = await AI.generate('Summarize the latest AI news.');

    // Two arguments: system instruction + user content (string or multimodal parts)
    const text2 = await AI.generate(
      'You are a helpful assistant.',
      [{ type: 'text', text: 'What products do you recommend?' }]
    );
    ```

    **Full options — returns rich result:**

    ```typescript theme={null}
    const result = await AI.generate({
      model: 'google/gemini-2.0-flash',
      system: 'You are concise.',
      prompt: 'What is the weather in London?',
    });

    result.text           // Generated text
    result.finishReason   // 'stop', 'length', etc.
    result.usage          // { promptTokens, completionTokens, totalTokens }
    result.sources        // Google Search grounding URLs (when available)
    ```

    **Supported providers:** `google/*` (Vertex AI), `openai/*`, `anthropic/*` — with automatic fallback if the requested provider's API key is missing.

    Google Search grounding is automatically attached for Google models.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Lazy keytar loading for WebContainer support">
    Keytar is now loaded on demand and skipped entirely when `LUA_SKIP_KEYCHAIN` is set. Fixes `MODULE_NOT_FOUND` errors in StackBlitz WebContainers and browser sandboxes.

    ```bash theme={null}
    export LUA_SKIP_KEYCHAIN=1
    lua --version    # Now works without keytar.node
    ```
  </Accordion>
</AccordionGroup>

***

## v3.7.0

**Released:** March 20, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Chat thread isolation">
    Use `lua chat -t` or `--thread <id>` for isolated sessions. `lua chat clear --thread <id>` clears one thread. Omit the thread ID with `-t` to auto-generate a UUID.

    ```bash theme={null}
    lua chat --thread my-test
    lua chat -t
    lua chat clear --thread my-test --force
    ```
  </Accordion>

  <Accordion title="Auto-clear chat history">
    `--clear` / `--clear-thread` clear history when the session ends—useful after testing without running `lua chat clear` separately.

    ```bash theme={null}
    lua chat --clear
    lua chat -t my-test --clear
    ```
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Model cleared when removed from agent">
    Pushing after removing `model` from your agent now clears the server-side model (BAC-87).
  </Accordion>

  <Accordion title="Features help and examples">
    Help text and examples reference current feature names (e.g. `inquiry` instead of deprecated `tickets`).
  </Accordion>
</AccordionGroup>

***

## v3.6.7

**Released:** March 15, 2026

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="MCP integrations defaults (BAC-83)">
    Connecting integrations defaults to exposing full MCP tool payloads (hide sensitive off). `defer_tools` is aligned with Unified.to expectations.
  </Accordion>

  <Accordion title="Skill tool references">
    Compiling skills resolves tool references more reliably for imports and dependencies.
  </Accordion>
</AccordionGroup>

***

## v3.6.6

**Released:** March 11, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Agent error filter in logs">
    Added `lua logs --type agent_error` to filter logs for execution errors in
    tools, webhooks, and jobs.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Cron timezone and logs">
    Fixed timezone handling for cron schedules and improved error logging for
    failed cron jobs.
  </Accordion>
</AccordionGroup>

***

## v3.6.5

**Released:** March 10, 2026

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Internal URL resolution">
    Extended base URLs for internal service discovery.
  </Accordion>
</AccordionGroup>

***

## v3.6.1

**Released:** March 2, 2026

### 🐛 Bug Fixes

<AccordionGroup>
  <Accordion title="Job Schedule Fields Now Preserved">
    `interval` and `once` job schedules now compile and push correctly. Previously, the `seconds` field (interval) and `executeAt` field (once) were silently dropped during compilation, causing `lua push job` to fail with:

    ```
    Push Error: Interval seconds must be at least 60
    ```

    All three schedule types now work as documented:

    ```typescript theme={null}
    // Interval — seconds now correctly sent to server
    schedule: { type: 'interval', seconds: 300 }

    // Once — executeAt now correctly sent to server
    schedule: { type: 'once', executeAt: new Date(Date.now() + 3600000) }

    // Cron — was already working
    schedule: { type: 'cron', expression: '0 9 * * *' }
    ```
  </Accordion>

  <Accordion title="Agent Imported Primitive Resolution">
    Agents that reference imported primitives using instantiation patterns in
    their config arrays (e.g. `jobs: [new MyJob()]`) now correctly resolve and
    compile.
  </Accordion>

  <Accordion title="CLI Exits Immediately">
    The CLI now exits immediately after completing a command. Previously, a background timer kept the process alive for up to \~1s after all work was done.
  </Accordion>
</AccordionGroup>

***

## v3.6.0

**Released:** February 27, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Agent Model Selection">
    `LuaAgent` now supports a `model` property to control which AI model your agent uses. Specify a static model string or a dynamic resolver function.

    ```typescript theme={null}
    import { LuaAgent } from 'lua-cli';

    // Static model
    export const agent = new LuaAgent({
      name: 'my-agent',
      persona: 'You are a helpful assistant.',
      model: 'openai/gpt-4o',
    });

    // Dynamic model based on channel
    export const agent = new LuaAgent({
      name: 'my-agent',
      persona: 'You are a helpful assistant.',
      model: async (request) => {
        if (request.channel === 'whatsapp') return 'openai/gpt-4o-mini';
        return 'openai/gpt-4o';
      },
    });
    ```

    Supported providers: `google/*`, `openai/*`, `anthropic/*`. Default: `google/gemini-2.5-flash`.
  </Accordion>

  <Accordion title="Usage Telemetry">
    lua-cli now collects usage data to help improve the developer experience. A new `lua telemetry` command lets you control data collection:

    ```bash theme={null}
    lua telemetry          # Show current status
    lua telemetry on       # Enable telemetry
    lua telemetry off      # Disable telemetry
    ```

    Or set `LUA_TELEMETRY=false` in your environment. See [Telemetry](/cli/utility-commands#lua-telemetry) for details.
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="keytar as Optional Dependency">
    `keytar` (OS keychain access) is now optional. Fixes installation on CI/CD
    systems without native build tools. Falls back to environment variables or
    `.env` file.
  </Accordion>
</AccordionGroup>

***

## v3.5.0

**Released:** February 20, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="User Lookup by Email or Phone">
    The `User.get()` method now supports looking up users by email address or phone number, in addition to userId.

    ```typescript theme={null}
    import { User } from 'lua-cli';

    // Look up by email
    const user = await User.get({ email: 'customer@example.com' });

    // Look up by phone (both formats work)
    const user = await User.get({ phone: '+1234567890' });

    // Handle not found (returns null, doesn't throw)
    if (!user) {
      return { error: 'User not found' };
    }
    ```

    Useful for webhooks receiving contact info from external systems.
  </Accordion>

  <Accordion title="Integrations Command">
    Connect your agent to 250+ third-party services via [Unified.to](https://unified.to). When you connect an account, an MCP server is automatically created to expose tools to your agent.

    ```bash theme={null}
    lua integrations              # Interactive mode
    lua integrations connect      # Connect (OAuth or API token)
    lua integrations list         # List connected accounts
    lua integrations webhooks     # Manage webhook triggers
    lua integrations mcp          # Manage MCP servers
    ```

    **Key Features:**

    * OAuth and API token authentication
    * Automatic MCP server creation and activation per connection
    * Event-driven webhook triggers that wake up your agent
    * Server-side finalization for reliable connection setup

    See the [Integrations Command](/cli/integrations-command) documentation.
  </Accordion>

  <Accordion title="Webhook Triggers for Integrations">
    Event-driven triggers that wake up your agent when events occur in connected services.

    ```bash theme={null}
    # Connect with triggers (all selected by default in interactive mode)
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created,task_task.updated

    # Use custom webhook URL instead of agent trigger
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created --custom-webhook --hook-url https://my-server.com/webhook
    ```

    * Triggers pre-selected by default in interactive mode
    * Choose between "Agent wake-up" mode or custom webhook URLs
    * Friendly labels for OAuth scopes and webhook events
    * JSON output: `lua integrations webhooks list --json`
  </Accordion>

  <Accordion title="Project Backup & Restore">
    Back up your project source files to cloud storage and restore them on any machine.

    ```bash theme={null}
    # Backup project sources
    lua push backup

    # Restore on new machine
    lua init --agent-id abc123 --restore-sources
    ```

    **Key Features:**

    * Content-addressed storage with automatic deduplication
    * S3 direct upload — no file size limits
    * Efficient incremental backups (only changed files uploaded)
    * Full project recovery on new machines

    See the [Skill Management](/cli/skill-management#lua-push-backup) documentation.
  </Accordion>

  <Accordion title="CI/CD Mode (--ci flag)">
    New global `--ci` flag makes the CLI fail loudly on missing required arguments instead of silently hanging in non-TTY environments.

    ```bash theme={null}
    # In CI/CD pipelines
    lua --ci push skill --name mySkill --set-version ${{ github.sha }} --force

    # In local development (interactive prompts work normally)
    lua push skill
    ```

    See the [Non-Interactive Mode](/cli/non-interactive-mode#cicd-mode-ci-flag) documentation.
  </Accordion>

  <Accordion title="Self-Update Command">
    New `lua update` command for self-updating from npm, plus a background outdated version warning on every command.

    ```bash theme={null}
    lua update   # Force-fetch latest version and install
    ```

    * Background version check with 24h file cache (zero latency impact)
    * Alpha users stay on alpha channel, stable users stay on latest
    * Boxed warning to stderr when outdated
  </Accordion>

  <Accordion title="Agents Discovery Command">
    New `lua agents` command lists all organizations and agents you have access to.

    ```bash theme={null}
    lua agents            # Formatted output
    lua agents --json     # JSON output for scripting
    ```

    See the [Utility Commands](/cli/utility-commands#lua-agents) documentation.
  </Accordion>

  <Accordion title="Variable References in Primitive Config">
    You can now define primitive properties using variables and imports — not just inline literals.

    ```typescript theme={null}
    const MY_SCHEDULE = { type: 'cron', expression: '0 9 * * *' };
    const MY_TOOLS = [calculatorTool, weatherTool];
    import { RETRY_CONFIG } from './config';

    export const myJob = defineJob({
      schedule: MY_SCHEDULE,        // ✅ variable reference
      retry: RETRY_CONFIG,          // ✅ imported constant
      execute: async () => { ... }
    });
    ```

    **Supported for:** job schedule/retry, skill tools arrays, MCP server resolver functions, and all agent config arrays.
  </Accordion>

  <Accordion title="Complete Push All — Persona & Backup Included">
    `lua push all` now pushes everything including persona and backup:

    ```bash theme={null}
    lua push all --force                # All primitives + persona + backup
    lua push all --force --auto-deploy  # Also deploys persona to production
    ```

    Persona and backup failures are non-fatal — the rest of the push completes normally.
  </Accordion>

  <Accordion title="Auto-Add dist-v2/ to .gitignore">
    The CLI now automatically adds `dist-v2/` to your `.gitignore`: - **New
    projects**: Included in `lua init` template - **Existing projects**: Added
    after first successful compilation - Idempotent and safe to run multiple times
  </Accordion>

  <Accordion title="MCP and Mastra Log Types">
    ````bash lua logs --type mcp # View MCP tool execution logs lua logs --type theme={null}
    mastra # View Mastra AI runtime logs lua logs --user-id user_123456 # Filter
    by user ID ```
    </Accordion>

    <Accordion title="Non-Interactive Configure Command">
    ```bash lua configure --api-key YOUR_API_KEY # Direct setup lua configure
    --email user@example.com # Request OTP lua configure --email user@example.com
    --otp 123 # Verify OTP ```
    </Accordion>

    <Accordion title="Non-Interactive Sandbox View Commands">
      ```bash
      lua persona sandbox view    # Print persona and exit
      lua skills sandbox view     # List local skills and exit
    ````
  </Accordion>
</AccordionGroup>

### 🔧 Breaking Changes

<Warning>
  These changes may affect existing scripts and workflows. Please update
  accordingly.
</Warning>

<AccordionGroup>
  <Accordion title="Push Flag: --version renamed to --set-version">
    ```bash theme={null}
    # Old (no longer works)
    lua push skill --name mySkill --version 1.0.5

    # New (correct)
    lua push skill --name mySkill --set-version 1.0.5
    ```

    **Reason:** Avoids confusion with the global `--version` flag that shows CLI version.
  </Accordion>

  <Accordion title="Compile Sync: --no-sync changed to --sync (opt-in)">
    ```bash theme={null}
    # Old behavior (sync ran by default)
    lua compile             # Checked for drift

    # New behavior (sync is opt-in)
    lua compile             # No drift check (fast)
    lua compile --sync      # Enable drift check
    ```

    **New flag:** `--verbose` for detailed compilation output.
  </Accordion>
</AccordionGroup>

### 🚀 Improvements

<AccordionGroup>
  <Accordion title="Version Conflict Avoidance in Push">
    `lua push --force` now automatically checks the server for the highest existing version.

    **Benefit:** Prevents "Version already exists" errors during automated deployments.
  </Accordion>

  <Accordion title="Sync Compiles Before Checking Drift">
    `lua sync` now runs compilation first for more accurate drift detection.
  </Accordion>

  <Accordion title="Chat Preprocessor Block Response">
    Chat now displays preprocessor block response text instead of showing empty
    responses.
  </Accordion>

  <Accordion title="Consistent Error Messages">
    All errors now go through standardized formatting for clearer, more actionable messages.
  </Accordion>
</AccordionGroup>

### ⚡ Performance

<AccordionGroup>
  <Accordion title="Parallel Server Sync During Compilation">
    * **Before**: 6 sequential HTTP calls (\~3-6s)
    * **After**: All fetched in parallel (\~1s)
  </Accordion>

  <Accordion title="Batch Version Checks in Push All">
    One HTTP call per primitive type instead of one per entity.
  </Accordion>

  <Accordion title="Lazy Authentication">
    No upfront validation call. The first API call validates the key.
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

* **Job Creation**: Fixed `__exports` naming collision when primitives called `Jobs.create()` at runtime
* **Backup Size Limit**: S3 presigned uploads fix "request entity too large" for large projects
* **MCP Server Duplicates**: Intelligent URL merging handles concurrent MCP creation flows
* **Email Channels**: Aligned with updated API schema (mode selection, displayName, response types)
* **Agent Config Arrays**: Defining `jobs: MY_JOBS` via variables no longer silently empties the agent
* **Webhook headerSchema**: Header validation schemas now correctly pushed to server
* **Tool Conditions**: Tools without `condition()` no longer fail at runtime
* **MCP Server Push**: Fixed detection, manifest metadata, and push pipeline (3 bugs)
* **Auth Errors**: `AuthenticationError` properly propagated; 403 Forbidden handling added
* **Compile Sync**: Handlers no longer overwrite each other's IDs
* **Marketplace**: Only shows skills with published and approved versions
* **Test Command**: Fixed preprocessor test handling for object format

### 📝 Interface Updates

* Added `UserLookupOptions` for email/phone lookup
* Added `EmailChannelMode`, `CreateGeneratedEmailChannelResponse`, `CreateExistingEmailChannelResponse`
* Added `MCPServerSource` enum for tracking MCP server origin
* Updated `User.get()` return type to `UserDataInstance | null`
* Added `'mcp'` and `'mastra'` to log type enums

***

## v3.4.0

**Released:** January 22, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Non-Destructive Compile Sync">
    The `lua compile` command now uses a safer, non-destructive sync pattern. Instead of automatically deleting primitives on the server that aren't in your local code, it now:

    * **Warns** about orphaned primitives (skills, webhooks, jobs, MCP servers)
    * **Suggests** using explicit delete commands
    * **Filters** warnings to CLI-sourced skills only (ignores marketplace and manual skills)

    This prevents accidental data loss and gives you full control over what gets removed.
  </Accordion>

  <Accordion title="New Delete Commands">
    Explicit delete commands for managing primitives no longer in your local code:

    ````bash # Delete a skill from the server lua skills delete --skill-name theme={null}
    my-old-skill # Delete a webhook lua webhooks delete --webhook-name old-webhook
    # Delete a job lua jobs delete --job-name deprecated-job ``` **Features:** -
    Server lookup for orphaned items not in local YAML - Interactive mode with
    confirmation prompts - `--force` flag for non-interactive deletion
    </Accordion>

    <Accordion title="Streamable HTTP MCP Transport">
      Added support for the modern Streamable HTTP transport (MCP spec 2025-03-26):
      
      ```typescript
      const server = new LuaMCPServer({
        name: 'my-api',
        transport: 'streamable-http',  // New transport type
        url: 'https://mcp.example.com/mcp',
        headers: () => ({
          'Authorization': `Bearer ${env("API_KEY")}`
        })
      });
    ````

    **Supported transports:**

    * `'streamable-http'` - Modern MCP standard (recommended)
    * `'sse'` - Legacy Server-Sent Events transport

    <Warning>
      **stdio transport removed:** Local MCP servers using `stdio` transport are not supported yet. Use remote servers with `streamable-http` or `sse` instead.
    </Warning>
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

* **Push**: Fixed crash when pushing primitives without a version field. First push now defaults to version `0.0.1` and shows "(none - first push)" in prompts.

### 📝 Interface Updates

* Added `MCPStreamableHttpServerConfig` interface for streamable-http transport
* Updated `MCPTransport` type to `'sse' | 'streamable-http'`
* Added `SkillSource` type: `'cli' | 'marketplace' | 'manual'`
* Removed `MCPStdioServerConfig` (stdio not supported yet)

***

## v3.3.0

**Released:** January 20, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Complete Non-Interactive Mode for All Commands">
    All CLI commands now support full non-interactive operation, enabling seamless automation for AI IDEs, CI/CD pipelines, and shell scripting.

    **Design Patterns:**

    * Consistent option naming: `--<entity>-name` and `--<entity>-version`
    * `--force` flag for skipping confirmation prompts
    * `--json` flag for machine-readable output
    * Action arguments for entity management (view, versions, deploy, activate, deactivate)

    ```bash theme={null}
    # Entity management
    lua skills view
    lua skills versions --skill-name mySkill
    lua skills deploy --skill-name mySkill --skill-version 1.0.3

    # Init command
    lua init --agent-id abc123
    lua init --agent-name "My Bot" --org-id org1

    # Sync command
    lua sync --check    # CI drift detection
    lua sync --accept   # Auto-sync from server

    # Test command
    lua test skill --name get_weather --input '{"city": "London"}'

    # Logs command
    lua logs --type skill --name mySkill --limit 10 --json
    ```

    See the [Non-Interactive Mode Guide](/cli/non-interactive-mode) for complete documentation.
  </Accordion>

  <Accordion title="User Message and Agent Response Log Types">
    The logs command now supports filtering by user messages and agent responses:

    ````bash lua logs --type user_message --limit 20 lua logs --type agent_response theme={null}
    --limit 20 ``` - 💬 **User Messages**: View incoming user messages with
    channel and userId info - 🤖 **Agent Responses**: View AI-generated responses
    with distinct coloring
    </Accordion>

    <Accordion title="Function-Based Environment Resolution for MCP Servers">
      MCP server configurations now support dynamic environment variable resolution using the `env()` API:
      
      ```typescript
      const mcpServer = new LuaMCPServer({
        name: 'mongo-mcp',
        transport: 'stdio',
        command: 'npx',
        args: ['-y', '@mongodb/mcp-server'],
        env: () => ({
          MDB_CONNECTION_STRING: env("MDB_CONNECTION_STRING")
        })
      });
    ````

    Also supported for SSE transport with `url` and `headers` resolver functions.
  </Accordion>

  <Accordion title="Products.get() Filter Support">
    Added filter support to `Products.get()` with backward compatibility:

    ```typescript theme={null}
    // Backward compatible
    const products = await Products.get(1, 10);

    // New approach with filters
    const products = await Products.get({
      page: 1,
      limit: 10,
      filter: {
        category: 'electronics',
        inStock: true
      }
    });
    ```
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

* **Chat**: Allow `lua chat` to work without mandatory skills - agents can now have only webhooks, jobs, or processors
* **Commands**: Normalized action handling for case-insensitive action comparisons

### 🔧 Improvements

* **Chat Command**: Informational message when defaulting to sandbox environment
* **Chat Command**: Improved visual separation between compile logs and chat response
* **Env Command**: Proper error handling for save/delete operations
* **Push Command**: Shared helper functions reduce code duplication

***

## v3.2.0

**Released:** January 13, 2026

### ✨ New Features

<AccordionGroup>
  <Accordion title="Sync Command for Drift Detection">
    New `lua sync` command to detect drift between server and local code:

    ```bash theme={null}
    lua sync
    ```

    **Features:**

    * Compare agent name and persona between server state and local code
    * Fetch latest published persona version (excludes drafts and rollbacks)
    * Show colored line-by-line diff for easy comparison
    * Interactive resolution: update local from server or continue with local
    * Integrated into compile flow with `--no-sync` and `--force-sync` flags
  </Accordion>

  <Accordion title="Chat History Clear Command">
    New `lua chat clear` command to clear conversation history:

    ```bash theme={null}
    # Clear all conversation history
    lua chat clear

    # Clear history for a specific user
    lua chat clear --user user@example.com
    ```

    Accepts userId, email, or mobile number as the identifier.
  </Accordion>

  <Accordion title="Lua Runtime API with Channel Type">
    New `Lua` namespace for runtime access:

    ```typescript theme={null}
    import { Lua } from 'lua-cli';

    // Access channel information
    const channel = Lua.request.channel; // 'dev', 'webchat', 'whatsapp', etc.
    ```

    Channel is typed as a union type: `'dev' | 'webchat' | 'whatsapp' | 'messenger' | 'voice' | 'api' | 'email'`
  </Accordion>

  <Accordion title="Lua.request.webhook for Raw Webhook Payload">
    Access raw webhook payloads in tool execute functions:

    ```typescript theme={null}
    import { Lua } from 'lua-cli';

    // Access raw webhook payload when triggered by webhook
    const webhookPayload = Lua.request.webhook;
    ```
  </Accordion>

  <Accordion title="Marketplace Pagination">
    Browse marketplace skills now supports pagination:

    * Navigate through pages with Previous/Next options
    * Shows page info (Page X/Y) and total count
    * Configurable page size (default: 10 items)
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

* **Simplified Agent Creation**: Streamlined `lua init` flow with cleaner prompts
* **Better TypeScript Support**: Improved handling of path aliases and variable references in your code

### 🐛 Bug Fixes

* Fixed sync command occasionally showing false drift detection
* Fixed skill publishing issues
* Fixed compilation when skills are defined inline vs imported from separate files

***

## v3.1.0

**Released:** December 7, 2025

### ✨ New Features

<AccordionGroup>
  <Accordion title="MCP Server Support">
    New `LuaMCPServer` class for integrating Model Context Protocol servers with your agent:

    ```typescript theme={null}
    import { LuaMCPServer, LuaAgent } from 'lua-cli';

    const docsServer = new LuaMCPServer({
      name: 'lua-docs',
      transport: 'sse',
      url: 'https://docs.heylua.ai/mcp/sse'
    });

    export const agent = new LuaAgent({
      mcpServers: [docsServer]
    });
    ```

    **CLI commands:**

    * `lua mcp` - List, activate, deactivate, or delete MCP servers
    * `lua push mcp` - Push individual MCP servers
    * MCP servers included in `lua push all --force`
  </Accordion>

  <Accordion title="Tool Conditions">
    Tools can now have a `condition` function that determines if the tool is available:

    ```typescript theme={null}
    const adminTool = new LuaTool({
      name: 'admin-tool',
      condition: async () => {
        const user = await User.get();
        return user.data?.isAdmin === true;
      },
      execute: async (input) => { return 'admin action completed'; }
    });
    ```

    Use conditions to dynamically enable/disable tools based on user subscription, verification status, feature flags, or region.
  </Accordion>

  <Accordion title="CDN API">
    New `CDN` namespace for uploading and retrieving files:

    ```typescript theme={null}
    import { CDN } from 'lua-cli';

    // Upload a file
    const file = new File([buffer], 'image.png', { type: 'image/png' });
    const fileId = await CDN.upload(file);

    // Get file
    const file = await CDN.get(fileId);
    ```
  </Accordion>

  <Accordion title="Jobs API Enhancements">
    New methods for job management:

    ```typescript theme={null}
    // Get all jobs
    const jobs = await Jobs.getAll();

    // Activate/deactivate job scheduling
    await job.activate();
    await job.deactivate();

    // Manually trigger execution
    await job.trigger();
    ```
  </Accordion>

  <Accordion title="Evaluations Dashboard">
    New `lua evals` command opens the Evaluations Dashboard with your agent
    pre-configured. `bash lua evals `
  </Accordion>

  <Accordion title="Templates API">
    New `Templates` namespace for WhatsApp template messaging:

    ```typescript theme={null}
    import { Templates } from 'lua-cli';

    // List templates
    const result = await Templates.whatsapp.list(channelId);

    // Send template message
    await Templates.whatsapp.send(channelId, templateId, {
      phoneNumbers: ['+447551166594'],
      values: { body: { name: 'John' } }
    });
    ```
  </Accordion>

  <Accordion title="Marketplace CLI">
    New `lua marketplace` command for discovering, installing, and publishing
    skills: **For Creators:** - Publish skills to the global marketplace - Version
    management with semantic versioning - Environment variable configuration per
    version **For Installers:** - Browse and search for verified skills - Smart
    installation with dependency checks - Interactive environment variable
    configuration
  </Accordion>

  <Accordion title="Enhanced Logs Command">
    The `lua logs` command now features: - Interactive filtering by primitive type
    (Skills, Jobs, Webhooks, etc.) - Live data from API including dynamically
    created jobs - Context-aware log display with detailed metadata
  </Accordion>

  <Accordion title="Immutable User Profile">
    New `user._luaProfile` property for read-only core user data:

    ```typescript theme={null}
    const userId = user._luaProfile.userId;        // ✅ Recommended
    const fullName = user._luaProfile.fullName;
    const emails = user._luaProfile.emailAddresses;

    // user.userId still works but is deprecated
    ```
  </Accordion>
</AccordionGroup>

### 💥 Breaking Changes

<Warning>These changes may require updates to your existing code.</Warning>

<AccordionGroup>
  <Accordion title="JobInstance Restructured">
    `JobInstance` now receives the full `Job` entity with `activeVersion`:

    ```typescript theme={null}
    // Before
    const schedule = job.schedule;
    const id = job.jobId;

    // After
    const schedule = job.activeVersion.schedule;
    const id = job.id;
    await job.trigger(); // New method
    ```
  </Accordion>

  <Accordion title="welcomeMessage Removed from LuaAgent">
    The `welcomeMessage` field has been removed from `LuaAgent` configuration: -
    For voice: use `voiceConfig.welcomeMessage` - For chat widgets: use
    `WebchatChannelConfig.welcomeMessage`
  </Accordion>

  <Accordion title="Webhook Execute Signature Changed">
    Webhook execute functions now receive a single event object:

    ```typescript theme={null}
    // Before
    execute: async (query, headers, body) => {
      // handle webhook
    }

    // After
    execute: async (event) => {
      const { query, headers, body, timestamp } = event;
      // handle webhook
    }
    ```
  </Accordion>

  <Accordion title="PreProcessor Response Redesigned">
    `PreProcessorResult` now uses a discriminated union:

    ```typescript theme={null}
    // Block response
    return { action: 'block', response: 'Blocked' };

    // Proceed response
    return {
      action: 'proceed',
      modifiedMessage: [{ type: 'text', text: '...' }]
    };
    ```

    * `modifiedMessage` is now `ChatMessage[]` (array)
    * Added `priority` field for execution order
    * Removed `context` field
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

* **Data API Type Safety**: `searchText` parameter added to `Data.create()` and `Data.update()`, `data` parameter type changed to `Record<string, any>`
* **PostProcessor Simplified**: Return type now requires `modifiedResponse: string`, removed `async` field
* **Compilation**: Handle `.js` extensions for Node16/NodeNext module resolution
* **Template**: Minimal by default, use `--with-examples` flag for examples
* **Web UI**: React Query, Sonner toasts, improved env panels, docs in toolbar

### 🛠️ Refactoring

* Removed `context` field from webhooks, jobs, and postprocessors
* Removed `version` field from `LuaSkill`, `LuaJob`, and processor configurations
* Improved push command: displays both `webhookId` and `webhook-name` URL formats
* Rewritten `interfaces/jobs.ts` to match `lua-api` DTOs exactly

***

## v3.0.3

**Released:** October 30, 2025

### 🎯 User API Enhancement

Enhanced `User.get()` method now accepts an optional `userId` parameter:

```typescript theme={null}
// Get current user (existing behavior)
const userData = await User.get();

// NEW: Get specific user by ID
const specificUser = await User.get('user_123456');
```

**Use Cases:**

* Fetch data for specific users in admin tools
* Access user information in webhooks/jobs
* Multi-user data operations
* User management features

<Note>
  This enhancement allows tools, webhooks, and jobs to access any user's data,
  enabling more sophisticated multi-user scenarios.
</Note>

***

## v3.0.2

**Released:** October 30, 2025

### 🚀 Major Improvements to Compilation System

This release brings comprehensive dependency bundling, debug mode, enhanced validation, and critical bug fixes.

<AccordionGroup>
  <Accordion title="Comprehensive Dependency Bundling">
    All components now properly bundle external dependencies:

    * ✅ **LuaWebhooks** bundle dependencies (e.g., Stripe, axios)
    * ✅ **LuaJobs** bundle dependencies
    * ✅ **PreProcessors** bundle dependencies (e.g., lodash)
    * ✅ **PostProcessors** bundle dependencies (e.g., date-fns)
    * ✅ **Nested Jobs** (`Jobs.create()`) independently bundle their own dependencies

    **Impact:** All compiled components are now truly portable and self-contained, requiring no dependency installation on deployment targets.
  </Accordion>

  <Accordion title="Debug Mode">
    Added `--debug` flag to `lua compile` command: `bash lua compile --debug #
          or LUA_DEBUG=true lua compile ` **Features:** - Verbose step-by-step logging

    * Shows detected imports and dependencies - Displays bundle sizes
      (uncompressed and compressed) - Preserves temp files for inspection - Shows
      timing information for each component - Full error stack traces
  </Accordion>

  <Accordion title="Enhanced Validation">
    * **tsconfig.json validation** - Clear error if missing or invalid - **Empty
      bundle detection** - Warns about suspiciously small bundles (under 100 bytes)
    * **Bundle output validation** - Ensures esbuild creates valid output - **Null
      config handling** - Graceful compilation without lua.skill.yaml - **Safe
      optional chaining** - Fixed crash when agentData is null
  </Accordion>

  <Accordion title="Improved Error Handling">
    Context-aware error messages with actionable hints: - Dependency resolution
    failures → "Run npm install" - TypeScript syntax errors → "Check syntax in
    filename.ts" - Missing files → Shows expected path - Full stack traces in
    debug mode
  </Accordion>

  <Accordion title="Import Resolution">
    Enhanced `resolveImportPath()` to support:

    * `.ts`, `.tsx`, `.js`, `.jsx` files
    * Directory imports (`index.ts`, `index.tsx`, `index.js`)

    **Critical Fix:** Relative imports now work correctly in Jobs, Webhooks, and Processors:

    ```typescript theme={null}
    // ✅ Now works perfectly
    import { MyService } from "../services/MyService";
    // ✅ Also works
    import { MyService } from "@/services/MyService";
    ```
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

* Fixed null reference error when compiling without LuaAgent
* Fixed crash when lua.skill.yaml is missing
* Fixed compilation with empty agent name/persona
* **Critical:** Fixed relative import resolution in all component types

### 🧹 Code Quality

* Removed obsolete `dynamic-job-bundler.ts`
* Extracted common helpers (`extractRelevantImports`, `bundleAndCompressExecuteFunction`)
* Reduced bundling.ts from 1,149 to 1,036 lines (9.8% reduction)
* Added 27 comprehensive tests for bundling, execution, validation, and relative imports

***

## v3.0.0

**Released:** October 2025

### 🎉 Major Release

Version 3.0.0 focuses on developer experience, deployment automation, and real-time chat capabilities.

### ✨ New Features

<AccordionGroup>
  <Accordion title="LuaAgent - Unified Configuration">
    The flagship feature: a single, intuitive way to configure your entire agent.

    **Before (v2.x):**

    ```typescript theme={null}
    export const skill1 = new LuaSkill({ name: 'skill1', tools: [] });
    export const skill2 = new LuaSkill({ name: 'skill2', tools: [] });
    export const webhook1 = new LuaWebhook({ name: 'webhook1', execute: async () => 'ok' });
    ```

    **After (v3.0.0):**

    ```typescript theme={null}
    export const agent = new LuaAgent({
      name: 'my-assistant',
      persona: 'You are a helpful AI assistant...',
      skills: [skill1, skill2],
      webhooks: [webhook1],
      jobs: [job1],
      preProcessors: [processor1],
      postProcessors: [processor2]
    });
    ```

    **Benefits:**

    * Single source of truth
    * Clearer organization
    * Automatic YAML synchronization
    * Better IDE support
  </Accordion>

  <Accordion title="Streaming Chat Interface">
    Real-time chat responses with improved UX: `bash lua chat ` - ✅ Animated
    typing indicator while waiting - ✅ Text streams character-by-character - ✅
    Sandbox and production environment selection - ✅ Uses `/chat/stream` endpoint
    for real-time updates
  </Accordion>

  <Accordion title="Batch Deployment">
    New command for deploying all components without prompts: `bash # Push all
          with auto-versioning lua push all --force # Push and deploy to production lua
          push all --force --auto-deploy ` **What it does:** 1. Compiles project 2.
    Reads all components from `lua.skill.yaml` 3. Increments patch versions
    automatically 4. Pushes all components to server 5. Deploys to production (if
    `--auto-deploy`) **Features:** - Auto-bumps patch versions (e.g., `1.0.0` →
    `1.0.1`) - Perfect for CI/CD pipelines - Retry mechanism with exponential
    backoff
  </Accordion>

  <Accordion title="API Key Fallback">
    Flexible authentication with multiple sources (priority order): 1. **System
    Keychain** (macOS Keychain, Windows Credential Vault, Linux libsecret) 2.
    **Environment Variable** (`LUA_API_KEY`) 3. **.env File** (`LUA_API_KEY=...`)
    **Usage in CI/CD:** `bash export LUA_API_KEY=your-key lua push all --force   --auto-deploy `
  </Accordion>

  <Accordion title="Auto-Sync YAML and Code">
    Bidirectional synchronization ensures consistency:

    **On `lua init`:**

    * Agent name, persona → YAML + `index.ts` LuaAgent

    **On `lua compile`:**

    * LuaAgent persona → YAML

    No manual synchronization needed!
  </Accordion>
</AccordionGroup>

### 🔧 Improvements

<AccordionGroup>
  <Accordion title="Enhanced Bundling">
    * Excluded lua-cli internals from bundles
    * Reduced bundle sizes by 50-70%
    * Fixed relative import issues
    * Proper sandbox globals (tools use sandbox-provided APIs)
  </Accordion>

  <Accordion title="Jobs.create() Fixes">
    * `code` field now properly compressed and included - Execute function
      properly converts to strings - Excludes lua-cli imports from job execute
      functions - Better metadata support for passing data
  </Accordion>

  <Accordion title="Developer Experience">
    * Comprehensive template with 30+ example tools
    * Quick Start Guide for new users
    * TypeScript examples with best practices
    * CI/CD integration examples
  </Accordion>
</AccordionGroup>

### 🐛 Bug Fixes

**Bundling:**

* Fixed `Cannot find module '../services/ApiService'` in pre-bundled tools
* Fixed `process.cwd is not a function` in sandbox execution
* Fixed lua-cli API code being bundled into tools

**Push & Deploy:**

* Fixed webhooks and jobs not found during `push all`
* Fixed missing `tools` array causing validation errors
* Fixed deployment timing issues with retry mechanism

**Chat:**

* Fixed welcome message reading from `lua.skill.yaml`
* Fixed streaming endpoint integration
* Fixed typing indicator cleanup on errors

### 💥 Breaking Changes

<Warning>These changes require updates to your existing code.</Warning>

<AccordionGroup>
  <Accordion title="LuaAgent Required">
    **Old Way:**

    ```typescript theme={null}
    export const skill1 = new LuaSkill({ name: 'skill1', tools: [] });
    export const skill2 = new LuaSkill({ name: 'skill2', tools: [] });
    ```

    **New Way:**

    ```typescript theme={null}
    export const agent = new LuaAgent({
      skills: [skill1, skill2]
    });
    ```

    **Migration:**

    1. Wrap your existing skills in a `LuaAgent`
    2. Add `name` and `persona` fields
    3. Run `lua compile` to sync with YAML
  </Accordion>

  <Accordion title="Chat Endpoint Changed">
    * Old: `/chat/generate/:agentId` - New: `/chat/stream/:agentId` No action
      needed - handled automatically by CLI.
  </Accordion>

  <Accordion title="Jobs.create() Signature">
    Jobs must use `metadata` for data passing:

    ```typescript theme={null}
    await Jobs.create({
      metadata: { userId: input.userId },
      execute: async (job) => {
        const userId = job.metadata.userId;
      }
    });
    ```
  </Accordion>
</AccordionGroup>

### 📊 Statistics

| Metric            | Before  | After          |
| ----------------- | ------- | -------------- |
| Bundle overhead   | \~500KB | 50-70% smaller |
| Compilation speed | -       | 30% faster     |
| Template examples | 5       | 30+            |
| CLI commands      | -       | 25+            |

***

## Upgrade Guides

### From v3.0.x to v3.1.0

```bash theme={null}
npm install lua-cli@3.1.0
```

**Required changes:**

1. Update `JobInstance` access patterns (use `activeVersion.schedule`, `id` instead of `jobId`)
2. Update webhook execute functions to use event object
3. Update PreProcessor responses to use discriminated union
4. Remove `welcomeMessage` from LuaAgent (configure on channel/voice instead)

### From v2.x to v3.0.0

```bash theme={null}
npm install lua-cli@3.0.0
```

**Required changes:**

1. Wrap skills in a `LuaAgent` configuration
2. Update jobs to use `metadata` for data passing
3. Run `lua compile` to sync with YAML

```typescript theme={null}
// src/index.ts
import { LuaAgent } from 'lua-cli';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: 'Your agent persona...',
  skills: [
    /* your existing skills */
  ],
});
```


# Admin Dashboard
Source: https://docs.heylua.ai/channels/admin-dashboard

Add and manage agent channels from the admin dashboard

## Overview

The admin dashboard is the visual way to connect channels to an agent — no CLI required. Channels are configured **per agent**, so you add them from inside the agent you want to connect.

```bash theme={null}
lua admin
# Or visit https://admin.heylua.ai
```

<Info>
  The dashboard supports **more channels than the CLI** — including OAuth-based channels like Instagram. If a channel isn't available in `lua channels`, connect it here.
</Info>

## Add a channel

<Steps>
  <Step title="Open Agents">
    Click **Agents** in the main side navigation, then select the agent you want to connect from the list (or from the Overview cards).
  </Step>

  <Step title="Find the Channels section">
    The agent's overview opens. On the right-hand panel, find the **Channels** section.

    <Frame>
      <img alt="Agent overview with the Channels section" />
    </Frame>
  </Step>

  <Step title="Click the + icon">
    Click the **+** icon on the **Channels** row to open the channel picker.

    <Frame>
      <img alt="Connect a channel picker" />
    </Frame>

    Available channels include Facebook, WhatsApp, Instagram, Slack, and Email.
  </Step>

  <Step title="Follow the channel's workflow">
    Select a channel and follow its connection workflow. For example, Slack first asks whether to connect a **Private** or **Public** app.

    <Frame>
      <img alt="Connect to Slack workflow" />
    </Frame>

    Each channel has its own steps — see the full guides below.
  </Step>
</Steps>

## Channel setup guides

Each channel's full connection flow is documented on its own page:

<CardGroup>
  <Card title="WhatsApp Business" icon="whatsapp" href="/channels/whatsapp">
    Embedded Signup via Meta
  </Card>

  <Card title="Facebook Messenger" icon="facebook" href="/channels/facebook-messenger">
    Connect a Facebook Page
  </Card>

  <Card title="Instagram" icon="instagram" href="/channels/instagram">
    Direct Messages (dashboard only)
  </Card>

  <Card title="Slack" icon="slack" href="/channels/slack">
    Private bot or public app
  </Card>

  <Card title="Email" icon="envelope" href="/channels/email">
    Generated or existing inbox
  </Card>

  <Card title="Website Widget" icon="globe" href="/channels/website-widget">
    Embed the Lua Pop widget
  </Card>
</CardGroup>

## Manage connected channels

Once connected, a channel appears in the agent's **Channels** section and under the **Connections** tab at the top of the agent. From there you can review its status and reconfigure or disconnect it. To monitor channel traffic, use the agent's **Activity** tab (or the org-wide **Activity** section) for logs and conversations.

## CLI alternative

Prefer the terminal? The `lua channels` command manages channels interactively:

```bash theme={null}
# Connect a channel interactively (WhatsApp, Facebook, Slack, Email)
lua channels

# List connected channels
lua channels list
```

<Note>
  The CLI covers the credential-based channels. **Channels that rely on an OAuth flow (such as Instagram) are only available in the dashboard.** See the [Channels Command reference](/cli/channels-command) for full CLI usage.
</Note>

## Next Steps

<CardGroup>
  <Card title="CLI Management" icon="terminal" href="/channels/cli-management">
    Terminal-based channel management
  </Card>

  <Card title="All Channels" icon="list" href="/channels/introduction">
    View all channel options
  </Card>
</CardGroup>


# Channel Capabilities
Source: https://docs.heylua.ai/channels/channel-capabilities

What each channel supports for outbound messaging — windows, cold start, recipients, and limits

## Overview

Channels differ in what they allow for **agent-initiated** (outbound) messages: some let you message anyone any time, some require a prior conversation, and some enforce platform-specific time windows. This page is the reference matrix. For the API itself, see [Channels API](/api/channels); for the concepts, see [Proactive Messaging](/channels/proactive-messaging).

## Capability matrix

| Channel       | Free-form outbound            | Cold start      | Address by                 | Time window            | Notes                                             |
| ------------- | ----------------------------- | --------------- | -------------------------- | ---------------------- | ------------------------------------------------- |
| **WhatsApp**  | In-window only                | Template only   | `userId`, `phoneNumber`    | 24h since last inbound | Outside the window, use an approved template      |
| **SMS**       | Any time                      | ✅ `phoneNumber` | `userId`, `phoneNumber`    | None                   | Carrier opt-out (STOP/HELP/START); regional rules |
| **Email**     | Any time                      | ✅ `email`       | `userId`, `email`          | None                   | Subject, HTML, cc/bcc, attachments                |
| **Web chat**  | To known user                 | —               | `userId`                   | None                   | Renders the full formatting component set         |
| **Teams**     | To known user or conversation | —               | `userId`, `conversationId` | None                   | **Warm-only** — needs an existing conversation    |
| **Instagram** | To known user                 | —               | `userId`                   | None                   | **Warm-only**                                     |
| **Messenger** | To known user                 | —               | `userId`                   | None                   | **Warm-only**                                     |

* **Cold start** — reach a recipient who has *never* messaged your agent (by raw `phoneNumber` / `email`).
* **Warm-only** — you can only message a user who already has a conversation with your agent (address them by `userId`).
* **`conversationId`** — addresses a shared conversation instead of a person. Everyone in it receives the message.

## WhatsApp

<CardGroup>
  <Card title="24-hour window" icon="clock">
    Free-form messages are allowed only within 24 hours of the user's last inbound message (a Meta rule).
  </Card>

  <Card title="Templates outside the window" icon="whatsapp">
    Use an approved template via `Channels.whatsapp.sendTemplate` to start or re-open a conversation.
  </Card>
</CardGroup>

* **Cold start:** only via an approved template — you cannot free-form message a number that hasn't messaged you.
* **Closed-window default:** `Channels.send` queues the message and prompts the recipient to opt in; the queued text delivers once they re-engage (`queued: true`). Override with `options.whatsapp.onClosedWindow: 'fail'` to handle the fallback yourself.
* **US (+1) recipients:** the opt-in prompt is a marketing-category template that Meta may not deliver to US numbers — send a utility template directly for reliable US outreach.
* **Media & rich templates:** image/video/document headers and buttons are supported — see [Templates API](/api/templates#media-headers).

## SMS

* **No time window** — you can send any time.
* **Cold start:** ✅ via `phoneNumber`.
* **Opt-out compliance:** recipients can reply `STOP` (opt out), `HELP` (info), or `START` (opt back in). Opted-out recipients are suppressed automatically — a send to a suppressed number is rejected.
* **Branding & regional rules:** outbound SMS is brand-prefixed and includes the required disclosures; delivery is subject to regional allow-lists and carrier (10DLC) registration.
* **Sender number:** resolved automatically — your agent's own SMS number if configured, otherwise a shared Lua number matched to the recipient's country, otherwise a shared fallback. You don't need a dedicated number to send.

## Email

* **No time window.**
* **Cold start:** ✅ via `email`.
* **Rich content:** subject, plain-text and/or HTML body, `cc`/`bcc`, and attachments (fetched from a public URL at send time; combined cap 28 MB).
* **Threading:** replies thread back to the agent's conversation via standard email reply headers.
* Use [`Channels.email.send`](/api/channels#channels-email-send) for the full shape.

## Web chat

* **Warm delivery** to a known user (`userId`) — delivered to the user's embedded [chat widget](/chat-widget/introduction).
* Renders the full set of [response formatting components](/formatting/introduction).

## Teams, Instagram, Messenger

* **Warm-only.** You can message a user only if they already have a conversation with your agent — address them by `userId`. There is no cold-start path on these channels.

### Teams group chats and channels

Teams also lets you address a **conversation** rather than a person, using `to: { conversationId }`. Use it to post into a group chat or a team channel that your agent is already part of — someone must have added the bot and @mentioned it at least once, which is what makes the conversation addressable.

```typescript theme={null}
await Channels.send({
  channel: 'teams',
  to: { conversationId: '19:9495c339...@thread.v2' },
  text: 'Sample LOT-4471 is missing origin and cupping score.',
});
```

The `conversationId` is the Teams conversation id, available on inbound messages as `webhookPayload.conversation.id`.

<Note>
  A shared conversation has no single recipient, so there is nobody to record the message against — these sends return `persisted: false` and are not written to agent memory. `to: { userId }` still means the user's **direct** conversation, never a group they happen to be in.
</Note>

## Recipient resolution

When you pass `to: { userId }`, the channel-native address (phone number, email, page-scoped ID, etc.) is resolved from the user's conversation history with your agent. When you pass a raw `phoneNumber` or `email`, it's used directly (cold start, where the channel supports it).

<Note>
  A recipient must be reachable on the channel you choose. Sending WhatsApp to a `userId` who has only ever used email will fail to resolve a WhatsApp address — pick a channel the user is actually on, or use [`user.send()`](/api/user#send) to reach them on their active channel.
</Note>

## Next steps

<CardGroup>
  <Card title="Channels API" icon="paper-plane" href="/api/channels">
    The send methods and their full input/output shapes
  </Card>

  <Card title="Proactive Messaging" icon="bell" href="/channels/proactive-messaging">
    The model behind agent-initiated messages
  </Card>
</CardGroup>


# CLI Management
Source: https://docs.heylua.ai/channels/cli-management

Manage channels via terminal

## Overview

The `lua channels` command provides terminal-based channel management for developers who prefer command-line workflows.

```bash theme={null}
lua channels
```

## Supported Operations

<CardGroup>
  <Card title="List Channels" icon="list">
    View all connected channels
  </Card>

  <Card title="Link New Channel" icon="link">
    Connect new platforms
  </Card>

  <Card title="View Details" icon="info">
    Channel status and configuration
  </Card>

  <Card title="Open Admin" icon="arrow-up-right-from-square">
    Quick access to dashboard
  </Card>
</CardGroup>

## Complete Command Reference

<Card title="Full CLI Documentation" icon="terminal" href="/cli/channels-command">
  See complete `lua channels` command reference
</Card>

## Supported Channels via CLI

<Tabs>
  <Tab title="✅ Supported">
    **Can connect via CLI:**

    * 📱 WhatsApp Business
    * 💬 Facebook Messenger
    * 📧 Email
    * 💼 Slack (Private & Public)

    All require credentials you provide
  </Tab>

  <Tab title="🌐 Admin Only">
    **Require admin dashboard:**

    * 📸 Instagram (OAuth flow)
    * 💻 Website Widget (code snippet)

    These use visual OAuth flows or don't need "connection"
  </Tab>
</Tabs>

## Quick Workflows

### List All Channels

```bash theme={null}
$ lua channels

? What would you like to do? 📋 List channels

✅ Found 4 channel(s)

📱 WHATSAPP - +15557986280
💬 FACEBOOK - Business Page  
📧 EMAIL - support@company.com
💼 SLACK - Team Workspace
```

### Link WhatsApp

```bash theme={null}
$ lua channels
→ Link new channel
→ WhatsApp
→ Enter credentials
✅ Connected
```

### View Details

```bash theme={null}
$ lua channels
→ List channels
→ Select channel
📄 View full configuration
```

### Open Admin Dashboard

```bash theme={null}
$ lua channels
→ Link on admin dashboard
🌐 Opens browser to admin
```

## When to Use CLI

<AccordionGroup>
  <Accordion title="✅ Use CLI when:">
    * You're already in terminal
    * Automating channel setup
    * Scripting deployments
    * Quick status checks
    * You have credentials ready
  </Accordion>

  <Accordion title="🌐 Use Admin when:">
    * OAuth flows needed (Instagram)
    * Visual interface preferred
    * Managing many channels
    * Team collaboration
    * Viewing analytics
    * Non-technical users
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Admin Dashboard" icon="gauge" href="/channels/admin-dashboard">
    Visual channel management
  </Card>

  <Card title="Command Reference" icon="book" href="/cli/channels-command">
    Complete CLI documentation
  </Card>
</CardGroup>


# Email
Source: https://docs.heylua.ai/channels/email

Connect your agent to email for automated responses

## Overview

Email integration allows your agent to automatically respond to emails. There are two modes:

* **Generated inbox** - Lua creates a dedicated email address for your agent (e.g. `agent-abc@mail.heylua.ai`)
* **Existing email** - Use your own email address (e.g. `support@mybusiness.com`) with forwarding

<CardGroup>
  <Card title="Professional" icon="briefcase">
    Business-appropriate channel
  </Card>

  <Card title="Universal" icon="globe">
    Everyone has email
  </Card>

  <Card title="B2B Friendly" icon="handshake">
    Preferred for business
  </Card>

  <Card title="Threaded" icon="reply">
    Conversation threading
  </Card>
</CardGroup>

## How It Works

<Tabs>
  <Tab title="Generated Inbox">
    <Steps>
      <Step title="Lua Creates Inbox">
        A dedicated email address is generated for your agent
      </Step>

      <Step title="User Sends Email">
        Customer emails the generated address directly
      </Step>

      <Step title="Agent Processes">
        Agent reads and understands email
      </Step>

      <Step title="Agent Responds">
        Agent sends reply via email
      </Step>

      <Step title="User Receives Reply">
        Reply appears in their inbox
      </Step>
    </Steps>
  </Tab>

  <Tab title="Existing Email">
    <Steps>
      <Step title="User Sends Email">
        Customer emails: [support@yourcompany.com](mailto:support@yourcompany.com)
      </Step>

      <Step title="Email Forwards to Lua">
        Your email provider forwards to Lua
      </Step>

      <Step title="Agent Processes">
        Agent reads and understands email
      </Step>

      <Step title="Agent Responds">
        Agent sends reply via email
      </Step>

      <Step title="User Receives Reply">
        Reply appears in their inbox
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Connection Method 1: CLI

<Tabs>
  <Tab title="Generated Inbox">
    ```bash theme={null}
    $ lua channels
    ✅ Using agent: myAgent

    ? What would you like to do? 🔗 Link new channel
    ? Select channel type: 📧 Email

    ? Select email channel mode: 📬 Generate new inbox
    ? Enter display name (shown in email header): Support Team

    📡 Creating Email channel...

    ✅ Email channel created successfully!

    📧 Display Name:    Support Team
    📬 Email Address:   agent-abc123@mail.heylua.ai

    ────────────────────────────────────────────────────
    Your agent's email inbox has been created.
    ────────────────────────────────────────────────────

    Share this address with your customers or use it
    in your workflows:
       agent-abc123@mail.heylua.ai

    Emails sent to this address will be handled by
    your agent.
    ────────────────────────────────────────────────────
    ```

    No additional setup required -- your agent is ready to receive emails immediately.
  </Tab>

  <Tab title="Existing Email">
    ```bash theme={null}
    $ lua channels
    ✅ Using agent: myAgent

    ? What would you like to do? 🔗 Link new channel
    ? Select channel type: 📧 Email

    ? Select email channel mode: 📧 Use existing email
    ? Enter display name (shown in email header): Support Team
    ? Enter sender email address: support@mybusiness.com

    📡 Creating Email channel...

    ✅ Email channel created successfully!

    📧 Display Name:    Support Team
    📧 Sender Email:    support@mybusiness.com
    📬 Forward To:      b5469c03-082e-481d-929b-663daf66bbef@mail.heylua.ai

    ────────────────────────────────────────────────────
    IMPORTANT: Email Forwarding Setup Required
    ────────────────────────────────────────────────────

    1. Log into your email provider's settings
    2. Set up email forwarding or filtering
    3. Forward all emails from support@mybusiness.com to:
       b5469c03-082e-481d-929b-663daf66bbef@mail.heylua.ai

    4. Test by sending an email to support@mybusiness.com
       Your agent will respond automatically!
    ────────────────────────────────────────────────────
    ```

    See [Email Provider Setup](#email-provider-setup) below for forwarding instructions.
  </Tab>
</Tabs>

## Connection Method 2: Admin Dashboard

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent and add a channel">
    Click **Agents** in the main side navigation, select your agent's card, click the **+** (plus) icon to add a channel, then choose **Email**.
  </Step>

  <Step title="Choose a connection type">
    In the **Connect to Email** dialog, enter a **Display name** (shown in the email header, e.g. "Support Team") and pick how to connect, then click **Connect**.

    <Tabs>
      <Tab title="Generate new email">
        Lua creates a new email address your customers can email directly.

        <Frame>
          <img alt="Generate new email" />
        </Frame>
      </Tab>

      <Tab title="Use existing email">
        Enter your business **Email address** — you'll forward mail from it to Lua.

        <Frame>
          <img alt="Use existing email" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Finish setup">
    * **Generated** — Lua shows **"Your email address is ready!"** with the new address. Copy it and share it with your customers.
    * **Existing** — Lua shows a **forwarding address**. Copy it and set up forwarding from your email provider (see [Email Provider Setup](#email-provider-setup) below). Your agent only receives email once forwarding is active.
  </Step>
</Steps>

## Email Provider Setup

<Tabs>
  <Tab title="Gmail">
    **Gmail Forwarding:**

    1. Open Gmail Settings
    2. "Forwarding and POP/IMAP" tab
    3. "Add a forwarding address"
    4. Paste Lua forwarding address
    5. Check verification email
    6. Click verification link
    7. Return to Gmail settings
    8. Enable "Forward a copy"
  </Tab>

  <Tab title="Outlook">
    **Outlook Forwarding:**

    1. Open Outlook Settings
    2. Mail → Forwarding
    3. Enable forwarding
    4. Enter Lua forwarding address
    5. Save changes
  </Tab>

  <Tab title="Google Workspace">
    **Workspace Routing:**

    1. Admin Console
    2. Apps → Gmail → Routing
    3. Create routing rule
    4. Condition: recipient = your email
    5. Action: forward to Lua address
  </Tab>

  <Tab title="cPanel">
    **Email Forwarders:**

    1. cPanel → Email Forwarders
    2. Add Forwarder
    3. From: your email
    4. To: Lua forwarding address
    5. Add Forwarder
  </Tab>
</Tabs>

## Testing

<Steps>
  <Step title="Send a test email">
    Email your connected address — the generated address, or your business address once forwarding is set up:

    ```
    To: support@mybusiness.com
    Subject: Test
    Body: Is this working?
    ```
  </Step>

  <Step title="Check Activity → Logs">
    In the admin dashboard, open **Activity → Logs**. You'll see the inbound email and your agent's response there as it's processed.
  </Step>

  <Step title="Agent responds">
    Your agent replies automatically — the response lands in the sender's inbox.
  </Step>
</Steps>

## Accessing Email Metadata in Tools

For inbound emails, `Lua.request.webhook.payload` is populated with a JMAP-aligned object containing parsed message metadata. Use this to build threaded replies, deduplicate by Message-ID, read custom headers, or implement conversation threading.

```typescript theme={null}
import { Lua, LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class ThreadedReplyTool implements LuaTool {
  name = 'send_threaded_reply';
  description = 'Send a reply to an email, preserving thread';

  inputSchema = z.object({
    message: z.string(),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const webhook = Lua.request.webhook;

    if (Lua.request.channel === 'email' && webhook) {
      const { messageId, inReplyTo, subject } = webhook.payload;
      
      // Build reply subject
      const replySubject = subject?.startsWith('Re:') ? subject : `Re: ${subject}`;
      
      // Use messageId to thread the reply
      return {
        message: input.message,
        threadId: inReplyTo ?? messageId,
        subject: replySubject,
      };
    }

    return { error: 'Not an email channel' };
  }
}
```

For full details on the shape, headers, and AgentMail divergence, see [Webhook Payload → Email](/api/lua#email-metadata).

## Attachments and Embedded Images

Inbound emails can carry files two ways, and both reach your agent as file parts alongside the message text:

* **Regular attachments** (the paperclip) — always forwarded, no size restrictions.
* **Embedded images** (pasted or dragged into the compose window, e.g. in Gmail) — forwarded when they are genuinely part of the message: the image must be referenced from the email's HTML body, be an image type, and be at least 1 KB (filters out 1×1 spacer pixels). Up to **10 embedded images per email** are forwarded.

<Note>
  Email clients insert a plain-text placeholder like `[image: photo.png]` where an embedded image sits in the body. That placeholder still appears in the message text your agent sees — but the actual image now arrives as a separate image part. Don't try to parse the placeholder; use the image part.
</Note>

A few behaviors worth knowing:

* **Remote-hosted images are not fetched.** Images referenced by URL — for example Gmail signature images, which are hosted rather than embedded — are not downloaded. Only data actually transmitted in the email is processed.
* **Embedded signature logos may come through.** Some email clients (commonly corporate Outlook setups) embed signature logos directly in the message. An embedded logo over 1 KB is indistinguishable from a content image and will reach your agent as an image part. If your users' emails are signature-heavy, consider instructing your agent to disregard branding imagery.
* **Mislabeled attachments are recovered.** Some clients mark real attachments as embedded content; these are detected and forwarded as normal attachments rather than dropped.

## Sending Proactive Emails

Your agent can send email on its own — receipts, confirmations, reports — using the [Channels API](/api/channels). Email has no time window, so you can send any time, and you can reach a cold address (one with no prior conversation).

Pass `html` to send your exact markup as-is, or `richBody` to have markdown / `:::` components rendered into the branded email template (the same rendering your agent's replies use). Use one or the other.

```typescript theme={null}
import { Channels } from 'lua-cli';

await Channels.email.send({
  to: { email: 'customer@example.com' },
  subject: 'Your receipt',
  html: '<h1>Thanks for your order!</h1><p>Total: $99.00</p>',
  cc: ['accounts@example.com'],
  attachments: [
    { filename: 'receipt.pdf', contentType: 'application/pdf', url: 'https://files.example.com/receipt.pdf' }
  ]
});
```

See [Channels API → email.send](/api/channels#channels-email-send) for the full shape and [Proactive Messaging](/channels/proactive-messaging) for the model.

## Best Practices

<AccordionGroup>
  <Accordion title="Professional Tone">
    Email is a more formal channel than chat. If your agent's core persona is casual or emoji-heavy, that style will carry into its emails unless you account for it. Prompt-engineer any skills or tools that generate email content to enforce a more formal tone — for example, instruct them to avoid emojis, use proper greetings and sign-offs, and write in complete paragraphs. This keeps email responses professional even when the underlying persona is playful elsewhere.
  </Accordion>

  <Accordion title="Response Time">
    * Aim for \< 1 hour response
    * Set auto-reply for delays
    * Mention expected response time
  </Accordion>

  <Accordion title="Formatting">
    * Use proper paragraphs
    * Include signature
    * Format lists clearly
    * Proofread responses
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Website Widget" icon="globe" href="/channels/website-widget">
    Add chat to website
  </Card>

  <Card title="All Channels" icon="list" href="/channels/introduction">
    View all options
  </Card>
</CardGroup>


# Facebook Messenger
Source: https://docs.heylua.ai/channels/facebook-messenger

Connect your agent to Facebook Page messages

## Overview

Facebook Messenger integration allows your agent to respond to messages sent to your Facebook Business Page.

<CardGroup>
  <Card title="2.9B Users" icon="users">
    Massive Facebook user base
  </Card>

  <Card title="Page Integration" icon="facebook">
    Connect to business page
  </Card>

  <Card title="Rich Media" icon="image">
    Images, videos, buttons
  </Card>

  <Card title="Social Context" icon="network-wired">
    See user's public profile
  </Card>
</CardGroup>

## Prerequisites

<Info>
  Meta updates Facebook and its developer tools frequently. The steps below describe what you need; for exact, up-to-date screens, see Meta's [Messenger Platform documentation](https://developers.facebook.com/docs/messenger-platform/).
</Info>

<Steps>
  <Step title="Facebook Business Page">
    You need admin access to a Facebook Page. The dashboard method connects it for you via Facebook login — no developer app required.
  </Step>

  <Step title="Facebook App (CLI only)">
    Only needed for the CLI method. Create one at [developers.facebook.com](https://developers.facebook.com).
  </Step>
</Steps>

## Connection Method 1: Admin Dashboard (Recommended)

<Info>
  The dashboard connects Facebook via **Facebook Login (OAuth)** — you authorize Lua in a Facebook popup and pick your Page there, so there's nothing to copy or paste. Use the [CLI method](#connection-method-2-cli-advanced) if you'd rather supply a Page access token manually.
</Info>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent">
    Click **Agents** in the main side navigation, then select your agent's card.
  </Step>

  <Step title="Add a channel">
    Click the **+** (plus) icon to add a channel, then choose **Facebook**.

    <Frame>
      <img alt="Add a channel" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the channel options*
  </Step>

  <Step title="Accept terms & connect">
    Tick the box to accept the **Terms of Service** and **Privacy Policy**, then click **Connect**.
  </Step>

  <Step title="Authorize with Facebook">
    A Facebook login popup opens. Log in, select the **Page** you want to connect, and grant the messaging permissions Facebook requests. When the popup closes, the channel is connected.

    <Note>
      This popup is Facebook's own UI and changes periodically. See Meta's [Messenger Platform documentation](https://developers.facebook.com/docs/messenger-platform/) if you get stuck.
    </Note>
  </Step>

  <Step title="Connection success">
    Facebook appears in your connected channels and is ready to receive messages.
  </Step>
</Steps>

## Connection Method 2: CLI (Advanced)

### CLI Setup with Page Token

<Steps>
  <Step title="Get Page Access Token">
    From your Facebook App Dashboard:

    1. Go to your app
    2. Messenger → Settings
    3. Generate a Page Access Token
    4. Copy the token

    See Meta's [Messenger Platform documentation](https://developers.facebook.com/docs/messenger-platform/) for the current steps.
  </Step>

  <Step title="Get Page ID">
    From your Facebook Page:

    1. Go to page settings
    2. Copy Page ID

    Or from URL: `facebook.com/[page-id]`
  </Step>

  <Step title="Run lua channels">
    ```bash theme={null}
    $ lua channels
    ✅ Using agent: myAgent

    ? What would you like to do? 🔗 Link new channel
    ? Select channel type: 💬 Facebook Messenger

    ? Enter Facebook page access token: ****
    ? Enter Facebook page ID: 705555819301071

    📡 Creating Facebook channel...

    ✅ Facebook channel created successfully!

    💬 Page Name: My Business Page
    📄 Category: Local Business
    🔗 Webhook: https://wa.heylua.ai/fb/webhook/xyz789
    ```
  </Step>

  <Step title="Configure Webhook in Facebook App">
    1. Go to App Dashboard
    2. Messenger → Settings → Webhooks
    3. Click "Add Callback URL"
    4. Paste the webhook URL from the CLI output
    5. Enter your verify token
    6. Subscribe to `messages`, `messaging_postbacks`, and `messaging_optins`

    See Meta's [Messenger Platform Webhooks guide](https://developers.facebook.com/docs/messenger-platform/webhooks) for the current UI.
  </Step>
</Steps>

## Testing

<Steps>
  <Step title="Send a message to your Page">
    Open Messenger and send a message to your Page (for example, "Hi!").
  </Step>

  <Step title="Agent responds">
    Your agent replies automatically in the Messenger thread.
  </Step>

  <Step title="View in admin">
    Monitor the conversation in the admin dashboard.

    <Frame>
      <img alt="Admin conversation" />
    </Frame>

    *Screenshot: The conversation in the admin dashboard*
  </Step>
</Steps>

## Features

<CardGroup>
  <Card title="Text Messages" icon="message">
    Send and receive text
  </Card>

  <Card title="Rich Media" icon="image">
    Images, videos, files
  </Card>

  <Card title="Quick Replies" icon="list">
    Suggested response buttons
  </Card>

  <Card title="Templates" icon="file">
    Reusable message templates
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Response Time">
    * Respond quickly (within minutes)
    * Facebook shows "Typically responds in..."
    * Fast responses improve visibility
  </Accordion>

  <Accordion title="Use Page Features">
    * Set greeting message
    * Configure away message
    * Use quick replies
    * Add call-to-action buttons
  </Accordion>

  <Accordion title="Monitor Page Rating">
    * Check page rating regularly
    * Respond to all messages
    * Address negative feedback
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Instagram" icon="instagram" href="/channels/instagram">
    Connect Instagram DMs
  </Card>

  <Card title="Email" icon="envelope" href="/channels/email">
    Add email support
  </Card>
</CardGroup>


# HTTP API
Source: https://docs.heylua.ai/channels/http-api

Consume your Lua agent directly via HTTP requests

## Overview

The HTTP API is the external consumption interface for deployed Lua AI agents. Use it when a custom integration, mobile app, backend service, or other client needs to send a user turn to an agent and receive the response.

<Warning>
  **Calling from Lua code? Do not call these endpoints directly.** Inside a tool, job, webhook, preprocessor, or postprocessor, use [`Agents.invoke`](/api/agents) instead. It runs the same full agent pipeline without a manually managed API URL or bearer token.
</Warning>

| Where the call originates                     | Use                                                  |
| --------------------------------------------- | ---------------------------------------------------- |
| External app, service, device, or integration | `/chat/generate/:agentId` or `/chat/stream/:agentId` |
| Lua runtime code inside an agent primitive    | [`Agents.invoke(targetAgentId, ...)`](/api/agents)   |

<CardGroup>
  <Card title="Stream Endpoint" icon="wave-pulse">
    Real-time streaming responses via SSE
  </Card>

  <Card title="Generate Endpoint" icon="bolt">
    Single response generation
  </Card>
</CardGroup>

## Base URL

```
https://api.heylua.ai
```

## Authentication

All requests require authentication via Bearer token in the Authorization header. You can use your API key as the token:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Tip>
  You can find your API key in the [Admin Dashboard](https://admin.heylua.ai) under **Settings → API Keys**.
</Tip>

<Note>
  A key scoped to a specific organization or agent can only reach the resources its role covers — see [API Keys](/concepts/api-keys) for legacy vs. scoped keys and how roles are granted.
</Note>

***

## Endpoints

### Stream Chat Response

Stream a chat response using Server-Sent Events (SSE).

```
POST /chat/stream/:agentId
```

### Generate Chat Response

Generate a complete chat response (non-streaming).

```
POST /chat/generate/:agentId
```

<Note>
  **PostProcessors:** Only the `/generate` endpoint supports PostProcessors. Streaming responses (`/stream`) bypass post-processing because text is sent incrementally before the full response is available.
</Note>

***

## Path Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `agentId` | string | **Yes**  | The ID of your deployed agent. |

## Query Parameters

| Parameter    | Type   | Required | Description                                                                                                                               |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `channel`    | string | No       | The channel context for the conversation. Options: `web`, `whatsapp`, `email`, `slack`, `facebook`, `instagram`. Defaults to `undefined`. |
| `identifier` | string | No       | A unique identifier for the message. Can be used for tracking purposes.                                                                   |

***

## Request Body

The request body follows the AI SDK 5 `UserContent` format for messages.

### Required Fields

| Field      | Type          | Description                                                                                                   |
| ---------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
| `messages` | `UserContent` | Array of content parts (text, image, or file). This is a single user message that can contain multiple parts. |

### Optional Fields

| Field            | Type   | Description                                                                                                                                                                                                                                                                                                                                                      |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `threadId`       | string | Conversation thread identifier. Turns sharing a `threadId` share history; omit it and the platform uses one default thread per user, agent, and channel. Use a fresh value to start a clean conversation.                                                                                                                                                        |
| `systemPrompt`   | string | Override the agent's default persona/prompt                                                                                                                                                                                                                                                                                                                      |
| `runtimeContext` | string | Additional context injected into the agent's prompt                                                                                                                                                                                                                                                                                                              |
| `clientContext`  | object | Client-side context for the request. Currently supports `timezone` — an IANA timezone string (e.g. `"Africa/Nairobi"`) used as the user's local timezone for date/time-aware responses. When omitted, the agent falls back to the user's stored profile, country, or UTC.                                                                                        |
| `options`        | object | Normalized per-request model options. `options.reasoning` — `{ effort?, show? }` — overrides the agent's `modelSettings.reasoning` for this request (the request always wins, field by field). `options.verbosity` — `'low' \| 'medium' \| 'high'` — requests output verbosity (provider support varies). See [With Reasoning Options](#with-reasoning-options). |

<Accordion title="Advanced Options (rarely needed)">
  These options are for advanced use cases and typically not needed for standard integrations:

  | Field                   | Type    | Description                                                   |
  | ----------------------- | ------- | ------------------------------------------------------------- |
  | `navigate`              | boolean | Enable navigation responses for web widget (default: `false`) |
  | `skillOverride`         | array   | Override the agent's skills with specific sandbox versions    |
  | `personaOverride`       | string  | Override the agent's persona                                  |
  | `preprocessorOverride`  | array   | Override preprocessors                                        |
  | `postprocessorOverride` | array   | Override postprocessors                                       |
</Accordion>

***

## Message Content Types

Messages follow the AI SDK 5 `UserContent` format:

### Text Message

```json theme={null}
{
  "type": "text",
  "text": "Hello, how can you help me today?"
}
```

### Image Message

```json theme={null}
{
  "type": "image",
  "image": "https://example.com/image.jpg",
  "mediaType": "image/jpeg"
}
```

### File Message

```json theme={null}
{
  "type": "file",
  "data": "https://example.com/document.pdf",
  "mediaType": "application/pdf"
}
```

***

## Examples

### Basic Text Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        {
          "type": "text",
          "text": "What products do you have available?"
        }
      ]
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.heylua.ai/chat/generate/my-agent', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [
        {
          type: 'text',
          text: 'What products do you have available?'
        }
      ]
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.heylua.ai/chat/generate/my-agent',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'messages': [
              {
                  'type': 'text',
                  'text': 'What products do you have available?'
              }
          ]
      }
  )

  print(response.json())
  ```
</CodeGroup>

### Streaming Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.heylua.ai/chat/stream/my-agent" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        {
          "type": "text",
          "text": "Tell me about your services"
        }
      ]
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.heylua.ai/chat/stream/my-agent', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [
        {
          type: 'text',
          text: 'Tell me about your services'
        }
      ]
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n\n').filter(line => line.trim());
    
    for (const line of lines) {
      const data = JSON.parse(line);
      console.log(data);
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.heylua.ai/chat/stream/my-agent',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'messages': [
              {
                  'type': 'text',
                  'text': 'Tell me about your services'
              }
          ]
      },
      stream=True
  )

  for line in response.iter_lines():
      if line:
          print(line.decode('utf-8'))
  ```
</CodeGroup>

### With Image Attachment

```bash theme={null}
curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "What can you tell me about this product?"
      },
      {
        "type": "image",
        "image": "https://example.com/product-photo.jpg",
        "mediaType": "image/jpeg"
      }
    ]
  }'
```

### With System Prompt Override

Use `systemPrompt` to temporarily override the agent's persona for a specific request:

```bash theme={null}
curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "Help me with my order"
      }
    ],
    "systemPrompt": "You are a friendly customer support agent. Be concise and helpful."
  }'
```

### With Runtime Context

Use `runtimeContext` to inject additional context into the agent's prompt:

```bash theme={null}
curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "What are my recent orders?"
      }
    ],
    "runtimeContext": "Current user: John Doe (ID: 12345). VIP customer since 2020."
  }'
```

### With Timezone

Use `clientContext.timezone` to tell the agent the user's local IANA timezone for date/time-aware responses. When omitted, the agent falls back to the user's stored profile, country, or UTC:

```bash theme={null}
curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "What time should I schedule my call for tomorrow morning?"
      }
    ],
    "clientContext": {
      "timezone": "Africa/Nairobi"
    }
  }'
```

### With Reasoning Options

Use `options.reasoning` to control how much the model reasons for this specific request. It works on both `/chat/generate` and `/chat/stream`, and overrides the agent's `modelSettings.reasoning` default — the request always wins, field by field (setting only `effort` doesn't clear an agent-level `show: false`):

```bash theme={null}
curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "Walk me through the tradeoffs of these two contract options."
      }
    ],
    "options": {
      "reasoning": { "effort": "high", "show": false }
    }
  }'
```

| Field              | Type                                                         | Description                                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reasoning.effort` | `'off' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'max'` | How much the model reasons before responding. Any value is safe to send for any model — Lua clamps it to the nearest behavior the resolved model supports, never erroring. Unrecognized values are ignored and defaults apply. |
| `reasoning.show`   | boolean                                                      | Whether the reasoning trace is surfaced in the response. Default `true`. `false` suppresses reasoning from both the stream and the generate response.                                                                          |
| `verbosity`        | `'low' \| 'medium' \| 'high'`                                | Requested output verbosity (provider support varies).                                                                                                                                                                          |

<Note>
  Leaving `options.reasoning` unset falls back to the agent's `modelSettings.reasoning`, then to the platform default — adaptive reasoning where the model supports it, low effort otherwise. See [Model Selection → Reasoning Effort](/overview/model-selection#reasoning-effort).
</Note>

### With Channel Context

Specify the channel for channel-specific behavior:

```bash theme={null}
curl -X POST "https://api.heylua.ai/chat/generate/my-agent?channel=whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "Send me the order confirmation"
      }
    ]
  }'
```

***

## Response Format

### Generate Response

The generate endpoint returns a complete response object:

```json theme={null}
{
  "text": "Here are the products we have available...",
  "toolCalls": [],
  "usage": {
    "promptTokens": 150,
    "completionTokens": 200,
    "totalTokens": 350
  }
}
```

### Stream Response

The stream endpoint returns Server-Sent Events (SSE) with JSON chunks:

```
{"type":"text-delta","textDelta":"Here "}

{"type":"text-delta","textDelta":"are "}

{"type":"text-delta","textDelta":"the products..."}

{"type":"finish","finishReason":"stop"}
```

<Note>
  **Reasoning visibility.** The default stream format above never carries the model's reasoning trace. Reasoning is only streamed on the AI SDK UI message stream — opt in with `?protocol=ui` on `/chat/stream`, where it arrives as `reasoning` parts. Setting `reasoning.show: false` (per request via `options.reasoning`, or per agent via `modelSettings.reasoning`) suppresses reasoning everywhere: from the UI message stream and from the generate response.
</Note>

***

## Error Responses

| Status Code | Description                                                                                                                |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `400`       | Invalid request payload                                                                                                    |
| `401`       | Unauthorized - Invalid, expired, suspended, or revoked token                                                               |
| `403`       | Forbidden - Token is valid, but its role doesn't allow this action on this resource                                        |
| `423`       | Agent is disabled for this user                                                                                            |
| `503`       | Lua is restarting before your turn starts. Retry once only when the body matches the typed `CORE_DRAINING` contract below. |
| `500`       | Internal server error                                                                                                      |

**Standard error response format:**

```json theme={null}
{
  "type": "error",
  "message": "Error description",
  "statusCode": 400
}
```

**Typed pre-admission rollout response:**

```json theme={null}
{
  "error": {
    "code": "CORE_DRAINING",
    "message": "Lua is restarting. Please retry your request.",
    "retryable": true
  }
}
```

When you receive this exact `503` response, the turn did not start. Retry once after the `Retry-After` header. If the header is missing, wait about one second.

***

## Long-Running Turns

Turns that run research-grade tools or Space delegations can legitimately take 60–120 seconds. The HTTP edge closes a connection that has produced no output for roughly 90 seconds, so a long `/chat/generate` call — or a `/chat/stream` call during a single long tool execution — can return a `502`/`504` or a terminated stream **even though the turn completes on the platform**. The agent's reply is still generated, persisted to the conversation, and visible to every later turn on the same `threadId`.

Handle it like this:

1. **Prefer `/chat/stream`** for any agent that runs tools. Streamed events extend the window and give you partial progress to show.
2. **Treat an edge cut on a long turn as "likely completed", not failed.** Do not automatically resend the same message. The original turn usually finished, and a resend runs the whole tool chain a second time.
3. **Continue on the same `threadId`.** The completed reply is already in the conversation history; a follow-up message (for example, "show me the result again") returns it without redoing the work.

Do not confuse these edge cuts with the typed `503 CORE_DRAINING` response above. The `CORE_DRAINING` response is the safe retry signal. Raw `502`, `504`, and terminated transport failures are not.

### Safe retry during rollouts

Retry only this case:

1. The status is `503`.
2. The body matches the typed `CORE_DRAINING` response.
3. The response arrives before any stream body or generated output.

Do not retry these cases automatically:

1. Raw `502` or `504`.
2. A terminated or reset stream.
3. Any response that already streamed body data.

```typescript theme={null}
async function sendTurnOnce(run: () => Promise<Response>): Promise<Response> {
  const first = await run();
  if (!(await isCoreDraining(first))) {
    return first;
  }

  const delayMs = retryAfterMs(first.headers.get("retry-after"));
  await first.body?.cancel();
  await new Promise((resolve) => setTimeout(resolve, delayMs));
  return run();
}

async function isCoreDraining(response: Response): Promise<boolean> {
  if (response.status !== 503) return false;
  try {
    const payload = await response.clone().json();
    return (
      payload?.error?.code === "CORE_DRAINING" &&
      payload?.error?.message === "Lua is restarting. Please retry your request." &&
      payload?.error?.retryable === true
    );
  } catch {
    return false;
  }
}

function retryAfterMs(value: string | null): number {
  if (value === null) return 1000;
  const seconds = /^\d+$/.test(value.trim()) ? Number(value) : Number.NaN;
  const delay = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(value) - Date.now();
  return Number.isFinite(delay) ? Math.min(Math.max(0, delay), 5000) : 1000;
}
```

Pass a function that creates a fresh request body for each attempt. Do not reuse a consumed `Request` or `ReadableStream` body.

***

## Navigate Option

<Note>
  The `navigate` option is specifically for web widget integrations. When enabled, it allows the agent to send navigation commands that direct users to specific pages on your website.
</Note>

```json theme={null}
{
  "messages": [{ "type": "text", "text": "Show me pricing" }],
  "navigate": true
}
```

When `navigate` is `true`, the agent can include navigation components in its response that trigger the `onNavigate` callback in the LuaPop widget.

<Card title="Learn More About Navigation" icon="compass" href="/formatting/navigate">
  See the Navigate Component documentation for details on how navigation works with the web widget.
</Card>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use Streaming for Better UX">
    For user-facing applications, use the `/chat/stream` endpoint to provide real-time feedback as the response is generated.
  </Accordion>

  <Accordion title="Include Channel Context">
    When building integrations, specify the `channel` parameter to help the agent format responses appropriately for the platform.
  </Accordion>

  <Accordion title="Use Runtime Context Wisely">
    The `runtimeContext` field is great for injecting user-specific information or session context without modifying the agent's core persona.
  </Accordion>

  <Accordion title="Handle Streaming Properly">
    When using the stream endpoint, ensure you properly handle the SSE format and parse each JSON chunk separately.
  </Accordion>

  <Accordion title="Plan for Long Turns">
    Research- or delegation-heavy turns can run past the edge's \~90-second no-output window and surface as a `502`/`504` while still completing on the platform. See [Long-Running Turns](#long-running-turns) before adding retry logic.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Mobile Apps" icon="mobile">
    Build native mobile experiences with your Lua agent
  </Card>

  <Card title="Custom Integrations" icon="plug">
    Integrate with internal tools and systems
  </Card>

  <Card title="Voice Assistants" icon="microphone">
    Power voice interfaces with AI responses
  </Card>

  <Card title="Automation" icon="robot">
    Trigger agent responses from workflows
  </Card>
</CardGroup>

***

## Related

<CardGroup>
  <Card title="Channels" icon="comments" href="/channels/introduction">
    Pre-built channel integrations
  </Card>

  <Card title="Chat Widget" icon="message" href="/chat-widget/introduction">
    Embeddable web widget
  </Card>

  <Card title="Navigate Component" icon="compass" href="/formatting/navigate">
    Web navigation feature
  </Card>

  <Card title="LuaAgent" icon="robot" href="/api/luaagent">
    Agent configuration
  </Card>
</CardGroup>


# Instagram
Source: https://docs.heylua.ai/channels/instagram

Connect your agent to Instagram Direct Messages

## Overview

Instagram integration allows your agent to respond to Direct Messages sent to your Instagram Business account.

<CardGroup>
  <Card title="Visual Platform" icon="camera">
    Image and video-focused
  </Card>

  <Card title="Young Demographic" icon="users">
    Popular with Gen Z and Millennials
  </Card>

  <Card title="DMs & Story Replies" icon="message">
    Respond to messages and story interactions
  </Card>

  <Card title="Business Account" icon="building">
    Professional presence
  </Card>
</CardGroup>

## Prerequisites

<Info>
  Meta updates Instagram and its developer tools frequently. The steps below describe what you need; for exact, up-to-date screens, see Meta's [Instagram Platform documentation](https://developers.facebook.com/docs/instagram-platform).
</Info>

<Steps>
  <Step title="Instagram Professional Account">
    Convert your Instagram account to a Professional (Business or Creator) account.
  </Step>

  <Step title="Link to a Facebook Page">
    Connect your Instagram account to a Facebook Business Page.
  </Step>

  <Step title="Enable Messaging">
    Allow message access so your agent can receive DMs (in Instagram: **Settings → Messages and story replies → Connected tools → Allow access to messages**).
  </Step>
</Steps>

## Connection Method: Admin Dashboard Only

<Warning>
  **Instagram connection is only available through the admin dashboard** due to OAuth requirements and Meta's authentication flow.
</Warning>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent">
    Click **Agents** in the main side navigation, then select your agent's card.
  </Step>

  <Step title="Add a channel">
    Click the **+** (plus) icon to add a channel, then choose **Instagram**.

    <Frame>
      <img alt="Add a channel" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the channel options*
  </Step>

  <Step title="Accept terms & connect">
    Tick the box to accept the **Terms of Service** and **Privacy Policy**, then click **Connect**.
  </Step>

  <Step title="Authorize with Instagram">
    A login popup opens. Log in with the account that manages your Instagram Professional account, grant the messaging permissions requested, and select the Instagram account to connect. When the popup closes, the channel is connected.

    <Note>
      This popup is Meta's own UI and changes periodically. See Meta's [Instagram Platform documentation](https://developers.facebook.com/docs/instagram-platform) if you get stuck.
    </Note>
  </Step>

  <Step title="Connection success">
    Instagram appears in your connected channels and is ready to receive DMs.
  </Step>
</Steps>

## Testing Your Instagram Channel

<Steps>
  <Step title="Send a DM to your account">
    From another Instagram account, send a DM to your business account (for example, "Hi!").
  </Step>

  <Step title="Agent responds">
    Your agent replies automatically in the Instagram DM thread.
  </Step>

  <Step title="View in admin">
    Monitor the conversation in the admin dashboard.

    <Frame>
      <img alt="Admin conversation" />
    </Frame>

    *Screenshot: The conversation in the admin dashboard*
  </Step>
</Steps>

## Features

<CardGroup>
  <Card title="Direct Messages" icon="message">
    Respond to DMs automatically
  </Card>

  <Card title="Story Replies" icon="reply">
    Reply to story mentions
  </Card>

  <Card title="Rich Media" icon="image">
    Send images, videos
  </Card>

  <Card title="Quick Replies" icon="bolt">
    Suggested response buttons
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Visual Content">
    Instagram is visual - use:

    * Product images
    * Demo videos
    * Infographics
    * Visual guides
  </Accordion>

  <Accordion title="Casual Tone">
    Instagram users expect:

    * Friendly, casual communication
    * Emojis and personality
    * Quick, concise responses
    * Less formal than email
  </Accordion>

  <Accordion title="Response Time">
    * Respond within minutes if possible
    * Instagram shows response time publicly
    * Fast responses improve visibility
  </Accordion>

  <Accordion title="Monitor Engagement">
    ```bash theme={null}
    lua admin
    # Check Instagram engagement metrics
    # Track response rates
    # Monitor user satisfaction
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth fails">
    **Check:**

    * Instagram account is Business type
    * Linked to Facebook Page
    * Permissions granted
    * Pop-up blocker disabled
  </Accordion>

  <Accordion title="Messages not responding">
    **Check:**

    * Channel status in admin (CONNECTED)
    * Instagram messaging is enabled
    * Account not restricted
    * Test with simple message
  </Accordion>

  <Accordion title="Can't find Business account">
    **Ensure:**

    * Account is converted to Business
    * Linked to Facebook Page
    * Page has admin access
    * Try disconnecting and reconnecting
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Slack" icon="slack" href="/channels/slack">
    Connect team workspace
  </Card>

  <Card title="Admin Dashboard" icon="gauge" href="/channels/admin-dashboard">
    Manage all channels visually
  </Card>
</CardGroup>


# Channels Overview
Source: https://docs.heylua.ai/channels/introduction

Connect your agent to WhatsApp, Facebook, Email, Slack, and more

## What are Channels?

**Channels** are the communication platforms where users interact with your AI agent. They're the "front doors" that connect your users to your agent's capabilities.

## Currently Supported Channels (7+)

<CardGroup>
  <Card title="Email" icon="envelope">
    Professional communication
  </Card>

  <Card title="WebChat (LuaPop)" icon="globe">
    Website chat widget
  </Card>

  <Card title="Facebook Messenger" icon="facebook">
    Page messages
  </Card>

  <Card title="Instagram Messenger" icon="instagram">
    Direct messages
  </Card>

  <Card title="WhatsApp" icon="whatsapp">
    Business messaging
  </Card>

  <Card title="Slack" icon="slack">
    Workspace integration
  </Card>

  <Card title="Microsoft Teams" icon="microsoft">
    Business communication
  </Card>

  <Card title="HTTP API" icon="code">
    Direct programmatic access
  </Card>
</CardGroup>

<Note>
  **🚀 More channels coming soon!** SMS, Discord, Telegram, LinkedIn, and WeChat are in active development. Want a specific channel? Let us know at [support@heylua.ai](mailto:support@heylua.ai)
</Note>

<Note>
  **Channels are two-way.** Your agent doesn't only respond to inbound messages — it can **initiate** them. Send notifications, reminders, and follow-ups from tools, jobs, and webhooks with the [Channels API](/api/channels). See [Proactive Messaging](/channels/proactive-messaging) for the model and per-channel rules.
</Note>

## How Channels Work

<Steps>
  <Step title="User Sends Message">
    Customer messages your business on WhatsApp, Facebook, Email, etc.
  </Step>

  <Step title="Channel Forwards to Lua">
    The channel forwards the message to your Lua agent
  </Step>

  <Step title="Agent Processes">
    Your agent understands the message and determines response
  </Step>

  <Step title="Agent Uses Tools">
    Agent calls your tools to take actions (search products, check orders, etc.)
  </Step>

  <Step title="Response Sent Back">
    Agent's response is sent back through the same channel
  </Step>

  <Step title="User Receives Reply">
    Customer gets response on their preferred platform
  </Step>
</Steps>

## Multi-Channel Benefits

<CardGroup>
  <Card title="Meet Users Anywhere" icon="location-dot">
    Users on WhatsApp, Facebook, Email - all talk to same agent
  </Card>

  <Card title="Consistent Experience" icon="equals">
    Same capabilities and personality across all platforms
  </Card>

  <Card title="Centralized Management" icon="grip">
    Manage all channels from one place
  </Card>

  <Card title="Unified Analytics" icon="chart-line">
    Track conversations across all channels together
  </Card>
</CardGroup>

## Available Channels

<Tabs>
  <Tab title="Messaging">
    ### WhatsApp Business

    * Business messaging at scale
    * Rich media support
    * High engagement rates
    * Popular in many regions

    <Card title="Setup Guide" href="/channels/whatsapp" />

    ### Facebook Messenger

    * Facebook Page messaging
    * Reach Facebook users
    * Integrated with social
    * Rich content support

    <Card title="Setup Guide" href="/channels/facebook-messenger" />

    ### Instagram

    * Direct messages
    * Story replies
    * Visual platform
    * Young demographic

    <Card title="Setup Guide" href="/channels/instagram" />
  </Tab>

  <Tab title="Business">
    ### Email

    * Professional communication
    * B2B friendly
    * Universal platform
    * Formal inquiries

    <Card title="Setup Guide" href="/channels/email" />

    ### Slack

    * Team collaboration
    * Internal use
    * Developer friendly
    * Real-time messaging

    <Card title="Setup Guide" href="/channels/slack" />

    ### Microsoft Teams

    * Business communication
    * Built for Microsoft 365 orgs
    * Chats and channel @mentions
    * Quick start or bring your own bot

    <Card title="Setup Guide" href="/channels/teams" />
  </Tab>

  <Tab title="Web">
    ### Website Chat Widget

    * Embed on website
    * Customizable design
    * Voice chat support
    * Analytics built-in

    <Card title="Setup Guide" href="/channels/website-widget" />
  </Tab>
</Tabs>

## Two Ways to Connect

<Tabs>
  <Tab title="CLI Command">
    **Quick terminal-based setup**

    ```bash theme={null}
    lua channels
    ```

    **Supported:**

    * ✅ WhatsApp
    * ✅ Facebook Messenger
    * ✅ Email
    * ✅ Slack (Private & Public)

    **Best for:**

    * Developers
    * Terminal workflow
    * Automated setup
    * Scripting

    <Card title="CLI Guide" href="/channels/cli-management" />
  </Tab>

  <Tab title="Admin Dashboard">
    **Visual web interface**

    ```bash theme={null}
    lua admin
    # Or visit: https://admin.heylua.ai
    ```

    **Supported:**

    * ✅ All channels
    * ✅ Instagram (OAuth)
    * ✅ SMS/Twilio
    * ✅ Analytics
    * ✅ Monitoring

    **Best for:**

    * All users
    * OAuth flows
    * Visual management
    * Team collaboration

    <Card title="Dashboard Guide" href="/channels/admin-dashboard" />
  </Tab>
</Tabs>

## Channel Selection Guide

### For E-commerce

* ✅ **WhatsApp** - High engagement
* ✅ **Instagram** - Visual products
* ✅ **Facebook** - Social shoppers
* ✅ **Website Widget** - On-site support

### For B2B/SaaS

* ✅ **Email** - Professional
* ✅ **Slack** - Team integration
* ✅ **Website Widget** - Product support

### For Customer Support

* ✅ **Email** - Ticket system
* ✅ **WhatsApp** - Quick responses
* ✅ **Website Widget** - Live help
* ✅ **Facebook** - Social support

### For Internal Use

* ✅ **Slack** - Team collaboration
* ✅ **Microsoft Teams** - Team collaboration
* ✅ **Email** - Company communication

## Quick Start

<Steps>
  <Step title="Deploy Your Agent">
    ```bash theme={null}
    lua push
    lua deploy
    ```
  </Step>

  <Step title="Choose Channel">
    Pick where your users are
  </Step>

  <Step title="Connect Channel">
    Use CLI or admin dashboard
  </Step>

  <Step title="Test">
    Send message on that platform
  </Step>

  <Step title="Go Live">
    Users can now reach your agent!
  </Step>
</Steps>

## Explore Channels

<CardGroup>
  <Card title="WhatsApp Business" icon="whatsapp" href="/channels/whatsapp">
    Set up WhatsApp messaging
  </Card>

  <Card title="Facebook Messenger" icon="facebook" href="/channels/facebook-messenger">
    Connect Facebook Page
  </Card>

  <Card title="Instagram" icon="instagram" href="/channels/instagram">
    Instagram DMs
  </Card>

  <Card title="Email" icon="envelope" href="/channels/email">
    Email integration
  </Card>

  <Card title="Slack" icon="slack" href="/channels/slack">
    Workspace integration
  </Card>

  <Card title="Microsoft Teams" icon="microsoft" href="/channels/teams">
    Business communication
  </Card>

  <Card title="Website Widget" icon="globe" href="/channels/website-widget">
    Embed on website
  </Card>

  <Card title="HTTP API" icon="code" href="/channels/http-api">
    Direct programmatic access
  </Card>
</CardGroup>

## Coming Soon 🚀

We're actively adding support for more channels:

<CardGroup>
  <Card title="SMS/Twilio" icon="message">
    Text messaging
  </Card>

  <Card title="Discord" icon="discord">
    Community platform
  </Card>

  <Card title="Telegram" icon="telegram">
    Secure messaging
  </Card>

  <Card title="LinkedIn" icon="linkedin">
    Professional network
  </Card>

  <Card title="WeChat" icon="weixin">
    Chinese market
  </Card>
</CardGroup>

<Note>
  Want a specific channel? Let us know at [support@heylua.ai](mailto:support@heylua.ai)
</Note>

<CardGroup>
  <Card title="CLI Management" icon="terminal" href="/channels/cli-management">
    Terminal-based setup
  </Card>

  <Card title="Admin Dashboard" icon="gauge" href="/channels/admin-dashboard">
    Visual management
  </Card>
</CardGroup>


# Proactive Messaging
Source: https://docs.heylua.ai/channels/proactive-messaging

Reach out first — how agent-initiated messages work across channels

## Channels are two-way

Your agent doesn't only reply — it can **initiate**. A scheduled job can send a reminder, a webhook can confirm a payment, a tool can follow up hours later. Outbound messages flow through the [Channels API](/api/channels), and every one is recorded to the recipient's conversation thread so your agent stays coherent across the whole exchange.

```typescript theme={null}
import { Channels } from 'lua-cli';

await Channels.send({
  channel: 'whatsapp',
  to: { userId: 'user_123' },
  text: "Your appointment is confirmed for tomorrow at 3pm."
});
```

## How continuity works

There's no durable "wait for reply" machinery to manage. The model is simple:

1. Your agent **sends** a message (from a tool, job, webhook, or trigger). The message is recorded to the recipient's thread.
2. Hours or days later, the user **replies** on that channel.
3. The reply wakes your agent with the **same thread loaded** — it sees the message it sent and continues naturally.

<Note>
  A user is identified by their Lua `userId`, and one user ↔ agent pair shares one conversation thread. Send on WhatsApp, get a reply on WhatsApp — the agent has the full history either way. You don't manage sessions or state machines for this; the thread is the memory.
</Note>

## Three ways to send

Pick the one that matches what you have and where you want the message to go.

<CardGroup>
  <Card title="Channels.send(...) — pick the channel explicitly" icon="paper-plane">
    Choose exactly which channel and recipient. Works from any context, can reach **cold** recipients (a phone number or email with no prior conversation), and records to the thread. This is the general-purpose proactive send.
  </Card>

  <Card title="user.send(...) — reach the user you already have" icon="user">
    If you've already loaded a [`User`](/api/user) instance, `user.send([...])` delivers to that user's active conversation. Simplest when you just want to message the user you're working with, on the channel they're already on.
  </Card>

  <Card title="Templates.whatsapp.send(...) — bulk template send" icon="whatsapp">
    Send an approved WhatsApp template to one or many phone numbers by channel ID. Best for campaigns and batch notifications. See the [Templates API](/api/templates).
  </Card>
</CardGroup>

### Which should I use?

| You want to…                                                      | Use                                                                               |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Message the current user, on the channel they're on               | [`user.send([...])`](/api/user#send)                                              |
| Choose a specific channel (e.g. always WhatsApp) for a known user | [`Channels.send`](/api/channels#channels-send) with `to.userId`                   |
| Reach a phone/email with no prior conversation                    | [`Channels.send`](/api/channels#channels-send) with `to.phoneNumber` / `to.email` |
| Start or re-open a WhatsApp conversation (window closed)          | [`Channels.whatsapp.sendTemplate`](/api/channels#channels-whatsapp-sendtemplate)  |
| Blast an approved template to many numbers                        | [`Templates.whatsapp.send`](/api/templates#send)                                  |
| React to a specific WhatsApp message with an emoji                | [`Channels.whatsapp.sendReaction`](/api/channels#channels-whatsapp-sendreaction)  |

## The WhatsApp 24-hour window

WhatsApp only allows **free-form** business messages within **24 hours** of the user's last inbound message. This is a Meta rule, not a Lua one — and it shapes how proactive WhatsApp sends behave.

* **Window open** (user messaged within 24h) → `Channels.send({ channel: 'whatsapp', ... })` delivers immediately (`delivered: true`).
* **Window closed** → free-form isn't allowed. Two options:
  * **Send an approved template** with [`Channels.whatsapp.sendTemplate`](/api/channels#channels-whatsapp-sendtemplate). Templates are allowed any time and are how you start or re-open a conversation.
  * **Let `Channels.send` queue it** (the default). The message is held, the recipient is shown a short opt-in prompt, and the queued text is delivered once they re-engage. The call returns `queued: true` (not yet `delivered`).

```typescript theme={null}
// Default: queue if the window is closed
const result = await Channels.send({
  channel: 'whatsapp',
  to: { userId: 'user_123' },
  text: 'Following up on your request.'
});

if (result.queued) {
  // Held until the user re-engages; not delivered yet
}

// Or fail fast and fall back to a template yourself
try {
  await Channels.send({
    channel: 'whatsapp',
    to: { userId: 'user_123' },
    text: 'Following up on your request.',
    options: { whatsapp: { onClosedWindow: 'fail' } }
  });
} catch {
  await Channels.whatsapp.sendTemplate({
    to: { userId: 'user_123' },
    templateName: 'follow_up',
    languageCode: 'en_US',
    messageContext: 'Followed up on the customer’s open request'
  });
}
```

<Warning>
  You **cannot** send a free-form WhatsApp message to someone who has never messaged your agent, or whose window has closed. The honest cold-start path is an approved template. Plan template content for any outreach that might land outside the window.
</Warning>

<Note>
  **US (+1) recipients:** the opt-in prompt used by the queue path is a marketing-category template, which Meta may not deliver to US numbers. For reliable US outreach outside the window, send an approved utility template directly with `Channels.whatsapp.sendTemplate`.
</Note>

## Per-channel constraints

Windows and policies differ by channel:

| Channel                           | Proactive send                       | Constraint                                                                                             |
| --------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **WhatsApp**                      | Free-form (in-window) or template    | 24-hour window; templates required outside it                                                          |
| **SMS**                           | Free-form any time                   | No window, but subject to carrier opt-out (STOP/HELP/START) and regional rules                         |
| **Email**                         | Free-form any time                   | No window                                                                                              |
| **Web chat**                      | Free-form to a known user            | Delivered to the user's web widget                                                                     |
| **Teams / Instagram / Messenger** | Free-form to a known user            | **Warm-only** — the user must have an existing conversation with your agent                            |
| **Teams (group)**                 | Free-form to a group chat or channel | **Warm-only** — address it with `to: { conversationId }`; the bot must already be in that conversation |

See [Channel Capabilities](/channels/channel-capabilities) for the full matrix, sender resolution, and compliance details.

## Scheduled outbound

There's no separate "campaign" primitive — scheduled outreach is just a [job](/api/luajob) that calls `Channels.send`:

```typescript theme={null}
import { LuaJob, Channels } from 'lua-cli';

const reminders = new LuaJob({
  name: 'appointment-reminders',
  description: 'Send next-day appointment reminders every morning',
  schedule: {
    type: 'cron',
    expression: '0 9 * * *' // every day at 9 AM
  },
  execute: async () => {
    const due = await getTomorrowsAppointments();
    for (const appt of due) {
      await Channels.send({
        channel: 'whatsapp',
        to: { userId: appt.userId },
        text: `Reminder: your appointment is tomorrow at ${appt.time}.`
      });
    }
  }
});

export default reminders;
```

See the [Proactive Send recipe](/examples/proactive-send) for a complete walkthrough.

## Components in proactive messages

Proactive messages support the same [response formatting components](/formatting/introduction) (the `:::` blocks) as inline replies — lists, links, images, actions — on channels that render them. The web chat widget renders the full component set; messaging channels render what their platform supports (text, media), and fall back to text otherwise.

To react to a specific message rather than send new text, call [`Channels.whatsapp.sendReaction`](/api/channels#channels-whatsapp-sendreaction) directly with the target message's ID — useful from a job or webhook, outside the context of a normal reply.

## Next steps

<CardGroup>
  <Card title="Channels API" icon="paper-plane" href="/api/channels">
    Full reference for send, sendTemplate, sendReaction, and email.send
  </Card>

  <Card title="Channel Capabilities" icon="table-list" href="/channels/channel-capabilities">
    Per-channel limits and sender resolution
  </Card>

  <Card title="Proactive Send Recipe" icon="clock" href="/examples/proactive-send">
    Schedule outreach with defineJob + Channels.send
  </Card>

  <Card title="Jobs API" icon="calendar" href="/api/jobs">
    Schedule recurring and one-off work
  </Card>
</CardGroup>


# Quick Testing Channels
Source: https://docs.heylua.ai/channels/quick-testing

Test your agent on existing Lua channels without setup

## Overview

During development, you can test your newly created agent on **existing Lua channels** without setting up your own integrations. This is perfect for quick testing and validation before deploying to your own channels.

<Note>
  **Quick Testing Only:** These channels are for development and testing. For production, you'll want to set up your own dedicated channels.
</Note>

<CardGroup>
  <Card title="Instant Testing" icon="bolt">
    No channel setup required - start testing immediately
  </Card>

  <Card title="All Platforms" icon="grid">
    Test on WhatsApp, Facebook, Instagram, Email, and Slack
  </Card>

  <Card title="Real Environment" icon="check">
    Test exactly how your agent will behave in production
  </Card>

  <Card title="Easy Switch" icon="arrows-rotate">
    Link and unlink agents anytime during development
  </Card>
</CardGroup>

## How to Link Your Agent

Each channel uses a special "link" command with your agent ID. Find your agent ID in your `lua.skill.yaml` file:

```yaml theme={null}
agent:
  agentId: agent_abc123xyz456  # ← Your agent ID
```

***

## WhatsApp Testing

**Instant link via WhatsApp:**

<Steps>
  <Step title="Get Your Link">
    Replace `agentId` with your actual agent ID from `lua.skill.yaml`:

    **Format:**

    ```
    https://wa.me/13023778932?text=link-me-to:agentId
    ```

    **Example with agent ID:**

    ```
    https://wa.me/13023778932?text=link-me-to:agent_abc123xyz456
    ```

    <Card title="📱 Click to Open WhatsApp" icon="whatsapp" href="https://wa.me/13023778932?text=link-me-to:YOUR_AGENT_ID">
      Replace YOUR\_AGENT\_ID in the URL with your actual agent ID before clicking
    </Card>
  </Step>

  <Step title="Send Message">
    The message will be pre-filled with your link command. Just tap Send!
  </Step>

  <Step title="Start Testing">
    Your agent is now linked. Start chatting to test your agent!
  </Step>
</Steps>

***

## Facebook Messenger Testing

<Steps>
  <Step title="Copy Link Command">
    Copy this text and replace `agentId` with yours:

    ```
    link-me-to:agentId
    ```

    **Example:**

    ```
    link-me-to:agent_abc123xyz456
    ```
  </Step>

  <Step title="Open Messenger">
    Click to open the Lua Facebook page:

    <Card title="💬 Open Facebook Messenger" icon="facebook" href="https://m.me/61569665392939">
      Click to start conversation with Lua on Messenger
    </Card>
  </Step>

  <Step title="Send Link Command">
    Paste and send the exact message you copied in Step 1
  </Step>

  <Step title="Confirmation">
    You'll receive confirmation that your agent is linked
  </Step>

  <Step title="Start Testing">
    Now chat with your agent through Facebook Messenger!
  </Step>
</Steps>

***

## Instagram Testing

<Steps>
  <Step title="Copy Link Command">
    Copy this text and replace `agentId` with yours:

    ```
    link-me-to:agentId
    ```

    **Example:**

    ```
    link-me-to:agent_abc123xyz456
    ```
  </Step>

  <Step title="Open Instagram DM">
    Click to open the Lua Instagram account:

    <Card title="📸 Open Instagram Messages" icon="instagram" href="https://ig.me/m/heylua.ai">
      Click to message @heylua.ai on Instagram
    </Card>
  </Step>

  <Step title="Send Link Command">
    Paste and send the exact message you copied in Step 1
  </Step>

  <Step title="Start Testing">
    Your agent is linked! Test through Instagram DMs
  </Step>
</Steps>

***

## Email Testing

<Steps>
  <Step title="Copy Link Command">
    Copy this text and replace `agentId` with yours:

    ```
    link-me-to:agentId
    ```

    **Example:**

    ```
    link-me-to:agent_abc123xyz456
    ```
  </Step>

  <Step title="Compose Email">
    Click to open your email client:

    <Card title="✉️ Send Email to chat@heylua.ai" icon="envelope" href="mailto:chat@heylua.ai?subject=Link%20Agent&body=link-me-to:YOUR_AGENT_ID">
      Click to compose email (replace YOUR\_AGENT\_ID in the body)
    </Card>
  </Step>

  <Step title="Send Link Command">
    Replace YOUR\_AGENT\_ID in the email body with your actual agent ID and send
  </Step>

  <Step title="Start Testing">
    Reply to the confirmation email to start testing your agent via email
  </Step>
</Steps>

***

## Slack Testing

<Steps>
  <Step title="Install Lua App">
    First, add the Lua app to your Slack workspace:

    <Card title="🔗 Install Lua on Slack" icon="slack" href="https://slack.com/oauth/v2/authorize?client_id=8037381401492.9620618924578&scope=channels:history,channels:read,chat:write,commands,groups:history,groups:read,im:history,im:read,im:write,mpim:history,mpim:read,users:read,app_mentions:read,users:read.email,files:read&user_scope=">
      Click to authorize Lua app in your Slack workspace
    </Card>
  </Step>

  <Step title="Copy Link Command">
    Copy this text and replace `agentId` with yours:

    ```
    link-me-to:agentId
    ```

    **Example:**

    ```
    link-me-to:agent_abc123xyz456
    ```
  </Step>

  <Step title="DM Lua App">
    In Slack, find the "Lua" app in your workspace and send it a direct message with your link command
  </Step>

  <Step title="Start Testing">
    Your agent is linked! Continue chatting in the Slack DM to test
  </Step>
</Steps>

***

## Finding Your Agent ID

Your agent ID is in your `lua.skill.yaml` file:

```yaml theme={null}
agent:
  agentId: agent_abc123xyz456  # ← Copy this
  orgId: org_xyz789
```

Or run this command in your project directory:

```bash theme={null}
# View your agent configuration
lua production

# Or check the YAML file
cat lua.skill.yaml | grep agentId
```

***

## Testing Workflow

<Steps>
  <Step title="Link Agent">
    Use one of the methods above to link your agent to a test channel
  </Step>

  <Step title="Make Changes">
    Edit your tools, skills, or persona locally
  </Step>

  <Step title="Push Changes">
    ```bash theme={null}
    lua push
    ```
  </Step>

  <Step title="Test on Channel">
    Chat with your agent on the linked channel to test changes
  </Step>

  <Step title="Iterate">
    Repeat steps 2-4 until satisfied
  </Step>
</Steps>

***

## Unlinking Your Agent

To stop testing on a channel, send:

```
unlink-me
```

This removes the agent link from that channel.

***

## When to Use Test Channels vs Your Own

<Tabs>
  <Tab title="Use Test Channels For">
    ✅ **Quick development testing**

    * Testing during active development
    * Validating changes before production
    * Trying new features
    * Debugging issues

    ✅ **When you don't have channels yet**

    * Early development phase
    * Proof of concept
    * Learning the platform
  </Tab>

  <Tab title="Use Your Own Channels For">
    ✅ **Production deployment**

    * Customer-facing agents
    * Official business communications
    * Branded experience

    ✅ **Professional testing**

    * User acceptance testing
    * Team demonstrations
    * Client demos

    ✅ **Full control**

    * Custom branding
    * Analytics integration
    * Compliance requirements
  </Tab>
</Tabs>

***

## Setting Up Your Own Channels

When ready for production, set up your own channels:

<CardGroup>
  <Card title="WhatsApp Setup" icon="whatsapp" href="/channels/whatsapp">
    Connect your own WhatsApp Business account
  </Card>

  <Card title="Facebook Setup" icon="facebook" href="/channels/facebook-messenger">
    Connect your Facebook page
  </Card>

  <Card title="Instagram Setup" icon="instagram" href="/channels/instagram">
    Connect your Instagram business account
  </Card>

  <Card title="Email Setup" icon="envelope" href="/channels/email">
    Set up your custom email channel
  </Card>

  <Card title="Slack Setup" icon="slack" href="/channels/slack">
    Install on your Slack workspace
  </Card>

  <Card title="Website Widget" icon="comments" href="/chat-widget/quick-start">
    Add chat widget to your website
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Link command not working">
    **Make sure:**

    * You're using the exact format: `link-me-to:agentId`
    * No spaces in the command
    * Agent ID is correct (check `lua.skill.yaml`)
    * You've deployed your agent with `lua push`
  </Accordion>

  <Accordion title="Agent not responding">
    **Check:**

    * Agent is deployed: `lua push && lua deploy`
    * Skills are compiled: `lua compile`
    * No errors in logs: `lua logs`
    * Agent has at least one skill with tools
  </Accordion>

  <Accordion title="Wrong agent responding">
    **Solution:**

    * Send `unlink-me` to unlink current agent
    * Send new `link-me-to:agentId` with correct ID
  </Accordion>

  <Accordion title="Changes not appearing">
    **Make sure to:**

    1. Save your code changes
    2. Run `lua push` to upload
    3. Run `lua deploy` if needed
    4. Test may need a fresh conversation (some platforms cache)
  </Accordion>
</AccordionGroup>

***

## Quick Reference

### Link Commands by Channel

| Channel       | Link / Instructions                                                                                                                                                                                                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **WhatsApp**  | [Open WhatsApp](https://wa.me/13023778932?text=link-me-to:YOUR_AGENT_ID) → Replace YOUR\_AGENT\_ID                                                                                                                                                                                                                                |
| **Facebook**  | [Open Messenger](https://m.me/61569665392939) → Send `link-me-to:agentId`                                                                                                                                                                                                                                                         |
| **Instagram** | [Open Instagram DM](https://ig.me/m/heylua.ai) → Send `link-me-to:agentId`                                                                                                                                                                                                                                                        |
| **Email**     | [Compose Email](mailto:chat@heylua.ai?subject=Link%20Agent\&body=link-me-to:YOUR_AGENT_ID) → Replace YOUR\_AGENT\_ID                                                                                                                                                                                                              |
| **Slack**     | [Install App](https://slack.com/oauth/v2/authorize?client_id=8037381401492.9620618924578\&scope=channels:history,channels:read,chat:write,commands,groups:history,groups:read,im:history,im:read,im:write,mpim:history,mpim:read,users:read,app_mentions:read,users:read.email,files:read\&user_scope=) → DM `link-me-to:agentId` |

### Unlink

Send `unlink-me` on any channel to disconnect your agent.

***

## All Testing Channels

<CardGroup>
  <Card title="WhatsApp Testing" icon="whatsapp" href="https://wa.me/13023778932?text=link-me-to:YOUR_AGENT_ID">
    Click to open (replace YOUR\_AGENT\_ID in URL)
  </Card>

  <Card title="Facebook Messenger" icon="facebook" href="https://m.me/61569665392939">
    Click to open, then send link command
  </Card>

  <Card title="Instagram DM" icon="instagram" href="https://ig.me/m/heylua.ai">
    Click to open, then send link command
  </Card>

  <Card title="Email Channel" icon="envelope" href="mailto:chat@heylua.ai?subject=Link%20Agent&body=link-me-to:YOUR_AGENT_ID">
    Click to compose (replace YOUR\_AGENT\_ID)
  </Card>

  <Card title="Slack Installation" icon="slack" href="https://slack.com/oauth/v2/authorize?client_id=8037381401492.9620618924578&scope=channels:history,channels:read,chat:write,commands,groups:history,groups:read,im:history,im:read,im:write,mpim:history,mpim:read,users:read,app_mentions:read,users:read.email,files:read&user_scope=">
    Click to install Lua app on Slack
  </Card>

  <Card title="Terminal Testing" icon="terminal" href="/cli/chat-command">
    Use `lua chat` for command-line testing
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Test Your Agent" icon="vial" href="/cli/chat-command">
    Use `lua chat` for local testing first
  </Card>

  <Card title="Set Up Your Channels" icon="plug" href="/channels/introduction">
    Connect your own channels for production
  </Card>

  <Card title="Deploy to Production" icon="rocket" href="/cli/skill-management">
    Learn the deployment process
  </Card>

  <Card title="Monitor Your Agent" icon="chart-line" href="/cli/logs-command">
    View logs and performance
  </Card>
</CardGroup>


# Slack
Source: https://docs.heylua.ai/channels/slack

Connect your agent to Slack workspaces

## Overview

Slack integration allows your agent to participate in workspace conversations - perfect for internal teams or community support.

<CardGroup>
  <Card title="Team Collaboration" icon="users">
    Internal communication
  </Card>

  <Card title="Real-Time" icon="bolt">
    Instant messaging
  </Card>

  <Card title="Developer Friendly" icon="code">
    Popular with tech teams
  </Card>

  <Card title="Two Types" icon="list">
    Private Bot or Public App
  </Card>
</CardGroup>

## Two integration types

Slack supports two connection styles. The admin dashboard wizard walks you through either one and **generates the Slack app manifest for you**, so you don't have to configure scopes and event subscriptions by hand.

<Tabs>
  <Tab title="Private (bot token)">
    **Just your workspace**

    * Single workspace
    * Authenticates with a bot token (`xoxb-...`)
    * Simplest option for internal team use

    Available in the dashboard and CLI.
  </Tab>

  <Tab title="Public (distributable app)">
    **A distributable app**

    * Installable by other workspaces
    * Authenticates with App ID, Client ID and Client Secret
    * For distributing your agent beyond your own workspace

    Available in the dashboard.
  </Tab>
</Tabs>

## Connection Method 1: Admin Dashboard (Recommended)

<Info>
  The dashboard provides a guided wizard and **generates a ready-to-paste Slack app manifest** after you connect, so you don't configure scopes, event subscriptions, or interactivity by hand.
</Info>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent and add a channel">
    Click **Agents** in the main side navigation, select your agent's card, click the **+** (plus) icon to add a channel, then choose **Slack**.

    <Frame>
      <img alt="Add a channel" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the channel options*
  </Step>

  <Step title="Choose how to connect">
    Pick the connection type:

    * **Private — just my workspace**: use a bot token from a Slack app you control. Simplest if you only need the agent inside your own workspace.
    * **Public — a distributable app**: build a Slack app other organizations can install.

    Not sure? Start with **Private** — you can always add a public app later.

    <Frame>
      <img alt="Choose Slack connection type" />
    </Frame>

    *Screenshot: The "Connect to Slack" step with the Private and Public choices*
  </Step>

  <Step title="Create your Slack app">
    If you don't already have one, the wizard walks you through creating it at [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**. Give it any name and pick your workspace.

    <Tabs>
      <Tab title="Private (bot token)">
        1. In your app, open **OAuth & Permissions** and add the [bot token scopes](#required-bot-scopes) your agent needs.
        2. Click **Install to Workspace** and approve the permissions.
        3. Copy the **Bot User OAuth Token** — it starts with `xoxb-`.

        Treat the bot token like a password — anyone with it can act as your bot.
      </Tab>

      <Tab title="Public (app credentials)">
        1. Open **Basic Information → App Credentials**.
        2. Copy your **App ID**, **Client ID**, and **Client Secret** (click **Show** to reveal the secret).

        You don't need to set up scopes, redirect URLs, or event subscriptions yet — Lua generates a manifest for that after you connect.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enter your credentials">
    Paste your details into the wizard and click **Connect**.

    * **Private**: your bot token (`xoxb-...`).
    * **Public**: App ID, Client ID, and Client Secret.

    <Frame>
      <img alt="Enter Slack credentials" />
    </Frame>

    *Screenshot: The credentials step (bot token, or App ID / Client ID / Client Secret)*
  </Step>

  <Step title="Finish in Slack (apply the manifest)">
    After connecting, Lua shows a generated **app manifest**. Copy it, then in Slack open **App Manifest**, switch to the **JSON** tab, paste it in, and click **Save Changes**. This sets up the permissions and event subscriptions your agent needs.

    <Frame>
      <img alt="Apply Slack manifest" />
    </Frame>

    *Screenshot: The "finish in Slack" dialog with the generated manifest*

    <Warning>
      **Public apps:** use the **Add to Slack** button in the dialog to install. Don't use Slack's green **Install to Workspace** button on the Install App page — it creates a token inside Slack but never finishes the connection to Lua.
    </Warning>
  </Step>

  <Step title="Start chatting">
    DM your bot in Slack, or **@mention** it in a channel it's been invited to, and your agent will reply.
  </Step>
</Steps>

## Required bot scopes

Add these **Bot Token Scopes** under **OAuth & Permissions**. The dashboard manifest includes them automatically; you only add them by hand for the private bot or CLI paths.

* `chat:write` — Send messages
* `channels:history` — Read public channel messages
* `groups:history` — Read private channel messages
* `im:history` — Read direct messages
* `mpim:history` — Read group direct messages
* `channels:read` — List public channels
* `groups:read` — List private channels
* `im:read` — List direct messages
* `mpim:read` — List group direct messages
* `users:read` — View user information
* `users:read.email` — View user emails
* `app_mentions:read` — Detect @mentions
* `files:read` — Access uploaded files

<AccordionGroup>
  <Accordion title="Message Scopes">
    **Reading messages:**

    * `channels:history` - Read public channel messages
    * `groups:history` - Read private channel messages
    * `im:history` - Read direct messages
    * `mpim:history` - Read group direct messages

    **Sending messages:**

    * `chat:write` - Required to send any messages
  </Accordion>

  <Accordion title="Channel Scopes">
    **Reading channel info:**

    * `channels:read` - List public channels
    * `groups:read` - List private channels
    * `im:read` - List DMs
    * `mpim:read` - List group DMs
  </Accordion>

  <Accordion title="User Scopes">
    **User information:**

    * `users:read` - Get user display names
    * `users:read.email` - Get user email addresses

    **Useful for:**

    * Personalizing responses
    * User identification
    * Profile information
  </Accordion>

  <Accordion title="Additional Scopes">
    **Other features:**

    * `app_mentions:read` - Detect when bot is @mentioned
    * `files:read` - Read uploaded files
  </Accordion>
</AccordionGroup>

## Connection Method 2: CLI (Private Bot)

The CLI connects a **private** bot using a bot token. Create your Slack app at [api.slack.com/apps](https://api.slack.com/apps), add the [required scopes](#required-bot-scopes), install it to your workspace, and copy the bot token first.

```bash theme={null}
$ lua channels
✅ Using agent: myAgent

? What would you like to do? 🔗 Link new channel
? Select channel type: 🔒 Slack (Private)

? Enter Slack bot token (xoxb-...): ****

📡 Creating Slack channel...

✅ Slack channel created successfully!

💼 Bot Name: My Agent Bot
🏢 Workspace: My Company
🔗 Webhook: https://wa.heylua.ai/slack/webhook
```

<Note>
  For the CLI path you configure the Slack app yourself. Set both **Event Subscriptions** and **Interactivity** request URLs to `https://wa.heylua.ai/slack/webhook`, and subscribe to the `app_mention`, `message.channels`, `message.groups`, and `message.im` bot events. The dashboard does this for you via the generated manifest.
</Note>

## Testing

DM your bot in Slack (or **@mention** it in a channel it's been invited to). Your agent replies automatically. Monitor the conversation in the admin dashboard.

## Sending Proactive Messages

To message a Slack user your agent is already in conversation with, load the [`User`](/api/user) and call `user.send(...)` — it delivers on the channel they're active on:

```typescript theme={null}
import { User } from 'lua-cli';

const user = await User.get(userId);
await user.send([{ type: 'text', text: 'Heads up — your report is ready.' }]);
```

<Note>
  Slack is **not yet** part of the unified [`Channels.send`](/api/channels) outbound API (which today covers WhatsApp, SMS, email, web chat, Teams, Instagram, and Messenger). For Slack, use `user.send()` to reach a user in an existing conversation.
</Note>

## Next Steps

<CardGroup>
  <Card title="Email" icon="envelope" href="/channels/email">
    Add email support
  </Card>

  <Card title="Management" icon="wrench" href="/channels/cli-management">
    Manage all channels
  </Card>
</CardGroup>


# Microsoft Teams
Source: https://docs.heylua.ai/channels/teams

Connect your agent to Microsoft Teams

## Overview

Microsoft Teams integration lets your agent respond inside Teams chats and channels - a natural fit for internal tooling and organizations already standardized on Microsoft 365.

<CardGroup>
  <Card title="Enterprise Ready" icon="building">
    Built for Microsoft 365 organizations
  </Card>

  <Card title="Chats & Channels" icon="users">
    DMs, group chats, and @mentions in team channels
  </Card>

  <Card title="Quick Start Available" icon="bolt">
    Use Lua's shared bot with no Azure setup
  </Card>

  <Card title="Bring Your Own Bot" icon="key">
    Full control with your own Azure Bot registration
  </Card>
</CardGroup>

## Two ways to connect

<Tabs>
  <Tab title="Lua's Teams bot (quick start)">
    **Recommended for most teams**

    * No Azure account, Bot resource, or app registration — nothing to set up on Microsoft's side
    * Install Lua's ready-made Teams app and link your agent
    * Best for getting started quickly, or when you don't need your own app identity

    Available in the dashboard.
  </Tab>

  <Tab title="Bring your own bot (advanced)">
    **Full control**

    * Your own Azure Bot resource, App ID, and secret
    * Your own Teams app manifest and branding
    * For organizations that require their own Azure app registration

    Available in the dashboard.
  </Tab>
</Tabs>

## Connection Method 1: Use Lua's Teams bot (Quick Start)

<Info>
  The fastest way in — Lua hosts the bot for you. **No Azure subscription, no Bot resource, no app registration, no client secrets to manage.** You install one ready-made app and link your agent; that's the whole job.
</Info>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent and add a channel">
    Click **Agents** in the main side navigation, select your agent's card, click the **+** (plus) icon to add a channel, then choose **Microsoft Teams**.

    <Frame>
      <img alt="Add a channel" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the channel options*
  </Step>

  <Step title="Choose Use Lua's Teams bot">
    Pick **Use Lua's Teams bot**. No Azure credentials are required for this path.
  </Step>

  <Step title="Install the Lua Teams app">
    The dashboard gives you a Teams app package to install (or a direct install link). In Microsoft Teams, an admin uploads the app: **Apps → Manage your apps → Upload a custom app**, then selects the package Lua provided. If your tenant restricts custom app uploads, a Teams admin may need to approve it first in the Teams admin center.
  </Step>

  <Step title="Connect your agent">
    Installing the app doesn't yet link it to your agent — one quick step does. The dashboard gives you a **Connect** link. Open it: it starts a chat with the Lua bot and pre-fills a one-time connect message. Just **send** it, and the bot replies *"Connected to agent…"* — your organization is now linked to this agent.

    <Info>
      **Why this step exists:** Lua's bot is shared across many organizations, so this one-time link is how Lua learns which agent *your* organization belongs to. (Running your own bot instead? Then there's no connect step — see [Bring Your Own Azure Bot](/channels/teams-byo-azure-bot).)
    </Info>

    <Note>
      The connect link is single-use and expires after 24 hours. If it expires before you use it, regenerate it from the dashboard.
    </Note>
  </Step>

  <Step title="Start chatting">
    **@mention** the bot in a team channel, or send it a direct message, and your agent will reply.

    <Check>
      Done — with zero Azure setup. No subscription, no Bot resource, no secrets to rotate.
    </Check>
  </Step>
</Steps>

## Connection Method 2: Bring Your Own Bot (Advanced)

<Info>
  Use this path if your organization requires its own Azure app registration, or you want the bot to appear under your own name and branding.
</Info>

The short version:

1. In the [Azure Portal](https://portal.azure.com), create an **Azure Bot** (**Single Tenant**), set its **Messaging endpoint** to `https://wa.heylua.ai/teams/webhook`, and enable the **Microsoft Teams** channel.
2. Copy the bot's **App ID**, create a **client secret**, and note your **Tenant ID**.
3. In the Lua dashboard, choose **Bring your own bot**, paste those three values, and click **Connect** — your bot is now linked to your agent. Download the app package Lua generates, upload it to Teams, then **@mention** or DM the bot.

<Card title="Full step-by-step walkthrough" icon="arrow-right" href="/channels/teams-byo-azure-bot">
  Every click in Azure and Teams, with each concept explained, a values reference, and troubleshooting.
</Card>

## Files and images

Your agent can read images, documents, audio and video that users send it in Teams. Attachments are downloaded, stored on Lua's CDN, and passed to your agent the same way as on every other channel — so the model sees the actual file contents, not a link.

**Where it works:**

| Scope                         | Pasted image | File sent with the attachment button |
| ----------------------------- | ------------ | ------------------------------------ |
| Direct message with the agent | Yes          | Yes                                  |
| Channel / group chat          | Yes          | **No**                               |

Microsoft Teams does not deliver files uploaded with the attachment button to a bot outside a direct message, and gives the bot no indication one was sent. Images pasted directly into the message box come through everywhere. If someone shares a file with your agent in a channel, your agent will explain it can't see it and ask for a direct message.

<Note>
  The attachment button only appears once the Teams app has been updated. **If you added your agent to Teams before file support shipped, download the app package again from the dashboard and re-upload it** — Teams enables the attachment button only after the update is applied.
</Note>

**Limits:**

* Attachments over **25 MB** are declined — your agent tells the user rather than failing silently.
* Whether a given file type can actually be interpreted depends on the model your agent uses. Anything the model can't read natively is converted to text where possible; otherwise your agent says so. See [Model capabilities](/agents/models).

**Sending files to a user.** When your agent replies with a document, Teams shows the user a consent prompt in a direct message; accepting saves the file to their OneDrive and renders it as a native Teams file. In channels and group chats the document is delivered as a link instead, because Teams has no file-transfer API there.

## Notes & limitations

* **Reactive replies and warm follow-ups only.** Your agent replies wherever it's been messaged or @mentioned. There is no cold-start path — you can't message a Teams user who has never contacted your agent. See [Channel Capabilities](/channels/channel-capabilities) for the full outbound matrix.
* **Where the bot replies.** The bot responds in the same chat or channel it was messaged or @mentioned in — a DM gets a DM reply, a channel @mention gets a channel reply.
* **Tenant admin approval.** Depending on your Microsoft 365 tenant's app policies, uploading a custom Teams app (Lua's shared bot or your own manifest) may require a Teams admin to allow custom app uploads or approve the app in the Teams admin center.
* **Further reading:** Microsoft's [Azure Bot Service documentation](https://learn.microsoft.com/en-us/azure/bot-service/) and [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema).

## Sending Proactive Messages

To message a Teams user your agent is already in conversation with, load the [`User`](/api/user) and call `user.send(...)`, or use [`Channels.send`](/api/channels) with `channel: 'teams'` and `to: { userId }`:

```typescript theme={null}
import { Channels } from 'lua-cli';

await Channels.send({
  channel: 'teams',
  to: { userId },
  text: 'Heads up — your report is ready.',
});
```

<Note>
  Teams is **warm-only** — you can only reach a user who already has a conversation with your agent. See [Proactive Messaging](/channels/proactive-messaging) for the model and per-channel rules.
</Note>

## Next Steps

<CardGroup>
  <Card title="Slack" icon="slack" href="/channels/slack">
    Add Slack support
  </Card>

  <Card title="Management" icon="wrench" href="/channels/cli-management">
    Manage all channels
  </Card>
</CardGroup>


# Bring Your Own Azure Bot
Source: https://docs.heylua.ai/channels/teams-byo-azure-bot

Create your own Microsoft Azure Bot and connect it to your Lua agent for Microsoft Teams — every step, click by click.

## Overview

This is the complete, click-by-click walkthrough for the **bring-your-own-bot** path: you create a bot in Microsoft Azure under your own app registration, point it at Lua, and connect it to your agent. Choose this path if your organization requires its own Azure app registration, or you want the bot to appear under your own name and branding.

<Note>
  Just want the fastest route with no Azure setup? Use **[Lua's shared Teams bot](/channels/teams)** instead — no Azure account, no app registration. This page is only for teams that want to run their own bot.
</Note>

The whole flow is short once you see the shape: **create the bot in Azure → hand its three values to Lua → install the Teams app.** Budget about 25–35 minutes.

## Before you start

Two roles are involved. It's fine if that's two different people — each step notes who does what.

<CardGroup>
  <Card title="An Azure subscription" icon="cloud">
    With permission to create a resource and register an app in your Microsoft Entra ID (formerly Azure AD) directory. Usually an IT / cloud administrator.
  </Card>

  <Card title="A Teams administrator" icon="user-shield">
    To allow a custom app to be uploaded, or to approve it for the whole organization. Good to line up early.
  </Card>

  <Card title="Your Lua login" icon="key">
    Access to the Lua admin dashboard for the agent you want to put in Teams.
  </Card>
</CardGroup>

<Info>
  **Cost:** an Azure Bot's free pricing tier (**F0**) is enough — the Microsoft Teams channel is included at no charge.
</Info>

## How the pieces fit together

You're building a small chain:

<Info>
  **Azure Bot** (identity + message router) → its **messaging endpoint** points at Lua → a **Teams app** wraps the bot so people can add it → the **Lua dashboard** ties the bot to your agent.
</Info>

Two of those produce values you'll copy into Lua — the bot's **App ID**, its **password (client secret)**, and your **Tenant ID**.

One thing worth knowing up front: because your bot's App ID is **unique to you**, handing those three values to Lua is *all it takes* to link the bot to your agent — there's no in-chat confirmation step, and you can even do it **before the Teams app exists**. The bot's identity (from Azure) and the Teams app (the wrapper people install) are separate things. More on this in Part 2.

## Part 1 — Create the Azure Bot

Done in the [Azure Portal](https://portal.azure.com). This creates the bot's identity, points it at Lua, and turns on Teams.

<Steps>
  <Step title="Open the Azure Portal and start a new Azure Bot">
    Go to [portal.azure.com](https://portal.azure.com) and sign in with your work account. In the top search bar type **Azure Bot**, then select **Azure Bot** (publisher: Microsoft). On the product page, click **Create**.
  </Step>

  <Step title="Fill in the Create an Azure Bot form">
    Work down the fields:

    * **Bot handle** — a unique name for the resource, e.g. `contoso-lua-bot`. This is an internal label; it isn't the name users see in Teams.
    * **Subscription** — pick your Azure subscription.
    * **Resource group** — choose an existing one or click **Create new** (a resource group is just a folder for related Azure resources, e.g. `rg-lua-teams`).
    * **Pricing tier** — click **Change plan** if needed and choose **Free (F0)**.
    * **Type of App** — choose **Single Tenant**. Your bot serves only your own organization — this is the correct, recommended choice.
    * **Creation type** — leave **Create new Microsoft App ID** selected. Azure creates the app registration (the bot's identity) for you.

    <Info>
      **What "Microsoft App ID" is:** choosing *Create new Microsoft App ID* makes Azure register an **application** in your Entra ID directory alongside the bot. That app registration is the bot's login identity, and its **Application (client) ID** is what everyone calls the **App ID** — you'll copy it into Lua shortly.
    </Info>

    Click **Review + create**, then **Create**. When deployment finishes, click **Go to resource**.
  </Step>

  <Step title="Set the Messaging endpoint (point the bot at Lua)">
    In the left menu open **Settings → Configuration**. Find the **Messaging endpoint** field and paste exactly:

    ```
    https://wa.heylua.ai/teams/webhook
    ```

    Then click **Apply**.

    <Info>
      **The messaging endpoint** is the address Microsoft calls every time someone messages your bot. Setting it to Lua's URL is what makes messages reach your agent. It's the same for everyone — no per-organization part.
    </Info>
  </Step>

  <Step title="Copy your App ID and Tenant ID">
    Still on **Settings → Configuration**, copy the **Microsoft App ID** and keep it safe — that's one of the three values Lua needs.

    To get the **Tenant ID**, click the **Manage Password** link next to the App ID — this opens the bot's **app registration**. On its **Overview** page both are labelled precisely:

    * **Application (client) ID** = your **App ID**
    * **Directory (tenant) ID** = your **Tenant ID**

    <Note>
      **Another place to find the Tenant ID:** search **Microsoft Entra ID** (or "Azure Active Directory") in the top bar → **Overview** → **Tenant ID**. It's a single GUID that identifies your whole organization's directory — the same value everywhere.
    </Note>
  </Step>

  <Step title="Create the client secret (the bot's password)">
    You should now be on the app registration (from *Manage Password*). In the left menu open **Certificates & secrets** → the **Client secrets** tab → **New client secret**.

    * **Description** — e.g. `Lua Teams bot`.
    * **Expires** — pick a duration (e.g. **24 months**). Note this date.

    Click **Add**. A row appears with a **Value** and a **Secret ID**.

    <Warning>
      **Copy the Value now.** Copy the **Value** column immediately (not the Secret ID) — Azure hides it forever the moment you leave the page. If you miss it, delete the secret and create a new one. This Value is the **App password** Lua asks for.
    </Warning>

    <Warning>
      **Set a renewal reminder.** When the secret **expires**, the bot stops replying until you create a new one and update it in Lua. Add a calendar reminder a couple of weeks before the expiry date you chose.
    </Warning>
  </Step>

  <Step title="Turn on the Microsoft Teams channel">
    Go back to the **Azure Bot** resource (not the app registration). Open **Settings → Channels** and click the **Microsoft Teams** icon.

    * Accept the **Terms of Service**.
    * Leave the default **Microsoft Teams Commercial** option selected.
    * Click **Apply** / **Save**.

    Teams should now show as a connected channel with status *Running*.

    <Check>
      Azure is done. The bot exists, points at Lua, and speaks Teams — and you've collected the three values Lua needs: **App ID**, **App password** (secret Value), and **Tenant ID**.
    </Check>
  </Step>
</Steps>

## Part 2 — Connect the bot in the Lua dashboard

This links the bot to your agent — and hands you a ready-to-install Teams app package.

<Steps>
  <Step title="Open your agent's Channels">
    Sign in to the Lua admin dashboard, open **Agents**, choose the agent you want in Teams, and open its **Channels**. Click **Connect** (the **+** / add-channel control) and choose **Microsoft Teams**.
  </Step>

  <Step title="Choose Bring your own Azure Bot">
    When asked how you want to connect, pick **Bring your own Azure Bot**. (The other option, *Use Lua's Teams bot*, skips Azure entirely but runs under Lua's identity.)
  </Step>

  <Step title="Paste the three Azure values">
    Enter the values from Part 1, then click **Connect**:

    * **App ID** — the Application (client) ID.
    * **App password** — the client secret **Value**.
    * **Tenant ID** — the Directory (tenant) ID.

    <Info>
      **This is where the bot links to your agent — no connect link needed.** Your Azure Bot has its **own unique App ID**, so these three values *are* the connection. The moment you click **Connect**, Lua stores an active route — **(your App ID + Tenant ID) → this agent** — and you're linked. There's no in-chat "connect" step like Lua's shared bot uses.

      Because the identity comes entirely from Azure, you can complete this step **before you've built or installed the Teams app** — the bot's identity and the Teams app (the wrapper people add) are separate. The route is live immediately, but nothing reaches the bot until its messaging endpoint points at Lua and the Teams app is installed (Parts 3–4).
    </Info>
  </Step>

  <Step title="Download your app package and confirm the endpoint">
    After connecting, Lua shows a short setup panel that:

    * Lets you **download the Teams app package** — a `.zip` with your bot's App ID already baked in. This is the easy route in Part 3.
    * Reminds you the Azure **messaging endpoint** must be `https://wa.heylua.ai/teams/webhook`, which you already set.

    Keep this `.zip` handy — you'll upload it to Teams next.
  </Step>
</Steps>

## Part 3 — The Teams app package

The bot needs a Teams "app" wrapper so people can add it. There are two ways to get one — pick either.

<CardGroup>
  <Card title="Use the package Lua generated" icon="bolt">
    **Recommended · easiest.** In Part 2 you downloaded a ready-made `.zip` with your App ID already inside. Nothing more to build — skip straight to Part 4 and install it.
  </Card>

  <Card title="Build your own in the Teams Developer Portal" icon="screwdriver-wrench">
    **Alternative.** Choose this if you want your own name, icons, and description, or to publish it to your organization's app catalog. Steps below.
  </Card>
</CardGroup>

<Info>
  **Bot vs. Teams app:** the **Azure Bot** is the engine. The **Teams app** is the wrapper Teams users actually add — it carries the name, icon, and a pointer to your bot. Both packages produce the same result: a Teams app pointing at *your* bot's App ID.
</Info>

### Option B — build it in the Teams Developer Portal

<Steps>
  <Step title="Create a new app">
    Go to [dev.teams.microsoft.com](https://dev.teams.microsoft.com), sign in with your Microsoft 365 account, open **Apps → New app**, give it a name, and click **Add**.

    <Note>
      The **App ID** shown here is the *Teams app* ID — a different GUID from your bot's App ID. That's expected; they're two different things.
    </Note>
  </Step>

  <Step title="Fill in Basic information">
    Complete the required fields: short and long **name** and **description**, **developer/company name**, **website**, and **privacy** + **terms of use** URLs. Teams requires these before it will let you publish or download.
  </Step>

  <Step title="Add the Bot feature and link your Azure Bot">
    Open **App features → Bot**. Under "Identify your bot", choose **Select an existing bot** and pick the Azure Bot you created — or choose **Enter a bot ID manually** and paste your bot's **App ID** (the Microsoft App ID from Part 1).

    Under **scopes**, tick all three so the bot works everywhere:

    * **Personal** — direct messages
    * **Team** — @mentions in channels
    * **Group chat** — group conversations

    Save.
  </Step>

  <Step title="Add icons (optional but recommended)">
    Under **Branding / Icons**, upload a **color icon (192×192 px)** and an **outline icon (32×32 px, transparent)**. This is what your team sees in Teams.
  </Step>

  <Step title="Publish or download">
    Open **Publish** and pick one:

    * **Publish to org** — submits the app to your Teams admin; once approved it appears in *Built for your org* for everyone to add. Best for a real rollout.
    * **Download app package** — gives you a `.zip` to install manually (same as the Lua-generated one). Best for a quick test.
  </Step>
</Steps>

## Part 4 — Install and test in Teams

<Steps>
  <Step title="Make sure custom apps can be uploaded">
    Many tenants block custom app uploads by default. If the upload option is greyed out, a Teams admin enables it in the **Teams admin center → Teams apps → Setup policies → Upload custom apps**. If you published to org in Part 3 instead, the admin approves it under **Teams apps → Manage apps**.
  </Step>

  <Step title="Upload the app package">
    In Microsoft Teams, open **Apps** (left rail) → **Manage your apps → Upload an app → Upload a custom app**, and select the `.zip` from Part 2 or 3.
  </Step>

  <Step title="Add the bot where you want it">
    Add it to **yourself** (a personal chat with the bot), to a **team/channel**, or to a **group chat** — matching the scopes you enabled.
  </Step>

  <Step title="Say hello">
    **Direct message** the bot, or **@mention** it in a channel. Your Lua agent replies — you're live.

    <Note>
      **How the bot behaves:** it replies where it's spoken to (a DM gets a DM reply; a channel @mention gets a channel reply). It responds when messaged and can follow up in an existing conversation, but it can't cold-message someone who has never contacted it. See [Proactive Messaging](/channels/proactive-messaging) for the details.
    </Note>
  </Step>
</Steps>

## Reference

Everything you copy or set, in one place.

```
https://wa.heylua.ai/teams/webhook
```

| What Lua asks for | Where it comes from (Azure)                          | Its exact label         |
| ----------------- | ---------------------------------------------------- | ----------------------- |
| **App ID**        | App registration → Overview                          | Application (client) ID |
| **App password**  | App registration → Certificates & secrets            | Client secret → *Value* |
| **Tenant ID**     | App registration → Overview (or Entra ID → Overview) | Directory (tenant) ID   |

| Setting                        | Value                                |
| ------------------------------ | ------------------------------------ |
| Azure Bot — Type of App        | Single Tenant                        |
| Azure Bot — Messaging endpoint | `https://wa.heylua.ai/teams/webhook` |
| Azure Bot — Channel            | Microsoft Teams (Commercial)         |
| Teams app — Bot scopes         | Personal · Team · Group chat         |
| Teams app — Icons              | Color 192×192 · Outline 32×32        |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The bot never replies">
    * Re-check the **messaging endpoint** is exactly `https://wa.heylua.ai/teams/webhook` (no trailing space) and that you clicked **Apply**.
    * Confirm the **Microsoft Teams channel** shows as *Running* on the Azure Bot.
    * Confirm the three values in Lua are correct — a mistyped **App password** is the most common cause.
  </Accordion>

  <Accordion title="'Upload a custom app' is greyed out">
    Your tenant blocks custom app uploads. A Teams admin turns it on in **Teams admin center → Teams apps → Setup policies → Upload custom apps**, or approves the app after you *Publish to org*.
  </Accordion>

  <Accordion title="It worked, then suddenly stopped">
    Your **client secret expired**. Create a new secret (Part 1, step 5), copy the new **Value**, and update the **App password** in the Lua dashboard.
  </Accordion>

  <Accordion title="Sign-in or authorization error right after setup">
    Occasionally a freshly created bot needs a minute for its identity to propagate across Microsoft. Give it a few minutes and try again.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Microsoft Teams overview" icon="comments" href="/channels/teams">
    The shared-bot quick start and the big picture for Teams.
  </Card>

  <Card title="Proactive messaging" icon="paper-plane" href="/channels/proactive-messaging">
    How your agent follows up in existing conversations.
  </Card>
</CardGroup>


# Website Chat Widget
Source: https://docs.heylua.ai/channels/website-widget

Embed the Lua Pop chat widget on your website

## Overview

Lua Pop is an embeddable chat widget that brings your AI agent directly to your website - no channel connection needed, just add a script tag!

<CardGroup>
  <Card title="2-Minute Setup" icon="clock">
    Single script tag
  </Card>

  <Card title="Fully Customizable" icon="palette">
    Match your brand
  </Card>

  <Card title="Voice Chat" icon="microphone">
    Optional voice support
  </Card>

  <Card title="Any Framework" icon="code">
    Works everywhere
  </Card>
</CardGroup>

## Two ways to set it up

* **No code** — configure the widget visually in the admin dashboard, then drop in a one-line `window.LuaPop.init()` snippet.
* **Inline** — pass your options directly to `window.LuaPop.init({ ... })` in code.

<Info>
  **Configuration priority:** dashboard settings apply only when you call `window.LuaPop.init()` with **no arguments**. If your embed script passes options to `window.LuaPop.init({ ... })`, those values take priority over the settings configured in the dashboard.
</Info>

## Configure in the dashboard (no code)

<Steps>
  <Step title="Open the widget settings">
    In the admin dashboard, click **Agents** in the side navigation, select your agent's card, click the **settings cog** in the top right, then choose **Chat widget**.

    <Frame>
      <img alt="Open Chat widget settings from the agent settings menu" />
    </Frame>
  </Step>

  <Step title="Customize the widget">
    Adjust the settings in the **Chat widget customization** panel on the right.

    <Frame>
      <img alt="Chat widget customization panel" />
    </Frame>

    The panel includes:

    * **Allowed websites** *(required)* — the domains the widget is allowed to load on.
    * **Excluded paths** — pages where the widget should stay hidden (e.g. `/checkout`).
    * **General** — display mode (**floating** or **embedded**), custom instructions, chat input placeholder, and welcome message.
    * **Floating button settings** *(floating mode)* — position, **draggable button**, button text, color and icon, button spacing, and chat window size.
    * **Embedded settings** *(embedded mode)* — target container ID and conversation starters.
    * **Features** — voice mode, microphone, attachments, and link previews.
    * **Chat header** — chat title and header colors.

    Click **Create channel** (or **Update configuration**) to save.
  </Step>

  <Step title="Add the embed snippet">
    Under **Installation**, copy the snippet and place it before the closing `</body>` tag on your site:

    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init();
    </script>
    ```

    Because `init()` is called with no arguments, the widget uses the settings you configured in the dashboard.
  </Step>
</Steps>

## Configure inline (code)

Prefer to keep configuration in code? Pass your options directly to `init()`. These override any dashboard settings.

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",

    // Position
    position: "bottom-right",  // or bottom-left, top-right, top-left
    draggable: true,           // let visitors drag the button to reposition it

    // Appearance
    buttonColor: "#ff173a",
    buttonText: "💬 Chat with us",
    chatTitle: "Customer Support",

    // Features
    voiceModeEnabled: true,

    // Branding
    chatHeaderSubtitle: {
      visible: true,
      brandName: "Your Company",
      iconUrl: "/logo.png"
    }
  });
</script>
```

Get your agent ID from your `lua.skill.yaml` file. Place the script before the closing `</body>` tag.

## Complete Documentation

<Card title="Full Lua Pop Guide" icon="book" href="/chat-widget/quick-start">
  Complete chat widget documentation with configuration, styling, events, frameworks, and more
</Card>

## Framework Integration

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    import { useEffect } from 'react';

    export default function ChatWidget() {
      useEffect(() => {
        const script = document.createElement('script');
        script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
        script.onload = () => {
          window.LuaPop?.init({
            agentId: process.env.REACT_APP_AGENT_ID,
            position: "bottom-right"
          });
        };
        document.body.appendChild(script);
      }, []);
      return null;
    }
    ```
  </Tab>

  <Tab title="Next.js">
    ```tsx theme={null}
    import Script from 'next/script';

    export default function Layout({ children }) {
      return (
        <>
          {children}
          <Script 
            src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"
            onLoad={() => {
              window.LuaPop?.init({
                agentId: process.env.NEXT_PUBLIC_AGENT_ID
              });
            }}
          />
        </>
      );
    }
    ```
  </Tab>

  <Tab title="WordPress">
    Add to theme's `footer.php` or use "Insert Headers and Footers" plugin
  </Tab>

  <Tab title="Shopify">
    Add to `theme.liquid` before `</body>`
  </Tab>
</Tabs>

<Card title="Framework Guides" href="/chat-widget/frameworks">
  Complete integration guides for all frameworks
</Card>

## Next Steps

<CardGroup>
  <Card title="Widget Configuration" icon="cog" href="/chat-widget/configuration">
    All configuration options
  </Card>

  <Card title="Styling Guide" icon="palette" href="/chat-widget/styling">
    Customize appearance
  </Card>
</CardGroup>


# WhatsApp Business
Source: https://docs.heylua.ai/channels/whatsapp

Connect your agent to WhatsApp Business API

## Overview

WhatsApp Business API allows your agent to communicate with customers via WhatsApp - the world's most popular messaging app with 2+ billion users.

<CardGroup>
  <Card title="Business Messaging" icon="building">
    Professional customer communication
  </Card>

  <Card title="Rich Media" icon="image">
    Images, videos, documents, location
  </Card>

  <Card title="High Engagement" icon="chart-line">
    98% open rates
  </Card>

  <Card title="Global Reach" icon="globe">
    Available in 180+ countries
  </Card>
</CardGroup>

## Prerequisites

Before connecting WhatsApp, you need:

<Info>
  Meta updates its developer dashboard and Business Suite UI frequently. The steps below describe what you need; for exact, up-to-date clicks, follow Meta's official [WhatsApp Cloud API — Get Started](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) guide.
</Info>

<Steps>
  <Step title="Meta Business Account">
    Create account at [https://business.facebook.com](https://business.facebook.com)

    <Frame>
      <img alt="Meta Business signup" />
    </Frame>

    *Screenshot: Meta Business account creation page*
  </Step>

  <Step title="WhatsApp Business Account (WABA)">
    In Meta's developer dashboard, create an app and select the **WhatsApp** use case. A WhatsApp Business Account is created for you, and you can open it under **WhatsApp → API Setup**.

    See Meta's official guide: [Create an app with the WhatsApp use case](https://developers.facebook.com/docs/development/create-an-app/whatsapp-use-case/).
  </Step>

  <Step title="Phone Number">
    Add and verify a business phone number, or use the free test number Meta provides for development. See Meta's [Get Started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) for adding and verifying numbers.
  </Step>

  <Step title="Get Credentials">
    Collect the required information:

    * **Phone Number ID**
    * **WhatsApp Business Account (WABA) ID**
    * **Access Token**

    All three appear on the **WhatsApp → API Setup** page of your app in the [Meta developer dashboard](https://developers.facebook.com/apps). For production, generate a permanent token via a System User — see Meta's [Get Started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started).
  </Step>
</Steps>

## Connection Method 1: CLI

### Step-by-Step CLI Setup

<Steps>
  <Step title="Run Command">
    ```bash theme={null}
    lua channels
    ```
  </Step>

  <Step title="Select Link New Channel">
    ```
    ✅ Using agent: myAgent

    ? What would you like to do?
    ❯ 🔗 Link new channel
    ```
  </Step>

  <Step title="Select WhatsApp">
    ```
    ? Select channel type:
    ❯ 📱 WhatsApp
      💬 Facebook Messenger
      📧 Email
      🔒 Slack (Private)
    ```
  </Step>

  <Step title="Enter Phone Number ID">
    ```
    ? Enter phone number ID: 647834045087314
    ```

    Find this in Meta Business Suite → WhatsApp → Phone Numbers
  </Step>

  <Step title="Enter WABA ID">
    ```
    ? Enter WhatsApp Business Account ID (WABA ID): 1390592278829291
    ```

    Find this in Meta Business Suite → WhatsApp → Settings
  </Step>

  <Step title="Enter Access Token">
    ```
    ? Enter access token: ****
    ```

    Generate in Meta Business Suite → System Users → Generate Token
  </Step>

  <Step title="Success">
    ```
    📡 Creating WhatsApp channel...

    ✅ WhatsApp channel created successfully!

    📱 Phone Number: +15557986280
    📊 Status: CONNECTED
    🌍 Country: USA
    🎯 Webhook URL: https://wa.heylua.ai/whatsapp/webhook/abc123
    ```
  </Step>
</Steps>

### Configure Webhook in Meta

<Steps>
  <Step title="Copy Webhook URL">
    Copy the webhook URL from the CLI output.
  </Step>

  <Step title="Open WhatsApp Configuration">
    In your app's developer dashboard, go to **WhatsApp → Configuration**.
  </Step>

  <Step title="Add Webhook">
    Click **Edit**, paste the webhook URL as the **Callback URL**, enter your **Verify token**, and save.
  </Step>

  <Step title="Subscribe to Events">
    Under **Webhook fields**, click **Manage** and subscribe to `messages` and `message_status`.
  </Step>

  <Step title="Verify">
    Meta sends a verification request to confirm the webhook. A green check confirms it's connected.
  </Step>
</Steps>

<Info>
  Meta's webhook setup UI changes periodically. For the current steps and field names, follow Meta's official guide: [Set up Webhooks for WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks).
</Info>

## Connection Method 2: Admin Dashboard

### Step-by-Step Dashboard Setup

<Info>
  The dashboard uses Meta's **Embedded Signup**, so you don't enter credentials or configure webhooks by hand. Signing in with Facebook lets Meta provision (or connect) your WhatsApp Business Account, phone number, and webhook automatically. Use the [CLI method](#connection-method-1-cli) instead if you already have credentials and prefer to enter them manually.
</Info>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent">
    Click **Agents** in the main side navigation, then select your agent's card.
  </Step>

  <Step title="Add a channel">
    Click the **+** (plus) icon to add a channel, then choose **WhatsApp**.

    <Frame>
      <img alt="Add a channel" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the WhatsApp option*
  </Step>

  <Step title="Accept terms & connect">
    Tick the box to accept the **Terms of Service** and **Privacy Policy**, then click **Connect**.
  </Step>

  <Step title="Log in with Facebook">
    A Meta **Embedded Signup** popup opens. Log in with your Facebook details and continue the Facebook workflow — select or create your Business account, WhatsApp Business Account, and phone number. Meta handles verification and webhook setup for you.

    <Note>
      This popup is Meta's own UI and changes periodically. See Meta's [Embedded Signup overview](https://developers.facebook.com/docs/whatsapp/embedded-signup) if you get stuck.
    </Note>
  </Step>

  <Step title="Connection success">
    When signup completes, you'll see a **"WhatsApp channel connected"** confirmation and WhatsApp appears in your connected channels.
  </Step>
</Steps>

## Testing Your WhatsApp Channel

<Steps>
  <Step title="Send Test Message">
    From your phone, send WhatsApp message to your business number

    ```
    You: Hi!
    ```
  </Step>

  <Step title="Agent Responds">
    Your agent should respond automatically

    ```
    Agent: Hello! How can I help you today?
    ```
  </Step>

  <Step title="Monitor in Admin">
    View conversation in admin dashboard

    <Frame>
      <img alt="WhatsApp conversation" />
    </Frame>

    *Screenshot: Real-time conversation view*
  </Step>
</Steps>

## Message Status Events

When you send messages via WhatsApp (including template messages), Meta sends status updates back to Lua as messages progress through delivery. Lua captures these events and can forward them to your webhooks.

### Status Lifecycle

A typical message goes through these statuses:

```
sent → delivered → read
```

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `sent`      | Message accepted by WhatsApp servers                    |
| `delivered` | Message delivered to recipient's device                 |
| `read`      | Recipient opened and read the message                   |
| `failed`    | Message could not be delivered (includes error details) |
| `played`    | Recipient played a voice or video message               |

### Tracking Delivery with Webhooks

To receive these events in your code, subscribe a webhook to the event types you need:

```bash theme={null}
lua webhooks subscribe --webhook-name my-tracker --event message.sent
lua webhooks subscribe --webhook-name my-tracker --event message.delivered
lua webhooks subscribe --webhook-name my-tracker --event message.read
lua webhooks subscribe --webhook-name my-tracker --event message.failed
```

Your webhook receives the full status payload including the message ID, recipient, timestamp, conversation context, and pricing information. See the [Webhooks API Reference](/api/luawebhook#event-subscriptions) for the complete payload shape.

<Note>
  Status events are particularly useful when sending template messages via the [Templates API](/api/templates). After sending a campaign, subscribe to `message.delivered` and `message.read` to measure engagement, or `message.failed` to catch delivery issues.
</Note>

### Prerequisites

For status events to flow through, make sure you've subscribed to `messages` **and** `message_status` in your Meta webhook configuration (see [Configure Webhook in Meta](#configure-webhook-in-meta) above).

## Status & Quality

### Connection Status

* 🟢 **CONNECTED** - Working normally
* 🔴 **DISCONNECTED** - Needs reconnection
* 🟡 **PENDING** - Setup in progress

### Quality Rating

Meta assigns quality ratings based on user feedback:

* 🟢 **GREEN** - High quality (good!)
* 🟡 **YELLOW** - Medium quality (watch carefully)
* 🔴 **RED** - Low quality (take action)

<Warning>
  Low quality ratings can result in rate limiting or account restrictions. Monitor quality in admin dashboard.
</Warning>

## Sending Proactive Messages

Your agent can message WhatsApp users on its own — order updates, reminders, follow-ups — using the [Channels API](/api/channels), not just reply to inbound messages.

```typescript theme={null}
import { Channels } from 'lua-cli';

// In-window: free-form message (within 24h of the user's last message)
await Channels.send({
  channel: 'whatsapp',
  to: { userId: 'user_123' },
  text: 'Your order has shipped! 📦'
});

// Outside the window: send an approved template to re-open the conversation
await Channels.whatsapp.sendTemplate({
  to: { phoneNumber: '+14155552671' },
  templateName: 'order_update',
  languageCode: 'en_US',
  messageContext: 'Told the customer their order shipped'
});
```

<Warning>
  WhatsApp allows **free-form** messages only within **24 hours** of the user's last inbound message. Outside that window, use an approved template (or rely on the default queue behavior). See [Proactive Messaging](/channels/proactive-messaging#the-whatsapp-24-hour-window) and [Channel Capabilities](/channels/channel-capabilities#whatsapp).
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Response Time">
    * Respond within 24 hours
    * Quick responses improve quality rating
    * Agent handles this automatically
  </Accordion>

  <Accordion title="Message Templates">
    * Use templates for notifications
    * Required for messages after 24 hours
    * Set up in Meta Business Suite
  </Accordion>

  <Accordion title="Opt-In Required">
    * Users must message you first
    * Cannot send unsolicited messages
    * Respect user privacy
  </Accordion>

  <Accordion title="Monitor Quality">
    ```bash theme={null}
    lua admin
    # Check quality rating regularly
    # Address any user complaints promptly
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Channel shows DISCONNECTED">
    **Causes:**

    * Token expired
    * WABA disabled
    * Phone number removed

    **Solution:**

    1. Regenerate access token
    2. Update in admin dashboard
    3. Verify WABA is active
  </Accordion>

  <Accordion title="Messages not delivering">
    **Check:**

    * Quality rating (RED = issues)
    * Webhook configured correctly
    * Phone number status in Meta
    * Message templates approved
  </Accordion>

  <Accordion title="Quality rating dropped">
    **Actions:**

    1. Review recent conversations
    2. Check user feedback in Meta
    3. Improve agent responses
    4. Address user complaints
    5. May need to adjust persona
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Facebook Messenger" icon="facebook" href="/channels/facebook-messenger">
    Connect another channel
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Test agent behavior
  </Card>

  <Card title="Monitor Channels" icon="chart-line" href="/channels/admin-dashboard">
    View channel analytics
  </Card>

  <Card title="CLI Command Reference" icon="terminal" href="/cli/channels-command">
    Complete CLI guide
  </Card>
</CardGroup>


# Analytics & Tracking
Source: https://docs.heylua.ai/chat-widget/analytics

Track chat interactions and measure engagement

## Overview

Track chat widget performance and user interactions by listening to widget events.

## Google Analytics 4

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'LUA_POP_EVENT') {
    gtag('event', 'chat_interaction', {
      event_category: 'engagement',
      event_label: event.data.eventType,
      chat_agent_id: 'your-agent-id'
    });
  }
});

window.LuaPop.init({
  agentId: "your-agent-id",
  position: "bottom-right"
});
```

## Custom Analytics

```javascript theme={null}
class ChatAnalytics {
  constructor() {
    this.sessionStart = Date.now();
    this.interactions = [];
    this.setupTracking();
  }

  setupTracking() {
    window.addEventListener('message', (event) => {
      if (event.data?.type === 'LUA_POP_EVENT') {
        this.track(event.data.eventType, event.data.data);
      }
    });
  }

  track(eventType, data = {}) {
    const event = {
      type: eventType,
      timestamp: Date.now(),
      sessionDuration: Date.now() - this.sessionStart,
      page: window.location.pathname,
      ...data
    };
    
    this.interactions.push(event);
    
    // Send to your analytics service
    fetch('/api/analytics/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event)
    }).catch(console.error);
  }
}

const analytics = new ChatAnalytics();
```

## Mixpanel Integration

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'LUA_POP_EVENT') {
    mixpanel.track('Chat Interaction', {
      event_type: event.data.eventType,
      agent_id: 'your-agent-id',
      page: window.location.pathname
    });
  }
});
```

## Segment Integration

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'LUA_POP_EVENT') {
    analytics.track('Chat Event', {
      eventType: event.data.eventType,
      data: event.data.data
    });
  }
});
```

## Key Metrics to Track

<AccordionGroup>
  <Accordion title="Engagement Rate">
    ```javascript theme={null}
    let pageViews = 0;
    let chatOpens = 0;

    // Track page views
    pageViews++;

    // Track chat opens
    window.addEventListener('message', function(event) {
      if (event.data?.type === 'LUA_POP_EVENT') {
        if (event.data.eventType === 'widget_opened') {
          chatOpens++;
          console.log('Engagement rate:', (chatOpens / pageViews * 100).toFixed(2) + '%');
        }
      }
    });
    ```
  </Accordion>

  <Accordion title="Session Duration">
    ```javascript theme={null}
    let sessionStart = null;

    window.addEventListener('message', function(event) {
      if (event.data?.type === 'LUA_POP_EVENT') {
        if (event.data.eventType === 'widget_opened') {
          sessionStart = Date.now();
        }
        
        if (event.data.eventType === 'widget_closed' && sessionStart) {
          const duration = Date.now() - sessionStart;
          console.log('Session duration:', duration / 1000, 'seconds');
          
          gtag('event', 'chat_session_duration', {
            value: duration,
            metric_id: 'chat_duration'
          });
        }
      }
    });
    ```
  </Accordion>

  <Accordion title="Messages Per Session">
    ```javascript theme={null}
    let messagesInSession = 0;

    window.addEventListener('message', function(event) {
      if (event.data?.type === 'LUA_POP_EVENT') {
        if (event.data.eventType === 'widget_opened') {
          messagesInSession = 0;
        }
        
        if (event.data.eventType === 'message_sent') {
          messagesInSession++;
        }
        
        if (event.data.eventType === 'widget_closed') {
          console.log('Messages in session:', messagesInSession);
        }
      }
    });
    ```
  </Accordion>
</AccordionGroup>

## Dashboard Example

```javascript theme={null}
class ChatDashboard {
  constructor() {
    this.metrics = {
      totalSessions: 0,
      totalMessages: 0,
      avgSessionDuration: 0,
      engagementRate: 0
    };
    
    this.sessions = [];
    this.setupTracking();
  }

  setupTracking() {
    window.addEventListener('message', (event) => {
      if (event.data?.type === 'LUA_POP_EVENT') {
        this.handleEvent(event.data);
      }
    });
  }

  handleEvent({ eventType, data }) {
    switch (eventType) {
      case 'widget_opened':
        this.startSession();
        break;
      case 'widget_closed':
        this.endSession();
        break;
      case 'message_sent':
      case 'message_received':
        this.trackMessage();
        break;
    }
    
    this.updateDashboard();
  }

  startSession() {
    this.metrics.totalSessions++;
    this.currentSession = {
      start: Date.now(),
      messages: 0
    };
  }

  endSession() {
    if (this.currentSession) {
      const duration = Date.now() - this.currentSession.start;
      this.sessions.push({
        duration,
        messages: this.currentSession.messages
      });
      
      this.calculateAverages();
    }
  }

  trackMessage() {
    this.metrics.totalMessages++;
    if (this.currentSession) {
      this.currentSession.messages++;
    }
  }

  calculateAverages() {
    const totalDuration = this.sessions.reduce((sum, s) => sum + s.duration, 0);
    this.metrics.avgSessionDuration = totalDuration / this.sessions.length;
  }

  updateDashboard() {
    // Send to your dashboard
    console.log('📊 Chat Metrics:', this.metrics);
  }
}

const dashboard = new ChatDashboard();
```

## Next Steps

<CardGroup>
  <Card title="Events API" icon="bolt" href="/chat-widget/events">
    Complete events reference
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See analytics implementations
  </Card>
</CardGroup>


# Configuration Reference
Source: https://docs.heylua.ai/chat-widget/configuration

Complete configuration options for LuaPop

## Dashboard vs Inline Configuration

All widget settings can be configured directly in the **Lua AI admin dashboard** — no code changes needed. To use dashboard settings, initialize the widget with no arguments:

```javascript theme={null}
window.LuaPop.init();
```

To override specific settings in code, pass a config object:

```javascript theme={null}
window.LuaPop.init({
  sessionId: dynamicSessionId, // runtime value — overrides dashboard
});
```

<Info>
  **Configuration priority:** Any option passed to `window.LuaPop.init({...})` takes priority over the corresponding dashboard setting. Options not passed in code fall back to dashboard values. Call `window.LuaPop.init()` with no arguments to use dashboard settings exclusively.
</Info>

***

## window\.LuaPop.init(config)

Initialize the LuaPop widget with the provided configuration.

```javascript theme={null}
const widget = window.LuaPop.init({
  agentId: "your-agent-id",
  // ... other options
});
```

**Returns:** Widget instance with `destroy()` method

## Required Configuration

<ParamField type="string">
  **Required.** The ID of the AI agent to use for conversations.

  Get this from your Lua AI dashboard.

  ```javascript theme={null}
  agentId: "agent_abc123xyz"
  ```
</ParamField>

## Basic Configuration

<ParamField type="string">
  Widget position on the page.

  **Options**: `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`

  ```javascript theme={null}
  position: "bottom-right"
  ```
</ParamField>

<ParamField type="string">
  Text displayed on the chat button.

  ```javascript theme={null}
  buttonText: "💬 Need Help?"
  ```
</ParamField>

<ParamField type="string">
  API environment to use.

  **Options**: `"staging"`, `"production"`, `"custom"`

  ```javascript theme={null}
  environment: "production"
  ```
</ParamField>

## Authentication & Session

<ParamField type="string">
  Unique session identifier for the user.

  If not provided, auto-generated. Use for persistent conversations across page loads.

  ```javascript theme={null}
  sessionId: "user-12345"
  ```
</ParamField>

<ParamField type="string">
  Optional authentication token for authenticated users.

  ```javascript theme={null}
  authToken: "bearer-token-here"
  ```
</ParamField>

<ParamField type="string">
  Custom API base URL (only when `environment` is `"custom"`).

  ```javascript theme={null}
  environment: "custom",
  customBaseApiUri: "https://your-api.com"
  ```
</ParamField>

## Display Configuration

<ParamField type="string">
  How the widget is displayed.

  **Options**: `"floating"`, `"embedded"`

  ```javascript theme={null}
  displayMode: "floating" // or "embedded"
  ```
</ParamField>

<ParamField type="boolean">
  Allow users to drag and drop the floating button (pill) to reposition it. Useful when the button overlaps other elements on your page — users can move it out of the way. Only applies when `displayMode` is `"floating"`.

  ```javascript theme={null}
  displayMode: "floating",
  draggable: true
  ```
</ParamField>

<ParamField type="object">
  Configuration for embedded mode. Required when `displayMode` is `"embedded"`.

  ```typescript theme={null}
  embeddedDisplayConfig: {
    targetContainerId: string;       // ID of the container element to render into
    conversationStarters?: string[]; // Suggested prompts shown before first message
    useContainerHeight?: boolean;    // Always use container height (100%) vs auto-detect
  }
  ```

  **`targetContainerId`** *(required)* — The `id` of the DOM element the widget will render into.

  **`conversationStarters`** *(optional)* — An array of suggested prompts displayed to the user before they send their first message. Clicking a starter sends it as a message.

  **`useContainerHeight`** *(optional, default `false`)* — When `true`, the widget always fills its container using `height: 100%`. Use this for footer or expandable layouts where the container height changes dynamically. When `false`, the widget auto-detects an explicit container height and falls back to `100dvh` if none is set.

  **Example:**

  ```javascript theme={null}
  displayMode: "embedded",
  embeddedDisplayConfig: {
    targetContainerId: "my-chat-container",
    conversationStarters: [
      "What can you help me with?",
      "Show me your latest products",
      "I need support with my order"
    ],
    useContainerHeight: true
  }
  ```
</ParamField>

<ParamField type="string | number">
  Height of the chat window.

  ```javascript theme={null}
  chatWindowHeight: "600px"  // or 600
  ```
</ParamField>

<ParamField type="string | number">
  Width of the chat window.

  ```javascript theme={null}
  chatWindowWidth: "400px"  // or 400
  ```
</ParamField>

## Visual Customization

<ParamField type="string">
  Background color of the chat button.

  ```javascript theme={null}
  buttonColor: "#28a745"
  ```
</ParamField>

<ParamField type="string">
  Icon or emoji displayed on the button.

  ```javascript theme={null}
  buttonIcon: "🤖"
  ```
</ParamField>

<ParamField type="string">
  Title displayed in the chat header.

  ```javascript theme={null}
  chatTitle: "Customer Support"
  ```
</ParamField>

<ParamField type="string">
  Placeholder text for the input field.

  ```javascript theme={null}
  chatInputPlaceholder: "How can we help you today?"
  ```
</ParamField>

<ParamField type="string">
  Welcome message displayed when the chat is first opened and no conversation history exists.

  This message appears as the first assistant message, helping to greet users and set the tone for the conversation.

  ```javascript theme={null}
  welcomeMessage: "Hello! How can we assist you today?"
  ```
</ParamField>

## Advanced Styling

<ParamField type="React.CSSProperties">
  Custom CSS styles for the chat button.

  ```javascript theme={null}
  popupButtonStyles: {
    borderRadius: "50%",
    width: "60px",
    height: "60px",
    fontSize: "24px",
    boxShadow: "0 4px 12px rgba(0,0,0,0.15)"
  }
  ```
</ParamField>

<ParamField type="React.CSSProperties">
  Custom CSS styles for button positioning.

  ```javascript theme={null}
  popupButtonPositionalContainerStyles: {
    bottom: "20px",
    right: "20px",
    zIndex: "9999"
  }
  ```
</ParamField>

<ParamField type="React.CSSProperties">
  Custom CSS styles for the chat header.

  ```javascript theme={null}
  chatTitleHeaderStyles: {
    background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
    color: "white",
    borderRadius: "10px 10px 0 0"
  }
  ```
</ParamField>

## Branding

<ParamField type="object">
  Subtitle configuration for branding.

  ```typescript theme={null}
  chatHeaderSubtitle: {
    visible: boolean;
    brandName?: string;
    iconUrl?: string;
    linkUrl?: string;
  }
  ```

  **Example:**

  ```javascript theme={null}
  chatHeaderSubtitle: {
    visible: true,
    brandName: "Your Company",
    iconUrl: "https://yoursite.com/logo.png",
    linkUrl: "https://yoursite.com"
  }
  ```
</ParamField>

## Advanced Features

<ParamField type="boolean">
  Enable voice chat functionality. When `true`, users can switch to a full voice interaction mode where AI responses are spoken aloud. See the [Voice Chat guide](/chat-widget/voice-chat) for details.

  ```javascript theme={null}
  voiceModeEnabled: true
  ```
</ParamField>

<ParamField type="boolean">
  Show a microphone button in the chat input bar, allowing users to dictate messages via speech-to-text. Unlike `voiceModeEnabled`, this keeps the interaction in text mode — the spoken input is transcribed into the text field rather than switching to a full voice experience.

  ```javascript theme={null}
  microphoneEnabled: true
  ```
</ParamField>

<ParamField type="boolean">
  Allow users to upload and send file attachments (images, documents, etc.) within the chat. When `true`, a file attachment button appears in the chat input bar.

  ```javascript theme={null}
  attachmentsEnabled: true
  ```
</ParamField>

<ParamField type="boolean">
  Disable automatic link previews.

  ```javascript theme={null}
  disablePreviewOnLinks: true
  ```
</ParamField>

<ParamField type="string">
  Additional context passed to the AI agent.

  Useful for providing page context, user roles, etc.

  ```javascript theme={null}
  runtimeContext: "page:pricing,user:premium,lang:en"
  ```
</ParamField>

## Event Handlers

<ParamField type="function">
  Handler for navigation events from the chat.

  ```typescript theme={null}
  onNavigate: (pathname: string, options: { query: Record<string, string> }) => void
  ```

  **Example:**

  ```javascript theme={null}
  onNavigate: (pathname, options) => {
    console.log('Navigate to:', pathname);
    console.log('Query params:', options.query);
    
    // Handle navigation in your app
    window.location.href = pathname + '?' + new URLSearchParams(options.query);
  }
  ```
</ParamField>

## Complete Example

```javascript theme={null}
window.LuaPop.init({
  // Required
  agentId: "customer-support-agent",
  
  // Basic
  position: "bottom-right",
  buttonText: "💬 Need Help?",
  environment: "production",
  
  // Session
  sessionId: "user-12345",
  authToken: "your-auth-token",
  
  // Display
  displayMode: "floating",
  chatWindowHeight: "600px",
  chatWindowWidth: "400px",
  
  // Visual
  buttonColor: "#28a745",
  buttonIcon: "🤖",
  chatTitle: "Customer Support",
  
  // Styling
  popupButtonStyles: {
    borderRadius: "25px",
    padding: "15px 20px",
    fontSize: "16px"
  },
  
  popupButtonPositionalContainerStyles: {
    bottom: "30px",
    right: "30px"
  },
  
  chatTitleHeaderStyles: {
    background: "#28a745",
    color: "white"
  },
  
  // Branding
  chatInputPlaceholder: "How can we help?",
  welcomeMessage: "Hi there! 👋 How can we help you today?",
  chatHeaderSubtitle: {
    visible: true,
    brandName: "Your Company",
    iconUrl: "/logo.png",
    linkUrl: "/"
  },
  
  // Advanced
  voiceModeEnabled: true,
  microphoneEnabled: true,
  attachmentsEnabled: true,
  disablePreviewOnLinks: false,
  runtimeContext: "page:home",
  
  // Events
  onNavigate: (pathname, options) => {
    console.log('Navigate:', pathname);
  }
});
```

## Configuration Tips

<AccordionGroup>
  <Accordion title="Use Staging for Testing">
    Always test new configurations with staging first:

    ```javascript theme={null}
    environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging'
    ```
  </Accordion>

  <Accordion title="Generate Unique Session IDs">
    Create unique sessions for better tracking:

    ```javascript theme={null}
    sessionId: `user-${userId}-${Date.now()}`
    ```
  </Accordion>

  <Accordion title="Use Runtime Context">
    Pass page context to help the AI provide better responses:

    ```javascript theme={null}
    runtimeContext: `page:${window.location.pathname},lang:${document.documentElement.lang}`
    ```
  </Accordion>

  <Accordion title="Responsive Configuration">
    Adjust for different screen sizes:

    ```javascript theme={null}
    const isMobile = window.innerWidth <= 768;

    window.LuaPop.init({
      agentId: "your-agent-id",
      chatWindowWidth: isMobile ? "100vw" : "400px",
      chatWindowHeight: isMobile ? "100vh" : "600px"
    });
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Styling Guide" icon="palette" href="/chat-widget/styling">
    Customize colors, fonts, and appearance
  </Card>

  <Card title="Events API" icon="bolt" href="/chat-widget/events">
    Listen to chat events and interactions
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See real-world configurations
  </Card>

  <Card title="Framework Integration" icon="code" href="/chat-widget/frameworks">
    React, Vue, Angular guides
  </Card>
</CardGroup>


# Events & Callbacks
Source: https://docs.heylua.ai/chat-widget/events

Listen to chat widget events and interactions

## Event System

LuaPop communicates with your website through the browser's `postMessage` API. Listen for events to track interactions, trigger actions, or integrate with analytics.

## Widget Events

### Listening to Events

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'LUA_POP_EVENT') {
    const { eventType, data } = event.data;
    
    console.log('Event:', eventType);
    console.log('Data:', data);
  }
});
```

### Available Events

<ParamField type="event">
  Fired when the chat widget is opened by the user.

  **Data:** `{}`

  ```javascript theme={null}
  case 'widget_opened':
    console.log('Chat widget opened');
    // Track in analytics, show help hints, etc.
    break;
  ```
</ParamField>

<ParamField type="event">
  Fired when the chat widget is closed.

  **Data:** `{}`

  ```javascript theme={null}
  case 'widget_closed':
    console.log('Chat widget closed');
    // Track session duration, save state, etc.
    break;
  ```
</ParamField>

<ParamField type="event">
  Fired when the user sends a message.

  **Data:** `{ content: string, timestamp: string }`

  ```javascript theme={null}
  case 'message_sent':
    console.log('User sent:', data.content);
    // Track user messages, sentiment analysis, etc.
    break;
  ```
</ParamField>

<ParamField type="event">
  Fired when the AI sends a response.

  **Data:** `{ content: string, timestamp: string }`

  ```javascript theme={null}
  case 'message_received':
    console.log('AI responded:', data.content);
    // Track AI responses, measure quality, etc.
    break;
  ```
</ParamField>

## Resize Events

For embedded mode, listen to resize events:

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'LUA_POP_RESIZE') {
    const { width, height } = event.data;
    console.log('Widget resized:', width, height);
    
    // Adjust surrounding layout if needed
    adjustLayout(width, height);
  }
});
```

## Navigation Handler

Handle navigation events from the chat:

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  
  onNavigate: (pathname, options) => {
    console.log('Navigate to:', pathname);
    console.log('Query params:', options.query);
    
    // Example 1: Standard navigation
    window.location.href = pathname;
    
    // Example 2: With query params
    const url = pathname + '?' + new URLSearchParams(options.query);
    window.location.href = url;
    
    // Example 3: React Router
    navigate(pathname, { state: options.query });
    
    // Example 4: Vue Router
    router.push({ path: pathname, query: options.query });
  }
});
```

## Complete Event Handler

```javascript theme={null}
class LuaPopEventHandler {
  constructor() {
    this.setupEventListeners();
  }

  setupEventListeners() {
    window.addEventListener('message', (event) => {
      if (!event.data) return;
      
      switch (event.data.type) {
        case 'LUA_POP_EVENT':
          this.handleWidgetEvent(event.data);
          break;
        case 'LUA_POP_RESIZE':
          this.handleResize(event.data);
          break;
        case 'LUA_POP_ERROR':
          this.handleError(event.data);
          break;
      }
    });
  }

  handleWidgetEvent({ eventType, data }) {
    switch (eventType) {
      case 'widget_opened':
        this.onWidgetOpened();
        break;
      case 'widget_closed':
        this.onWidgetClosed();
        break;
      case 'message_sent':
        this.onMessageSent(data);
        break;
      case 'message_received':
        this.onMessageReceived(data);
        break;
    }
  }

  onWidgetOpened() {
    console.log('✅ Widget opened');
    
    // Track in analytics
    gtag('event', 'chat_opened', {
      event_category: 'engagement'
    });
    
    // Update UI
    document.body.classList.add('chat-active');
  }

  onWidgetClosed() {
    console.log('❌ Widget closed');
    
    // Track session duration
    gtag('event', 'chat_closed', {
      event_category: 'engagement'
    });
    
    // Update UI
    document.body.classList.remove('chat-active');
  }

  onMessageSent(data) {
    console.log('📤 User sent:', data.content);
    
    // Track user engagement
    this.trackMessage('user', data.content);
  }

  onMessageReceived(data) {
    console.log('📥 AI responded:', data.content);
    
    // Track AI responses
    this.trackMessage('ai', data.content);
  }

  handleResize({ width, height }) {
    console.log(`📐 Widget resized: ${width}x${height}`);
  }

  handleError({ error }) {
    console.error('❌ LuaPop Error:', error);
    
    // Show fallback UI or error message
    this.showErrorFallback(error);
  }

  trackMessage(sender, content) {
    // Send to analytics service
    fetch('/api/analytics/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        sender,
        content,
        timestamp: new Date().toISOString()
      })
    });
  }

  showErrorFallback(error) {
    // Show user-friendly error message
    alert('Chat is temporarily unavailable. Please try again later.');
  }
}

// Initialize event handler
new LuaPopEventHandler();
```

## Use Cases

### Track Chat Engagement

```javascript theme={null}
let chatSessions = 0;
let messagesExchanged = 0;

window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'LUA_POP_EVENT') {
    switch (event.data.eventType) {
      case 'widget_opened':
        chatSessions++;
        console.log('Total chat sessions:', chatSessions);
        break;
        
      case 'message_sent':
      case 'message_received':
        messagesExchanged++;
        console.log('Total messages:', messagesExchanged);
        break;
    }
  }
});
```

### Show Help Hints

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'LUA_POP_EVENT') {
    if (event.data.eventType === 'widget_opened') {
      // Show contextual help based on current page
      const page = window.location.pathname;
      
      if (page.includes('/pricing')) {
        // Could trigger AI to suggest pricing questions
        console.log('User opened chat on pricing page');
      }
    }
  }
});
```

### Auto-Open for New Users

```javascript theme={null}
// Check if user is new
const isNewUser = !localStorage.getItem('has_used_chat');

window.LuaPop.init({
  agentId: "onboarding-agent",
  buttonText: isNewUser ? "🚀 Get Started" : "💬 Chat"
});

// Auto-open for new users after 5 seconds
if (isNewUser) {
  setTimeout(() => {
    // Trigger chat open
    document.querySelector('.lua-pop-button')?.click();
    localStorage.setItem('has_used_chat', 'true');
  }, 5000);
}
```

## Next Steps

<CardGroup>
  <Card title="Analytics" icon="chart-line" href="/chat-widget/analytics">
    Track chat interactions
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See event handling examples
  </Card>
</CardGroup>

EOFSTYLE


# Examples & Use Cases
Source: https://docs.heylua.ai/chat-widget/examples

Real-world implementation examples for different industries

## Customer Support Widget

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Customer Support Example</title>
</head>
<body>
  <header>
    <h1>Welcome to Our Business</h1>
  </header>

  <main>
    <p>We're here to help 24/7!</p>
  </main>

  <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
  <script>
    window.LuaPop.init({
      agentId: "customer-support",
      chatTitle: "Customer Support",
      buttonText: "💬 Get Help",
      position: "bottom-right",
      welcomeMessage: "Hi there! 👋 How can we help you today?",
      chatInputPlaceholder: "Describe your issue..."
    });
  </script>
</body>
</html>
```

## E-commerce Shopping Assistant

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "shopping-assistant",
    chatTitle: "Shopping Assistant",
    buttonText: "🛒 Shop Help",
    buttonColor: "#e74c3c",
    position: "bottom-right",
    welcomeMessage: "Welcome! 🛍️ Looking for something specific? I can help you find the perfect product!",

    onNavigate: (pathname, options) => {
      // Navigate to product pages
      if (pathname.startsWith('/product/')) {
        window.location.href = pathname;
      }
    }
  });

  // Track shopping events
  window.addEventListener('message', function(event) {
    if (event.data && event.data.type === 'LUA_POP_EVENT') {
      console.log('Shopping event:', event.data.eventType);
    }
  });
</script>
```

## Hotel Booking Assistant

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "hotel-concierge",
    chatTitle: "Hotel Concierge",
    buttonText: "🛎️ Concierge",
    buttonColor: "#d4af37",
    position: "bottom-right",
    welcomeMessage: "Welcome to Luxury Resort & Spa! 🌴 How may I assist you with your stay today?",

    popupButtonStyles: {
      borderRadius: "50%",
      width: "70px",
      height: "70px",
      boxShadow: "0 4px 20px rgba(212, 175, 55, 0.3)"
    },
    
    chatTitleHeaderStyles: {
      background: "linear-gradient(135deg, #d4af37, #ffd700)",
      color: "#2c3e50"
    },
    
    chatHeaderSubtitle: {
      visible: true,
      brandName: "Luxury Resort & Spa",
      iconUrl: "/hotel-logo.png"
    }
  });
</script>
```

## SaaS Onboarding Assistant

```javascript theme={null}
// Check if user is new
const isNewUser = !localStorage.getItem('user_onboarded');

window.LuaPop.init({
  agentId: "onboarding-assistant",
  chatTitle: "Onboarding Assistant",
  buttonText: isNewUser ? "🚀 Get Started" : "💡 Need Help?",
  buttonColor: "#9b59b6",
  position: "bottom-right",
  welcomeMessage: isNewUser 
    ? "Welcome aboard! 🚀 I'm here to help you get started. What would you like to set up first?"
    : "Hey! 👋 Need help with anything?",
  voiceModeEnabled: true,
  sessionId: `user-${Date.now()}`,
  
  onNavigate: (pathname, options) => {
    const section = pathname.replace('/', '');
    document.getElementById(section)?.scrollIntoView({ behavior: 'smooth' });
  }
});

// Auto-open for new users
if (isNewUser) {
  setTimeout(() => {
    document.querySelector('.lua-pop-button')?.click();
    localStorage.setItem('user_onboarded', 'true');
  }, 2000);
}
```

## Embedded Documentation Chat

```html theme={null}
<div style="display: flex; gap: 20px;">
  <!-- Documentation content -->
  <div style="flex: 1;">
    <h1>Documentation</h1>
    <p>API reference and guides...</p>
  </div>
  
  <!-- Embedded chat assistant -->
  <div id="docs-chat" style="width: 400px; height: 800px; border: 1px solid #ddd; border-radius: 8px;"></div>
</div>

<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "docs-assistant",
    displayMode: "embedded",
    embeddedDisplayConfig: {
      targetContainerId: "docs-chat"
    },
    chatTitle: "Documentation Assistant",
    welcomeMessage: "Hi! I can help you find anything in our documentation. What are you looking for?",
    chatInputPlaceholder: "Search documentation..."
  });
</script>
```

## Conditional Loading

```javascript theme={null}
class ConditionalChatLoader {
  constructor() {
    this.shouldLoad = this.checkConditions();
    if (this.shouldLoad) {
      this.loadChat();
    }
  }

  checkConditions() {
    // Only load on support pages
    if (window.location.pathname.includes('/support')) return true;
    
    // Only load for logged-in users
    if (document.cookie.includes('user_logged_in=true')) return true;
    
    // Only load during business hours
    const hour = new Date().getHours();
    if (hour >= 9 && hour <= 17) return true;
    
    return false;
  }

  loadChat() {
    window.LuaPop.init({
      agentId: "conditional-agent",
      position: "bottom-right"
    });
  }
}

new ConditionalChatLoader();
```

## Multi-Agent Setup

```javascript theme={null}
// Different agents for different pages
const agentMap = {
  '/': 'general-support',
  '/pricing': 'sales-agent',
  '/docs': 'technical-support',
  '/support': 'customer-service'
};

function getAgentForPage() {
  const path = window.location.pathname;
  return agentMap[path] || agentMap['/'];
}

window.LuaPop.init({
  agentId: getAgentForPage(),
  position: "bottom-right",
  runtimeContext: `page:${window.location.pathname}`
});
```

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="cog" href="/chat-widget/configuration">
    All configuration options
  </Card>

  <Card title="Migration" icon="arrows-turn-right" href="/chat-widget/migration">
    Migrate from other chat widgets
  </Card>
</CardGroup>


# Framework Integration
Source: https://docs.heylua.ai/chat-widget/frameworks

Integrate LuaPop with React, Vue, Angular, and more

## React

### Basic Integration

```tsx theme={null}
import { useEffect } from 'react';

export default function ChatWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return null;
}
```

### With Environment Variables

```tsx theme={null}
// components/ChatWidget.tsx
import { useEffect } from 'react';

export default function ChatWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: process.env.REACT_APP_AGENT_ID,
        environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging',
        position: "bottom-right",
        sessionId: `user-${Date.now()}`
      });
    };
    document.body.appendChild(script);
  }, []);

  return null;
}
```

## Next.js

### App Router

```tsx theme={null}
// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        
        <Script 
          src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"
          strategy="lazyOnload"
          onLoad={() => {
            window.LuaPop?.init({
              agentId: process.env.NEXT_PUBLIC_AGENT_ID,
              environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging',
              position: "bottom-right"
            });
          }}
        />
      </body>
    </html>
  );
}
```

### Pages Router

```tsx theme={null}
// pages/_app.tsx
import Script from 'next/script';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      
      <Script 
        src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"
        strategy="lazyOnload"
        onLoad={() => {
          window.LuaPop?.init({
            agentId: process.env.NEXT_PUBLIC_AGENT_ID,
            position: "bottom-right"
          });
        }}
      />
    </>
  );
}
```

## Vue.js

### Vue 3

```vue theme={null}
<template>
  <div>
    <!-- Your app content -->
  </div>
</template>

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
  script.onload = () => {
    window.LuaPop?.init({
      agentId: import.meta.env.VITE_AGENT_ID,
      position: "bottom-right"
    });
  };
  document.body.appendChild(script);
});
</script>
```

### Nuxt.js

```vue theme={null}
<!-- plugins/luapop.client.ts -->
export default defineNuxtPlugin(() => {
  if (process.client) {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: useRuntimeConfig().public.agentId,
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);
  }
});
```

## Angular

```typescript theme={null}
// app.component.ts
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <router-outlet></router-outlet>
  `
})
export class AppComponent implements OnInit {
  ngOnInit() {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      (window as any).LuaPop?.init({
        agentId: environment.agentId,
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);
  }
}
```

## Svelte

```svelte theme={null}
<!-- ChatWidget.svelte -->
<script>
  import { onMount } from 'svelte';

  onMount(() => {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: import.meta.env.VITE_AGENT_ID,
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);
  });
</script>
```

## WordPress

### Using Theme Editor

```php theme={null}
<!-- Add to footer.php before </body> -->
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "<?php echo get_option('luapop_agent_id', 'your-agent-id'); ?>",
    position: "bottom-right",
    chatTitle: "<?php bloginfo('name'); ?> Support"
  });
</script>
```

### Using Plugin (Recommended)

Install plugin like "Insert Headers and Footers" or "Code Snippets" and add the LuaPop initialization code to the footer.

## Shopify

```liquid theme={null}
<!-- Add to theme.liquid before </body> -->
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "{{ settings.luapop_agent_id }}",
    chatTitle: "{{ shop.name }} Assistant",
    buttonText: "🛍️ Shop Help",
    position: "bottom-right",
    {% if customer %}
    sessionId: "customer-{{ customer.id }}",
    runtimeContext: "customer:{{ customer.email }}"
    {% endif %}
  });
</script>
```

## TypeScript Support

```typescript theme={null}
declare global {
  interface Window {
    LuaPop: {
      init: (config: LuaPopConfig) => { destroy: () => void };
      config?: LuaPopConfig;
    };
  }
}

interface LuaPopConfig {
  agentId: string;
  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
  buttonText?: string;
  buttonColor?: string;
  environment?: "staging" | "production" | "custom";
  sessionId?: string;
  authToken?: string;
  displayMode?: "floating" | "embedded";
  draggable?: boolean;
  voiceModeEnabled?: boolean;
  welcomeMessage?: string;
  chatInputPlaceholder?: string;
  chatTitle?: string;
  onNavigate?: (pathname: string, options: { query: Record<string, string> }) => void;
  // ... other options
}

// Usage with type safety
window.LuaPop.init({
  agentId: "your-agent-id",
  position: "bottom-right" // TypeScript autocomplete works!
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Environment Variables">
    ```tsx theme={null}
    // ✅ Good
    agentId: process.env.REACT_APP_AGENT_ID

    // ❌ Bad
    agentId: "hardcoded-id"
    ```
  </Accordion>

  <Accordion title="Cleanup in useEffect">
    ```tsx theme={null}
    useEffect(() => {
      // Load script
      const script = document.createElement('script');
      document.body.appendChild(script);
      
      // Cleanup
      return () => {
        document.body.removeChild(script);
      };
    }, []);
    ```
  </Accordion>

  <Accordion title="Handle SSR">
    ```tsx theme={null}
    // Next.js - only run on client
    useEffect(() => {
      if (typeof window !== 'undefined') {
        // Load LuaPop
      }
    }, []);
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="cog" href="/chat-widget/configuration">
    Complete configuration options
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See framework-specific examples
  </Card>
</CardGroup>


# Installation
Source: https://docs.heylua.ai/chat-widget/installation

Install LuaPop on your website or application

## Configuration Approaches

You can configure the widget in two ways — choose what works best for your workflow:

<CardGroup>
  <Card title="Dashboard Settings" icon="sliders">
    Configure appearance and behavior in the Lua AI admin dashboard. Call `window.LuaPop.init()` with no arguments — the widget pulls settings automatically.
  </Card>

  <Card title="Inline Config" icon="code">
    Pass configuration directly to `window.LuaPop.init({...})`. Useful for dynamic values or overriding specific dashboard settings.
  </Card>
</CardGroup>

<Info>
  **Configuration priority:** Inline config passed to `window.LuaPop.init({...})` always takes priority over dashboard settings. To rely entirely on dashboard settings, call `window.LuaPop.init()` with no arguments.
</Info>

## Site Whitelisting

<Warning>
  **You must whitelist your domain before the widget will load.** The widget silently refuses to initialise on any domain not in the allowed list.
</Warning>

<Steps>
  <Step title="Open the dashboard">
    Go to the **Chat Widget** section in your [Lua AI admin dashboard](https://admin.heylua.ai/).
  </Step>

  <Step title="Add your domain">
    Under **Customization**, add each domain where you want the widget to appear (e.g. `https://yoursite.com`).
  </Step>

  <Step title="Save">
    Save your settings. The widget will only initialise on whitelisted domains — requests from unlisted origins are blocked.
  </Step>
</Steps>

<Warning>
  **Testing on localhost?** `localhost` cannot be whitelisted. You must pass your config inline and set `environment: "production"` explicitly — this bypasses the domain whitelist check so the widget loads during local development:

  ```html theme={null}
  <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
  <script>
    window.LuaPop.init({
      agentId: "your-agent-id",
      environment: "production"
    });
  </script>
  ```
</Warning>

## Installation Methods

<CardGroup>
  <Card title="CDN Script" icon="link">
    Quickest setup — no build process
  </Card>

  <Card title="NPM Package" icon="box">
    For modern frameworks and build tools
  </Card>
</CardGroup>

## CDN Installation (Recommended)

Perfect for static websites, WordPress, Shopify, or any HTML page.

### Step 1: Add Script Tag

Add this code right before the closing `</body>` tag:

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
```

### Step 2: Initialize

**Using dashboard settings (recommended):**

```html theme={null}
<script>
  window.LuaPop.init();
</script>
```

**Using inline config (advanced / overrides):**

```html theme={null}
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    position: "bottom-right",
  });
</script>
```

### Complete Example

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Website</h1>
  <p>Your content here...</p>

  <!-- LuaPop Chat Widget — settings pulled from the Lua AI dashboard -->
  <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
  <script>
    window.LuaPop.init();
  </script>
</body>
</html>
```

## NPM Installation

For React, Vue, Angular, or other modern frameworks.

### Step 1: Install Package

<CodeGroup>
  ```bash npm theme={null}
  npm install @lua/pop
  ```

  ```bash yarn   theme={null}
  yarn add @lua/pop
  ```

  ```bash pnpm theme={null}
  pnpm add @lua/pop
  ```
</CodeGroup>

### Step 2: Import and Use

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    import { LuaPopWidget } from '@lua/pop';
    import '@lua/pop/dist/style.css';

    function App() {
      return (
        <div>
          {/* Your app content */}
          
          <LuaPopWidget 
            config={{
              agentId: "your-agent-id",
              position: "bottom-right",
              buttonText: "Chat with AI"
            }}
            apiUrl="https://api.heylua.ai"
            cdnUrl="https://cdn.heylua.ai"
            authUrl="https://auth.heylua.ai"
          />
        </div>
      );
    }
    ```
  </Tab>

  <Tab title="Vue 3">
    ```vue theme={null}
    <template>
      <div>
        <!-- Your app content -->
        <LuaPopWidget :config="chatConfig" />
      </div>
    </template>

    <script setup>
    import { LuaPopWidget } from '@lua/pop';
    import '@lua/pop/dist/style.css';

    const chatConfig = {
      agentId: "your-agent-id",
      position: "bottom-right",
    };
    </script>
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { LuaPopWidget, LuaPopConfig } from '@lua/pop';
    import '@lua/pop/dist/style.css';

    const config: LuaPopConfig = {
      agentId: "your-agent-id",
      position: "bottom-right",
      buttonText: "Chat with AI"
    };

    // Use in your framework
    ```
  </Tab>
</Tabs>

## Platform-Specific Installation

### WordPress

<Steps>
  <Step title="Access Theme Editor">
    Go to **Appearance** → **Theme File Editor**
  </Step>

  <Step title="Edit footer.php">
    Find your theme's `footer.php` file
  </Step>

  <Step title="Add Script">
    Add before `</body>`:

    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init({
        agentId: "<?php echo get_option('luapop_agent_id'); ?>",
        position: "bottom-right",
      });
    </script>
    ```
  </Step>
</Steps>

**Alternative:** Use plugin like "Insert Headers and Footers" to add the script without editing theme files.

### Shopify

<Steps>
  <Step title="Access Theme Editor">
    Go to **Online Store** → **Themes** → **Edit code**
  </Step>

  <Step title="Edit theme.liquid">
    Find `theme.liquid` in **Layout** folder
  </Step>

  <Step title="Add Script">
    Add before `</body>`:

    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init({
        agentId: "your-agent-id",
        chatTitle: "Shop Assistant",
        buttonText: "🛍️ Shop Help",
        position: "bottom-right",
      });
    </script>
    ```
  </Step>

  <Step title="Save and Test">
    Click **Save** and view your store
  </Step>
</Steps>

### Wix

<Steps>
  <Step title="Add Custom Code">
    Go to **Settings** → **Custom Code**
  </Step>

  <Step title="Add to Body End">
    Click **+ Add Custom Code** → **Body - end**
  </Step>

  <Step title="Paste Code">
    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init({
        agentId: "your-agent-id",
        position: "bottom-right",
      });
    </script>
    ```
  </Step>

  <Step title="Apply to All Pages">
    Select "All pages" and click **Apply**
  </Step>
</Steps>

### Squarespace

<Steps>
  <Step title="Access Code Injection">
    Go to **Settings** → **Advanced** → **Code Injection**
  </Step>

  <Step title="Add to Footer">
    In the **Footer** section, add:

    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    </script>
    ```
  </Step>

  <Step title="Save">
    Click **Save** and your chat widget will appear on all pages
  </Step>
</Steps>

### Webflow

<Steps>
  <Step title="Open Project Settings">
    Go to **Project Settings** → **Custom Code**
  </Step>

  <Step title="Add to Footer Code">
    Paste in **Footer Code** section:

    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    </script>
    ```
  </Step>

  <Step title="Publish">
    Publish your site to see the widget
  </Step>
</Steps>

## Single Page Applications

### React

```tsx theme={null}
// components/ChatWidget.tsx
import { useEffect } from 'react';

export default function ChatWidget() {
  useEffect(() => {
    // Load LuaPop script
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: process.env.NEXT_PUBLIC_AGENT_ID,
        position: "bottom-right",
        sessionId: `user-${Date.now()}`
      });
    };
    document.body.appendChild(script);

    // Cleanup
    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return null;
}

// In your main App component
import ChatWidget from './components/ChatWidget';

function App() {
  return (
    <div>
      {/* Your app */}
      <ChatWidget />
    </div>
  );
}
```

### Next.js

```tsx theme={null}
// app/layout.tsx or pages/_app.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        
        {/* LuaPop Widget */}
        <Script 
          src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"
          strategy="lazyOnload"
          onLoad={() => {
            window.LuaPop?.init({
              agentId: process.env.NEXT_PUBLIC_AGENT_ID,
              position: "bottom-right"
            });
          }}
        />
      </body>
    </html>
  );
}
```

<Card title="More Framework Examples" icon="code" href="/chat-widget/frameworks">
  Vue, Angular, Svelte, and more
</Card>

## Verification

### Check Installation

Open your website and verify:

<Steps>
  <Step title="Chat Button Appears">
    Look for the chat button in your chosen position
  </Step>

  <Step title="Button Opens Chat">
    Click the button - chat window should open
  </Step>

  <Step title="Chat Responds">
    Send a test message - AI should respond
  </Step>

  <Step title="No Console Errors">
    Check browser console (F12) - no errors should appear
  </Step>
</Steps>

### Browser Console Check

```javascript theme={null}
// Type this in browser console to verify LuaPop loaded
console.log(window.LuaPop);
// Should show the LuaPop object

// Check current configuration
console.log(window.LuaPop.config);
// Should show your configuration
```

## Environment Variables

For different environments, use environment variables:

<Tabs>
  <Tab title="React/Next.js">
    ```env theme={null}
    # .env.local
    NEXT_PUBLIC_AGENT_ID=your-agent-id
    NEXT_PUBLIC_LUAPOP_ENV=production
    ```

    ```tsx theme={null}
    window.LuaPop.init({
      agentId: process.env.NEXT_PUBLIC_AGENT_ID,
      environment: process.env.NEXT_PUBLIC_LUAPOP_ENV
    });
    ```
  </Tab>

  <Tab title="Vue">
    ```env theme={null}
    # .env
    VUE_APP_AGENT_ID=your-agent-id
    VUE_APP_LUAPOP_ENV=production
    ```

    ```javascript theme={null}
    window.LuaPop.init({
      agentId: process.env.VUE_APP_AGENT_ID,
      environment: process.env.VUE_APP_LUAPOP_ENV
    });
    ```
  </Tab>

  <Tab title="Angular">
    ```typescript theme={null}
    // environment.ts
    export const environment = {
      agentId: 'your-agent-id',
      luaPopEnv: 'production'
    };
    ```

    ```typescript theme={null}
    import { environment } from './environments/environment';

    window.LuaPop.init({
      agentId: environment.agentId,
      environment: environment.luaPopEnv
    });
    ```
  </Tab>
</Tabs>

## Security Considerations

<Warning>
  **Never expose sensitive agent credentials in client-side code!**
</Warning>

### Best Practices

* ✅ Use environment-specific agent IDs
* ✅ Use `staging` environment for development
* ✅ Generate unique session IDs per user
* ✅ Don't store user PII in `runtimeContext`
* ✅ Use HTTPS on your website

### Example Secure Setup

```javascript theme={null}
window.LuaPop.init({
  agentId: process.env.LUAPOP_AGENT_ID, // From environment
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging',
  sessionId: generateSecureSessionId(), // Your session logic
  authToken: await getAuthToken() // If using authenticated users
});
```

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="cog" href="/chat-widget/configuration">
    Complete configuration reference
  </Card>

  <Card title="Customization" icon="palette" href="/chat-widget/styling">
    Style the widget to match your brand
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See real-world implementations
  </Card>

  <Card title="Troubleshooting" icon="circle-question" href="/chat-widget/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>


# LuaPop Chat Widget
Source: https://docs.heylua.ai/chat-widget/introduction

Embeddable AI chat widget for your website

## Overview

**LuaPop** is a powerful, embeddable chat widget that brings AI-powered conversations directly to your website. Similar to Intercom or Zendesk, but powered by Lua AI technology for intelligent, context-aware customer interactions.

<Card title="Get Started in 2 Minutes" icon="rocket" href="/chat-widget/quick-start">
  Add AI chat to your website with a single script tag
</Card>

## Key Features

<CardGroup>
  <Card title="One-Line Integration" icon="code">
    Add to any website with a single script tag
  </Card>

  <Card title="AI-Powered" icon="robot">
    Intelligent responses using Lua AI technology
  </Card>

  <Card title="Highly Customizable" icon="palette">
    Colors, positions, themes, and branding
  </Card>

  <Card title="Mobile Responsive" icon="mobile">
    Perfect experience across all devices
  </Card>

  <Card title="Secure Authentication" icon="lock">
    Token-based security with session management
  </Card>

  <Card title="Rich Media Support" icon="image">
    Images, files, location sharing, and more
  </Card>

  <Card title="Voice Chat" icon="microphone">
    Optional voice interaction capabilities
  </Card>

  <Card title="Real-time Updates" icon="bolt">
    Live message synchronization via WebSockets
  </Card>
</CardGroup>

## Quick Preview

```html theme={null}
<!-- Add this to your website -->
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    position: "bottom-right",
    buttonText: "Chat with AI",
    environment: "production"
  });
</script>
```

## Display Modes

<Tabs>
  <Tab title="Floating Widget">
    **Perfect for most websites**

    Appears as a floating button that opens a chat window

    ```javascript theme={null}
    window.LuaPop.init({
      agentId: "your-agent-id",
      displayMode: "floating", // Default
      position: "bottom-right"
    });
    ```

    Great for:

    * General website support
    * E-commerce assistance
    * Always-available help
  </Tab>

  <Tab title="Embedded Widget">
    **Integrate into your page layout**

    Chat appears in a specific container on your page

    ```javascript theme={null}
    window.LuaPop.init({
      agentId: "your-agent-id",
      displayMode: "embedded",
      embeddedDisplayConfig: {
        targetContainerId: "chat-container"
      }
    });
    ```

    Great for:

    * Dedicated support pages
    * Help center integration
    * Custom page layouts
  </Tab>
</Tabs>

## Use Cases

<CardGroup>
  <Card title="Customer Support" icon="headset">
    24/7 AI-powered customer service

    Answer FAQs, help with orders, troubleshoot issues
  </Card>

  <Card title="Sales Assistant" icon="cart-shopping">
    Boost conversions with shopping help

    Product recommendations, cart assistance, checkout help
  </Card>

  <Card title="Product Guide" icon="compass">
    Help users navigate your product

    Feature explanations, tutorials, onboarding
  </Card>

  <Card title="Documentation Assistant" icon="book">
    Make docs searchable and interactive

    Answer questions, find articles, guide users
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Add Script">
    Include LuaPop script on your website
  </Step>

  <Step title="Configure">
    Set your agent ID and customization options
  </Step>

  <Step title="Chat Opens">
    Users click the chat button to start conversation
  </Step>

  <Step title="AI Responds">
    Your Lua AI agent provides intelligent responses
  </Step>

  <Step title="Tools Execute">
    AI uses your skills to take actions (search, create orders, etc.)
  </Step>
</Steps>

## Installation Options

<Tabs>
  <Tab title="CDN (Recommended)">
    **Quickest setup - no build process needed**

    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init({
        agentId: "your-agent-id"
      });
    </script>
    ```
  </Tab>

  <Tab title="NPM Package">
    **For React, Vue, Angular, etc.**

    ```bash theme={null}
    npm install @lua/pop
    ```

    ```tsx theme={null}
    import { LuaPopWidget } from '@lua/pop';
    import '@lua/pop/dist/style.css';

    <LuaPopWidget config={{
      agentId: "your-agent-id"
    }} />
    ```
  </Tab>
</Tabs>

## Key Benefits

<AccordionGroup>
  <Accordion title="🚀 Fast Integration">
    Add AI chat to your website in under 2 minutes. No complex setup or configuration required.
  </Accordion>

  <Accordion title="🤖 AI-Powered from Day One">
    Unlike traditional chat widgets that require human agents, LuaPop uses AI to provide instant, intelligent responses 24/7.
  </Accordion>

  <Accordion title="🎨 Fully Customizable">
    Match your brand with custom colors, fonts, positions, and styling. Complete control over appearance.
  </Accordion>

  <Accordion title="📱 Mobile-First Design">
    Automatically optimized for mobile devices with responsive layouts and touch-friendly interfaces.
  </Accordion>

  <Accordion title="🔒 Enterprise Security">
    Token-based authentication, HTTPS encryption, session isolation, and GDPR compliance built-in.
  </Accordion>

  <Accordion title="📊 Analytics Ready">
    Built-in event system integrates seamlessly with Google Analytics, Mixpanel, or custom analytics.
  </Accordion>
</AccordionGroup>

## Quick Comparison

| Feature               | LuaPop           | Traditional Chat Widgets |
| --------------------- | ---------------- | ------------------------ |
| **AI Responses**      | ✅ Built-in       | ❌ Requires integration   |
| **24/7 Availability** | ✅ Always on      | ❌ Human availability     |
| **Setup Time**        | ⚡ 2 minutes      | ⏰ Hours/days             |
| **Voice Chat**        | ✅ Optional       | ❌ Usually not available  |
| **Customization**     | ✅ Extensive      | 🟡 Limited               |
| **Mobile Optimized**  | ✅ Automatic      | 🟡 Varies                |
| **Cost**              | 💰 Pay per usage | 💰💰 Monthly fees        |

## Next Steps

<Steps>
  <Step title="Quick Start">
    Get LuaPop running on your website in 2 minutes

    <Card title="Quick Start Guide" icon="rocket" href="/chat-widget/quick-start" />
  </Step>

  <Step title="Customize">
    Match your brand with custom styling

    <Card title="Styling Guide" icon="palette" href="/chat-widget/styling" />
  </Step>

  <Step title="Integrate">
    Add to React, Vue, or any framework

    <Card title="Framework Integration" icon="code" href="/chat-widget/frameworks" />
  </Step>

  <Step title="Track Events">
    Monitor chat interactions and analytics

    <Card title="Analytics Guide" icon="chart-line" href="/chat-widget/analytics" />
  </Step>
</Steps>

## Resources

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/chat-widget/quick-start">
    2-minute setup guide
  </Card>

  <Card title="Configuration" icon="cog" href="/chat-widget/configuration">
    Complete configuration reference
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    Real-world implementations
  </Card>

  <Card title="Migration" icon="arrows-turn-right" href="/chat-widget/migration">
    Migrate from Intercom, Zendesk, etc.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/chat-widget/analytics">
    Track chat interactions
  </Card>

  <Card title="Troubleshooting" icon="circle-question" href="/chat-widget/troubleshooting">
    Common issues & solutions
  </Card>
</CardGroup>

## Popular Implementations

<AccordionGroup>
  <Accordion title="E-commerce Store">
    Shopping assistant that helps with product discovery and checkout

    Features: Product search, cart management, order tracking
  </Accordion>

  <Accordion title="SaaS Platform">
    Onboarding assistant for new users

    Features: Feature guidance, setup help, troubleshooting
  </Accordion>

  <Accordion title="Hotel Website">
    Booking concierge for reservations

    Features: Room availability, booking creation, local recommendations
  </Accordion>

  <Accordion title="Healthcare Portal">
    Patient assistance for appointments and information

    Features: Appointment scheduling, prescription refills, general info
  </Accordion>
</AccordionGroup>

## Need Help?

<CardGroup>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Chat with other builders and get help
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.heylua.ai">
    Complete guides and references
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@heylua.ai">
    Email our support team
  </Card>
</CardGroup>


# Migration Guide
Source: https://docs.heylua.ai/chat-widget/migration

Migrate from Intercom, Zendesk, Drift, and other chat widgets

## Overview

This guide helps you migrate from popular chat widgets to LuaPop with minimal disruption.

## From Intercom

### Before (Intercom)

```html theme={null}
<script>
  window.intercomSettings = {
    app_id: "your_app_id",
    name: "John Doe",
    email: "john@example.com"
  };
</script>
<script>
  (function(){var w=window;var ic=w.Intercom;...})();
</script>
```

### After (LuaPop)

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    sessionId: "john-doe-123",
    position: "bottom-right",
    welcomeMessage: "Hi John! 👋 How can I help you today?",
    runtimeContext: "user:john@example.com"
  });
</script>
```

### Migration Benefits

* ✅ **Simpler Setup** - Single script tag vs complex initialization
* ✅ **AI-Powered** - Intelligent responses vs human-only support
* ✅ **24/7 Availability** - AI never sleeps
* ✅ **Lower Cost** - Pay per usage vs monthly fees

## From Zendesk Chat

### Before (Zendesk)

```html theme={null}
<script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=your-key"></script>
<script>
  zE('webWidget', 'updateSettings', {
    webWidget: {
      color: { theme: '#78a300' }
    }
  });
</script>
```

### After (LuaPop)

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    position: "bottom-right",
    buttonColor: "#78a300"
  });
</script>
```

## From Drift

### Before (Drift)

```javascript theme={null}
drift.load('your-drift-id');
```

### After (LuaPop)

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    position: "bottom-right",
    buttonText: "👋 Let's chat",
    buttonColor: "#2d88ff",
    voiceModeEnabled: true
  });
</script>
```

## From Tawk.to

### Before (Tawk.to)

```javascript theme={null}
var Tawk_API = Tawk_API || {};
(function(){
  var s1=document.createElement("script");
  s1.src='https://embed.tawk.to/your-tawk-id/default';
  document.head.appendChild(s1);
})();
```

### After (LuaPop)

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    position: "bottom-right",
    buttonColor: "#00b894"
  });
</script>
```

## Configuration Mapping

| Feature             | Intercom                   | Zendesk       | Drift                | LuaPop           |
| ------------------- | -------------------------- | ------------- | -------------------- | ---------------- |
| **ID**              | `app_id`                   | `key`         | `drift-id`           | `agentId`        |
| **Position**        | Not configurable           | `position`    | Not configurable     | `position`       |
| **Color**           | `color_override`           | `color.theme` | `theme.primaryColor` | `buttonColor`    |
| **Button Text**     | Not available              | Custom CSS    | `teaser.text`        | `buttonText`     |
| **Welcome Message** | `custom_launcher_selector` | Limited       | `teaser.text`        | `welcomeMessage` |
| **User ID**         | `user_id`                  | Custom        | `userId`             | `sessionId`      |

## Event Migration

### From Intercom Events

<CodeGroup>
  ```javascript Intercom theme={null}
  Intercom('onShow', function() {
    console.log('Widget opened');
  });
  ```

  ```javascript LuaPop theme={null}
  window.addEventListener('message', function(event) {
    if (event.data?.type === 'LUA_POP_EVENT') {
      if (event.data.eventType === 'widget_opened') {
        console.log('Widget opened');
      }
    }
  });
  ```
</CodeGroup>

### From Zendesk Events

<CodeGroup>
  ```javascript Zendesk theme={null}
  zE('webWidget:on', 'open', function() {
    console.log('Opened');
  });
  ```

  ```javascript LuaPop theme={null}
  window.addEventListener('message', function(event) {
    if (event.data?.type === 'LUA_POP_EVENT') {
      if (event.data.eventType === 'widget_opened') {
        console.log('Opened');
      }
    }
  });
  ```
</CodeGroup>

## Gradual Migration

Roll out LuaPop to a percentage of users:

```javascript theme={null}
class GradualMigration {
  constructor() {
    this.migrationPercentage = 25; // Start with 25%
    this.shouldUseLuaPop = this.inMigrationGroup();
    
    if (this.shouldUseLuaPop) {
      this.initLuaPop();
    } else {
      this.initLegacyChat();
    }
  }

  inMigrationGroup() {
    const userId = this.getUserId();
    const hash = this.simpleHash(userId);
    return (hash % 100) < this.migrationPercentage;
  }

  simpleHash(str) {
    let hash = 0;
    for (let i = 0; i < str.length; i++) {
      hash = ((hash << 5) - hash) + str.charCodeAt(i);
    }
    return Math.abs(hash);
  }

  getUserId() {
    return localStorage.getItem('user_id') || 'anonymous';
  }

  initLuaPop() {
    window.LuaPop.init({
      agentId: "migration-agent",
      position: "bottom-right"
    });
  }

  initLegacyChat() {
    // Your existing chat solution
  }
}

new GradualMigration();
```

## Migration Checklist

<Steps>
  <Step title="Pre-Migration">
    * [ ] Audit current chat setup
    * [ ] Document custom features
    * [ ] Plan agent configuration
    * [ ] Test LuaPop in staging
  </Step>

  <Step title="During Migration">
    * [ ] Start with 10-25% of users
    * [ ] Monitor performance metrics
    * [ ] Collect user feedback
    * [ ] Compare analytics data
  </Step>

  <Step title="Post-Migration">
    * [ ] Remove legacy chat code
    * [ ] Update documentation
    * [ ] Train support team
    * [ ] Optimize configuration
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="cog" href="/chat-widget/configuration">
    Complete configuration options
  </Card>

  <Card title="Quick Start" icon="rocket" href="/chat-widget/quick-start">
    Get started with LuaPop
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.heylua.ai/chat-widget/quick-start

Get LuaPop running on your website in 2 minutes

## Before You Start: Whitelist Your Website

<Warning>
  **You must whitelist your domain before the widget will load.** In the [Lua AI admin dashboard](https://admin.heylua.ai/), go to **Chat Widget** → **Customization** and add your website URL to the allowed sites list. The widget silently refuses to initialise on any domain not listed here.
</Warning>

<Warning>
  **Testing on localhost?** `localhost` cannot be whitelisted — the dashboard approach will not work. You must pass your configuration inline and set `environment: "production"` explicitly:

  ```html theme={null}
  <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
  <script>
    window.LuaPop.init({
      agentId: "your-agent-id",
      environment: "production"
    });
  </script>
  ```

  This bypasses the domain whitelist check so you can develop and test locally against your real agent.
</Warning>

## Setup Options

There are two ways to get the widget running. The **dashboard approach** is recommended — it requires no code changes when you update settings.

<Tabs>
  <Tab title="Dashboard (Recommended)">
    Configure everything from the Lua AI admin dashboard and embed a single script with no payload.

    <Steps>
      <Step title="Whitelist your site">
        In the admin dashboard, go to **Chat Widget** → **Customization** and add your website URL(s) to the allowed sites list. The widget will only load on whitelisted domains.
      </Step>

      <Step title="Configure in the dashboard">
        Set your agent behavior, appearance, and features directly in the dashboard UI — no code required.
      </Step>

      <Step title="Add the script">
        Copy and paste this code right before the closing `</body>` tag:

        ```html theme={null}
        <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
        <script>
          window.LuaPop.init();
        </script>
        ```
      </Step>

      <Step title="Test">
        Refresh your page — the chat button will appear using your dashboard settings.
      </Step>
    </Steps>

    <Check>
      **That's it!** Update appearance or behavior any time from the dashboard — no code deploys needed. ✨
    </Check>

    <Info>
      **Configuration priority:** If you pass options to `window.LuaPop.init({...})`, those values override the dashboard settings. To use dashboard settings exclusively, call `window.LuaPop.init()` with no arguments.
    </Info>
  </Tab>

  <Tab title="Inline Config">
    Pass configuration directly in the script for full programmatic control, or to override specific dashboard values. **This is also required when testing on localhost.**

    <Steps>
      <Step title="Add the Script">
        Copy and paste this code right before the closing `</body>` tag:

        ```html theme={null}
        <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
        <script>
          window.LuaPop.init({
            agentId: "your-agent-id",
            environment: "production",
            position: "bottom-right",
            buttonText: "Chat with AI"
          });
        </script>
        ```
      </Step>

      <Step title="Replace Agent ID">
        Get your agent ID from the [Lua AI admin dashboard](https://admin.heylua.ai/) and replace `"your-agent-id"`
      </Step>

      <Step title="Test">
        Refresh your page — you should see a chat button in the bottom-right corner!
      </Step>
    </Steps>

    <Check>
      **That's it!** Your AI chat widget is now live. ✨
    </Check>
  </Tab>
</Tabs>

## Common Setups

### Customer Support

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "support-agent-id",
    chatTitle: "Customer Support",
    buttonText: "💬 Need Help?",
    position: "bottom-right",
    welcomeMessage: "Hi there! 👋 How can we help you today?",
    chatInputPlaceholder: "Describe your issue..."
  });
</script>
```

### Sales Assistant

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "sales-agent-id",
    chatTitle: "Sales Assistant",
    buttonText: "💰 Get Quote",
    buttonColor: "#28a745",
    position: "bottom-right"
  });
</script>
```

### Embedded Chat (No Floating Button)

```html theme={null}
<!-- Create a container -->
<div id="chat-container" style="width: 400px; height: 600px;"></div>

<!-- Initialize embedded mode -->
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    displayMode: "embedded",
    embeddedDisplayConfig: {
      targetContainerId: "chat-container"
    }
  });
</script>
```

## Quick Customizations

### Change Position

<Tabs>
  <Tab title="Bottom Right">
    ```javascript theme={null}
    position: "bottom-right"
    ```
  </Tab>

  <Tab title="Bottom Left">
    ```javascript theme={null}
    position: "bottom-left"
    ```
  </Tab>

  <Tab title="Top Right">
    ```javascript theme={null}
    position: "top-right"
    ```
  </Tab>

  <Tab title="Top Left">
    ```javascript theme={null}
    position: "top-left"
    ```
  </Tab>
</Tabs>

### Custom Colors & Button

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  buttonColor: "#ff6b6b",      // Custom button color
  buttonText: "💬 Chat Now",   // Custom text
  buttonIcon: "🤖",            // Custom icon/emoji
  chatTitle: "AI Assistant"    // Custom title
});
```

## Testing Environments

### Staging (For Testing)

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  environment: "staging", // Uses api.lua.dev
  position: "bottom-right"
});
```

### Production (Live)

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  environment: "production", // Uses api.heylua.ai
  position: "bottom-right"
});
```

<Warning>
  Always test with `environment: "staging"` before switching to production!
</Warning>

## Framework Integration Quick Start

### React

```tsx theme={null}
import { useEffect } from 'react';

export default function ChatWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);
  }, []);

  return null;
}
```

### Vue

```vue theme={null}
<script>
export default {
  mounted() {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);
  }
};
</script>
```

<Card title="More Framework Examples" icon="code" href="/chat-widget/frameworks">
  See integration guides for Angular, Next.js, and more
</Card>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget not appearing?">
    **Check these:**

    1. Open browser console for JavaScript errors
    2. Verify your agent ID is correct
    3. Ensure script is loaded after DOM is ready
    4. Check if another chat widget is conflicting
  </Accordion>

  <Accordion title="Button shows but chat won't open?">
    **Solutions:**

    1. Check your internet connection
    2. Verify agent ID exists in Lua AI dashboard
    3. Try `environment: "staging"` for testing
    4. Check browser console for API errors
  </Accordion>

  <Accordion title="Styling issues?">
    **Solutions:**

    1. Check for CSS conflicts using browser dev tools
    2. Try a different position
    3. Add higher z-index:
       ```javascript theme={null}
       popupButtonStyles: {
         zIndex: "9999"
       }
       ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Full Configuration" icon="cog" href="/chat-widget/configuration">
    Explore all configuration options
  </Card>

  <Card title="Custom Styling" icon="palette" href="/chat-widget/styling">
    Match your brand perfectly
  </Card>

  <Card title="Real Examples" icon="layer-group" href="/chat-widget/examples">
    See production implementations
  </Card>

  <Card title="Track Events" icon="chart-line" href="/chat-widget/analytics">
    Monitor chat interactions
  </Card>
</CardGroup>


# Styling & Customization
Source: https://docs.heylua.ai/chat-widget/styling

Customize LuaPop to match your brand perfectly

## Custom Colors

### Button Color

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  buttonColor: "#ff6b6b"  // Any hex color
});
```

## Custom Button Styling

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  
  // Button text and icon
  buttonText: "💬 Chat Now",
  buttonIcon: "🤖",
  
  // Button styles
  popupButtonStyles: {
    borderRadius: "25px",
    width: "auto",
    height: "50px",
    padding: "0 20px",
    fontSize: "16px",
    fontWeight: "600",
    boxShadow: "0 4px 12px rgba(0,0,0,0.15)",
    transition: "all 0.3s ease"
  }
});
```

## Custom Positioning

```javascript theme={null}
popupButtonPositionalContainerStyles: {
  bottom: "30px",
  right: "30px",
  zIndex: "9999"
}
```

### Position Presets

<CodeGroup>
  ```javascript Bottom Right theme={null}
  position: "bottom-right"
  ```

  ```javascript Bottom Left theme={null}
  position: "bottom-left"
  ```

  ```javascript Top Right theme={null}
  position: "top-right"
  ```

  ```javascript Top Left theme={null}
  position: "top-left"
  ```
</CodeGroup>

## Chat Header Styling

```javascript theme={null}
chatTitleHeaderStyles: {
  background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
  color: "white",
  padding: "15px 20px",
  borderRadius: "15px 15px 0 0",
  fontWeight: "bold"
}
```

## Brand Integration

```javascript theme={null}
chatHeaderSubtitle: {
  visible: true,
  brandName: "Your Company",
  iconUrl: "https://yoursite.com/logo.png",
  linkUrl: "https://yoursite.com"
}
```

## CSS Class Overrides

```css theme={null}
/* Override button styles */
.lua-pop-button {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
  border: none !important;
  box-shadow: 0 8px 25px rgba(102, 126, 234, 0.3) !important;
}

/* Override chat header */
.lua-pop-chat-header {
  background: #2c3e50 !important;
  color: white !important;
}

/* Custom animations */
.lua-pop-widget {
  animation: slideInUp 0.3s ease-out;
}

@keyframes slideInUp {
  from {
    transform: translateY(100px);
    opacity: 0;
  }
  to {
    transform: translateY(0);
    opacity: 1;
  }
}
```

## Complete Styling Example

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  
  // Floating button position
  position: "bottom-right",
  
  // Button
  buttonText: "💬 Chat Now",
  buttonColor: "#8B5CF6",
  
  // Button custom styles
  popupButtonStyles: {
    borderRadius: "30px",
    padding: "12px 24px",
    fontSize: "15px",
    fontWeight: "600",
    boxShadow: "0 8px 20px rgba(139, 92, 246, 0.3)",
    border: "2px solid rgba(255, 255, 255, 0.3)"
  },
  
  // Positioning
  popupButtonPositionalContainerStyles: {
    bottom: "25px",
    right: "25px",
    zIndex: "9999"
  },
  
  // Chat header
  chatTitle: "AI Assistant",
  chatTitleHeaderStyles: {
    background: "linear-gradient(135deg, #8B5CF6 0%, #7C3AED 100%)",
    color: "white",
    padding: "16px 20px",
    borderRadius: "12px 12px 0 0",
    fontWeight: "700"
  },
  
  // Branding
  chatHeaderSubtitle: {
    visible: true,
    brandName: "Your Company",
    iconUrl: "/logo.png",
    linkUrl: "/"
  },
  
  // Messages
  welcomeMessage: "Hi there! 👋 How can I help you today?",
  chatInputPlaceholder: "Ask anything..."
});
```

## Next Steps

<CardGroup>
  <Card title="Events API" icon="bolt" href="/chat-widget/events">
    Listen to chat interactions
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See styling examples
  </Card>
</CardGroup>


# Troubleshooting
Source: https://docs.heylua.ai/chat-widget/troubleshooting

Common issues and solutions for LuaPop

## Common Issues

### Widget Not Appearing

<AccordionGroup>
  <Accordion title="Script not loading">
    **Check:**

    1. Open browser console (F12)
    2. Look for JavaScript errors
    3. Verify script URL is correct

    **Solution:**

    ```html theme={null}
    <!-- Ensure correct script URL -->
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    ```
  </Accordion>

  <Accordion title="Agent ID incorrect">
    **Check:**

    1. Verify agent ID from Lua AI dashboard
    2. Check for typos
    3. Ensure agent is active

    **Solution:**

    ```javascript theme={null}
    // Double-check agent ID
    console.log('Agent ID:', 'your-agent-id');
    ```
  </Accordion>

  <Accordion title="Script loads before DOM">
    **Check:**

    * Is script in `<head>` instead of before `</body>`?

    **Solution:**

    ```html theme={null}
    <!-- Move script to end of body -->
    <body>
      <!-- Your content -->
      
      <!-- LuaPop script should be here -->
      <script src="..."></script>
    </body>
    ```
  </Accordion>

  <Accordion title="CSS conflicts">
    **Check:**

    * Other chat widgets interfering
    * CSS hiding the button

    **Solution:**

    ```javascript theme={null}
    popupButtonStyles: {
      zIndex: "99999",  // Higher z-index
      display: "block !important"
    }
    ```
  </Accordion>
</AccordionGroup>

### Button Shows But Chat Won't Open

<AccordionGroup>
  <Accordion title="Network issues">
    **Check:**

    1. Open Network tab in dev tools
    2. Look for failed API requests
    3. Check internet connection

    **Solution:** Try staging environment:

    ```javascript theme={null}
    environment: "staging"
    ```
  </Accordion>

  <Accordion title="Agent not found">
    **Error:** Agent ID doesn't exist on server

    **Solution:**

    1. Verify agent exists in Lua AI dashboard
    2. Check environment matches (staging vs production)
    3. Try different agent ID
  </Accordion>

  <Accordion title="Authentication errors">
    **Check:**

    * Invalid auth token
    * Expired session

    **Solution:**

    ```javascript theme={null}
    // Remove auth token to test
    window.LuaPop.init({
      agentId: "your-agent-id",
      // authToken: "...",  // Comment out temporarily
    });
    ```
  </Accordion>
</AccordionGroup>

### Embedded Mode Issues

<AccordionGroup>
  <Accordion title="Container not found">
    **Error:** Target container doesn't exist

    **Solution:**

    ```html theme={null}
    <!-- Ensure container exists -->
    <div id="chat-container"></div>

    <script>
      // Wait for DOM to load
      window.addEventListener('load', () => {
        window.LuaPop.init({
          displayMode: "embedded",
          embeddedDisplayConfig: {
            targetContainerId: "chat-container" // Must match
          }
        });
      });
    </script>
    ```
  </Accordion>

  <Accordion title="Chat not visible">
    **Check:**

    * Container has dimensions (width/height)
    * Container is not hidden by CSS

    **Solution:**

    ```css theme={null}
    #chat-container {
      width: 400px;
      height: 600px;
      display: block;
      visibility: visible;
    }
    ```
  </Accordion>
</AccordionGroup>

### Styling Issues

<AccordionGroup>
  <Accordion title="Button in wrong position">
    **Solution:**

    ```javascript theme={null}
    popupButtonPositionalContainerStyles: {
      bottom: "20px !important",
      right: "20px !important",
      position: "fixed !important"
    }
    ```
  </Accordion>

  <Accordion title="Colors not applying">
    **Check:**

    * CSS specificity conflicts
    * Theme overrides

    **Solution:**

    ```javascript theme={null}
    // Use more specific styles
    popupButtonStyles: {
      backgroundColor: "#ff6b6b !important"
    }
    ```
  </Accordion>

  <Accordion title="Custom CSS not working">
    **Solution:** Add `!important` or increase specificity:

    ```css theme={null}
    .lua-pop-button {
      background: #ff6b6b !important;
    }

    /* Or use higher specificity */
    body .lua-pop-widget .lua-pop-button {
      background: #ff6b6b;
    }
    ```
  </Accordion>
</AccordionGroup>

### Voice Chat Issues

<AccordionGroup>
  <Accordion title="Microphone not working">
    **Check:**

    1. HTTPS enabled (required for microphone)
    2. Browser permissions granted
    3. Microphone physically working

    **Solution:**

    * Use HTTPS (voice requires secure connection)
    * Check browser permissions
    * Test microphone in other apps
  </Accordion>

  <Accordion title="Permission denied">
    **Issue:** User denied microphone permission

    **Solution:** Widget shows fallback to text input automatically
  </Accordion>
</AccordionGroup>

## Debug Mode

Enable detailed logging:

```javascript theme={null}
// Use staging for verbose logging
window.LuaPop.init({
  agentId: "your-agent-id",
  environment: "staging"  // More detailed logs
});

// Check console for detailed information
console.log('LuaPop config:', window.LuaPop.config);
```

## Browser Console Checks

### Verify LuaPop Loaded

```javascript theme={null}
// In browser console
console.log(window.LuaPop);
// Should show the LuaPop object

console.log(window.LuaPop.config);
// Should show your configuration
```

### Check for Errors

```javascript theme={null}
// Look for errors in console
// Common errors:
// - Script loading failed
// - Agent not found
// - Network errors
// - Permission denied
```

## Getting Help

### Diagnostic Information

When reporting issues, include:

```javascript theme={null}
// Browser info
console.log('Browser:', navigator.userAgent);

// LuaPop version
console.log('LuaPop:', window.LuaPop);

// Configuration
console.log('Config:', window.LuaPop.config);

// Current errors
console.error('Errors:', /* copy error messages */);
```

### Support Channels

<CardGroup>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Get real-time help from the community
  </Card>

  <Card title="Documentation" icon="book">
    Search these docs
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@heylua.ai">
    Get help from our team
  </Card>
</CardGroup>

## Prevention Tips

<AccordionGroup>
  <Accordion title="Test in Staging First">
    ```javascript theme={null}
    // Always test new changes in staging
    const env = process.env.NODE_ENV === 'production' 
      ? 'production' 
      : 'staging';

    window.LuaPop.init({
      agentId: "your-agent-id",
      environment: env
    });
    ```
  </Accordion>

  <Accordion title="Use Feature Detection">
    ```javascript theme={null}
    // Check if LuaPop loaded
    if (window.LuaPop) {
      window.LuaPop.init({ /* config */ });
    } else {
      console.error('LuaPop failed to load');
      // Show fallback support option
    }
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    ```javascript theme={null}
    window.addEventListener('message', function(event) {
      if (event.data?.type === 'LUA_POP_ERROR') {
        console.error('LuaPop Error:', event.data.error);
        // Show fallback UI
        showFallbackSupport();
      }
    });
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="cog" href="/chat-widget/configuration">
    Review configuration options
  </Card>

  <Card title="Events" icon="bolt" href="/chat-widget/events">
    Learn about event system
  </Card>
</CardGroup>


# Voice Chat
Source: https://docs.heylua.ai/chat-widget/voice-chat

Enable voice interactions in your chat widget

## Overview

LuaPop supports optional voice chat functionality, allowing users to speak with your AI agent instead of typing.

## Enable Voice Chat

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  position: "bottom-right",
  voiceModeEnabled: true  // ✅ Enable voice chat
});
```

## Features

<CardGroup>
  <Card title="Speech-to-Text" icon="microphone">
    Users can speak their messages
  </Card>

  <Card title="Text-to-Speech" icon="volume-high">
    AI responses can be spoken aloud
  </Card>

  <Card title="Multi-Language" icon="globe">
    Supports multiple languages
  </Card>

  <Card title="Hands-Free" icon="hand">
    Great for accessibility and mobile
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="User Activates Voice">
    User clicks microphone icon in chat input
  </Step>

  <Step title="Browser Requests Permission">
    Browser asks for microphone access
  </Step>

  <Step title="User Speaks">
    User speaks their message
  </Step>

  <Step title="Speech-to-Text">
    Audio converted to text automatically
  </Step>

  <Step title="AI Responds">
    AI processes and responds as normal
  </Step>

  <Step title="Text-to-Speech (Optional)">
    Response can be played as audio
  </Step>
</Steps>

## Use Cases

### Accessibility

Voice chat improves accessibility for:

* Users with motor impairments
* Users who prefer speaking
* Hands-free scenarios
* Visually impaired users

### Mobile Users

Perfect for mobile where typing is harder:

```javascript theme={null}
const isMobile = window.innerWidth <= 768;

window.LuaPop.init({
  agentId: "mobile-agent",
  voiceModeEnabled: isMobile, // Enable on mobile only
  buttonText: isMobile ? "🎤 Voice Chat" : "💬 Chat"
});
```

### Driving/Hands-Free

Ideal for automotive or hands-free scenarios:

```javascript theme={null}
window.LuaPop.init({
  agentId: "hands-free-agent",
  voiceModeEnabled: true,
  chatTitle: "Voice Assistant",
  buttonText: "🎤 Voice Chat",
  welcomeMessage: "Hi! I'm your voice assistant. Tap the microphone to speak to me.",
  chatInputPlaceholder: "Click mic to speak..."
});
```

## Browser Support

Voice chat requires:

* Modern browser with Web Speech API
* HTTPS connection (required for microphone access)
* User permission for microphone

### Supported Browsers

| Browser       | Speech-to-Text | Text-to-Speech |
| ------------- | -------------- | -------------- |
| Chrome        | ✅ Full         | ✅ Full         |
| Safari        | ✅ Full         | ✅ Full         |
| Firefox       | ✅ Full         | ✅ Full         |
| Edge          | ✅ Full         | ✅ Full         |
| Mobile Safari | ✅ Full         | ✅ Full         |
| Chrome Mobile | ✅ Full         | ✅ Full         |

## Privacy & Permissions

<Warning>
  Voice chat requires user permission to access the microphone. Users must explicitly grant permission.
</Warning>

### Permission Handling

The widget automatically:

1. Requests microphone permission when needed
2. Shows appropriate UI if permission denied
3. Gracefully falls back to text-only chat

### Privacy

* Audio is processed in real-time
* No audio recordings are stored locally
* Audio converted to text server-side
* GDPR compliant

## Best Practices

<AccordionGroup>
  <Accordion title="Require HTTPS">
    Voice chat only works on HTTPS:

    ```javascript theme={null}
    const isSecure = window.location.protocol === 'https:';

    window.LuaPop.init({
      agentId: "your-agent-id",
      voiceModeEnabled: isSecure // Only enable on HTTPS
    });
    ```
  </Accordion>

  <Accordion title="Show Voice Indicator">
    Let users know voice is available:

    ```javascript theme={null}
    window.LuaPop.init({
      agentId: "your-agent-id",
      voiceModeEnabled: true,
      buttonText: "🎤 Voice Chat Available"
    });
    ```
  </Accordion>

  <Accordion title="Mobile-First for Voice">
    Voice chat is especially useful on mobile:

    ```javascript theme={null}
    const isMobile = window.innerWidth <= 768;

    window.LuaPop.init({
      agentId: "your-agent-id",
      voiceModeEnabled: true,
      buttonText: isMobile ? "🎤" : "💬 Chat",
      chatInputPlaceholder: isMobile 
        ? "Tap mic to speak" 
        : "Type or click mic to speak"
    });
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="cog" href="/chat-widget/configuration">
    All configuration options
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See voice chat implementations
  </Card>
</CardGroup>


# Authentication
Source: https://docs.heylua.ai/cli/authentication

Sign in to Lua CLI or configure an API key

## Overview

Lua CLI requires authentication to access the platform and deploy skills. For interactive work, sign in with email and keep a renewable session. For automation, configure an API key through an environment variable, a local credentials file, or a project `.env` file. The CLI does not use the system keychain.

<Note>
  New email login creates a renewable user session that follows your current organizations and agents. Login no longer asks you to choose an organization, agents, or role. Existing scoped and non-dotted legacy keys continue to work when supplied directly. Lua does not force legacy-key rotation or expiry. See [API Keys](/concepts/api-keys).
</Note>

## Commands

<CardGroup>
  <Card title="configure" icon="key">
    Set up authentication
  </Card>

  <Card title="key" icon="eye">
    Display stored key
  </Card>

  <Card title="logout" icon="right-from-bracket">
    Remove credentials
  </Card>
</CardGroup>

## lua auth configure

Sign in for interactive work or configure an API key for automation.

```bash theme={null}
lua auth configure
```

### Authentication Methods

<Tabs>
  <Tab title="Email (Recommended)">
    **Sign in with a renewable session**

    1. Choose **Email**.
    2. Enter your email address and the six-digit code sent to you.
    3. The CLI saves a renewable first-party session.
    4. Choose an agent later with `lua init` in each project directory.

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: Email
    ? Enter your email address: you@example.com
    ? Enter the OTP code: 123456
    ✅ Signed in as you@example.com.
    ```

    The CLI reads your current organizations and agents from Lua when each command runs. Creating an agent or joining another organization does not require another CLI login.
  </Tab>

  <Tab title="API Key">
    **Existing API Key**

    Use this method if you already have a scoped or legacy API key:

    1. Choose **API Key**.
    2. Enter the existing key.
    3. The CLI validates and saves the key without replacing, rotating, or revoking it.

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: API Key
    ? Enter your API key: api_abc123def456...
    🔐 Validating API key...
    ✅ API key validated and saved securely.
    ```

    Use direct keys for CI, existing integrations, and installations that already have a working credential.
  </Tab>
</Tabs>

### Non-Interactive Authentication

Direct-key setup and email OTP support non-interactive commands:

```bash theme={null}
# Direct API key (one shot)
lua auth configure --api-key "api_xxx..."

# Email OTP: request a code
lua auth configure --email you@example.com

# Email OTP: verify and save a renewable session
lua auth configure --email you@example.com --otp 123456
```

| Option            | Description                                                      |
| ----------------- | ---------------------------------------------------------------- |
| `--api-key <key>` | Validate and save an existing scoped or legacy key unchanged.    |
| `--email <email>` | Request an OTP to be sent to this email. Step 1 of the OTP flow. |
| `--otp <code>`    | Verify the six-digit code. Combine it with `--email`.            |

<Note>
  For CI, create a scoped key through a trusted setup flow, store it in your CI secret manager, and expose it as `LUA_API_KEY`. Do not put an email address, OTP, or credential into an AI conversation.
</Note>

### Where credentials are stored

Interactive sessions and API keys use separate owner-only files:

```
~/.lua-cli/sessions/<environment>.json
~/.lua-cli/credentials
```

Email login stores renewable session data in the environment-specific session file. Direct API-key setup writes `~/.lua-cli/credentials`. On POSIX systems, both files use mode `0600`.

The file contains the secret as plaintext. The "saved securely" CLI message refers to the owner-only file permissions, not encryption at rest.

<Warning>
  Never commit API keys to version control or share them publicly!
</Warning>

## Environment Variable Authentication

For CI/CD, Docker, and headless servers, set the `LUA_API_KEY` environment variable directly — no credentials file needed:

```bash theme={null}
export LUA_API_KEY=your-api-key
```

The environment variable always takes priority over a renewable session or stored API key.

<Tabs>
  <Tab title="Local terminal">
    ```bash theme={null}
    export LUA_API_KEY=your-api-key
    lua push
    ```

    Add to `~/.zshrc` or `~/.bashrc` for persistence.
  </Tab>

  <Tab title=".env file">
    Create a `.env` file in your project root:

    ```bash theme={null}
    LUA_API_KEY=your-api-key
    ```

    The CLI loads `.env` automatically. Add `.env` to `.gitignore`.
  </Tab>

  <Tab title="Dockerfile">
    ```dockerfile theme={null}
    FROM node:22-slim
    ENV LUA_API_KEY=your-api-key
    RUN npm install -g lua-cli
    ```

    Or pass at runtime:

    ```bash theme={null}
    docker run -e LUA_API_KEY=your-api-key my-image lua push
    ```
  </Tab>

  <Tab title="GitHub Actions">
    ```yaml theme={null}
    - name: Deploy
      env:
        LUA_API_KEY: ${{ secrets.LUA_API_KEY }}
      run: lua push all --force
    ```

    Add `LUA_API_KEY` to your repository secrets.
  </Tab>
</Tabs>

### Key Resolution Order

The CLI checks sources in this priority order:

| Priority | Source                                                                                   | Best for                        |
| -------- | ---------------------------------------------------------------------------------------- | ------------------------------- |
| 1        | `LUA_API_KEY`; if it is not exported, the CLI loads it from the current project's `.env` | CI/CD, Docker, headless servers |
| 2        | Renewable session for the active Lua environment                                         | Interactive development         |
| 3        | `~/.lua-cli/credentials`                                                                 | Existing API-key setup          |

## lua auth key

Display a stored API key. A renewable session is never displayed as an API key.

```bash theme={null}
lua auth key
```

### Security Confirmation

For security, you must confirm before displaying the key:

```bash theme={null}
$ lua auth key
? This will display your API key. Are you sure you want to continue? Yes
🔑 Your API key:
api_abc123def456...
```

Use `--force` to skip the confirmation prompt (useful in scripts):

```bash theme={null}
lua auth key --force
```

If you signed in with email, the command confirms that you have a renewable session and does not print its credential.

### Use Cases

* **Existing key setup**: Inspect an API key saved through direct-key configuration
* **CI/CD configuration**: Copy that key into a secret manager
* **Verification**: Confirm whether a local API key is configured

## lua auth logout

Sign out and remove locally stored authentication.

```bash theme={null}
lua auth logout
```

### Confirmation Required

```bash theme={null}
$ lua auth logout
? Sign out? A renewable login also signs you out of other Lua first-party sessions. Yes
✅ Signed out and removed local authentication.
```

Use `--force` to skip the confirmation:

```bash theme={null}
lua auth logout --force
```

### What Happens

<Steps>
  <Step title="Local Authentication Removed">
    The active environment's renewable session and any locally stored API key are removed.
  </Step>

  <Step title="CLI Access Lost">
    You'll need to run `lua auth configure` or set `LUA_API_KEY` to use the CLI again
  </Step>

  <Step title="Renewable Login Signed Out">
    If you used email login, Lua also signs out your other first-party sessions. If Lua cannot confirm that remote sign-out, the CLI warns you after removing the local session.
  </Step>

  <Step title="API Key Remains Valid">
    If you used direct API-key setup, logout removes only the local copy. The key remains valid until you revoke it in the dashboard.
  </Step>
</Steps>

<Note>
  An API key still works wherever else it is configured, such as a CI environment variable. To revoke it everywhere, use **Settings → API Keys** in the admin dashboard. See [Managing a key](/concepts/api-keys#managing-a-key).
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No authentication found">
    **Error**: `No Lua CLI authentication found.`

    **Solution**: Authenticate using one of:

    ```bash theme={null}
    lua auth configure          # Email sign-in or direct API-key setup
    export LUA_API_KEY=your-key # Environment variable
    echo "LUA_API_KEY=key" >> .env  # .env file
    ```
  </Accordion>

  <Accordion title="OTP not received">
    **Problem**: Didn't receive OTP email

    **Solutions**:

    1. Check spam/junk folder
    2. Wait a few minutes (can take up to 5 min)
    3. Try again with `lua auth configure`
    4. Use API Key method instead
  </Accordion>

  <Accordion title="Invalid OTP">
    **Error**: `❌ Invalid OTP code`

    **Solutions**:

    * Double-check the code from email
    * OTP expires after 10 minutes
    * Request new OTP by running command again
  </Accordion>

  <Accordion title="API key validation failed">
    **Error**: `❌ Authentication failed`

    A `401` means the key itself is the problem — it's invalid, expired, suspended, or revoked:

    * Verify you copied the complete key
    * Check the key hasn't expired, been suspended, or been revoked in **Settings → API Keys**
    * Ensure no extra spaces
    * Create a replacement through **Settings → API Keys**

    A `403` is different — the key is valid, but its role doesn't allow the action you're attempting. Grant it a broader role or an additional organization/agent in **Settings → API Keys**. See [API Keys → Errors](/concepts/api-keys#errors).
  </Accordion>

  <Accordion title="Upgrading from v3.8.x or earlier">
    Previous versions stored credentials in the OS keychain (via `keytar`). Starting in v3.9.0, credentials are stored in `~/.lua-cli/credentials`.

    This step does not rotate or invalidate the existing key. It copies the key into a credential source that current versions read.

    **One-time migration step:**

    ```bash theme={null}
    lua auth configure
    ```

    Or set the environment variable directly:

    ```bash theme={null}
    export LUA_API_KEY=your-api-key
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Use email login for local development">
    Email login follows your current Lua access. Use `lua init` in each project to select the agent for that directory.
  </Accordion>

  <Accordion title="Use LUA_API_KEY for CI and Docker">
    Inject a scoped key from a secret manager. These environments do not need a credentials file.

    ```bash theme={null}
    # GitHub Actions
    env:
      LUA_API_KEY: ${{ secrets.LUA_API_KEY }}

    # Docker
    docker run -e LUA_API_KEY=your-key my-image lua push
    ```
  </Accordion>

  <Accordion title="Keep keys private">
    * Don't commit `.env` to git (add to `.gitignore`)
    * Don't share in chat or email
    * Use `lua auth logout` when done on shared machines
    * Rotate a key if it is exposed or when your security policy requires it
  </Accordion>

  <Accordion title="Use a Scoped Key for Each Integration">
    Create a dedicated [scoped key](/concepts/api-keys) per integration, granted only the role it needs on the organizations or agents it touches — rather than sharing one broad key everywhere. Legacy keys keep working with no expiry, but a scoped key limits what a leaked credential can do.
  </Accordion>

  <Accordion title="Disable Telemetry in CI">
    ```bash theme={null}
    LUA_TELEMETRY=false lua push
    ```

    Or set `LUA_TELEMETRY=false` in your CI environment variables.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="API Keys" icon="shield-halved" href="/concepts/api-keys">
    Legacy vs. scoped keys, roles, and key management
  </Card>

  <Card title="Initialize Project" icon="plus" href="/cli/skill-management">
    Create your first skill after authentication
  </Card>

  <Card title="Deploy Commands" icon="rocket" href="/cli/production-command">
    Deploy primitives to production
  </Card>
</CardGroup>


# Channels Command
Source: https://docs.heylua.ai/cli/channels-command

Manage agent communication channels

## Overview

The `lua channels` command provides an interactive interface for managing your agent's communication channels - connect to WhatsApp, Facebook, Email, Slack, Instagram, and more.

```bash theme={null}
lua channels
```

### Non-Interactive Mode

```bash theme={null}
# List all channels
lua channels list
```

| Action | Description                 |
| ------ | --------------------------- |
| `list` | List all connected channels |

<Note>
  **Note:** Creating and configuring channels requires interactive mode due to complex multi-step input for tokens, IDs, and other credentials.
</Note>

<CardGroup>
  <Card title="List Channels" icon="list">
    View all connected channels
  </Card>

  <Card title="Link New Channel" icon="link">
    Connect WhatsApp, Facebook, Slack, Email
  </Card>

  <Card title="Channel Details" icon="info">
    View configuration and status
  </Card>

  <Card title="Admin Dashboard" icon="gauge">
    Open visual interface
  </Card>
</CardGroup>

## Currently Supported Channels

Lua currently supports 6 communication channels:

<Tabs>
  <Tab title="📧 Email">
    **Email Integration**

    Respond to emails automatically. Two modes available:

    **Generated Inbox Requirements:**

    * Display Name

    **Existing Email Requirements:**

    * Display Name
    * Sender Email Address
    * Email forwarding setup

    **Features:**

    * Automated email responses
    * Custom sender identity
    * Professional communication
    * Generated inbox (no forwarding needed)

    **CLI Support:** ✅ Yes
  </Tab>

  <Tab title="💻 WebChat">
    **LuaPop Widget**

    Chat widget for websites.

    **Requirements:**

    * Agent ID (from lua.skill.yaml)

    **Features:**

    * Embeddable widget
    * Customizable styling
    * Voice chat support
    * Mobile responsive

    **Setup:** Code snippet (no channel connection needed)

    See [Chat Widget docs](/chat-widget/introduction)
  </Tab>

  <Tab title="💬 Facebook">
    **Facebook Messenger**

    Connect to Facebook Page messages.

    **Requirements:**

    * Page Access Token
    * Page ID

    **Features:**

    * Respond to page messages
    * Customer conversations
    * Rich media support

    **CLI Support:** ✅ Yes
  </Tab>

  <Tab title="📸 Instagram">
    **Instagram Messenger**

    Respond to Instagram DMs.

    **Requirements:**

    * Instagram Business Account
    * Linked to Facebook Page

    **Features:**

    * DM responses
    * Story replies
    * Visual platform

    **CLI Support:** ❌ Admin Dashboard only (OAuth)
  </Tab>

  <Tab title="📱 WhatsApp">
    **WhatsApp Business**

    WhatsApp Business API integration.

    **Requirements:**

    * Phone Number ID
    * WABA ID
    * Access Token

    **Features:**

    * Business messaging
    * Rich media support
    * Quality ratings
    * Global reach

    **CLI Support:** ✅ Yes
  </Tab>

  <Tab title="💼 Slack">
    **Slack Integration**

    Connect to Slack workspaces.

    **Types:**

    * Private Bot (simple)
    * Public OAuth (distributable)

    **Features:**

    * Direct messages
    * Channel messages
    * Team collaboration

    **CLI Support:** ✅ Yes (both types)
  </Tab>
</Tabs>

<Note>
  **🚀 More channels coming soon!** SMS, Microsoft Teams, Discord, Telegram, LinkedIn, and WeChat are in active development.
</Note>

## Interactive Flow

<Steps>
  <Step title="Launch Command">
    ```bash theme={null}
    lua channels
    ```

    Automatically loads agent from `lua.skill.yaml`
  </Step>

  <Step title="Choose Action">
    ```
    ✅ Using agent: myAgent

    ? What would you like to do?
      📋 List channels
      🔗 Link new channel
      🌐 Link on admin dashboard
    ```
  </Step>

  <Step title="Complete Action">
    Follow the prompts based on your selection
  </Step>
</Steps>

## List Channels

View all configured channels with detailed information:

```bash theme={null}
? What would you like to do? 📋 List channels

✅ Found 3 channel(s)

? Select a channel to view details:
❯ 📱 WHATSAPP - +15557986280
  💬 FACEBOOK - My Business Page
  💼 SLACK - My Workspace
  ← Back to main menu
```

### Channel Details View

```
📱 WHATSAPP Channel Details
──────────────────────────────────────────────────
Type:           whatsapp
Identifier:     647834045087314
Created:        2/3/2025, 10:45:46 AM
Phone Number:   +15557986280
Phone ID:       647834045087314
Status:         CONNECTED
Quality:        GREEN
WABA ID:        1390592278829291

Metadata:
  Verified Name:  My Business
  Country:        USA
──────────────────────────────────────────────────

Press Enter to continue...
```

## Link New Channel

### WhatsApp Setup

```bash theme={null}
? What would you like to do? 🔗 Link new channel
? Select channel type: 📱 WhatsApp

? Enter phone number ID: 647834045087314
? Enter WhatsApp Business Account ID (WABA ID): 1390592278829291
? Enter access token: ****

📡 Creating WhatsApp channel...

✅ WhatsApp channel created successfully!

📱 Channel Details:
   Phone Number: +15557986280
   Status: CONNECTED
   Webhook: https://wa.heylua.ai/whatsapp/webhook/...
```

<Note>
  **Next Steps for WhatsApp:**

  1. Configure webhook in Meta Business Suite
  2. Copy webhook URL from output
  3. Set webhook URL in Meta dashboard
  4. Verify webhook connection
</Note>

### Facebook Setup

```bash theme={null}
? What would you like to do? 🔗 Link new channel
? Select channel type: 💬 Facebook Messenger

? Enter Facebook page access token: ****
? Enter Facebook page ID: 705555819301071

📡 Creating Facebook channel...

✅ Facebook channel created successfully!

💬 Page Name: My Business Page
📄 Page ID: 705555819301071
🔗 Webhook: https://wa.heylua.ai/fb/webhook
```

### Email Setup

Email channels support two modes: **generated inbox** (Lua creates an address) and **existing email** (forward from your own address).

<Tabs>
  <Tab title="Generated Inbox">
    ```bash theme={null}
    ? What would you like to do? 🔗 Link new channel
    ? Select channel type: 📧 Email

    ? Select email channel mode: 📬 Generate new inbox
    ? Enter display name (shown in email header): Support Team

    📡 Creating Email channel...

    ✅ Email channel created successfully!

    📧 Display Name:    Support Team
    📬 Email Address:   agent-abc123@mail.heylua.ai

    ────────────────────────────────────────────────────
    Your agent's email inbox has been created.
    ────────────────────────────────────────────────────

    Share this address with your customers or use it
    in your workflows:
       agent-abc123@mail.heylua.ai

    Emails sent to this address will be handled by
    your agent.
    ────────────────────────────────────────────────────
    ```
  </Tab>

  <Tab title="Existing Email">
    ```bash theme={null}
    ? What would you like to do? 🔗 Link new channel
    ? Select channel type: 📧 Email

    ? Select email channel mode: 📧 Use existing email
    ? Enter display name (shown in email header): Support Team
    ? Enter sender email address: support@mybusiness.com

    📡 Creating Email channel...

    ✅ Email channel created successfully!

    📧 Display Name:    Support Team
    📧 Sender Email:    support@mybusiness.com
    📬 Forward To:      b5469c03-082e-481d-929b-663daf66bbef@mail.heylua.ai

    ────────────────────────────────────────────────────
    IMPORTANT: Email Forwarding Setup Required
    ────────────────────────────────────────────────────

    1. Log into your email provider's settings
    2. Set up email forwarding or filtering
    3. Forward all emails from support@mybusiness.com to:
       b5469c03-082e-481d-929b-663daf66bbef@mail.heylua.ai

    4. Test by sending an email to support@mybusiness.com
       Your agent will respond automatically!
    ────────────────────────────────────────────────────
    ```
  </Tab>
</Tabs>

### Slack Private Setup

```bash theme={null}
? What would you like to do? 🔗 Link new channel
? Select channel type: 🔒 Slack (Private)

? Enter Slack bot token (xoxb-...): ****

📡 Creating Slack channel...

✅ Slack channel created successfully!

💼 Bot Name: My Agent Bot
🏢 Workspace: My Workspace
🔗 Webhook: https://wa.heylua.ai/slack/webhook
```

### Slack Public Setup

```bash theme={null}
? What would you like to do? 🔗 Link new channel
? Select channel type: 🌐 Slack (Public)

? Enter Slack app ID: A09J8J6T6H0
? Enter client ID: 1234567890.123456789012
? Enter client secret: ****

📡 Creating Slack app...

✅ Slack app created successfully!

📱 App ID: A09J8J6T6H0
🔗 Redirect URI: https://auth.heylua.ai/slack/oauth_redirect/...
🎯 Webhook: https://wa.heylua.ai/slack/webhook

Next Steps:
1. Copy the redirect URI
2. Add to your Slack app OAuth settings
3. Users can now install your Slack app
```

## Open Admin Dashboard

```bash theme={null}
? What would you like to do? 🌐 Link on admin dashboard

🌐 Opening Lua Admin Dashboard...
✅ Dashboard opened in your browser

  URL: https://admin.heylua.ai
  Agent: myAgent
```

Opens the admin interface where you can:

* Manage channels visually
* Configure OAuth flows
* View channel analytics
* Test channel connections
* Monitor message delivery

## Use Cases

### Multi-Channel Agent

```bash theme={null}
# Connect all your channels
$ lua channels

→ Link WhatsApp
→ Link Facebook
→ Link Email
→ Link Slack
→ Link Instagram

# Your agent now responds on all platforms!
```

### Channel Migration

```bash theme={null}
# Moving from old WhatsApp number

# 1. List current channels
$ lua channels → List
# Note: Old number 555-0000

# 2. Add new channel
$ lua channels → Link WhatsApp
# New number: 555-1111

# 3. Verify both working
$ lua channels → List
# See both channels

# 4. Remove old channel via admin
$ lua admin
# Delete old WhatsApp channel
```

### Team Collaboration

```bash theme={null}
# Add Slack for internal team
$ lua channels → Link Slack

# Now team can chat with agent
# Useful for testing and demos
```

## Channel-Specific Features

### WhatsApp

**Phone Number Requirements:**

* Must be registered with WhatsApp Business
* Verified with Meta Business Suite
* Has active WABA (Business Account)

**Status Indicators:**

* **CONNECTED**: Ready to send/receive
* **DISCONNECTED**: Needs reconnection
* **PENDING**: Setup in progress

**Quality Ratings:**

* **GREEN**: High quality, good delivery
* **YELLOW**: Medium quality, some issues
* **RED**: Low quality, delivery problems

### Facebook

**Page Requirements:**

* Business or Creator page (not personal profile)
* Page access token with messaging permissions
* Page must be published

**Capabilities:**

* Respond to page messages
* Handle conversation threads
* Access messenger features

### Email

**Two modes available:**

* **Generated inbox** - Lua creates an email address; no forwarding setup needed
* **Existing email** - Uses your own address; requires email forwarding

**Forwarding Setup (existing email mode only):**

* Must forward to the provided Lua address
* Can use email rules/filters
* Test after setup

**Response Behavior:**

* Agent replies to incoming emails
* Uses configured display name
* Threading supported
* Attachments handled

### Slack

**Private (Bot Token):**

* Simple bot installation
* Direct messages
* Channel mentions
* App home tab

**Public (OAuth App):**

* Users install your app
* Workspace-wide presence
* OAuth consent flow
* More complex setup

## Troubleshooting

<AccordionGroup>
  <Accordion title="No agent ID found">
    **Error:**

    ```
    ❌ No agent ID found in lua.skill.yaml
    ```

    **Solution:**

    ```bash theme={null}
    lua init
    ```
  </Accordion>

  <Accordion title="Authentication missing">
    **Error:**

    ```
    ❌ No Lua CLI authentication found
    ```

    **Solution:**

    ```bash theme={null}
    lua auth configure
    ```
  </Accordion>

  <Accordion title="Channel already exists">
    **Error:**

    ```
    ❌ Channel already exists
    💡 This WhatsApp number is already connected
    ```

    **Solution:**

    * List channels to see existing
    * Use different number/account
    * Remove old channel first (via admin)
  </Accordion>

  <Accordion title="Invalid credentials">
    **Error:**

    ```
    ❌ Invalid access token
    ```

    **Solution:**

    * Verify token is correct
    * Check token hasn't expired
    * Regenerate token from platform
    * Try again with new token
  </Accordion>

  <Accordion title="Email not working">
    **Problem:** Agent not responding to emails

    **Check:**

    1. Email forwarding is configured
    2. Forward address is correct
    3. Emails are being forwarded
    4. Test by sending email
    5. Check admin dashboard for errors
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Test After Setup">
    ```bash theme={null}
    # After linking channel
    $ lua channels → List
    # Verify channel appears

    # Test by sending message
    # WhatsApp: Send to connected number
    # Email: Send to configured address
    # Slack: Message the bot
    ```
  </Accordion>

  <Accordion title="Use Admin for OAuth">
    ```bash theme={null}
    # Complex OAuth flows easier in admin
    $ lua channels → Link on admin dashboard

    # Or directly:
    $ lua admin
    # Navigate to Channels section
    ```
  </Accordion>

  <Accordion title="Document Your Channels">
    ```bash theme={null}
    # Keep track of what's connected
    $ lua channels → List

    # Document:
    - WhatsApp: +1555-798-6280
    - Facebook: Business Page
    - Email: support@company.com
    - Slack: Team workspace
    ```
  </Accordion>

  <Accordion title="Regular Channel Review">
    ```bash theme={null}
    # Monthly review
    $ lua channels → List

    # Check:
    - All channels CONNECTED
    - No expired tokens
    - Quality ratings GREEN
    - Remove unused channels
    ```
  </Accordion>
</AccordionGroup>

## Common Workflows

### Initial Setup

```bash theme={null}
# 1. Create agent
$ lua init

# 2. Deploy skills
$ lua push
$ lua deploy

# 3. Connect channels
$ lua channels

→ Link WhatsApp
→ Link Facebook  
→ Link Email

# 4. Test channels
# Send messages on each platform
# Verify agent responds
```

### Add New Channel

```bash theme={null}
# Existing agent, add channel
$ lua channels
→ Link new channel
→ Select channel type
→ Enter credentials
✅ Channel created

# Verify
$ lua channels → List
# See new channel in list
```

### Channel Audit

```bash theme={null}
# Review all channels
$ lua channels → List

# For each channel:
→ Select channel
→ Note status and details
→ Back to list

# Document findings
# Update any needed
```

## Integration with Admin Dashboard

The CLI command and admin dashboard work together:

<Tabs>
  <Tab title="CLI (Quick)">
    **Use CLI when:**

    * Setting up via terminal
    * Scripting channel creation
    * Quick channel listing
    * During development workflow

    ```bash theme={null}
    lua channels
    ```
  </Tab>

  <Tab title="Admin (Visual)">
    **Use Admin when:**

    * Visual interface preferred
    * OAuth flows needed
    * Managing many channels
    * Viewing analytics
    * Team collaboration

    ```bash theme={null}
    lua admin
    # Or
    lua channels → Link on admin dashboard
    ```
  </Tab>
</Tabs>

## Channel Requirements by Platform

### WhatsApp Business

**Before you start:**

1. Register with Meta Business Suite
2. Create WhatsApp Business Account
3. Add phone number
4. Get API access
5. Obtain access token

**Then:**

```bash theme={null}
lua channels → Link WhatsApp
# Enter: Phone ID, WABA ID, Token
```

### Facebook Messenger

**Before you start:**

1. Create Facebook Business Page
2. Create Facebook App
3. Add Messenger product
4. Get page access token

**Then:**

```bash theme={null}
lua channels → Link Facebook
# Enter: Page token, Page ID
```

### Email

**Generated inbox -- before you start:**

1. Choose a display name for your agent

**Then:**

```bash theme={null}
lua channels → Link Email
# Select: Generate new inbox
# Enter: Display name
# Done -- share the generated address
```

**Existing email -- before you start:**

1. Have email address ready
2. Access to email provider settings
3. Ability to configure forwarding

**Then:**

```bash theme={null}
lua channels → Link Email
# Select: Use existing email
# Enter: Display name, Sender email
# Configure forwarding as instructed
```

### Slack

**Private (Simple):**

1. Create Slack app
2. Add bot token scopes
3. Install to workspace
4. Copy bot token

```bash theme={null}
lua channels → Link Slack (Private)
# Enter: Bot token
```

**Public (OAuth):**

1. Create Slack app
2. Configure OAuth
3. Set redirect URLs
4. Get credentials

```bash theme={null}
lua channels → Link Slack (Public)
# Enter: App ID, Client ID, Secret
```

## Security

<Warning>
  **Token Security:**

  * All tokens are masked during input
  * Never logged or displayed
  * Stored securely server-side
  * Use environment-specific tokens
</Warning>

**Best practices:**

* Use test accounts in development
* Production tokens in production only
* Rotate tokens regularly
* Revoke compromised tokens immediately

## Next Steps

<CardGroup>
  <Card title="Admin Dashboard" icon="gauge" href="/cli/utility-commands#lua-admin">
    Visual channel management
  </Card>

  <Card title="Chat Widget" icon="comments" href="/chat-widget/introduction">
    Add website chat channel
  </Card>

  <Card title="Test Your Agent" icon="message" href="/cli/chat-command">
    Test agent responses
  </Card>

  <Card title="Production Monitor" icon="chart-line" href="/cli/production-command">
    Monitor live channels
  </Card>
</CardGroup>


# Chat Command
Source: https://docs.heylua.ai/cli/chat-command

Interactive command-line chat with your AI agent

## Overview

The `lua chat` command provides an interactive command-line interface for conversing with your Lua AI agent in both sandbox and production environments.

```bash theme={null}
lua chat
```

<Note>
  **Want to test on real channels?** You can also test your agent on WhatsApp, Facebook, Instagram, Email, and Slack without setting up your own channels. See [Quick Testing Channels](/channels/quick-testing) for instant testing on any platform.
</Note>

## Features

<CardGroup>
  <Card title="Sandbox Mode" icon="flask">
    Test with local skill overrides and persona customizations
  </Card>

  <Card title="Production Mode" icon="rocket">
    Chat with your live production agent
  </Card>

  <Card title="Interactive Loop" icon="arrows-rotate">
    Continuous conversation until exit
  </Card>

  <Card title="Multi-Skill Support" icon="layer-group">
    All skills automatically included in sandbox
  </Card>
</CardGroup>

## Prerequisites

<Steps>
  <Step title="Configure API Key">
    ```bash theme={null}
    lua auth configure
    ```
  </Step>

  <Step title="Initialize Project">
    ```bash theme={null}
    lua init
    ```

    Ensures `lua.skill.yaml` exists
  </Step>

  <Step title="Deploy Skills">
    ```bash theme={null}
    lua push
    ```

    Required for sandbox testing
  </Step>
</Steps>

## How It Works

<Steps>
  <Step title="Authentication">
    ```
    ✅ Authenticated
    ```

    Validates your API key and retrieves user data
  </Step>

  <Step title="Environment Selection">
    ```
    ? Select environment: 
      🔧 Sandbox (with skill overrides)
      🚀 Production
    ```

    Choose between sandbox (testing) or production (live)
  </Step>

  <Step title="Sandbox Setup (if Sandbox)">
    ```
    🔄 Compiling skill...
    🔄 Pushing skills to sandbox...
    ✅ Pushed 2 skills to sandbox
    ```

    Compiles and deploys your local skills to sandbox
  </Step>

  <Step title="Chat Interface">
    ```
    ============================================================
    💬 Lua Chat Interface
    Environment: 🔧 Sandbox
    Press Ctrl+C to exit
    ============================================================

    🤖 Assistant: Hi there! How can I help you today?

    👤 You: 
    ```

    Interactive conversation begins
  </Step>
</Steps>

## Sandbox vs Production

<Tabs>
  <Tab title="Sandbox Mode">
    **For Development & Testing**

    ```bash theme={null}
    $ lua chat
    ? Select environment: 🔧 Sandbox
    ```

    **Features:**

    * ✅ Local skill overrides
    * ✅ Persona customization
    * ✅ Environment variables from `.env`
    * ✅ Test before deploying

    **Setup time:** \~10-30 seconds (includes compilation)

    **Use when:**

    * Developing new features
    * Testing skill changes
    * Iterating on persona
    * Before pushing to production
  </Tab>

  <Tab title="Production Mode">
    **For Validation**

    ```bash theme={null}
    $ lua chat
    ? Select environment: 🚀 Production
    ```

    **Features:**

    * ✅ Production skills only
    * ✅ Live production persona
    * ✅ Real environment variables
    * ✅ Verify deployed changes

    **Setup time:** \~1-2 seconds

    **Use when:**

    * Validating deployed changes
    * Testing production experience
    * Verifying skill interactions
  </Tab>
</Tabs>

## Example Session

### Sandbox Mode

```bash theme={null}
$ lua chat
✅ Authenticated
? Select environment: 🔧 Sandbox (with skill overrides)
🔄 Setting up sandbox environment...
🔄 Compiling skill...
✅ Skill compiled successfully - 3 tools bundled
🔄 Pushing skills to sandbox...
✅ Pushed 2 skills to sandbox

============================================================
💬 Lua Chat Interface
Environment: 🔧 Sandbox
Press Ctrl+C to exit
============================================================

🤖 Assistant: Hi there! How can I help you today?

👤 You: What's the weather in London?
🤖 Assistant: ...
🤖 Assistant: The current weather in London is 15°C and cloudy with light wind.

👤 You: Search for laptops
🤖 Assistant: ...
🤖 Assistant: I found 5 laptops in our catalog:
1. MacBook Pro - $1999
2. Dell XPS 13 - $1299
3. ThinkPad X1 - $1499
...

👤 You: ^C

👋 Goodbye!
```

## Persona Override

### Configuration

In `lua.skill.yaml`:

```yaml theme={null}
agent:
  agentId: "agent_abc123"
  organizationId: "org_xyz789"
  persona: |
    You are a helpful customer service assistant.
    You help users with product inquiries and order management.
    Be friendly, professional, and concise.
```

**In Sandbox Mode:**

* Persona is automatically loaded and sent with each request
* Test different persona variations
* Iterate quickly

**In Production Mode:**

* Uses production persona (from server)
* No local override

## Skill Override

### How It Works

**Sandbox mode automatically:**

1. Compiles all skills in your project
2. Pushes to sandbox environment
3. Gets sandbox IDs for each skill
4. Includes all sandbox IDs in chat requests

**Example override:**

```json theme={null}
{
  "skillOverride": [
    {
      "skillId": "skill_abc123",
      "sandboxId": "sandbox_def456"
    }
  ]
}
```

The AI uses your local sandbox versions instead of production versions.

## Thread Isolation

By default, `lua chat` uses your agent's shared conversation context. Use the `--thread` flag to scope a session to an isolated thread — useful for running consecutive tests without state leaking between runs.

### Usage

```bash theme={null}
# Scope to an explicit thread ID
lua chat --thread my-test-scenario

# Auto-generate a fresh thread ID (printed at session start)
lua chat --thread

# Reuse a thread across multiple non-interactive messages
lua chat -m "step 1" --thread test-flow
lua chat -m "step 2" --thread test-flow

# Isolated test: scoped thread, auto-cleared on exit
lua chat -m "run test" -t --clear

# Explicit thread with auto-clear
lua chat -m "run test" -t my-test --clear
```

### Flags

| Flag                        | Description                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `-t, --thread [id]`         | Scope to a thread. Omit the ID to auto-generate a UUID. The active thread ID is always printed at session start.               |
| `--clear`, `--clear-thread` | Clear the thread's history when the session ends (interactive: on exit, non-interactive: after response). Requires `--thread`. |

### Clearing a Thread Manually

```bash theme={null}
lua chat clear --thread my-test-scenario
```

To clear another user's history, pass a user ID, email address, or mobile number:

```bash theme={null}
lua chat clear --user user@example.com
lua chat clear --user +1234567890 --thread my-test-scenario --force
```

`--user` requires `org:manage` for the agent. Organization-admin grants do not cascade to private agents; organization owners and sufficient explicit agent grants retain access under the shared authorization rules. Without `--user`, `lua chat clear` is strictly self-scoped.

### Testing Workflow Example

Run 10 isolated test cases against your agent, each with a clean slate:

```bash theme={null}
for i in $(seq 1 10); do
  lua chat -m "test scenario $i" -t "test-run-$i" --clear -e sandbox
done
```

## File Attachments

You can attach files to any message using `@<path>` syntax — in both interactive and non-interactive mode.

```bash theme={null}
# Attach an image
@/path/to/screenshot.png what's wrong with this UI?

# Attach a document
@report.pdf summarize this

# Mix text and attachment
check @screenshot.png and tell me what you see
```

The `@` must appear at the start of your message or after a space. Email addresses (`user@example.com`) are never treated as attachments.

### Supported File Types

<Tabs>
  <Tab title="Images">
    Sent natively to vision-capable models.

    | Extension       | Type         |
    | --------------- | ------------ |
    | `.png`          | PNG image    |
    | `.jpg`, `.jpeg` | JPEG image   |
    | `.gif`          | GIF image    |
    | `.webp`         | WebP image   |
    | `.bmp`          | Bitmap image |
    | `.tiff`, `.tif` | TIFF image   |
    | `.heic`         | HEIC image   |
  </Tab>

  <Tab title="Documents & Spreadsheets">
    If the model natively supports the format it is sent as-is; otherwise it is converted to an LLM-friendly format automatically.

    | Extension       | Type                    |
    | --------------- | ----------------------- |
    | `.pdf`          | PDF document            |
    | `.doc`, `.docx` | Word document           |
    | `.xls`, `.xlsx` | Excel spreadsheet       |
    | `.ppt`, `.pptx` | PowerPoint presentation |
    | `.odt`          | OpenDocument text       |
    | `.epub`         | E-book                  |
  </Tab>

  <Tab title="Text & Markup">
    | Extension       | Type                   |
    | --------------- | ---------------------- |
    | `.txt`          | Plain text             |
    | `.md`           | Markdown               |
    | `.csv`          | Comma-separated values |
    | `.tsv`          | Tab-separated values   |
    | `.html`, `.htm` | HTML                   |
    | `.xml`          | XML                    |
    | `.json`         | JSON                   |
    | `.rtf`          | Rich text              |
    | `.rst`          | reStructuredText       |
    | `.org`          | Org-mode               |
  </Tab>

  <Tab title="Email">
    | Extension | Type            |
    | --------- | --------------- |
    | `.eml`    | Email message   |
    | `.msg`    | Outlook message |
  </Tab>
</Tabs>

Files with unsupported extensions are left as plain text in your message — they are never silently stripped.

<Note>
  **Model support required.** Attachment support depends on the model configured for your agent. If the model doesn't support vision or file inputs, attachments won't be processed — even if the CLI sends them successfully. Check your agent's model configuration if attachments aren't being picked up.
</Note>

### Limits

* Maximum file size: **10 MB** per attachment
* Multiple attachments per message are supported

### Non-Interactive Mode

The same `@<path>` syntax works in `-m` / `--message` flags:

```bash theme={null}
lua chat -m "@screenshot.png what do you see?" -e production
lua chat -m "review @report.pdf and @notes.txt" -e sandbox
```

## Batch Mode

Test how your agent handles concurrent or rapid-fire messages with the `-b/--batch` flag. Useful for stress-testing skills that share state or for reproducing race conditions reported in production.

```bash theme={null}
# Send 3 messages concurrently
lua chat --batch "list my orders" "what's the status of order 1" "cancel order 1"

# Add a delay (ms) between dispatches
lua chat --batch "msg 1" "msg 2" "msg 3" --delay 250
```

| Option                      | Description                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `-b, --batch <messages...>` | Dispatch multiple messages and print every reply. Each message is treated as an independent turn. |
| `-d, --delay <ms>`          | Delay between batch messages in milliseconds (default: `100`).                                    |

<Note>
  Batch mode is **not** a way to scriptably hold a multi-turn conversation — each batched message is a separate turn. For ordered scripted conversations, use repeated `lua chat -m "..."` calls with `-t <thread-id>` instead.
</Note>

## Keyboard Shortcuts

| Shortcut | Action                  |
| -------- | ----------------------- |
| `Enter`  | Send message            |
| `Ctrl+C` | Exit chat               |
| `Ctrl+D` | Exit chat (alternative) |

## Best Practices

<AccordionGroup>
  <Accordion title="Development Workflow">
    1. Make changes to your skills
    2. Run `lua chat` in sandbox mode
    3. Test changes interactively
    4. Iterate until satisfied
    5. Run `lua push` to deploy
    6. Test again in production mode
    7. Deploy with `lua deploy`
  </Accordion>

  <Accordion title="Testing Strategy">
    **Start with sandbox:**

    * Test happy paths
    * Test error cases
    * Test edge cases
    * Test multi-step flows

    **Validate with production:**

    * Verify deployed changes work
    * Test with production data
    * Confirm no regressions
  </Accordion>

  <Accordion title="Persona Iteration">
    1. Update `persona` in your `LuaAgent` code (`src/index.ts`)
    2. Run `lua chat` in sandbox
    3. Test conversation style
    4. Refine persona
    5. Repeat until satisfied
    6. Deploy to production with `lua push persona`
  </Accordion>
</AccordionGroup>

## Active log probe (`agent_error` after every turn)

After every `lua chat` turn — interactive or `-m` non-interactive — the CLI runs a quiet `lua logs --type agent_error` probe scoped to the current session. The probe checks for **server-side pipeline errors that don't always surface in the chat response itself** (billing failures, schema validation failures, LLM provider errors, post-processor errors).

**When the probe is silent**, no agent errors fired during your turn — you're clean.

**When new errors fire**, the CLI prints a one-line warning at the end of the turn:

```
⚠️  2 new agent error(s) during this turn — run `lua logs --type agent_error --limit 2` to inspect.
```

**Empty response:** If the agent returns **no text** (empty stream), the CLI warns: `⚠️  The agent returned an empty response` and points you at `agent_error` and `runtime` logs so you can see what failed on the server.

Run the suggested command verbatim to inspect the errors.

To opt out (for example in CI that captures only command output), set `LUA_NO_HINTS=1`:

```bash theme={null}
LUA_NO_HINTS=1 lua chat -m "test" -e production
```

### Debugging recipe

```bash theme={null}
# Send one isolated test, then check for pipeline errors
lua chat -m "test" -t debug-1 --clear && lua logs --type agent_error --limit 5
```

See [Debugging your agent — the post-deploy loop](/cli/debugging) for the complete flow.

## Troubleshooting

<Note>
  **Debugging after a failed chat:** If a chat turn returns a wrong, empty, or error response, the CLI now automatically surfaces a count of `agent_error` logs that fired during that turn. To inspect them, run the suggested `lua logs --type agent_error --limit N` command. See [Debugging your agent — the post-deploy loop](/cli/debugging) for the canonical loop.
</Note>

<AccordionGroup>
  <Accordion title="No authentication found">
    **Error:**

    ```
    ❌ No Lua CLI authentication found
    ```

    **Solution:**

    ```bash theme={null}
    lua auth configure
    ```
  </Accordion>

  <Accordion title="Configuration file missing">
    **Error:**

    ```
    ❌ No agent ID found in lua.skill.yaml
    ```

    **Solution:**

    ```bash theme={null}
    lua init
    ```
  </Accordion>

  <Accordion title="Compilation failed">
    **Error:**

    ```
    ❌ Compilation failed
    ```

    **Solution:**

    * Fix TypeScript errors in your code
    * Check `src/index.ts` for syntax errors
    * Verify all imports are correct
  </Accordion>

  <Accordion title="Skills not in sandbox">
    **Error:**

    ```
    ❌ Failed to push skills to sandbox
    ```

    **Solution:**

    ```bash theme={null}
    lua push  # Deploy skills first
    lua chat  # Then try again
    ```
  </Accordion>

  <Accordion title="Slow responses">
    **Issue:** Long wait times in sandbox

    **Causes:**

    * First request after compilation
    * Large skill bundles
    * Network latency

    **Solution:** Subsequent messages will be faster
  </Accordion>

  <Accordion title="Persona not working">
    **Issue:** Persona override not being applied

    **Check:**

    * Using sandbox mode (not production)
    * `agent.persona` exists in `lua.skill.yaml`
    * Persona is properly formatted YAML
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup>
  <Card title="Debugging Loop" icon="bug" href="/cli/debugging">
    Canonical push → test → check flow + the active log probe
  </Card>

  <Card title="lua logs" icon="terminal" href="/cli/logs-command">
    Inspect agent\_error and tool execution logs
  </Card>

  <Card title="lua test" icon="flask">
    Test individual tools with specific inputs
  </Card>

  <Card title="lua push" icon="upload">
    Deploy skills to server
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Test Individual Tools" icon="flask" href="/cli/skill-management#lua-test">
    Test tools one at a time
  </Card>

  <Card title="Deploy to Production" icon="rocket" href="/cli/skill-management#lua-deploy">
    Push your skills live
  </Card>
</CardGroup>


# Debugging Skills
Source: https://docs.heylua.ai/cli/debugging

How to inspect tool return values and debug skill behavior at runtime

## The Core Problem

A common debugging mistake is deploying five times to fix the same bug, when a single log line plus one deployment would have shown you the root cause immediately.

If you're patching against test failures rather than the actual return shape, stop and add a `console.log` first — then deploy once.

## The 5-Step Debug Loop

<Steps>
  <Step title="Add a console.log to the suspicious spot">
    Log the actual value — not a guess, the real thing:

    ```typescript theme={null}
    async execute(input: any) {
      const results = await Data.search('articles', input.query, 5, 0.7);
      
      // ✅ Log the raw return value FIRST
      console.log('Data.search result:', JSON.stringify(results, null, 2));
      
      // Don't touch the rest of the code yet
      return results.map(entry => ({ id: entry.id, title: entry.title }));
    }
    ```

    Log the entire object so you see the actual shape, not what you assumed it would be.
  </Step>

  <Step title="Push to sandbox (not production)">
    ```bash theme={null}
    lua push
    ```

    Or use sandbox mode for even faster iteration — no push needed:

    ```bash theme={null}
    lua chat
    # Select "Sandbox" when prompted
    ```

    In sandbox mode, `lua chat` compiles and uses your local code directly. Use this for rapid iteration before committing to a push.
  </Step>

  <Step title="Send ONE test message">
    ```bash theme={null}
    # Non-interactive: send a single message and exit
    lua chat -m "search for thriller movies"
    ```

    Or in interactive mode:

    ```bash theme={null}
    lua chat
    # Type your test message, then Ctrl+C
    ```

    Send the **minimum message needed to trigger the tool**. Don't run a full conversation — you need one clean execution to inspect.
  </Step>

  <Step title="Check logs immediately">
    ```bash theme={null}
    # See the most recent 10 skill executions
    lua logs --type skill --limit 10

    # Filter to a specific skill by name
    lua logs --type skill --name my-skill --limit 5

    # JSON output for piping/scripting
    lua logs --type skill --json | head -100
    ```

    Your `console.log` output appears in the log message body. Look for the `🔍 DEBUG` or `ℹ️ INFO` entries — they contain your logged values.

    **Example output:**

    ```
    🔍 [4/28/2026, 11:45:30 AM] DEBUG
       Skill Name: search-skill
       Skill ID:   skill_abc123
       Tool Name:  search_articles
       Data.search result: [
         {
           "id": "entry_xyz",
           "title": "Inception",
           "score": 0.92
         }
       ]
    ```

    Now you can see the exact shape of what was returned and fix accordingly.
  </Step>

  <Step title="Fix once, not five times">
    You now know:

    * **Exact shape** of the return value
    * **Which fields exist** (and which don't)
    * **What the actual values** look like

    Fix the code, push once, verify with `lua logs`. Repeat until correct.
  </Step>
</Steps>

## Suppressing CLI hints

All post-action hints can be silenced with:

```bash theme={null}
LUA_NO_HINTS=1 lua push all --force --auto-deploy
```

Set `LUA_NO_HINTS=true` (or `yes`) in your shell profile or CI environment to disable hints globally. This is useful in CI/CD pipelines that capture only command output.

## Reading lua logs Output

```bash theme={null}
lua logs --type skill --limit 20
```

### Log entry anatomy

```
✅ [4/28/2026, 11:45:30 AM] COMPLETE
   Skill Name: my-search-skill
   Skill ID:   skill_abc123
   Tool Name:  search_articles
   Duration:   234ms
   Execute function completed
```

| Field            | Meaning                                            |
| ---------------- | -------------------------------------------------- |
| Icon + timestamp | When the log was created                           |
| Log type         | ERROR, WARN, DEBUG, INFO, START, COMPLETE          |
| Skill/Tool Name  | Which component ran                                |
| Duration         | Execution time in ms                               |
| Message          | The actual log content (your `console.log` output) |

### Log types

| Type       | Color  | Means                                           |
| ---------- | ------ | ----------------------------------------------- |
| ❌ ERROR    | Red    | Tool threw an exception — check the stack trace |
| ⚠️ WARN    | Yellow | Non-fatal issue, tool continued                 |
| 🔍 DEBUG   | Blue   | `console.log` output from your tool code        |
| ℹ️ INFO    | Cyan   | Operational status messages                     |
| ▶️ START   | Green  | Tool execution began                            |
| ✅ COMPLETE | Green  | Tool execution finished successfully            |

### Filter by component type

```bash theme={null}
# Skill tool execution
lua logs --type skill --limit 20

# Webhook execution
lua logs --type webhook --name stripe-webhook --limit 10

# Scheduled job execution
lua logs --type job --name daily-report --limit 5

# Preprocessor/Postprocessor
lua logs --type preprocessor --limit 10
lua logs --type postprocessor --limit 10

# User messages and agent responses
lua logs --type user_message --limit 20
lua logs --type agent_response --limit 20

# All logs
lua logs --type all --limit 50
```

## When to Use lua test vs lua chat vs lua logs

| Goal                                                            | Use                                 |
| --------------------------------------------------------------- | ----------------------------------- |
| Test a tool with exact input before touching the server         | `lua test`                          |
| Test a conversational flow, verify the AI calls the right tools | `lua chat` (sandbox)                |
| See what actually ran in production                             | `lua logs --type skill`             |
| Debug why an API call returned unexpected data                  | `console.log` + push + `lua logs`   |
| Check if a job actually ran and what it returned                | `lua logs --type job --name my-job` |
| Verify a webhook received and processed correctly               | `lua logs --type webhook`           |

## console.log Debugging Patterns

### Log a full API return value

```typescript theme={null}
const results = await Data.search('articles', input.query, 5, 0.7);
console.log('[DEBUG] Data.search result type:', typeof results, Array.isArray(results) ? `array[${results.length}]` : 'not array');
console.log('[DEBUG] Data.search result:', JSON.stringify(results, null, 2));
```

### Log individual entries

```typescript theme={null}
const results = await Data.search('articles', input.query, 5);
results.forEach((entry, i) => {
  console.log(`[DEBUG] entry[${i}]:`, JSON.stringify({
    id: entry.id,
    score: entry.score,
    keys: Object.keys(entry.data || {}),
    sample: entry.title || entry.data?.title || '(no title field)'
  }));
});
```

### Log before and after transformation

```typescript theme={null}
const raw = await Data.get('orders', { status: 'pending' });
console.log('[DEBUG] Data.get result — pagination:', JSON.stringify(raw.pagination));
console.log('[DEBUG] Data.get result — entry count:', raw.data.length);
if (raw.data.length > 0) {
  console.log('[DEBUG] First entry sample:', JSON.stringify(raw.data[0]));
}

const mapped = raw.data.map(entry => ({
  id: entry.id,
  orderId: entry.data.orderId,
  total: entry.data.total
}));
console.log('[DEBUG] After mapping:', JSON.stringify(mapped.slice(0, 2)));
```

## Common Bugs and How to Spot Them

### Bug: results.data is undefined (Data.search)

```
[DEBUG] Data.search result type: object array[3]
[DEBUG] Data.search result: [{"id":"entry_abc","data":{"title":"Inception"},"score":0.92}]
```

`results.data` would be `undefined` — there is no `.data` wrapper on the array. Use `results[0].data.title` for the entry payload, or `results[0].title` via the Proxy shortcut.

### Bug: entry.title is undefined (Data.get)

```
[DEBUG] First entry sample: {"id":"entry_xyz","data":{"title":"The Matrix"}}
```

`entry.title` would be `undefined` — `Data.get` entries are raw, not proxied. Use `entry.data.title`.

### Bug: products.data is undefined (Products.search)

```
[DEBUG] Products.search result type: object
[DEBUG] Products.search result: {"products":[{"id":"prod_1","name":"Laptop"}]}
```

`results.data` doesn't exist on `ProductSearchInstance`. Use `results.products` or `results.map(p => p.name)`.

## Removing Debug Logs Before Production

Once the bug is fixed, clean up your logs. Production logs are visible to your whole team and consume log storage.

```typescript theme={null}
// ❌ Don't leave these in production code
console.log('[DEBUG] raw result:', JSON.stringify(results));

// ✅ Leave meaningful operational logs
console.log(`Processed ${results.length} search results for query: "${input.query}"`);
```

## Related

<CardGroup>
  <Card title="lua logs Command" icon="terminal" href="/cli/logs-command">
    Full reference for the logs command and all filter options
  </Card>

  <Card title="lua test Command" icon="flask" href="/cli/overview">
    Test tools locally before pushing
  </Card>

  <Card title="Data API" icon="database" href="/api/data">
    Data API return shapes reference
  </Card>

  <Card title="Troubleshooting" icon="circle-question" href="/cli/troubleshooting">
    Common errors and solutions
  </Card>
</CardGroup>


# Devices Command
Source: https://docs.heylua.ai/cli/devices-command

Manage connected IoT and physical devices — enable, disable, test commands, and fire triggers

## Overview

`lua devices` manages the registered devices your agent can command and receive triggers from — IoT sensors, label printers, smart-home gear, kiosks, etc. The command lets you list, enable, disable, remove, and test devices and their triggers without writing any code.

```bash theme={null}
lua devices                              # Interactive management
lua devices list                         # List all devices
lua devices status --device-name label-printer
lua devices test --device-name label-printer
```

<Note>
  For defining devices in code, see the [Devices](/devices/overview) tab. For building your own device client, see [Build Your Own](/devices/build-your-own).
</Note>

## Subcommands

| Action         | What it does                                                               |
| -------------- | -------------------------------------------------------------------------- |
| `list`         | List all registered devices (optionally filter by `--group`).              |
| `status`       | Print online/offline/disabled state and last-seen time for a device.       |
| `enable`       | Re-enable a previously disabled device.                                    |
| `disable`      | Stop the agent from issuing commands to a device (offline mode).           |
| `remove`       | Unregister a device. Use `--force` to skip the confirmation.               |
| `test`         | Send a test command to a device. Prompts interactively or use `--payload`. |
| `test-trigger` | Fire a test trigger as if it came from the device.                         |

## Options

| Option                 | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| `--device-name <name>` | Device name. Required for most non-interactive actions.   |
| `--group <name>`       | Filter device list by group (use with `list`).            |
| `--payload <json>`     | JSON payload for `test` / `test-trigger` (default: `{}`). |
| `--timeout <ms>`       | Command timeout in milliseconds (default: `30000`).       |
| `--force`              | Skip confirmation prompts (used with `remove`).           |

## Examples

```bash theme={null}
# Interactive picker
lua devices

# List all devices
lua devices list

# Filter list by group
lua devices list --group printers

# Inspect device state
lua devices status --device-name label-printer

# Enable / disable
lua devices enable  --device-name label-printer
lua devices disable --device-name label-printer

# Remove (confirms before deleting)
lua devices remove --device-name label-printer
lua devices remove --device-name label-printer --force

# Test a command (interactive payload)
lua devices test --device-name label-printer

# Test with a specific payload
lua devices test --device-name label-printer \
  --payload '{"command":"print","data":{"label":"order-1234"}}'

# Fire a test trigger
lua devices test-trigger --device-name label-printer \
  --payload '{"event":"button_pressed","data":{"button":"red"}}'
```

## Test Command vs Test Trigger

| Command        | Direction      | When to use                                                                   |
| -------------- | -------------- | ----------------------------------------------------------------------------- |
| `test`         | Agent → device | Verify your agent can send commands to a device and that the device responds. |
| `test-trigger` | Device → agent | Verify your agent reacts correctly when a trigger fires from a device.        |

## Common Workflow

After registering a new device:

```bash theme={null}
lua devices list                                       # Confirm registration
lua devices status --device-name new-device            # Check it's online
lua devices test --device-name new-device              # Verify command path
lua devices test-trigger --device-name new-device      # Verify trigger path
lua logs --type device --name new-device --limit 10    # Inspect logs
lua logs --type device-trigger --name new-device       # Inspect triggers
```

## Related

* [Devices Overview](/devices/overview)
* [Self-Describing Commands](/devices/self-describing-commands)
* [Device Triggers](/devices/triggers)
* [Agent Tools for Devices](/devices/agent-tools)
* [Logs Command](/cli/logs-command) — filter by `--type device` or `--type device-trigger`


# Environment Variables Command
Source: https://docs.heylua.ai/cli/env-command

Manage environment variables for sandbox and production

## Overview

The `lua env` command provides an interactive interface for managing environment variables in both sandbox (development) and production environments.

```bash theme={null}
lua env                  # Interactive: choose environment
lua env sandbox          # Direct: manage .env file
lua env staging          # Direct: alias for sandbox
lua env production       # Direct: manage production API vars
```

<Note>
  Direct environment access lets you skip the selection prompt for faster workflows!
</Note>

<Note>
  Full non-interactive mode with `-k`, `-v`, `--list`, and `--delete` flags for scripting and CI/CD.
</Note>

### Non-Interactive Mode

```bash theme={null}
# List variables
lua env sandbox --list
lua env production --list

# Set a variable
lua env sandbox -k DATABASE_URL -v "postgres://localhost/db"
lua env production -k API_KEY -v "sk_live_xxx"

# Delete a variable
lua env production -k OLD_KEY --delete
```

| Option              | Description                    |
| ------------------- | ------------------------------ |
| `--list`            | List all environment variables |
| `-k, --key <name>`  | Variable name                  |
| `-v, --value <val>` | Variable value                 |
| `-d, --delete`      | Delete the specified variable  |

<CardGroup>
  <Card title="Sandbox Mode" icon="flask">
    Manage `.env` file locally
  </Card>

  <Card title="Production Mode" icon="rocket">
    Manage variables on server via API
  </Card>

  <Card title="Interactive Menu" icon="list">
    Add, update, delete, and view variables
  </Card>

  <Card title="Secure" icon="lock">
    Values masked in list view
  </Card>
</CardGroup>

## Usage Modes

<Tabs>
  <Tab title="Interactive Mode">
    **Default behavior - prompts for environment**

    ```bash theme={null}
    $ lua env
    ? Select environment:
      › 🔧 Sandbox (.env file)
        🚀 Production (API)
    ```

    Best for: When you're not sure which environment
  </Tab>

  <Tab title="Direct Mode - Sandbox">
    **Skip prompt and go straight to sandbox**

    ```bash theme={null}
    $ lua env sandbox
    # No prompt - opens .env file management immediately
    ```

    Best for: Quick local configuration during development
  </Tab>

  <Tab title="Direct Mode - Production">
    **Skip prompt and go straight to production**

    ```bash theme={null}
    $ lua env production
    # No prompt - opens production API management immediately
    ```

    Best for: Fast production updates, automation
  </Tab>
</Tabs>

## Quick Start

<Steps>
  <Step title="Run Command">
    ```bash theme={null}
    lua env sandbox        # Direct to sandbox
    # or
    lua env                # Interactive
    ```
  </Step>

  <Step title="Choose Environment (if interactive)">
    ```
    ? Select environment:
      🔧 Sandbox (.env file)
      🚀 Production (API)
    ```
  </Step>

  <Step title="Manage Variables">
    * ➕ Add new variable
    * ✏️ Update existing
    * 🗑️ Delete variable
    * 👁️ View full value
  </Step>
</Steps>

## Environment Selection

<Tabs>
  <Tab title="Sandbox (.env)">
    **Local Development**

    Manages your `.env` file in the project directory.

    ```
    ? Select environment: 🔧 Sandbox (.env file)
    ```

    **Features:**

    * ✅ No authentication required
    * ✅ Instant changes
    * ✅ Local file management
    * ✅ Used by `lua test` and `lua chat`

    **File location:** `PROJECT_ROOT/.env`
  </Tab>

  <Tab title="Production (API)">
    **Production Environment**

    Manages variables on the server via API.

    ```
    ? Select environment: 🚀 Production (API)
    ✅ Authenticated
    ```

    **Features:**

    * ✅ Secure server storage
    * ✅ Team collaboration
    * ✅ Audit logging
    * ✅ Used by deployed skills

    **Requires:** Valid API key (`lua auth configure`)
  </Tab>
</Tabs>

## Actions Available

### Add New Variable

```bash theme={null}
? What would you like to do? ➕ Add new variable
? Variable name: STRIPE_API_KEY
? Variable value: sk_test_abc123
🔄 Saving...
✅ Variable "STRIPE_API_KEY" added successfully
```

<ParamField type="string">
  Must start with letter/underscore, contain only letters, numbers, underscores
</ParamField>

<ParamField type="string">
  Any string value (can include spaces, special characters)
</ParamField>

### Update Existing Variable

```bash theme={null}
? What would you like to do? ✏️ Update existing variable
? Select variable to update: STRIPE_API_KEY
? New value for STRIPE_API_KEY: sk_test_xyz789
🔄 Saving...
✅ Variable "STRIPE_API_KEY" updated successfully
```

### Delete Variable

```bash theme={null}
? What would you like to do? 🗑️ Delete variable
? Select variable to delete: OLD_KEY
? Are you sure you want to delete "OLD_KEY"? Yes
🔄 Saving...
✅ Variable "OLD_KEY" deleted successfully
```

<Warning>
  Deletion requires confirmation to prevent accidents. Default is "No".
</Warning>

### View Variable Value

```bash theme={null}
? What would you like to do? 👁️ View variable value
? Select variable to view: STRIPE_API_KEY
============================================================
Variable: STRIPE_API_KEY
============================================================
sk_test_abc123xyz789
============================================================

Press Enter to continue...
```

Shows the full unmasked value for copying.

## Variable Display

Variables are **masked for security** in the list view:

```
============================================================
📋 Environment Variables (Sandbox)
============================================================

1. DATABASE_URL = post**********************
2. STRIPE_KEY = sk-t**********************
3. API_SECRET = abc1**********************
```

**Masking rules:**

* Shows first 4 characters
* Replaces rest with asterisks (max 20)
* Values \< 4 chars show only asterisks

## Variable Naming Rules

<Tabs>
  <Tab title="Valid Names">
    ```bash theme={null}
    DATABASE_URL           ✅
    API_KEY                ✅
    STRIPE_SECRET_KEY      ✅
    MAX_CONNECTIONS        ✅
    enable_feature         ✅
    _INTERNAL_CONFIG       ✅
    ```
  </Tab>

  <Tab title="Invalid Names">
    ```bash theme={null}
    123_NUMBER             ❌ Starts with number
    MY-VARIABLE            ❌ Contains hyphen
    MY VARIABLE            ❌ Contains space
    MY.VARIABLE            ❌ Contains dot
    ```
  </Tab>
</Tabs>

## Use in Development Workflow

### Step 1: Configure Variables

```bash theme={null}
# Set up sandbox environment variables
lua env sandbox
# Add: DATABASE_URL, API_KEY, STRIPE_SECRET, etc.

# Set up production environment variables
lua env production
# Add production API keys and URLs
```

### Step 2: Test Locally

```bash theme={null}
# Variables are automatically loaded
lua test

# Or test in conversation
lua chat
```

### Step 3: Verify Production Config

```bash theme={null}
# Check production variables before deploying
lua env production
```

### Step 4: Deploy

```bash theme={null}
lua push
lua deploy
```

## Sandbox vs Production

<Tabs>
  <Tab title="When to Use Sandbox">
    **Local Development**

    ```bash theme={null}
    lua env  # → Choose Sandbox
    ```

    **Add variables like:**

    ```
    DATABASE_URL=postgresql://localhost:5432/dev
    STRIPE_KEY=sk_test_...
    DEBUG=true
    ```

    **Used by:**

    * `lua test`
    * `lua chat` (sandbox mode)
    * Local development
  </Tab>

  <Tab title="When to Use Production">
    **Production Deployment**

    ```bash theme={null}
    lua env  # → Choose Production
    ```

    **Add variables like:**

    ```
    DATABASE_URL=postgresql://prod-host:5432/prod
    STRIPE_KEY=sk_live_...
    DEBUG=false
    ```

    **Used by:**

    * Deployed skills
    * `lua chat` (production mode)
    * Live user interactions
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Different Keys per Environment">
    ```bash theme={null}
    # Sandbox - Test keys
    STRIPE_KEY=sk_test_abc123
    DATABASE=dev_database

    # Production - Live keys
    STRIPE_KEY=sk_live_xyz789
    DATABASE=prod_database
    ```
  </Accordion>

  <Accordion title="Never Commit .env">
    Add to `.gitignore`:

    ```
    .env
    .env.local
    .env.*.local
    ```

    Commit `.env.example` instead with placeholder values
  </Accordion>

  <Accordion title="Document Required Variables">
    Create `.env.example`:

    ```bash theme={null}
    # Required API Keys
    STRIPE_KEY=sk_test_your_key_here
    DATABASE_URL=postgresql://localhost:5432/dbname

    # Optional
    DEBUG=true
    MAX_RETRIES=3
    ```
  </Accordion>

  <Accordion title="Rotate Secrets Regularly">
    Update sensitive keys every 90 days:

    * API keys
    * Database passwords
    * JWT secrets
    * Encryption keys
  </Accordion>
</AccordionGroup>

## Example Session

```bash theme={null}
$ lua env sandbox
# Or interactive: lua env → Choose Sandbox

============================================================
📋 Environment Variables (Sandbox)
============================================================

ℹ️  No environment variables configured.

? What would you like to do? ➕ Add new variable
? Variable name: DATABASE_URL
? Variable value: postgresql://localhost:5432/myapp
🔄 Saving...
✅ Variable "DATABASE_URL" added successfully

============================================================
📋 Environment Variables (Sandbox)
============================================================

1. DATABASE_URL = post**********************

? What would you like to do? ➕ Add new variable
? Variable name: STRIPE_KEY
? Variable value: sk_test_abc123
🔄 Saving...
✅ Variable "STRIPE_KEY" added successfully

============================================================
📋 Environment Variables (Sandbox)
============================================================

1. DATABASE_URL = post**********************
2. STRIPE_KEY = sk-t**********************

? What would you like to do? ❌ Exit

👋 Goodbye!
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Variable not loading in tools">
    **Problem**: Tool can't find environment variable

    **Solution:**

    ```typescript theme={null}
    import { env } from 'lua-cli';

    const apiKey = env('STRIPE_KEY');
    if (!apiKey) {
      throw new Error('STRIPE_KEY not configured. Run: lua env');
    }
    ```
  </Accordion>

  <Accordion title=".env file permissions error">
    **Error**: `EACCES: permission denied`

    **Solution:**

    ```bash theme={null}
    chmod 644 .env
    ```
  </Accordion>

  <Accordion title="Production variables not saving">
    **Problem**: Changes don't persist

    **Solutions:**

    1. Verify API key: `lua auth key`
    2. Check network connection
    3. Try again
  </Accordion>

  <Accordion title="Invalid variable name">
    **Error**: Validation error

    **Fix:** Use valid format:

    * Start with letter or underscore
    * Only letters, numbers, underscores
    * No hyphens, spaces, or special characters
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup>
  <Card title="lua test" icon="flask">
    Uses sandbox environment variables
  </Card>

  <Card title="lua chat" icon="comments">
    Uses sandbox or production based on mode
  </Card>

  <Card title="lua push" icon="upload">
    Doesn't include env vars (stored separately)
  </Card>

  <Card title="lua deploy" icon="rocket">
    Uses production environment variables
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Environment Variables Guide" icon="key" href="/concepts/environment-variables">
    Complete guide to configuration management
  </Card>

  <Card title="Test Your Skills" icon="flask" href="/cli/skill-management#lua-test">
    Test tools with your environment variables
  </Card>
</CardGroup>


# Features Command
Source: https://docs.heylua.ai/cli/features-command

Manage agent capabilities and features

## Overview

The `lua features` command provides an interactive interface for managing your AI agent's capabilities: **Knowledge Search** (`rag`), **Web Search** (`webSearch`), and **Inquiry Forms** (`inquiry`).

For what each feature does and how it fits with resources and the Admin Dashboard, see [Features](/overview/features).

<Tip>
  Prefer a UI? The same toggles and per-agent context editing are available in the **Admin Dashboard** — see [Features → Admin Dashboard](/overview/features#from-the-admin-dashboard). The CLI and dashboard call the same API, so changes in one surface immediately in the other.
</Tip>

```bash theme={null}
lua features
```

<Note>
  Centralized control over agent features with instant enable/disable and context customization!
</Note>

### Non-Interactive Mode

```bash theme={null}
# List all features
lua features list

# Enable a feature
lua features enable --feature-name rag

# Disable a feature
lua features disable --feature-name rag

# View feature details
lua features view --feature-name webSearch
```

| Option                  | Description                                  |
| ----------------------- | -------------------------------------------- |
| `--feature-name <name>` | Feature name (`rag`, `webSearch`, `inquiry`) |

| Action    | Description                      | Required Options |
| --------- | -------------------------------- | ---------------- |
| `list`    | List all features with status    | None             |
| `enable`  | Enable a feature                 | `--feature-name` |
| `disable` | Disable a feature                | `--feature-name` |
| `view`    | View feature details and context | `--feature-name` |

<CardGroup>
  <Card title="View Features" icon="list">
    See all available features and their status
  </Card>

  <Card title="Enable/Disable" icon="toggle-on">
    Activate or deactivate features instantly
  </Card>

  <Card title="Update Context" icon="edit">
    Customize feature instructions
  </Card>

  <Card title="Batch Updates" icon="layer-group">
    Update status and context together
  </Card>
</CardGroup>

## Available Features

### Knowledge Search (`rag`)

RAG-based knowledge base search for retrieving information from your documentation.

**Capabilities:**

* Semantic search across knowledge base
* Category-based search (FAQ, policies, instructions)
* Document retrieval with citations
* Contextual information retrieval

**Best for:** Information agents, documentation assistants, customer support

***

### Web Search (`webSearch`)

Real-time internet search capability for accessing current information, with source links attached to the response.

Search runs one of two ways depending on your agent's model:

* **Native search** — models with a built-in, cited web search path (OpenAI, Anthropic, Google/Gemini, xAI, and Zhipu AI's GLM models) use the provider's own search tool.
* **Assisted search** — every other model falls back to Lua's own web-search tool.

Either way, responses come back with the same source-citation format, so your agent's behavior doesn't change based on which model it's using.

<Note>
  **Important:** The Web Search feature is not a web scraper. It cannot navigate to or read specific URLs directly, and it does not scrape content from individual or bulk pages.
</Note>

**Capabilities:**

* Search the web in real-time
* Retrieve up-to-date information and current events
* Return synthesized answers with source citations

**Best for:** Research agents, information lookup, real-time data needs

**How to Enable:**

* **Enabled by default** for new agents, like the other built-in features. Native search can add latency and per-search cost on some models, so disable it if your agent doesn't need it.
* Can be toggled on or off by running `lua features enable --feature-name webSearch` or `lua features disable --feature-name webSearch` in the CLI.

***

### Inquiry Forms (`inquiry`)

Define conversational forms so the agent can collect structured answers from users. Submissions are visible in the **Admin Dashboard**. Inquiry forms are general-purpose (leads, intake, feedback, or support-style flows)—they replaced the older standalone “support tickets” feature.

**Capabilities:**

* Generate inquiry forms from your form definitions
* Collect and track submissions
* Add comments and manage follow-up in the dashboard

**Best for:** Sales, lead capture, support intake, or any workflow that needs structured data from conversations

## Quick Start

<Steps>
  <Step title="Run Command">
    ```bash theme={null}
    lua features
    ```
  </Step>

  <Step title="View Features">
    See all available features with their current status:

    ```
    Available features:

    1. ✅ Knowledge Search (RAG)
       Name: rag
       Status: Active

    2. ❌ WebSearch
       Name: webSearch
       Status: Inactive

    3. ❌ Create Inquiry forms
       Name: inquiry
       Status: Inactive
    ```
  </Step>

  <Step title="Manage Features">
    Select what you want to do:

    * View feature details
    * Manage a feature (enable/disable/update)
    * Refresh list
  </Step>
</Steps>

## Main Menu Actions

<Tabs>
  <Tab title="View Feature Details">
    **See complete information about a feature**

    ```bash theme={null}
    ? What would you like to do? View feature details
    ? Select feature: ✅ Knowledge Search (RAG)

    ============================================================
    Feature: Knowledge Search (RAG)
    ============================================================

    Name: rag
    Status: ✅ Active

    Context/Instructions:
    Search the knowledge base for information.
    Use categories: FAQ, policies, instructions.
    Always cite sources when providing information.

    Press Enter to continue...
    ```

    **Use for:** Understanding what a feature does before enabling
  </Tab>

  <Tab title="Manage a Feature">
    **Enable, disable, or update a feature**

    ```bash theme={null}
    ? What would you like to do? Manage a feature
    ? Select feature: ❌ WebSearch

    ? What would you like to do with "WebSearch"?
      › Activate feature
        Update context/instructions
        Update both status and context
        Back to main menu
    ```

    **Use for:** Changing feature settings
  </Tab>

  <Tab title="Refresh List">
    **Reload features from server**

    ```bash theme={null}
    ? What would you like to do? Refresh list
    🔄 Refreshing features...
    ✅ Features refreshed successfully
    ```

    **Use for:** Getting latest feature status after external changes
  </Tab>
</Tabs>

## Managing Features

### Enable a Feature

<Steps>
  <Step title="Select Manage">
    ```bash theme={null}
    $ lua features
    ? What would you like to do? Manage a feature
    ```
  </Step>

  <Step title="Choose Feature">
    ```bash theme={null}
    ? Select feature: ❌ WebSearch
    ```
  </Step>

  <Step title="Activate">
    ```bash theme={null}
    ? What would you like to do? Activate feature

    ⚠️  This will enable "WebSearch" for your agent.

    ? Are you sure? Yes

    🔄 Updating feature...
    ✅ Feature "WebSearch" activated successfully
    ```
  </Step>
</Steps>

### Disable a Feature

<Steps>
  <Step title="Select Feature">
    ```bash theme={null}
    $ lua features
    ? What would you like to do? Manage a feature
    ? Select feature: ✅ Knowledge Search (RAG)
    ```
  </Step>

  <Step title="Deactivate">
    ```bash theme={null}
    ? What would you like to do? Deactivate feature

    ⚠️  This will disable "Knowledge Search (RAG)" for your agent.

    ? Are you sure? Yes

    🔄 Updating feature...
    ✅ Feature "Knowledge Search (RAG)" deactivated successfully
    ```
  </Step>
</Steps>

### Update Feature Context

Customize how your agent uses a feature by editing its instructions.

<Steps>
  <Step title="Select Feature">
    ```bash theme={null}
    $ lua features
    ? What would you like to do? Manage a feature
    ? Select feature: ✅ Knowledge Search (RAG)
    ```
  </Step>

  <Step title="Update Context">
    ```bash theme={null}
    ? What would you like to do? Update context/instructions

    Opening editor to modify feature context...
    ```

    Your system editor opens with the current context:

    ```
    Search the knowledge base for information.
    Use categories: FAQ, policies, instructions.
    Always cite sources when providing information.
    ```
  </Step>

  <Step title="Edit and Save">
    Modify the instructions:

    ```
    Search the knowledge base for product information.

    Categories available:
    - FAQ: Common customer questions
    - policies: Company policies and procedures
    - instructions: How-to guides and documentation

    Guidelines:
    - Always cite sources with document names
    - If information is not found, say so clearly
    - Suggest related topics when helpful
    - Keep responses concise but complete
    ```

    Save and exit your editor.
  </Step>

  <Step title="Confirm">
    ```bash theme={null}
    ? Do you want to save these changes? Yes

    🔄 Updating feature context...
    ✅ Context updated successfully
    ```
  </Step>
</Steps>

### Batch Update (Status + Context)

Update both feature status and context in one operation.

<Steps>
  <Step title="Select Feature">
    ```bash theme={null}
    $ lua features
    ? What would you like to do? Manage a feature
    ? Select feature: ❌ Create Inquiry forms
    ```
  </Step>

  <Step title="Choose Batch Update">
    ```bash theme={null}
    ? What would you like to do? Update both status and context

    ? New status for "Create Inquiry forms":
      › Enable
        Disable
    ```
  </Step>

  <Step title="Edit Context">
    Your editor opens for context editing...

    Save your changes.
  </Step>

  <Step title="Review and Confirm">
    ```bash theme={null}
    Summary of changes:
    - Status: Inactive → Active
    - Context: Updated

    ? Do you want to apply these changes? Yes

    🔄 Updating feature...
    ✅ Feature "Create Inquiry forms" updated successfully
    ```
  </Step>
</Steps>

## Use Cases

### Customer Support Agent

Enable features for internal knowledge and optional intake:

```bash theme={null}
$ lua features

# Enable Knowledge Search
→ Manage: ❌ Knowledge Search → Activate
✅ RAG enabled

# Optional: inquiry forms for structured support intake (visible in Admin Dashboard)
→ Manage: ❌ Inquiry Forms → Activate
✅ Inquiry forms enabled

# Disable Web Search if you only want org-approved sources
→ Manage: ✅ WebSearch → Deactivate
✅ WebSearch disabled

# Result: Agent focused on your knowledge base (and optional forms)
```

**Features Active:**

* ✅ Knowledge Search - Access help docs and policies
* ✅ Inquiry Forms (optional) - Structured intake or follow-up
* ❌ Web Search - Not needed for internal-only support

***

### Sales Agent

Configure for lead generation and product information:

```bash theme={null}
$ lua features

# Enable Inquiry Forms for lead capture
→ Manage: ❌ Inquiry Forms → Activate
→ Update context: "Collect contact info, company size, budget"
✅ Inquiry forms enabled

# Enable Knowledge Search for product info
→ Manage: ❌ Knowledge Search → Activate
✅ RAG enabled

# Enable Web Search for competitive research
→ Manage: ❌ Web Search → Activate
✅ WebSearch enabled

# Result: Lead capture + product knowledge + market research
```

**Features Active:**

* ✅ Inquiry Forms - Lead generation
* ✅ Knowledge Search - Product information
* ✅ Web Search - Market research

***

### Information Agent

Optimize for information retrieval:

```bash theme={null}
$ lua features

# Enable RAG as primary source
→ Manage: ❌ Knowledge Search → Activate
→ Update context: "Primary information source. Always check here first."
✅ RAG enabled

# Enable Web Search as backup
→ Manage: ❌ Web Search → Activate
→ Update context: "Use only when RAG doesn't have the answer."
✅ WebSearch enabled

# Disable inquiry if you only need read-only answers
→ Manage: ✅ Inquiry Forms → Deactivate
✅ Focused on information retrieval only
```

**Features Active:**

* ✅ Knowledge Search - Primary source
* ✅ Web Search - Supplementary data
* ❌ Inquiry Forms - No data collection needed

## Customizing Feature Context

### Writing Effective Context

Good feature context should include:

<AccordionGroup>
  <Accordion title="Clear Purpose">
    Explain what the feature is for:

    ```
    ✅ Good:
    "Use this feature to search our internal knowledge base
    for product documentation, FAQs, and policies."

    ❌ Bad:
    "Search stuff."
    ```
  </Accordion>

  <Accordion title="When to Use">
    Specify appropriate situations:

    ```
    ✅ Good:
    "Use inquiry forms when:
    - You need structured lead or intake data
    - The user agrees to submit a form
    - Follow-up will happen in the Admin Dashboard

    Do NOT use inquiry forms for:
    - Simple FAQs already in the knowledge base
    - One-off questions that RAG can answer"

    ❌ Bad:
    "Use forms sometimes."
    ```
  </Accordion>

  <Accordion title="Guidelines and Rules">
    Set boundaries and expectations:

    ```
    ✅ Good:
    "When using web search:
    1. Use for current events and real-time data
    2. Verify information with multiple sources
    3. Cite sources in your response
    4. If search fails, inform user honestly
    5. Don't rely on search for company-specific info"

    ❌ Bad:
    "Search the web when needed."
    ```
  </Accordion>

  <Accordion title="Examples">
    Provide concrete examples:

    ```
    ✅ Good:
    "Example inquiry form fields:
    - Name (required)
    - Email (required)
    - Company name
    - Company size (1-10, 11-50, 51-200, 201+)
    - Budget range
    - Timeline for decision
    - Additional notes"

    ❌ Bad:
    "Collect customer information."
    ```
  </Accordion>
</AccordionGroup>

### Context Templates

#### Knowledge Search Template

```markdown theme={null}
Search the internal knowledge base for information.

Categories available:
- FAQ: Frequently asked questions
- policies: Company policies and procedures
- instructions: Step-by-step guides
- products: Product documentation

Search best practices:
1. Try specific queries first
2. Use category filters when possible
3. Always cite the document source
4. If not found, try broader terms
5. Suggest related topics when helpful

When information is not found:
- Say so clearly and honestly
- Offer to escalate if needed
- Suggest alternative resources
```

#### Web Search Template

```markdown theme={null}
Use web search for real-time, current information.

Appropriate for:
- Current events and news
- Real-time data (stock prices, weather)
- Recent industry updates
- Public information not in knowledge base

Not appropriate for:
- Company-specific information (use RAG)
- Customer data or internal systems
- Proprietary information
- Historical company information

Always:
- Verify information quality
- Cite sources with URLs
- Cross-reference when possible
- Note the date of information
```

#### Inquiry Forms Template

```markdown theme={null}
Create inquiry forms to collect lead information.

Standard fields to include:
- Full name (required)
- Email address (required)
- Phone number (optional)
- Company name
- Company size
- Industry
- Budget range
- Timeline
- Specific needs/requirements

Qualification questions:
- What problem are you trying to solve?
- Have you used similar solutions?
- What's your timeline for implementation?
- Who else is involved in the decision?

After form submission:
- Thank the prospect
- Set expectations for response time
- Offer immediate resources if available
```

## Complete Workflows

### Initial Agent Setup

```bash theme={null}
# 1. Configure features for your agent type
lua features

# 2. Enable necessary features
→ Activate relevant features

# 3. Customize each feature's context
→ Update context for each enabled feature

# 4. Test with chat
lua chat
# Test each feature's behavior

# 5. Iterate based on results
lua features
→ Adjust context as needed
```

### Feature Testing Workflow

```bash theme={null}
# 1. Enable test feature
lua features
→ Activate feature
→ Add initial context

# 2. Test in sandbox
lua chat
# Try using the feature

# 3. Review and refine
# Based on test results

# 4. Update context
lua features
→ Update context with improvements

# 5. Test again
lua chat
# Verify improvements

# 6. Deploy when satisfied
lua push skill
lua deploy
```

### Feature Optimization

```bash theme={null}
# 1. Review current features
lua features
→ View all features and their usage

# 2. Disable unused features
→ Deactivate features not being used
# Improves performance and reduces complexity

# 3. Optimize active features
→ Update context for better behavior
→ Add examples and guidelines

# 4. Test optimization
lua chat
# Verify improvements

# 5. Monitor results
# Check conversations in admin dashboard
lua admin
```

## Integration with Other Commands

### Features + Persona

Coordinate features with persona:

```bash theme={null}
# 1. Enable features
lua features
→ Enable: rag, inquiry

# 2. Update persona to mention capabilities
lua persona sandbox
# Add: "I can search our knowledge base and collect details via inquiry forms"

# 3. Test together
lua chat

# 4. Deploy both
lua push persona
lua push skill
```

### Features + Skills

Build skills that use platform features:

```bash theme={null}
# 1. Enable features you need (e.g. RAG + inquiry)
lua features
→ Activate: rag

# 2. Add or extend tools in your skill project
vim src/tools/MyTool.ts

# 3. Test
lua test

# 4. Deploy
lua push skill
```

### Features + Environment

Different features per environment:

```bash theme={null}
# Development: Enable all features for testing
lua features
→ Activate: All features

# Production: Enable only needed features
lua features
→ Activate: rag, inquiry
→ Deactivate: webSearch
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start Minimal">
    Enable only features you need:

    ```bash theme={null}
    # ✅ Good: Start with essentials
    lua features
    → Enable: rag only (add webSearch or inquiry when needed)

    # Test and add more as needed

    # ❌ Bad: Enable everything "just in case"
    → Enable: All features
    # Adds complexity and potential confusion
    ```
  </Accordion>

  <Accordion title="Write Clear Context">
    Detailed instructions improve results:

    ```bash theme={null}
    # ✅ Good: Detailed context
    "Use inquiry forms for technical escalations.
    Include: problem summary, steps to reproduce,
    customer impact, and priority level."

    # ❌ Bad: Vague context
    "Use forms for problems."
    ```
  </Accordion>

  <Accordion title="Test After Changes">
    Always test feature changes:

    ```bash theme={null}
    lua features
    → Update context

    lua chat
    # Immediately test the changes

    # Verify behavior matches expectations
    ```
  </Accordion>

  <Accordion title="Document Your Setup">
    Keep notes on feature configuration:

    ```yaml theme={null}
    # In README.md or docs
    ## Active Features

    - Knowledge Search (rag): Internal docs only
    - Web Search: Disabled (use internal knowledge)
    - Inquiry Forms: Disabled (not collecting structured data)
    ```
  </Accordion>

  <Accordion title="Review Regularly">
    Audit features periodically:

    ```bash theme={null}
    # Monthly review
    lua features
    → Check active features
    → Disable unused features
    → Update context based on learnings
    → Test improvements
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Features not loading">
    **Error**: "Failed to fetch features"

    **Solutions:**

    1. Verify authentication:
       ```bash theme={null}
       lua auth key
       ```

    2. Check lua.skill.yaml has agentId:
       ```yaml theme={null}
       agent:
         agentId: agent_abc123
       ```

    3. Test API connection:
       ```bash theme={null}
       lua admin
       # If admin works, features should too
       ```
  </Accordion>

  <Accordion title="Context not saving">
    **Problem**: Editor opens but changes don't save

    **Solutions:**

    1. Make sure you save in editor (`:wq` for vim)
    2. Confirm when prompted after editing
    3. Check for error messages
    4. Try again with refresh:
       ```bash theme={null}
       lua features
       → Refresh list
       → Try update again
       ```
  </Accordion>

  <Accordion title="Feature not appearing in agent">
    **Problem**: Enabled feature not available in chat

    **Solutions:**

    1. Verify feature is active:
       ```bash theme={null}
       lua features
       # Check status shows ✅
       ```

    2. Refresh agent session:
       ```bash theme={null}
       lua chat
       # Start new chat session
       ```

    3. Check feature context is not empty

    4. Redeploy if needed:
       ```bash theme={null}
       lua push skill
       lua deploy
       ```
  </Accordion>

  <Accordion title="Cannot enable feature">
    **Error**: "Feature update failed"

    **Solutions:**

    1. Check agentId is correct
    2. Verify API key has permissions
    3. Ensure feature name is valid
    4. Check network connection
    5. Try refreshing features list first
  </Accordion>

  <Accordion title="Editor not opening">
    **Problem**: Context update doesn't open editor

    **Solutions:**

    1. Set EDITOR environment variable:
       ```bash theme={null}
       export EDITOR=vim
       # or nano, code, etc.
       ```

    2. Add to shell config (\~/.bashrc or \~/.zshrc):
       ```bash theme={null}
       echo 'export EDITOR=vim' >> ~/.bashrc
       source ~/.bashrc
       ```

    3. Try different editor:
       ```bash theme={null}
       export EDITOR=nano
       lua features
       ```
  </Accordion>
</AccordionGroup>

## Requirements

* **Authentication**: Valid API key (`lua auth configure`)
* **Project**: Must be in skill directory with `lua.skill.yaml`
* **Agent ID**: Configuration must contain `agent.agentId`
* **Permissions**: API key must have agent management permissions

## Related Commands

<CardGroup>
  <Card title="lua persona" icon="user">
    Configure agent personality to work with features
  </Card>

  <Card title="lua chat" icon="comments">
    Test features in conversation
  </Card>

  <Card title="lua admin" icon="gauge">
    View feature usage in admin dashboard
  </Card>

  <Card title="lua push skill" icon="upload">
    Deploy skills that use features
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Features overview" icon="book" href="/overview/features">
    What each feature does (rag, webSearch, inquiry)
  </Card>

  <Card title="Test Features" icon="flask" href="/cli/chat-command">
    Use lua chat to test feature behavior
  </Card>

  <Card title="Build Skills" icon="hammer" href="/cli/skill-management">
    Create tools that leverage features
  </Card>

  <Card title="Configure Persona" icon="user" href="/cli/persona-command">
    Update persona to mention capabilities
  </Card>

  <Card title="Admin Dashboard" icon="gauge" href="/cli/utility-commands#lua-admin">
    Monitor feature usage
  </Card>
</CardGroup>


# Git Command
Source: https://docs.heylua.ai/cli/git-command

Auto-commit your agent project and optionally push to GitHub

## Overview

The `lua git` commands connect your agent project to git, so that Lua
operations automatically commit a snapshot of your project. Optionally, each
commit can also be pushed to a linked GitHub repository.

```bash theme={null}
lua git connect      # enable auto-commits for this project
lua git auth github  # link a GitHub account
lua git status       # show the current git integration state
```

<Note>
  Git integration is **opt-in** and per-project. Until you run `lua git
      connect`, Lua never touches your git repository.
</Note>

## What Auto-Commit Does

Once enabled, these commands commit your project automatically after they
succeed:

| Command                                                           | Commits | Also tags  |
| ----------------------------------------------------------------- | ------- | ---------- |
| `lua push`                                                        | ✅       | —          |
| [`lua version create`](/cli/version-command#lua-version-create)   | ✅       | `lua/v<N>` |
| [`lua version promote`](/cli/version-command#lua-version-promote) | ✅       | —          |
| [`lua version delete`](/cli/version-command#lua-version-delete)   | ✅       | —          |
| `lua pull`                                                        | ✅       | —          |

Auto-commit is non-blocking: if a commit can't be made, the Lua command still
succeeds and prints a short warning.

## Enabling Auto-Commit

<Steps>
  <Step title="Prepare your repository">
    Auto-commit needs a git repository with an identity configured:

    ```bash theme={null}
    git init
    git config user.name "Your Name"
    git config user.email "you@example.com"
    ```

    <Note>
      Lua never runs `git init` or `git config` for you — you stay in control
      of your repository.
    </Note>
  </Step>

  <Step title="Connect">
    ```bash theme={null}
    lua git connect
    ```

    This runs sanity checks (git installed, inside a repository, identity
    configured) and, on success, records the setting in `lua.skill.yaml`.
  </Step>
</Steps>

## Pushing to GitHub

To also push each auto-commit to GitHub, link a GitHub account and enable
auto-push.

<Steps>
  <Step title="Link your GitHub account">
    ```bash theme={null}
    lua git auth github
    ```

    A code is shown in your terminal; open
    [github.com/login/device](https://github.com/login/device), enter the
    code, and authorize Lua. The token is stored locally under
    `~/.lua-cli/`.

    ```text theme={null}
    Open https://github.com/login/device and enter the code: WDJB-MJHT
    ✓ Logged in to GitHub as @your-username.
    ```
  </Step>

  <Step title="Add a GitHub remote">
    Auto-push targets your `origin` remote, which must be a GitHub HTTPS URL:

    ```bash theme={null}
    git remote add origin https://github.com/<owner>/<repo>.git
    ```
  </Step>

  <Step title="Enable auto-push">
    ```bash theme={null}
    lua git connect --auto-push
    ```

    This verifies that a GitHub account is linked **and** that `origin` is a
    GitHub HTTPS remote before enabling auto-push — so you find out about a
    missing link or remote immediately, not on your next `lua push`.
  </Step>
</Steps>

After this, every auto-commit is followed by a push to your GitHub repository.
Auto-push is non-blocking: if a push fails (revoked token, network issue,
etc.), the commit is kept locally and you can run `git push` manually.

## Commands

### `lua git connect`

Enable auto-commits for the current project.

| Flag          | Description                                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `--auto-push` | Also enable auto-push to the linked GitHub remote (requires `lua git auth github` and a GitHub HTTPS `origin`). |

### `lua git disconnect`

Disable auto-commits. Existing commits and tags in your repository are left
untouched.

### `lua git status`

Show the current integration state: whether it's enabled, your git identity,
and the most recent Lua-issued commit and tag.

### `lua git auth github`

Link a GitHub account using GitHub's OAuth **device flow** (enter a code at
[github.com/login/device](https://github.com/login/device)).

| Flag      | Description                                            |
| --------- | ------------------------------------------------------ |
| `--force` | Re-link without the "already linked, re-link?" prompt. |

### `lua git auth status`

Show the linked GitHub username, granted scopes, and when it was linked.

### `lua git auth disconnect`

Remove the locally stored GitHub token.

## Configuration

The `git` block in `lua.skill.yaml` is **managed by the CLI** — use the
commands above rather than editing it by hand, so the sanity checks always
run:

```yaml theme={null}
git:
  enabled: true    # set by `lua git connect`
  autoPush: true   # set by `lua git connect --auto-push`
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Git add skipped: no-repo">
    The project directory isn't a git repository yet. Run `git init` (and set
    your `user.name` / `user.email`), then `lua git connect`.
  </Accordion>

  <Accordion title="auto-push is enabled but no remote.origin.url is set">
    Add a GitHub remote: `git remote add origin
            https://github.com/<owner>/<repo>.git`. Auto-push supports GitHub HTTPS
    remotes only.
  </Accordion>

  <Accordion title="GitHub auth was revoked">
    Re-link your account with `lua git auth github`.
  </Accordion>
</AccordionGroup>


# Integrations Command
Source: https://docs.heylua.ai/cli/integrations-command

Connect third-party integrations and set up event-driven triggers for your agent via Unified.to

## Overview

The `lua integrations` command enables you to connect your agent to third-party services like Linear, Discord, Google Calendar, HubSpot, and 250+ other integrations via [Unified.to](https://unified.to). When you connect an integration:

* An **MCP server** is automatically created to expose tools to your agent
* **Triggers** can be set up to wake up your agent when events occur in the connected service

```bash theme={null}
lua integrations              # Interactive mode
lua integrations connect      # Connect a new integration
lua integrations list         # List connected integrations
lua integrations available    # View available integrations
lua integrations info <type>  # View integration details (scopes, triggers)
lua integrations disconnect   # Disconnect an integration
lua integrations update       # Update connection scopes
lua integrations webhooks     # Manage triggers (webhook subscriptions)
lua integrations mcp          # Manage MCP servers for connections

# Triggers shortcut (alias for lua integrations webhooks)
lua integrations triggers                  # Interactive trigger management
lua integrations triggers list             # List all triggers
lua integrations triggers create           # Create a new trigger
lua integrations triggers pause            # Pause a trigger or all triggers for a connection
lua integrations triggers resume           # Resume a trigger or all triggers for a connection
lua integrations triggers delete           # Delete a trigger
```

<Note>
  Top-level `lua triggers` is a different command — it manages [agent triggers](/cli/triggers-command) (paste-anywhere URLs that invoke your agent), not integration triggers.
</Note>

<Note>
  **Limit**: Only 1 connection per integration type is allowed per agent. To change scopes, use `lua integrations update`.
</Note>

## How It Works

1. **Connect**: Authenticate with a third-party service via OAuth or API token
2. **Auto-MCP**: An MCP server is automatically created and activated for the connection
3. **Agent Access**: Your agent can now use tools from that integration (e.g., create Linear issues, send Discord messages)
4. **Triggers** (optional): Set up event-driven triggers to wake up your agent when things happen (e.g., a task is created, a message is received). Triggers are opt-in — you can skip them at connect and add them later.

## Commands

### lua integrations connect

Connect a new third-party integration with optional triggers.

```bash theme={null}
# Interactive mode (recommended for first-time setup)
lua integrations connect

# Non-interactive: connect Linear with OAuth and all scopes
lua integrations connect --integration linear --auth-method oauth --scopes all

# Connect with triggers enabled (agent wakes up on events)
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated

# Connect with all available triggers
lua integrations connect --integration linear --auth-method oauth --scopes all --triggers all

# Use a custom webhook URL instead of agent trigger
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created --custom-webhook --hook-url https://my-server.com/webhook

# Specify specific scopes
lua integrations connect --integration linear --auth-method oauth --scopes "task_task_read,task_task_write"

# Use API token authentication
lua integrations connect --integration linear --auth-method token

# Control sensitive data visibility
lua integrations connect --integration discord --auth-method oauth --scopes all --hide-sensitive false
```

**What happens:**

1. In interactive mode, you're asked who should own the connection (see below)
2. CLI fetches available integrations
3. You select or specify an integration and auth method
4. Browser opens for OAuth authorization (or you enter API credentials)
5. Connection is established and stored
6. MCP server is automatically created and activated
7. In interactive mode, you're asked whether to configure triggers now (opt-in, default: skip). If triggers are specified via `--triggers`, they are created immediately.

#### Who owns the connection — `--scope`

| Scope             | Who can use it                                                                      |
| ----------------- | ----------------------------------------------------------------------------------- |
| `agent` (default) | This agent only. It holds the credential and loses it when the agent goes.          |
| `user`            | You. Every **private** agent you own can use it, including agents you create later. |

```bash theme={null}
# Connect as yourself — available on all your private agents
lua integrations connect --scope user --integration github --auth-method oauth --scopes all
```

Interactive runs ask and pre-select `agent`. A non-interactive run **without** `--scope` connects to the agent exactly as before, so existing scripts keep their meaning.

<Note>
  **Publishing an agent removes its access** to your personal connections. A published, shared or org-visible agent is not one only you can reach, so it is not covered — even if you created it.
</Note>

<Warning>
  Connecting as yourself has no wake-up triggers, no account name and no sensitive-data toggle. Passing `--triggers`, `--custom-webhook`, `--hook-url`, `--account-label` or `--hide-sensitive` together with `--scope user` is rejected before anything else happens. Connect at agent scope if you need those, or add triggers later on an agent connection.
</Warning>

<Note>
  **Triggers are opt-in**: The interactive flow asks "Do you want to configure triggers now?" and defaults to skip — add only what you actually need. You can always add triggers later with `lua integrations triggers create`. When using `--triggers` non-interactively, triggers are created immediately.
</Note>

### lua integrations convert

Turn a connection an agent owns into a personal one, without reconnecting.

```bash theme={null}
lua integrations convert --connection-id abc123
lua integrations convert --connection-id abc123 --force   # skip the confirmation
```

The agent you originally connected it to keeps access and its triggers keep firing; every other private agent you own gains it. Only a connection **you** created on a private agent can be converted, and a connection shared with the workspace must stop being shared first.

<Warning>
  There is no way to convert back, so the command asks for confirmation. Use `--force` only in scripts.
</Warning>

### lua integrations list

View all connected integrations and their status.

```bash theme={null}
lua integrations list                # this agent's connections
lua integrations list --scope user   # your personal connections
lua integrations list --scope all    # both
```

**Output:**

```
============================================================
🔗 Connected Integrations
============================================================

🟢 Linear
   ID: 6978e0294d9c2007ed5cb129
   Status: Active
   MCP Server: linear (✅ active)
   Connected: 1/27/2026

🟡 Discord
   ID: 6979e707ea702a223666bfd2
   Status: Connected (tools pending)
   MCP Server: discord (⏸️ inactive)
   Connected: 1/28/2026

============================================================
Total: 2 connection(s)
```

**Status Icons:**

* 🟢 Active - Connection healthy, tools available
* 🟡 Connected (tools pending) - Connection healthy, MCP server inactive
* 🔴 Unhealthy - Re-authorization required
* ⏸️ Paused - Connection paused

### lua integrations info

View detailed information about an integration type, including available OAuth scopes and triggers. This is useful for discovering what's available **before** connecting.

```bash theme={null}
# View integration details
lua integrations info linear

# Output as JSON (for scripting/AI agents)
lua integrations info linear --json
```

**Output:**

```
============================================================
📋 Integration Info: Linear
============================================================

🔑 OAuth Scopes:
   ✓ task_task_read
     Manage and view issues in Linear
   ✓ task_task_write
     Create and update issues in Linear
   ✓ task_project_read
     View projects in Linear
   ...

⚡ Available Triggers:
   • task_task.created [virtual, 60min interval]
     A new issue was created in Linear
   • task_task.updated [virtual, 60min interval]
     An issue was updated in Linear
   • task_task.deleted [virtual, 60min interval]
     An issue was deleted in Linear
   • task_comment.created [virtual, 60min interval]
     A new comment was added to an issue
   ...

============================================================
```

<Note>
  **Friendly Labels**: Scopes and triggers display user-friendly descriptions (e.g., "A new issue was created in Linear" instead of "task\_task.created") to help non-technical users understand what each option does.
</Note>

### lua integrations available

List all available integrations you can connect.

```bash theme={null}
lua integrations available
```

Shows integrations grouped by category (task, messaging, crm, etc.) with auth type indicators:

* 🔐 OAuth only
* 🔑 API Token only
* 🔐🔑 Both available

### lua integrations update

Update an existing connection's OAuth scopes. This re-authorizes the connection with new permissions.

```bash theme={null}
# Interactive mode
lua integrations update

# Non-interactive: update Linear with all scopes
lua integrations update --integration linear --scopes all

# Specific scopes
lua integrations update --integration linear --scopes "task_task_read,task_task_write,task_project_read"
```

<Note>
  Update deletes the old connection and creates a new one with updated scopes. You'll need to re-authorize in the browser.
</Note>

### lua integrations disconnect

Remove a connected account. This also deletes the associated MCP server and any webhook subscriptions.

```bash theme={null}
# Interactive mode
lua integrations disconnect

# Non-interactive
lua integrations disconnect --connection-id 6978e0294d9c2007ed5cb129

# Disconnect a personal connection — removes it from every agent at once
lua integrations disconnect --scope user --connection-id 6978e0294d9c2007ed5cb129
```

Disconnecting a personal connection asks whether to also forget what it added to memory. The default is **no** — disconnecting and forgetting are separate decisions, and only one of them can't be undone.

### lua integrations webhooks

Manage triggers (webhook subscriptions) for connected integrations. Triggers let your agent receive events when things happen in connected services (e.g., task created, message received).

<Tabs>
  <Tab title="list">
    List all triggers:

    ```bash theme={null}
    lua integrations webhooks list

    # Output as JSON for scripting
    lua integrations webhooks list --json
    ```

    **Output:**

    ```
    ────────────────────────────────────────────────────────────────────────────────
    ⚡ Triggers / Webhook Subscriptions
    ────────────────────────────────────────────────────────────────────────────────

    📦 linear
       ✅ task_task.created (poll, agent trigger)
          ID: 698304fa49d44978357b6435
       ⏸️  task_task.updated (paused by you) (poll, agent trigger)
          ID: 698304fb49d44978357b6436
       💳 task_comment.created (credit-suspended) (poll, agent trigger)
          ID: 698304fc49d44978357b6437

    ────────────────────────────────────────────────────────────────────────────────
    Total: 3 trigger(s)
    ```

    **Status Icons:**

    * ✅ Active — trigger is running
    * ⏸️ Paused by you — you paused this trigger; resume with `lua integrations triggers resume`
    * 💳 Credit-suspended — paused due to credit depletion; add credits to re-enable
    * 🔴 Unhealthy — requires re-authorization
    * ⚪ Paused externally — paused from outside Lua (e.g., Unified.to dashboard)

    **JSON Output:**

    ```json theme={null}
    {
      "triggers": [
        {
          "id": "698304fa49d44978357b6435",
          "integrationType": "linear",
          "objectType": "task_task",
          "event": "created",
          "webhookType": "virtual",
          "hookUrl": "https://api.heylua.ai/webhook/unifiedto/data",
          "status": "active",
          "userPaused": false,
          "creditSuspended": false,
          "interval": 60,
          "connectionId": "698304f949d44978357b6425"
        }
      ],
      "total": 1
    }
    ```

    <Note>
      Webhook IDs are displayed for each trigger, making it easy to reference them for pause/resume/delete operations.
    </Note>
  </Tab>

  <Tab title="events">
    List available trigger events for an integration:

    ```bash theme={null}
    # By integration type (before connecting)
    lua integrations webhooks events --integration linear

    # By connection ID (after connecting)
    lua integrations webhooks events --connection abc123

    # As JSON for scripting
    lua integrations webhooks events --integration linear --json
    ```

    **Output:**

    ```
    ⚡ Available Trigger Events for linear
    ────────────────────────────────────────────────────────────────────────────────
      • task_task.created [virtual]
        A new issue was created in Linear
      • task_task.updated [virtual]
        An issue was updated in Linear
      • task_task.deleted [virtual]
        An issue was deleted in Linear
      • task_comment.created [virtual]
        A new comment was added to an issue
    ────────────────────────────────────────────────────────────────────────────────
    ```
  </Tab>

  <Tab title="create">
    Create a new trigger:

    ```bash theme={null}
    # Interactive mode
    lua integrations webhooks create

    # Non-interactive: Agent trigger mode (default - wakes up your agent)
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created

    # Custom webhook URL (your own endpoint)
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created \
      --hook-url https://my-server.com/webhook

    # With custom polling interval for virtual webhooks
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event updated \
      --interval 120
    ```

    **Trigger Modes:**

    * **Agent Trigger** (default): Events wake up your agent with the payload in `runtimeContext`
    * **Custom URL**: Events are sent to your specified webhook URL

    **Webhook Types:**

    * **Native**: Real-time webhooks from the integration (when supported)
    * **Virtual**: Polling-based webhooks (Unified.to polls the API at intervals)

    **Interval options** (for virtual webhooks):

    * `60` - 1 hour (default)
    * `120` - 2 hours
    * `240` - 4 hours
    * `480` - 8 hours
    * `720` - 12 hours
    * `1440` - 24 hours
    * `2880` - 48 hours
  </Tab>

  <Tab title="delete">
    Delete a trigger:

    ```bash theme={null}
    lua integrations webhooks delete --webhook-id wh_abc123
    ```
  </Tab>

  <Tab title="pause">
    Pause a single trigger or all triggers for a connection. The connection and MCP server remain active — only event delivery is paused.

    ```bash theme={null}
    # Pause a single trigger (interactive: choose from list)
    lua integrations webhooks pause

    # Pause a specific trigger by ID
    lua integrations webhooks pause --webhook-id wh_abc123

    # Pause a specific trigger with a reason
    lua integrations webhooks pause --webhook-id wh_abc123 --reason "Maintenance window"

    # Pause ALL triggers for a connection
    lua integrations webhooks pause --connection-id 6978e0294d9c2007ed5cb129
    ```

    <Note>
      Pausing a trigger is different from deleting it. The subscription is preserved and can be resumed at any time. Credit-suspended triggers cannot be paused/resumed by users — add credits to re-enable them.
    </Note>
  </Tab>

  <Tab title="resume">
    Resume a paused trigger or all paused triggers for a connection.

    ```bash theme={null}
    # Resume a single trigger (interactive: choose from paused list)
    lua integrations webhooks resume

    # Resume a specific trigger by ID
    lua integrations webhooks resume --webhook-id wh_abc123

    # Resume ALL paused triggers for a connection
    lua integrations webhooks resume --connection-id 6978e0294d9c2007ed5cb129
    ```

    <Note>
      Credit-suspended triggers are skipped during resume — they require credits to be added to your account first.
    </Note>
  </Tab>
</Tabs>

### lua integrations mcp

Manage MCP servers for connections. MCP servers are automatically created when you connect an integration, but you can activate/deactivate them manually.

<Tabs>
  <Tab title="list">
    List connections with MCP server status:

    ```bash theme={null}
    lua integrations mcp list
    ```

    **Output:**

    ```
    ────────────────────────────────────────────────────────────────────────────────
    🔌 MCP Servers for Connections
    ────────────────────────────────────────────────────────────────────────────────

      Connection: 6978e0294d9c2007ed5cb129
      Integration: Linear
      MCP Server: linear
      Status: ✅ active
    ────────────────────────────────────────────────────────────────────────────────
    ```
  </Tab>

  <Tab title="activate">
    Activate MCP server for a connection:

    ```bash theme={null}
    lua integrations mcp activate --connection 6978e0294d9c2007ed5cb129
    ```

    Once activated, your agent can use tools from this integration.
  </Tab>

  <Tab title="deactivate">
    Deactivate MCP server for a connection:

    ```bash theme={null}
    lua integrations mcp deactivate --connection 6978e0294d9c2007ed5cb129
    ```

    The connection remains but tools are hidden from the agent.
  </Tab>
</Tabs>

## Non-Interactive Mode

All integrations commands support non-interactive mode for CI/CD, automation, and AI coding assistants.

### Discovery Commands

Use these to discover available options before connecting:

```bash theme={null}
# List available integrations
lua integrations available

# Get integration details (scopes and triggers)
lua integrations info linear
lua integrations info linear --json

# List available trigger events
lua integrations webhooks events --integration linear
lua integrations webhooks events --integration linear --json
```

### Connect Options

| Option                    | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| `--integration <type>`    | Integration type (e.g., `linear`, `discord`, `googlecalendar`)                  |
| `--auth-method <method>`  | Authentication method: `oauth` or `token`                                       |
| `--scopes <scopes>`       | Comma-separated OAuth scopes, or `all` for all available                        |
| `--hide-sensitive <bool>` | Hide sensitive data from MCP tools (default: `true`)                            |
| `--triggers <events>`     | Comma-separated triggers (e.g., `task_task.created,task_task.updated`) or `all` |
| `--custom-webhook`        | Use custom webhook URL instead of agent trigger                                 |
| `--hook-url <url>`        | Custom webhook URL (use with `--custom-webhook`)                                |

### Info Options

| Option   | Description                  |
| -------- | ---------------------------- |
| `--json` | Output as JSON for scripting |

### Disconnect Options

| Option                 | Description                 |
| ---------------------- | --------------------------- |
| `--connection-id <id>` | Connection ID to disconnect |

### Trigger/Webhook Options

| Option                 | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `--connection <id>`    | Connection ID for the trigger                     |
| `--connection-id <id>` | Connection ID for pause/resume all triggers       |
| `--integration <type>` | Integration type (for events discovery)           |
| `--object <type>`      | Object type (e.g., `task_task`, `calendar_event`) |
| `--event <type>`       | Event type: `created`, `updated`, or `deleted`    |
| `--hook-url <url>`     | Custom webhook URL (default: agent trigger)       |
| `--interval <minutes>` | Polling interval for virtual webhooks             |
| `--webhook-id <id>`    | Trigger ID (for delete/pause/resume actions)      |
| `--reason <text>`      | Optional reason for pausing (informational)       |
| `--json`               | Output as JSON (for list/events commands)         |

### MCP Options

| Option              | Description                      |
| ------------------- | -------------------------------- |
| `--connection <id>` | Connection ID for MCP operations |

### Examples

```bash theme={null}
# Discover available integrations and their details
lua integrations available
lua integrations info linear --json

# Connect (interactive — triggers are opt-in, default: skip)
lua integrations connect --integration linear --auth-method oauth --scopes all

# Connect with specific triggers in one command (non-interactive)
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated

# Add a trigger after connection (via alias)
lua integrations triggers create \
  --connection 6978e0294d9c2007ed5cb129 \
  --object task_task \
  --event deleted

# Create trigger with custom webhook URL
lua integrations webhooks create \
  --connection 6978e0294d9c2007ed5cb129 \
  --object task_task \
  --event created \
  --hook-url https://my-server.com/webhook

# Pause / resume a specific trigger
lua integrations triggers pause --webhook-id 698304fa49d44978357b6435
lua integrations triggers resume --webhook-id 698304fa49d44978357b6435

# Pause / resume ALL triggers for a connection
lua integrations triggers pause --connection-id 6978e0294d9c2007ed5cb129
lua integrations triggers resume --connection-id 6978e0294d9c2007ed5cb129

# List triggers with status icons
lua integrations triggers list
lua integrations triggers list --json

# Disconnect
lua integrations disconnect --connection-id 6978e0294d9c2007ed5cb129
```

## Workflow Example

<Steps>
  <Step title="Discover Available Integrations">
    ```bash theme={null}
    # See what integrations are available
    lua integrations available

    # Get details about a specific integration
    lua integrations info linear
    ```

    View available integrations, their OAuth scopes, and trigger events.
  </Step>

  <Step title="Connect the Integration">
    ```bash theme={null}
    # Interactive — you'll be asked whether to add triggers now (opt-in, default: skip)
    lua integrations connect --integration linear --auth-method oauth --scopes all

    # Or specify triggers directly (non-interactive)
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created,task_task.updated
    ```

    Complete OAuth in the browser. MCP server is auto-created and activated. Add triggers now or skip and add them later with `lua integrations triggers create`.
  </Step>

  <Step title="Verify Connection">
    ```bash theme={null}
    lua integrations list
    ```

    Confirm the connection shows as Active (🟢) and triggers are configured.
  </Step>

  <Step title="Test with Agent">
    ```bash theme={null}
    lua chat -e sandbox -m "Create a Linear issue titled 'Test from Lua'"
    ```

    Your agent should now have access to Linear tools.
  </Step>

  <Step title="Manage Triggers">
    ```bash theme={null}
    # List all triggers (with status icons)
    lua integrations triggers list

    # Add more triggers post-connect
    lua integrations triggers create --connection <id> --object task_task --event deleted

    # Pause a trigger temporarily
    lua integrations triggers pause --webhook-id <id>

    # Resume it later
    lua integrations triggers resume --webhook-id <id>
    ```

    When events occur in Linear, your agent will be notified automatically. Pause/resume any time without losing the subscription.
  </Step>
</Steps>

## Event-Driven Triggers

Triggers are a powerful way to make your agent **reactive** to external events. Instead of polling or manually checking for updates, your agent automatically wakes up when something happens.

### How Triggers Work

1. **You connect an integration** with triggers enabled
2. **Unified.to monitors** the connected service for events
3. **When an event occurs** (e.g., a task is created), Unified.to sends a webhook
4. **Your agent wakes up** with the event data in `runtimeContext`
5. **The agent can respond** based on what happened

### Example: React to New Linear Issues

```bash theme={null}
# Connect Linear with trigger for new issues
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created
```

When a new issue is created in Linear, your agent receives the event data and can:

* Send a notification to Slack
* Update a dashboard
* Assign the issue to a team member
* Any other action your agent is configured to perform

### Trigger Types

| Type        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| **Native**  | Real-time webhooks (when the integration supports them)        |
| **Virtual** | Polling-based (Unified.to checks at intervals, default 1 hour) |

Most integrations use virtual webhooks. The polling interval can be configured:

```bash theme={null}
# Set a 2-hour polling interval
lua integrations webhooks create --connection abc123 --object task_task --event created --interval 120
```

## Authentication Types

### OAuth 2.0 (Recommended)

* Secure authorization flow via browser
* Scope selection for fine-grained permissions
* Automatic token refresh
* Requires OAuth to be configured for the integration in your Unified.to workspace

### API Token / Personal Access Token

* Direct credential entry
* Simpler setup
* Token fields vary by integration (e.g., API Key, Personal Access Token, Bot Token)
* Instructions shown during connection for where to obtain credentials

## Tips

<AccordionGroup>
  <Accordion title="Use Triggers for Event-Driven Workflows">
    Triggers make your agent reactive to external events. They are opt-in — add only what you actually need:

    ```bash theme={null}
    # Add triggers after connecting (recommended: start with what you need)
    lua integrations triggers create --connection abc123 --object task_task --event created

    # Or specify triggers at connect time (non-interactive)
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created,task_task.updated

    # Pause a trigger temporarily (preserves subscription)
    lua integrations triggers pause --webhook-id <id>
    lua integrations triggers resume --webhook-id <id>
    ```

    Your agent automatically wakes up when events occur — no polling required!
  </Accordion>

  <Accordion title="Discover Before Connecting">
    Use discovery commands to understand what's available:

    ```bash theme={null}
    # See all integrations
    lua integrations available

    # Get detailed info about an integration
    lua integrations info linear

    # See available trigger events
    lua integrations webhooks events --integration linear
    ```

    This is especially useful for AI coding assistants building agents programmatically.
  </Accordion>

  <Accordion title="Hide Sensitive Data">
    By default, `--hide-sensitive true` is enabled, which hides sensitive fields from MCP tool responses. Disable only if your agent needs access to sensitive data:

    ```bash theme={null}
    lua integrations connect --integration discord --auth-method oauth --scopes all --hide-sensitive false
    ```
  </Accordion>

  <Accordion title="Scope Selection">
    When using OAuth, select only the scopes your agent needs. Use `all` during development, then restrict to specific scopes in production:

    ```bash theme={null}
    # Development
    lua integrations connect --integration linear --auth-method oauth --scopes all

    # Production
    lua integrations connect --integration linear --auth-method oauth --scopes "task_task_read,task_task_write"
    ```
  </Accordion>

  <Accordion title="One Connection Per Integration">
    Each agent can have only one connection per integration type. To change accounts or scopes, use `lua integrations update` or disconnect and reconnect.
  </Accordion>

  <Accordion title="JSON Output for Scripting">
    Use `--json` for machine-readable output:

    ```bash theme={null}
    lua integrations info linear --json
    lua integrations webhooks events --integration linear --json
    ```

    Perfect for CI/CD pipelines and AI coding assistants.
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup>
  <Card title="MCP Command" icon="plug" href="/cli/mcp-command">
    Manage all MCP servers (including non-integration servers)
  </Card>

  <Card title="Chat Command" icon="comments" href="/cli/chat-command">
    Test your agent with integration tools
  </Card>
</CardGroup>

## See Also

* [MCP Servers Overview](/overview/mcp-servers) - Understanding MCP servers
* [Webhooks Overview](/overview/webhooks) - Creating webhook handlers
* [LuaWebhook API](/api/luawebhook) - Webhook API reference


# Jobs Command
Source: https://docs.heylua.ai/cli/jobs-command

Manage scheduled jobs from the CLI — view, deploy, activate, trigger, and inspect execution history

## Overview

`lua jobs` manages scheduled jobs defined with `LuaJob`. It mirrors the surfaces available for skills (view, versions, deploy, activate, deactivate, delete) and adds two job-specific actions: `trigger` (manual fire) and `history` (execution log).

```bash theme={null}
lua jobs                                  # Interactive management
lua jobs view                             # List all jobs
lua jobs versions -i myJob                # List versions for a job
lua jobs trigger -i healthCheck           # Fire a job manually
lua jobs history -i myJob                 # View execution history
```

<Note>
  For defining jobs in code, see [LuaJob API](/api/luajob). For creating jobs dynamically from inside a tool at runtime, see [Jobs API](/api/jobs).
</Note>

## Subcommands

| Action       | What it does                                                                      |
| ------------ | --------------------------------------------------------------------------------- |
| `view`       | List all jobs defined on the agent.                                               |
| `versions`   | List every version of a specific job.                                             |
| `deploy`     | Promote a version to active.                                                      |
| `activate`   | Re-enable a deactivated job.                                                      |
| `deactivate` | Pause scheduled execution. Active version retained — re-activate with `activate`. |
| `trigger`    | Manually fire a job once (does not affect schedule).                              |
| `history`    | Print recent execution history with status and timestamps.                        |
| `delete`     | Permanently remove a job and all its versions.                                    |

## Options

| Option                    | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `-i, --job-name <name>`   | Job name. Required for most non-interactive actions.      |
| `-v, --job-version <ver>` | Version for `deploy`. Pass `latest` to deploy the newest. |

## Examples

```bash theme={null}
# Interactive — pick action and target from menus
lua jobs

# List everything
lua jobs view

# Promote a specific version to active
lua jobs deploy -i dailyReport -v 1.0.3

# Promote the latest version
lua jobs deploy -i dailyReport -v latest

# Pause and resume
lua jobs deactivate -i dailyReport
lua jobs activate   -i dailyReport

# Manually trigger a job (e.g. for ad-hoc runs)
lua jobs trigger -i healthCheck

# Inspect recent runs
lua jobs history -i dailyReport

# Delete a retired job
lua jobs delete -i oldCleanupJob
```

## Triggering vs Deploying

| Command                              | When to use                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `lua jobs trigger -i <name>`         | Run the job **once** right now. Useful for ad-hoc runs, smoke-tests after a deploy, and debugging. Schedule is untouched. |
| `lua jobs deploy -i <name> -v <ver>` | Promote a different version to active. Used after `lua push job` lands a new version on the server.                       |

## Common Workflow

After editing a job in code:

```bash theme={null}
lua push job             # Build + upload a new version
lua jobs versions -i myJob   # Confirm the new version is on the server
lua jobs deploy   -i myJob -v latest   # Promote it
lua jobs trigger  -i myJob   # Smoke-test the new version
lua jobs history  -i myJob   # Verify it ran cleanly
```

## Logs and Errors

To debug job execution, pair this with [`lua logs`](/cli/logs-command):

```bash theme={null}
lua logs --type job --name myJob --limit 20
lua logs --type job --name myJob --limit 20 --json | jq
```

## Related

* [LuaJob API](/api/luajob) — define a job in code
* [Jobs API](/api/jobs) — create jobs dynamically at runtime
* [Logs Command](/cli/logs-command)
* [Push & Deploy](/cli/skill-management#lua-push)
* [Version Command](/cli/version-command) — snapshot and promote every primitive, including jobs, together


# Logs Command
Source: https://docs.heylua.ai/cli/logs-command

View and debug agent execution logs

## Overview

The `lua logs` command provides an interactive interface for viewing and navigating your agent's execution logs with powerful filtering capabilities.

```bash theme={null}
lua logs
```

<Note>
  **Looking for the canonical debug loop?** See [Debugging your agent](/cli/debugging) for the recommended push → test → check flow that uses `lua logs` as the truth source.
</Note>

## When to run `lua logs`

There are three moments when `lua logs` is the most valuable command in the CLI:

**1. Immediately after a `lua chat -m "test"`.** A chat response can look fine while the server quietly logged a billing failure, a tool exception, or an LLM provider error. Run `lua logs --type agent_error --limit 5` after every test message — if the count is zero, the test passed cleanly. The CLI also runs a quiet `agent_error` probe automatically after each chat turn and prints a one-line warning when new errors fire (set `LUA_NO_HINTS=1` to silence it).

**2. After a `lua push` to verify a new version is healthy in production.** The CLI prints a `✨ Tip:` line at the end of every push pointing at the right `lua logs --type X --limit 10` command for what you just deployed — follow it.

**3. When investigating a user-reported issue.** Filter to the affected user with `--user-id <id>` and to the most likely component type:

```bash theme={null}
lua logs --type all --user-id user_abc123 --limit 50
lua logs --type skill --name <toolName> --user-id user_abc123 --limit 20
```

### Non-Interactive Mode

```bash theme={null}
# View all logs
lua logs --type all --limit 50

# Filter by type
lua logs --type skill --limit 20
lua logs --type webhook --limit 20
lua logs --type job --limit 20

# Filter by specific entity
lua logs --type skill --name mySkill --limit 10

# Pagination
lua logs --type all --limit 20 --page 2

# JSON output for scripting
lua logs --type all --json

# View logs for a different agent (admin access required)
lua logs --agent-id agent-abc123
lua logs --agent-id agent-abc123 --type skill --limit 10

# Voice calls
lua logs --type calls                                # recent voice calls (table)
lua logs --type calls --status failed --json         # failed calls as JSON
```

| Option                 | Description                                                                                                                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--type <type>`        | Filter: `all`, `skill`, `job`, `webhook`, `preprocessor`, `postprocessor`, `device`, `device-trigger`, `user_message`, `agent_response`, `agent_error`, `mcp`, `rag`, `runtime`, `calls` |
| `--name <name>`        | Entity name (requires --type, not for message types)                                                                                                                                     |
| `--user-id <userId>`   | Filter logs by user ID                                                                                                                                                                   |
| `--agent-id <agentId>` | View logs for a specific agent (overrides the agent in `lua.config.yaml`). Requires admin access to the target agent.                                                                    |
| `--status <status>`    | Filter calls by status (`completed`, `failed`, `in-progress`, etc.). Only with `--type calls`.                                                                                           |
| `--limit <n>`          | Number of logs (default: 20)                                                                                                                                                             |
| `--page <n>`           | Page number for pagination                                                                                                                                                               |
| `--json`               | Output as JSON for scripting                                                                                                                                                             |

<Note>
  **`--agent-id`** is useful for inspecting logs across multiple agents you own without switching project directories. If you don't have admin access to the requested agent, the command returns an access-denied error.
</Note>

<Note>
  **Type values:** Use `runtime` for platform runtime logs (was previously `mastra`). Use `rag` for knowledge base search logs, `device-trigger` for device trigger execution logs, and `calls` for voice call records.
</Note>

<Note>
  **`agent_error` vs `runtime`:** Use `--type agent_error` to find pipeline failures (billing, validation, LLM provider errors) — these often don't surface in the chat response itself. Use `--type runtime` for agent runtime / LLM SDK / framework-level diagnostics (low-level model and orchestration logs).
</Note>

## Post-deploy verification recipe

```bash theme={null}
# After deploying — generate traffic FIRST
lua push all --force --auto-deploy
lua chat -e production -m "your test message"   # ← generate traffic first
lua logs --type skill --limit 10                # ← now logs exist
```

Verify pipeline errors:

```bash theme={null}
lua chat -e production -m "verify deploy" -t prod-verify --clear
lua logs --type agent_error --limit 5
```

<Warning>
  `lua logs` returns nothing immediately after deploy. You must generate traffic (via `lua chat`, a webhook call, or a job trigger) before execution logs appear.
</Warning>

If `agent_error --limit 5` returns no entries timestamped after your deploy, the version is healthy. If it does, read the entries before walking away. See [Debugging your agent](/cli/debugging) for the complete flow.

<CardGroup>
  <Card title="Filter by Type" icon="filter">
    Filter logs by Skills, Jobs, Webhooks, Preprocessors, or Postprocessors
  </Card>

  <Card title="See All Your Components" icon="cloud">
    View logs for all your components, including dynamically created jobs
  </Card>

  <Card title="Detailed Information" icon="list">
    See which component generated each log, including names and IDs
  </Card>

  <Card title="Color-Coded" icon="palette">
    Easily spot errors, warnings, and different log types
  </Card>
</CardGroup>

## Log Types

<Tabs>
  <Tab title="❌ Error">
    **Execution errors and failures**

    * Tool execution failures
    * API errors
    * Invalid configurations
    * Stack traces for debugging

    Color: Red
  </Tab>

  <Tab title="⚠️ Warn">
    **Warnings and potential issues**

    * Performance warnings
    * Deprecated features
    * Configuration warnings

    Color: Yellow
  </Tab>

  <Tab title="🔍 Debug">
    **Debug information**

    * Tool inputs/outputs
    * Function execution status
    * Detailed operation info

    Color: Blue
  </Tab>

  <Tab title="ℹ️ Info">
    **General information**

    * Operation status
    * Configuration changes
    * General messages

    Color: Cyan
  </Tab>

  <Tab title="▶️ Start/✅ Complete">
    **Operation metrics**

    * Operation started
    * Operation completed
    * Duration measurements

    Color: Green
  </Tab>
</Tabs>

## Interactive Flow

<Steps>
  <Step title="Choose What to View">
    ```
    📊 Viewing logs for agent: myAgent

    ? What logs do you want to view?
    ❯ 📋 All agent logs
      🔎 Filter logs
    ```
  </Step>

  <Step title="Choose What to Filter (if filtering)">
    ```
    ? Filter by:
    ❯ Skills
      Jobs
      Webhooks
      Preprocessors
      Postprocessors
      MCP
      RAG (knowledge base)
      Runtime
      Agent errors
      Device trigger
      ──────────────────────
      📋 All logs
      ← Back
    ```
  </Step>

  <Step title="Select Specific Component (if filtering)">
    ```
    ? Select a job:
    ❯ All Jobs
      ──────────────────────
      Nightly User Report
      Daily Cleanup Task
      ──────────────────────
      ← Back
    ```

    <Note>
      **All Jobs Visible**: All your jobs appear in the list, including ones created dynamically in your code.
    </Note>
  </Step>

  <Step title="View Logs">
    ```
    All Agent Logs
    ────────────────────────────────────────────────────
    Page 1 of 88 (872 total logs)

    ❌ [2/3/2025, 4:40:55 PM] ERROR
       Job Name: Nightly User Report
       Job ID:   job_abc123
       Error executing function: Invalid API Key
    ──────────────────────────────────────────────────
    ✅ [2/3/2025, 4:40:55 PM] COMPLETE
       Skill Name: customer-service
       Skill ID:   skill_def456
       Tool Name:  search_products
       Duration: 125ms
       Execute function completed
    ──────────────────────────────────────────────────
    ```
  </Step>

  <Step title="Navigate">
    ```
    ? Navigation:
    ❯ Next Page →
      ← Previous Page
      🔢 Go to specific page
      🔄 Refresh
      ❌ Exit
    ```
  </Step>
</Steps>

## Use Cases

### Debug Tool Errors

```bash theme={null}
$ lua logs
→ Filter logs → Skills → Select your skill
→ Look for ❌ ERROR entries
→ Review error messages
→ Fix issues in your code
```

### Monitor Performance

```bash theme={null}
$ lua logs
→ Filter logs → Select component type
→ Find ✅ COMPLETE entries
→ Check duration metrics
→ Identify slow operations
```

### Verify Tool Execution

```bash theme={null}
$ lua logs
→ Filter logs → Skills → Select your skill
→ Look for 🔍 DEBUG entries
→ Verify tool inputs/outputs
```

### Track Webhook Activity

```bash theme={null}
$ lua logs
→ Filter logs → Webhooks → Select your webhook
→ Review webhook execution logs
→ Check request/response data
→ Debug external integrations
```

### Monitor Job Execution

```bash theme={null}
$ lua logs
→ Filter logs → Jobs → Select your job
→ View scheduled job execution logs
→ Check for errors or performance issues
```

## Example Session

```bash theme={null}
$ lua logs
✅ Authenticated
📊 Viewing logs for agent: myAgent

? What logs do you want to view? 🔎 Filter logs

? Filter by: Jobs

? Select a job: Nightly User Report

All Agent Logs
────────────────────────────────────────────────────────────────────────────────
Page 1 of 12 (120 total logs)

▶️ [11/7/2025, 10:30:00 AM] START
   Job Name: Nightly User Report
   Job ID:   job_abc123
   Duration: 150ms
   Starting job execution...
──────────────────────────────────────────────────────────────────────────────

✅ [11/7/2025, 10:30:05 AM] COMPLETE
   Job Name: Nightly User Report
   Job ID:   job_abc123
   Duration: 5234ms
   Job execution completed successfully
──────────────────────────────────────────────────────────────────────────────

? Navigation: Next Page →

[Shows page 2...]
```

### Filtering by Skill

```bash theme={null}
$ lua logs
? What logs do you want to view? 🔎 Filter logs
? Filter by: Skills
? Select a skill: customer-service

All Agent Logs
────────────────────────────────────────────────────────────────────────────────
Page 1 of 25 (250 total logs)

ℹ️ [11/7/2025, 10:31:15 AM] INFO
   Skill Name: customer-service
   Skill ID:   skill_def456
   Tool Name:  search_products
   Fetching products matching query...
──────────────────────────────────────────────────────────────────────────────

✅ [11/7/2025, 10:31:16 AM] COMPLETE
   Skill Name: customer-service
   Skill ID:   skill_def456
   Tool Name:  search_products
   Duration: 89ms
   Found 15 products matching "laptop"
──────────────────────────────────────────────────────────────────────────────
```

## Log Entry Details

Each log entry shows you:

### For Skill Logs

* **Skill Name** - Which skill generated the log
* **Skill ID** - Unique identifier for the skill
* **Tool Name** - Which tool was running (if applicable)
* **Timestamp** - When the log was created
* **Log Type** - Error, debug, info, warn, start, or complete
* **Message** - The actual log message
* **Duration** - How long the operation took (for completed operations)

### For Job Logs

* **Job Name** - Which job generated the log
* **Job ID** - Unique identifier for the job
* **Timestamp** - When the log was created
* **Log Type** - Error, debug, info, warn, start, or complete
* **Message** - The actual log message
* **Duration** - How long the job took to run

### For Webhook, Preprocessor, and Postprocessor Logs

* **Name** - Which component generated the log
* **ID** - Unique identifier
* **Timestamp** - When the log was created
* **Log Type** - Error, debug, info, warn, start, or complete
* **Message** - The actual log message
* **Duration** - How long the operation took

<Note>
  **Tool Information**: Tool names are only shown for skill logs, since tools belong to skills.
</Note>

## Navigation Options

<Tabs>
  <Tab title="Next Page →">
    View the next page of logs

    Disabled if on last page
  </Tab>

  <Tab title="← Previous Page">
    Go back to previous page

    Disabled if on first page
  </Tab>

  <Tab title="🔢 Go to specific page">
    ```
    ? Enter page number (1-88): 45
    ```

    Jump directly to any page
  </Tab>

  <Tab title="🔄 Refresh">
    Reload current page with latest logs

    Useful for monitoring in real-time
  </Tab>

  <Tab title="❌ Exit">
    Close the logs viewer
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Start with All Logs">
    ```bash theme={null}
    # Get overview first
    lua logs → All agent logs

    # Then filter if needed
    lua logs → Specific skill logs
    ```
  </Accordion>

  <Accordion title="Monitor After Deployment">
    ```bash theme={null}
    # After deploying — generate traffic FIRST
    lua push all --force --auto-deploy
    lua chat -e production -m "your test message"   # ← generate traffic first
    lua logs --type skill --limit 10                # ← now logs exist

    lua logs → All agent logs → Refresh periodically
    ```
  </Accordion>

  <Accordion title="Debug Specific Issues">
    ```bash theme={null}
    # Issue with specific skill
    lua logs → Specific skill logs → Select problem skill

    # Focus on errors
    # Look for ❌ ERROR entries
    ```
  </Accordion>

  <Accordion title="Track Performance">
    ```bash theme={null}
    # Check operation speed
    lua logs → All agent logs

    # Note duration on ✅ COMPLETE entries
    # Identify slow operations (>1000ms)
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No logs available">
    **Causes:**

    * Skills not deployed yet
    * Agent hasn't been used
    * Viewing wrong agent

    **Solution:**

    ```bash theme={null}
    lua push  # Deploy skills
    lua chat  # Use agent to generate logs
    lua logs  # View logs
    ```
  </Accordion>

  <Accordion title="Can't find specific error">
    **Try:**

    * Navigate through pages using the navigation menu
    * Filter by the specific component (skill, job, etc.)
    * Check the most recent pages first (page 1)
    * Look at the timestamp to find when the error occurred
  </Accordion>

  <Accordion title="Logs not updating">
    **Use refresh:**

    ```
    ? Navigation: 🔄 Refresh
    ```

    Reloads current page with latest data
  </Accordion>
</AccordionGroup>

## Integration with Workflow

### During Development

```bash theme={null}
# Make changes
vim src/tools/MyTool.ts

# Test
lua chat

# Check logs immediately
lua logs
# Look for errors or warnings
```

### After Deployment

```bash theme={null}
# Deploy
lua push && lua deploy

# Monitor logs
lua logs
# Watch for errors in production
# Check performance metrics
```

### Debugging Issues

```bash theme={null}
# User reports an issue
lua logs
# Find the relevant error in the logs
# Note the timestamp and which component had the error
# Fix the issue in your code
# Deploy the fix
# Monitor logs again to verify the fix
```

## Related Commands

<CardGroup>
  <Card title="Debugging Loop" icon="bug" href="/cli/debugging">
    Canonical push → test → check flow
  </Card>

  <Card title="lua chat" icon="comments" href="/cli/chat-command">
    Test agent (generates logs + auto agent\_error probe)
  </Card>

  <Card title="lua test" icon="flask" href="/cli/skill-management">
    Test tools locally (no remote logs)
  </Card>

  <Card title="lua push" icon="upload" href="/cli/skill-management">
    Deploy skills (required for logs)
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Generate logs to view
  </Card>

  <Card title="Deploy Skills" icon="rocket" href="/cli/skill-management">
    Push skills to generate logs
  </Card>

  <Card title="Troubleshooting" icon="circle-question" href="/cli/troubleshooting">
    Common issues and solutions
  </Card>

  <Card title="Production Monitoring" icon="chart-line" href="/cli/production-command">
    Monitor production environment
  </Card>
</CardGroup>


# Marketplace Command
Source: https://docs.heylua.ai/cli/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)


# MCP Command
Source: https://docs.heylua.ai/cli/mcp-command

Manage MCP servers for your agent

## Overview

The `lua mcp` command manages Model Context Protocol (MCP) servers. Use it to list, activate, deactivate, and delete MCP servers.

<Note>
  **MCP servers from integrations**: When you connect a third-party account via `lua integrations connect`, an MCP server is automatically created and activated. These integration-based servers have a `source` field set to `unifiedto`. You can manage them with both `lua mcp` and `lua integrations mcp` commands.
</Note>

```bash theme={null}
lua mcp              # Interactive mode
lua mcp list         # List all servers
lua mcp activate     # Activate a server
lua mcp deactivate   # Deactivate a server
lua mcp delete       # Delete a server
```

### Non-Interactive Mode

```bash theme={null}
# List all MCP servers
lua mcp list

# Activate a server (positional or flag style)
lua mcp activate docs-server
lua mcp activate --server-name docs-server

# Deactivate a server
lua mcp deactivate --server-name api-server

# Delete a server
lua mcp delete --server-name old-server
```

| Option                 | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `--server-name <name>` | MCP server name (for activate/deactivate/delete) |

| Action       | Description          | Required Options              |
| ------------ | -------------------- | ----------------------------- |
| `list`       | List all MCP servers | None                          |
| `activate`   | Activate a server    | `--server-name` or positional |
| `deactivate` | Deactivate a server  | `--server-name` or positional |
| `delete`     | Delete a server      | `--server-name` or positional |

## Commands

### lua mcp

Interactive MCP server management.

```bash theme={null}
lua mcp
```

Opens an interactive menu to:

* List MCP servers
* Activate a server
* Deactivate a server
* Delete a server

### lua mcp list

List all MCP servers and their status.

```bash theme={null}
lua mcp list
# or
lua mcp ls
```

**Output:**

```
============================================================
🔌 MCP Servers
============================================================

✅ Active Servers:

🟢 docs-server
   Transport: streamable-http
   URL: https://docs.example.com/mcp
   ID: mcp_abc123

────────────────────────────────────────

⏸️  Inactive Servers:

⚪ api-gateway
   Transport: streamable-http
   URL: https://api.example.com/mcp
   ID: mcp_def456

============================================================
```

### lua mcp activate

Activate an MCP server to make its tools available.

```bash theme={null}
lua mcp activate              # Interactive selection
lua mcp activate docs-server  # Activate by name
# or
lua mcp enable docs-server    # Alias
```

**What happens:**

* Server is marked as active
* Server's tools become available to your agent
* Tools appear in the agent's tool list at runtime

**Example:**

```bash theme={null}
$ lua mcp activate docs-server
🔄 Activating docs-server...

✅ MCP server "docs-server" activated successfully!

💡 The server's tools are now available to your agent.
```

### lua mcp deactivate

Deactivate an MCP server to remove its tools.

```bash theme={null}
lua mcp deactivate              # Interactive selection
lua mcp deactivate docs-server  # Deactivate by name
# or
lua mcp disable docs-server     # Alias
```

**What happens:**

* Server is marked as inactive
* Server's tools are removed from agent runtime
* Configuration is preserved (can be re-activated)

**Example:**

```bash theme={null}
$ lua mcp deactivate docs-server
🔄 Deactivating docs-server...

✅ MCP server "docs-server" deactivated successfully!

💡 The server's tools are no longer available to your agent.
```

### lua mcp delete

Permanently delete an MCP server.

```bash theme={null}
lua mcp delete              # Interactive selection
lua mcp delete docs-server  # Delete by name
# or
lua mcp rm docs-server      # Alias
```

<Warning>
  **This is permanent!** Deleting an MCP server removes it from the platform. You'll need to re-compile and push to recreate it.
</Warning>

**Example:**

```bash theme={null}
$ lua mcp delete docs-server

⚠️  You are about to delete MCP server: docs-server
⚠️  WARNING: This server is currently ACTIVE!
? Are you sure you want to delete this MCP server? (y/N) y

🔄 Deleting docs-server...

✅ MCP server "docs-server" deleted successfully!
```

## Command Aliases

| Command              | Alias             |
| -------------------- | ----------------- |
| `lua mcp list`       | `lua mcp ls`      |
| `lua mcp activate`   | `lua mcp enable`  |
| `lua mcp deactivate` | `lua mcp disable` |
| `lua mcp delete`     | `lua mcp rm`      |

## Pushing MCP Servers

MCP servers can also be pushed using the `lua push` command:

```bash theme={null}
# Push a single MCP server
lua push mcp
# Select server from list

# Push all components including MCP servers
lua push all --force
```

When pushing all with `--auto-deploy`, MCP servers are automatically activated:

```bash theme={null}
lua push all --force --auto-deploy
```

## Workflow Example

<Steps>
  <Step title="Define MCP Server">
    Create the server in your code:

    ```typescript theme={null}
    // src/mcp/docs.ts
    import { LuaMCPServer, env } from 'lua-cli';

    export const docsServer = new LuaMCPServer({
      name: 'docs-server',
      transport: 'streamable-http',
      url: 'https://docs.example.com/mcp',
      headers: () => ({
        'Authorization': `Bearer ${env("DOCS_API_KEY")}`
      })
    });
    ```
  </Step>

  <Step title="Add to Agent">
    ```typescript theme={null}
    // src/index.ts
    import { LuaAgent } from 'lua-cli';
    import { docsServer } from './mcp/docs';

    export const agent = new LuaAgent({
      name: 'my-agent',
      persona: '...',
      mcpServers: [docsServer]
    });
    ```
  </Step>

  <Step title="Compile">
    ```bash theme={null}
    lua compile
    # Server is registered, ID assigned
    ```
  </Step>

  <Step title="Push">
    ```bash theme={null}
    lua push mcp
    # or
    lua push all --force
    ```
  </Step>

  <Step title="Activate">
    ```bash theme={null}
    lua mcp activate docs-server
    # Tools are now available
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    lua mcp list
    # Shows docs-server as active
    ```
  </Step>
</Steps>

## Tips

<AccordionGroup>
  <Accordion title="Check status before activating">
    Use `lua mcp list` to see current status before making changes

    ```bash theme={null}
    lua mcp list
    # Shows which servers are active/inactive
    ```
  </Accordion>

  <Accordion title="Activate only what you need">
    Keep unused servers deactivated to reduce overhead

    ```bash theme={null}
    lua mcp activate docs-server    # When needed
    lua mcp deactivate docs-server  # When done
    ```
  </Accordion>

  <Accordion title="Use --force for automation">
    In CI/CD, use `lua push all --force` to avoid prompts

    ```bash theme={null}
    lua push all --force --auto-deploy
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup>
  <Card title="lua compile" href="/cli/skill-management#lua-compile" icon="gears">
    Compile and register MCP servers
  </Card>

  <Card title="lua push" href="/cli/skill-management#lua-push" icon="upload">
    Push MCP server configuration
  </Card>
</CardGroup>

## See Also

* [MCP Servers Overview](/overview/mcp-servers) - Conceptual introduction
* [LuaMCPServer API](/api/luamcpserver) - Complete API reference
* [Skill Management](/cli/skill-management) - Compile and push commands
* [Integrations Command](/cli/integrations-command) - Connect third-party accounts (auto-creates MCP servers)


# Non-Interactive Mode
Source: https://docs.heylua.ai/cli/non-interactive-mode

Automate CLI commands for AI IDEs, CI/CD pipelines, and scripting

## Overview

All Lua CLI commands now support **non-interactive mode**, enabling seamless automation for:

* **AI IDEs** (Cursor, GitHub Copilot, Windsurf, etc.)
* **CI/CD pipelines** (GitHub Actions, GitLab CI, Jenkins)
* **Shell scripting** and automation
* **Programmatic agent management**

Non-interactive mode bypasses all prompts by providing arguments and flags directly on the command line.

<Note>
  Every command now has non-interactive options with consistent naming patterns.
</Note>

<Card title="AI Agent Building Guide" icon="robot" href="/ai-guide">
  **Building with Cursor, Windsurf, or GitHub Copilot?** See the complete AI Agent Building Guide for the full end-to-end workflow including authentication, testing strategies, sandbox vs production, common gotchas, and debugging.
</Card>

## Design Patterns

### Consistent Option Naming

All commands follow these patterns:

| Pattern              | Description                | Example                 |
| -------------------- | -------------------------- | ----------------------- |
| `--<entity>-name`    | Select entity by name      | `--skill-name mySkill`  |
| `--<entity>-version` | Specify version            | `--skill-version 1.0.5` |
| `--force`            | Skip confirmation prompts  | `--force`               |
| `--json`             | Output as JSON for parsing | `--json`                |
| `[action]`           | Positional action argument | `lua jobs view`         |

### Action Arguments

Many commands accept an action as the first argument:

```bash theme={null}
lua skills view                    # View all skills
lua skills versions --skill-name x # View versions for skill x
lua skills deploy --skill-name x   # Deploy skill x
```

## CI/CD Mode (--ci flag)

<Note>
  The global `--ci` flag makes the CLI fail loudly on missing required arguments instead of silently prompting (which fails in non-TTY environments).
</Note>

In CI/CD pipelines and non-TTY environments (piped input, background jobs), interactive prompts silently fail, causing commands to cancel without clear error messages. The `--ci` flag prevents this by throwing errors when required arguments are missing:

```bash theme={null}
# Without --ci (fails silently in CI/CD)
lua push skill
# Silently cancels - no clear error

# With --ci (fails loudly with helpful error)
lua --ci push skill
# Error: Interactive prompt required but --ci flag is set. Provide all required flags or arguments.
```

### Usage

The `--ci` flag is a **global flag** that must come before the command:

```bash theme={null}
# Correct
lua --ci push skill --name mySkill --set-version 1.0.0 --force

# Incorrect
lua push skill --ci  # Won't work - must be global
```

### When to Use

<Tabs>
  <Tab title="CI/CD Pipelines">
    **Always use `--ci` in automated environments:**

    ```yaml theme={null}
    # GitHub Actions
    - name: Push skill
      run: lua --ci push skill --name mySkill --set-version ${{ github.sha }} --force

    # GitLab CI
    script:
      - lua --ci push all --force --auto-deploy
    ```

    **Why**: Ensures missing flags cause immediate, clear failures instead of silent hangs.
  </Tab>

  <Tab title="Local Development">
    **Don't use `--ci` locally:**

    ```bash theme={null}
    # Local - interactive prompts are helpful
    lua push skill
    ? Select a skill: mySkill
    ? Enter version: 1.0.1

    # CI/CD - no prompts, just errors
    lua --ci push skill
    # Error: missing --name flag
    ```

    **Why**: Interactive prompts provide guidance and defaults.
  </Tab>

  <Tab title="Scripts & Automation">
    **Use `--ci` in bash scripts:**

    ```bash theme={null}
    #!/bin/bash
    set -e

    # Fail fast if required args missing
    lua --ci push skill \
      --name "$SKILL_NAME" \
      --set-version "$VERSION" \
      --force
    ```

    **Why**: Scripts should fail fast and clearly, not hang waiting for input.
  </Tab>
</Tabs>

### Behavior Differences

| Scenario              | Without --ci               | With --ci                      |
| --------------------- | -------------------------- | ------------------------------ |
| Missing required flag | Shows prompt (hangs in CI) | Throws error immediately       |
| Non-TTY environment   | Shows warning, continues   | Throws error if prompts needed |
| All flags provided    | Works normally             | Works normally                 |

### Auto-Detection

Even without `--ci`, the CLI automatically detects non-TTY environments and shows a warning:

```bash theme={null}
echo "" | lua push skill
# Warning: stdin is not a TTY. Interactive prompts may not work correctly.
# Tip: Use --ci flag in CI/CD environments to fail loudly on missing required flags.
```

However, this still allows the command to continue (and likely fail silently). Using `--ci` prevents this by failing immediately.

## Complete Command Reference

### Project Setup

<Tabs>
  <Tab title="init">
    Initialize a new project without prompts:

    ```bash theme={null}
    # Use existing agent
    lua init --agent-id abc123

    # Create agent in existing organization
    lua init --agent-name "My Bot" --org-id org456

    # Create agent + new organization
    lua init --agent-name "My Bot" --org-name "Acme Corp"

    # Create agent with a specific model
    lua init --agent-name "My Bot" --org-id org456 --model openai/gpt-4o

    # Override existing project
    lua init --agent-id abc123 --force

    # With example code
    lua init --agent-id abc123 --with-examples
    ```

    | Option                | Description                                    |
    | --------------------- | ---------------------------------------------- |
    | `--agent-id <id>`     | Use existing agent by ID                       |
    | `--agent-name <name>` | Name for new agent                             |
    | `--org-id <id>`       | Existing organization ID                       |
    | `--org-name <name>`   | New organization name                          |
    | `--model <model>`     | LLM model for the agent (e.g. `openai/gpt-4o`) |
    | `--force`             | Override existing `lua.skill.yaml`             |
    | `--with-examples`     | Include example code                           |
  </Tab>
</Tabs>

### Development & Testing

<Tabs>
  <Tab title="test">
    Test skills, webhooks, or jobs without prompts:

    ```bash theme={null}
    # Test a skill/tool
    lua test skill --name get_weather --input '{"city": "London"}'

    # Test a webhook
    lua test webhook --name payment-hook --input '{"query": {}, "headers": {}, "body": {"type": "payment"}}'

    # Test a job
    lua test job --name daily-report

    # Test preprocessor
    lua test preprocessor --name filter --input '{"message": "hello", "channel": "web"}'

    # Test postprocessor
    lua test postprocessor --name formatter --input '{"message": "hi", "response": "hello", "channel": "web"}'
    ```

    | Option           | Description            |
    | ---------------- | ---------------------- |
    | `--name <name>`  | Entity name to test    |
    | `--input <json>` | JSON input for testing |
  </Tab>

  <Tab title="sync">
    Detect and resolve drift without prompts:

    ```bash theme={null}
    # Check for drift (exit code 1 if found)
    lua sync --check

    # Auto-accept server state (pull server → local)
    lua sync --accept

    # Push local state to server without prompting
    lua sync --push
    ```

    | Option     | Description                 |
    | ---------- | --------------------------- |
    | `--check`  | Check only, exit 1 if drift |
    | `--accept` | Pull server state to local  |
    | `--push`   | Push local state to server  |
  </Tab>

  <Tab title="chat">
    Send messages without interactive session:

    ```bash theme={null}
    # Send to sandbox
    lua chat -e sandbox -m "Hello, what can you do?"

    # Send to production
    lua chat -e production -m "Help me with my order"

    # Default: sandbox
    lua chat -m "Quick test message"

    # Scoped to an explicit thread
    lua chat -m "Run scenario A" --thread scenario-a

    # Auto-generated thread (UUID printed at start)
    lua chat -m "Isolated test" --thread

    # Isolated test with auto-clear after response
    lua chat -m "Run test" -t my-test --clear

    # Send multiple messages concurrently (load / batch testing)
    lua chat -b "Message 1" "Message 2" "Message 3"

    # Batch with delay between messages (ms)
    lua chat -b "Msg 1" "Msg 2" "Msg 3" -d 500
    ```

    **File attachments** — use `@<path>` inside the message string:

    ```bash theme={null}
    # Attach an image
    lua chat -m "@screenshot.png what's wrong with this UI?" -e sandbox

    # Attach a document
    lua chat -m "@report.pdf summarize this" -e production

    # Multiple attachments
    lua chat -m "compare @before.png and @after.png" -e sandbox
    ```

    | Option                      | Description                                               |
    | --------------------------- | --------------------------------------------------------- |
    | `-e, --env <env>`           | Environment: sandbox or production                        |
    | `-m, --message <text>`      | Message to send (supports `@<path>` file attachments)     |
    | `-t, --thread [id]`         | Scope to a thread (omit ID to auto-generate UUID)         |
    | `--clear`, `--clear-thread` | Clear thread history after response (requires `--thread`) |
    | `-b, --batch <messages...>` | Send multiple messages concurrently                       |
    | `-d, --delay <ms>`          | Delay between batch messages in ms (default: 100)         |
  </Tab>
</Tabs>

### Deployment

<Tabs>
  <Tab title="push">
    Push components without prompts:

    ```bash theme={null}
    # Push specific skill with version
    lua push skill --name mySkill --set-version 1.0.5

    # Push all components
    lua push all --force

    # Push and auto-deploy to production
    lua push all --force --auto-deploy

    # Push webhook
    lua push webhook --name payment-hook --set-version 2.0.0

    # Push job
    lua push job --name daily-report --set-version 1.0.0
    ```

    | Option                | Description         |
    | --------------------- | ------------------- |
    | `--name <name>`       | Entity name to push |
    | `--set-version <ver>` | Version to set      |
    | `--force`             | Skip confirmations  |
    | `--auto-deploy`       | Deploy after push   |
  </Tab>

  <Tab title="deploy">
    Deploy to production without prompts:

    ```bash theme={null}
    # Deploy specific version
    lua deploy --skill-name mySkill --skill-version 1.0.5 --force

    # Deploy latest version
    lua deploy --skill-name mySkill --skill-version latest --force
    ```

    | Option                  | Description         |
    | ----------------------- | ------------------- |
    | `--skill-name <name>`   | Skill to deploy     |
    | `--skill-version <ver>` | Version or 'latest' |
    | `--force`               | Skip confirmation   |

    <Note>
      If the agent has already promoted an agent version, `lua deploy` performs a scoped promote (creates and promotes a new agent version identical to the current one, except for the deployed primitive) so the deploy is live immediately and shows up in `lua version list`. For CI/CD pipelines that want to snapshot and promote every primitive together instead, see [`lua version create --auto-push`](/cli/version-command#lua-version-create) and [`lua version promote`](/cli/version-command#lua-version-promote).
    </Note>
  </Tab>
</Tabs>

### Entity Management

<Tabs>
  <Tab title="skills">
    Manage skills without prompts:

    ```bash theme={null}
    # View all production skills
    lua skills view

    # View skill versions
    lua skills versions --skill-name mySkill

    # Deploy specific version
    lua skills deploy --skill-name mySkill --skill-version 1.0.3

    # Deploy latest
    lua skills deploy --skill-name mySkill --skill-version latest
    ```

    | Action     | Options Required                  |
    | ---------- | --------------------------------- |
    | `view`     | None                              |
    | `versions` | `--skill-name`                    |
    | `deploy`   | `--skill-name`, `--skill-version` |
  </Tab>

  <Tab title="webhooks">
    Manage webhooks without prompts:

    ```bash theme={null}
    lua webhooks view
    lua webhooks activate --webhook-name myWebhook
    lua webhooks deactivate --webhook-name myWebhook
    lua webhooks versions --webhook-name myWebhook
    lua webhooks deploy --webhook-name myWebhook --webhook-version 1.0.3

    # Event subscriptions
    lua webhooks list-events
    lua webhooks subscribe --webhook-name myWebhook --event message.delivered
    lua webhooks unsubscribe --webhook-name myWebhook --event message.delivered
    ```

    | Action        | Options Required                      |
    | ------------- | ------------------------------------- |
    | `view`        | None                                  |
    | `activate`    | `--webhook-name`                      |
    | `deactivate`  | `--webhook-name`                      |
    | `versions`    | `--webhook-name`                      |
    | `deploy`      | `--webhook-name`, `--webhook-version` |
    | `list-events` | None                                  |
    | `subscribe`   | `--webhook-name`, `--event`           |
    | `unsubscribe` | `--webhook-name`, `--event`           |

    **Available event types (WhatsApp):**

    | Event               | Description                                     |
    | ------------------- | ----------------------------------------------- |
    | `message.sent`      | Message was sent to the recipient               |
    | `message.delivered` | Message was delivered to the recipient's device |
    | `message.read`      | Recipient read the message                      |
    | `message.failed`    | Message failed to send                          |
    | `message.played`    | Recipient played a voice/video message          |
  </Tab>

  <Tab title="jobs">
    Manage scheduled jobs without prompts:

    ```bash theme={null}
    lua jobs view
    lua jobs trigger -i healthCheck
    lua jobs activate -i myJob
    lua jobs deactivate -i myJob
    lua jobs versions -i myJob
    lua jobs deploy -i myJob -v 1.0.3
    lua jobs deploy -i myJob -v latest
    lua jobs history -i myJob
    lua jobs delete -i oldJob
    ```

    | Option                        | Description                       |
    | ----------------------------- | --------------------------------- |
    | `-i, --job-name <name>`       | Job name                          |
    | `-v, --job-version <version>` | Version or 'latest' (deploy only) |

    | Action       | Options Required              |
    | ------------ | ----------------------------- |
    | `view`       | None                          |
    | `trigger`    | `--job-name`                  |
    | `activate`   | `--job-name`                  |
    | `deactivate` | `--job-name`                  |
    | `versions`   | `--job-name`                  |
    | `deploy`     | `--job-name`, `--job-version` |
    | `history`    | `--job-name`                  |
    | `delete`     | `--job-name`                  |
  </Tab>

  <Tab title="preprocessors">
    Manage preprocessors without prompts:

    ```bash theme={null}
    lua preprocessors view
    lua preprocessors activate --preprocessor-name myPre
    lua preprocessors deactivate --preprocessor-name myPre
    lua preprocessors versions --preprocessor-name myPre
    lua preprocessors deploy --preprocessor-name myPre --preprocessor-version 1.0.3
    lua preprocessors delete --preprocessor-name oldPre
    ```
  </Tab>

  <Tab title="postprocessors">
    Manage postprocessors without prompts:

    ```bash theme={null}
    lua postprocessors view
    lua postprocessors activate --postprocessor-name myPost
    lua postprocessors deactivate --postprocessor-name myPost
    lua postprocessors versions --postprocessor-name myPost
    lua postprocessors deploy --postprocessor-name myPost --postprocessor-version 1.0.3
    lua postprocessors delete --postprocessor-name oldPost
    ```
  </Tab>
</Tabs>

### Configuration

<Tabs>
  <Tab title="env">
    Manage environment variables without prompts:

    ```bash theme={null}
    # List variables
    lua env sandbox --list
    lua env production --list

    # Set variable
    lua env sandbox -k DATABASE_URL -v "postgres://localhost/db"
    lua env production -k API_KEY -v "sk_live_xxx"

    # Delete variable
    lua env production -k OLD_KEY --delete
    ```

    | Option              | Description         |
    | ------------------- | ------------------- |
    | `--list`            | List all variables  |
    | `-k, --key <name>`  | Variable name       |
    | `-v, --value <val>` | Variable value      |
    | `-d, --delete`      | Delete the variable |
  </Tab>

  <Tab title="persona">
    Manage persona without prompts:

    ```bash theme={null}
    # View current persona
    lua persona production view

    # List versions
    lua persona production versions

    # Deploy specific version
    lua persona production deploy --persona-version 5

    # Deploy latest
    lua persona production deploy --persona-version latest --force
    ```

    | Action     | Options                        |
    | ---------- | ------------------------------ |
    | `view`     | None                           |
    | `versions` | None                           |
    | `deploy`   | `--persona-version`, `--force` |
  </Tab>

  <Tab title="features">
    Manage features without prompts:

    ```bash theme={null}
    lua features list
    lua features enable --feature-name rag
    lua features disable --feature-name rag
    lua features view --feature-name webSearch
    ```

    | Action    | Options Required |
    | --------- | ---------------- |
    | `list`    | None             |
    | `enable`  | `--feature-name` |
    | `disable` | `--feature-name` |
    | `view`    | `--feature-name` |
  </Tab>

  <Tab title="resources">
    Manage knowledge base without prompts:

    ```bash theme={null}
    lua resources list
    lua resources view --resource-name "FAQ Document"
    lua resources delete --resource-name "Old Document"
    ```

    | Action   | Options Required  |
    | -------- | ----------------- |
    | `list`   | None              |
    | `view`   | `--resource-name` |
    | `delete` | `--resource-name` |
  </Tab>

  <Tab title="mcp">
    Manage MCP servers without prompts:

    ```bash theme={null}
    lua mcp list
    lua mcp activate --server-name filesystem
    lua mcp deactivate --server-name api-server
    lua mcp delete --server-name old-server

    # Positional style also works
    lua mcp activate filesystem
    ```

    | Action       | Options Required |
    | ------------ | ---------------- |
    | `list`       | None             |
    | `activate`   | `--server-name`  |
    | `deactivate` | `--server-name`  |
    | `delete`     | `--server-name`  |
  </Tab>

  <Tab title="integrations">
    Connect and manage third-party integrations without prompts:

    **Discovery Commands (for AI agents and scripting):**

    ```bash theme={null}
    # View available integrations
    lua integrations available

    # Get integration details (scopes and triggers)
    lua integrations info linear
    lua integrations info linear --json

    # List available trigger events
    lua integrations webhooks events --integration linear
    lua integrations webhooks events --integration linear --json
    ```

    **Connect with Triggers:**

    ```bash theme={null}
    # Connect with triggers enabled (recommended)
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created,task_task.updated

    # Connect with all available triggers
    lua integrations connect --integration linear --auth-method oauth --scopes all --triggers all

    # Connect without triggers
    lua integrations connect --integration linear --auth-method oauth --scopes all

    # Connect with custom webhook URL instead of agent trigger
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created --custom-webhook --hook-url https://my-server.com/webhook

    # List connections
    lua integrations list

    # Update connection scopes
    lua integrations update --integration linear --scopes "task_task_read,task_task_write"

    # Disconnect
    lua integrations disconnect --connection-id 6978e0294d9c2007ed5cb129
    ```

    **Connect Options:**

    | Option                    | Description                              |
    | ------------------------- | ---------------------------------------- |
    | `--integration <type>`    | Integration type (linear, discord, etc.) |
    | `--auth-method <method>`  | `oauth` or `token`                       |
    | `--scopes <scopes>`       | Comma-separated scopes or `all`          |
    | `--hide-sensitive <bool>` | Hide sensitive data (default: true)      |
    | `--triggers <events>`     | Comma-separated triggers or `all`        |
    | `--custom-webhook`        | Use custom URL instead of agent trigger  |
    | `--hook-url <url>`        | Custom webhook URL                       |
    | `--connection-id <id>`    | Connection ID (for disconnect)           |

    **Info Options:**

    | Option   | Description                  |
    | -------- | ---------------------------- |
    | `--json` | Output as JSON for scripting |

    **Trigger Management:**

    ```bash theme={null}
    # List triggers
    lua integrations webhooks list

    # List available trigger events
    lua integrations webhooks events --integration linear --json

    # Create trigger (agent wake-up mode - default)
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created

    # Create trigger with custom webhook URL
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created \
      --hook-url https://my-server.com/webhook

    # Create trigger with custom polling interval
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event updated \
      --interval 120

    # Delete trigger
    lua integrations webhooks delete --webhook-id wh_xyz789
    ```

    **Trigger Options:**

    | Option                 | Description                                           |
    | ---------------------- | ----------------------------------------------------- |
    | `--connection <id>`    | Connection ID                                         |
    | `--integration <type>` | Integration type (for events discovery)               |
    | `--object <type>`      | Object type (task\_task, calendar\_event, etc.)       |
    | `--event <type>`       | Event: created, updated, deleted                      |
    | `--hook-url <url>`     | Custom webhook URL (default: agent trigger)           |
    | `--interval <mins>`    | Polling interval (60, 120, 240, 480, 720, 1440, 2880) |
    | `--webhook-id <id>`    | Trigger ID (for delete)                               |
    | `--json`               | Output as JSON (for events command)                   |

    **MCP Server Management:**

    ```bash theme={null}
    lua integrations mcp list
    lua integrations mcp activate --connection abc123
    lua integrations mcp deactivate --connection abc123
    ```
  </Tab>
</Tabs>

### Viewing & Debugging

<Tabs>
  <Tab title="logs">
    View logs without prompts:

    ```bash theme={null}
    # View all logs
    lua logs --type all --limit 50

    # Filter by type
    lua logs --type skill --limit 20
    lua logs --type webhook --limit 20
    lua logs --type job --limit 20

    # Filter by specific entity
    lua logs --type skill --name mySkill --limit 10

    # Pagination
    lua logs --type all --limit 20 --page 2

    # JSON output for scripting
    lua logs --type all --json

    # Inspect logs for another agent you own
    lua logs --agent-id agent-abc123 --type skill --limit 10
    ```

    | Option                 | Description                                                                           |
    | ---------------------- | ------------------------------------------------------------------------------------- |
    | `--type <type>`        | all, skill, job, webhook, preprocessor, postprocessor, user\_message, agent\_response |
    | `--name <name>`        | Entity name (requires --type, not for message types)                                  |
    | `--user-id <userId>`   | Filter logs by user ID                                                                |
    | `--agent-id <agentId>` | Target a specific agent (admin access required)                                       |
    | `--limit <n>`          | Number of logs (default: 20)                                                          |
    | `--page <n>`           | Page number                                                                           |
    | `--json`               | JSON output                                                                           |
  </Tab>

  <Tab title="production">
    View production state without prompts:

    ```bash theme={null}
    lua production overview    # Production summary
    lua production persona     # Current persona
    lua production skills      # Deployed skills
    lua production env         # Environment variables
    ```
  </Tab>

  <Tab title="channels">
    View channels without prompts:

    ```bash theme={null}
    lua channels list    # List all channels
    ```
  </Tab>
</Tabs>

### Authentication & Utilities

<Tabs>
  <Tab title="auth">
    Authentication commands with --force:

    ```bash theme={null}
    # View API key without confirmation
    lua auth key --force

    # Logout without confirmation
    lua auth logout --force
    ```
  </Tab>

  <Tab title="chat clear">
    Clear history without confirmation:

    ```bash theme={null}
    # Clear all history
    lua chat clear --force

    # Clear specific user's history
    lua chat clear --user user@email.com --force
    lua chat clear --user +1234567890 --force

    # Clear a specific thread's history
    lua chat clear --thread my-test-scenario --force
    ```

    `--user` requires `org:manage` for the agent. Organization-admin grants do not cascade to private agents; organization owners and sufficient explicit agent grants retain access under the shared authorization rules. Without it, the command clears only the authenticated caller's history.
  </Tab>
</Tabs>

### Marketplace

`lua marketplace [noun] [action]`, where `noun` is `skill` or `template`. See the [Marketplace Command reference](/cli/marketplace-command) for the full flag set.

<Tabs>
  <Tab title="Skill Actions">
    Publish, manage, and install skills — all in one flat action namespace:

    ```bash theme={null}
    # List a skill (public by default)
    lua marketplace skill list --skill-name mySkill --display-name "My Skill"

    # List a private skill (org-only)
    lua marketplace skill list --skill-name mySkill --display-name "My Skill" --visibility private

    # Publish a version
    lua marketplace skill publish --marketplace-id xyz --version-id v1 --changelog "Bug fixes"

    # Edit metadata
    lua marketplace skill edit --marketplace-id xyz --display-name "New Name"

    # Unlist
    lua marketplace skill unlist --marketplace-id xyz --force

    # Unpublish version
    lua marketplace skill unpublish --marketplace-id xyz --version-id v1 --force

    # View my listings
    lua marketplace skill mine --json

    # Search marketplace
    lua marketplace skill search --query "CRM" --limit 10 --json

    # View skill details
    lua marketplace skill view --marketplace-id xyz --json

    # Install skill
    lua marketplace skill install --marketplace-id xyz --version-id v1 --force

    # With environment variables
    lua marketplace skill install --marketplace-id xyz --version-id v1 --env-vars "API_KEY=xxx,SECRET=yyy" --force

    # Update installed skill
    lua marketplace skill update --skill-name mySkill --version-id v2

    # Uninstall
    lua marketplace skill uninstall --skill-name mySkill --force

    # List installed
    lua marketplace skill installed --json
    ```
  </Tab>

  <Tab title="Template Actions">
    Publish and roll out agent templates — see [Agent Templates](/marketplace/agent-templates) for the full lifecycle:

    ```bash theme={null}
    # 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 for review
    lua marketplace template draft --template-id tpl_abc

    # Publish a version, declaring its env contract
    lua marketplace template publish --template-id tpl_abc --changelog "Bug fixes" \
      --env-contract "STRIPE_KEY=Stripe secret key"

    # In scripts: --yes auto-confirms only the section clear/narrow consequence prompt
    lua marketplace template publish --template-id tpl_abc --yes

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

    # Roll a new version out to a fleet
    lua marketplace template apply --template-id tpl_abc --all-installed --force

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

    # List templates installed on this agent
    lua marketplace template installed --json

    # Uninstall from this agent
    lua marketplace template uninstall --template-id tpl_abc --force
    ```
  </Tab>
</Tabs>

## Example Workflows

### AI IDE Workflow (Cursor, Copilot)

When an AI assistant needs to manage your agent:

```bash theme={null}
# Initialize project for existing agent
lua init --agent-id agent_abc123

# Set environment variables
lua env sandbox -k OPENAI_KEY -v "sk-xxx"
lua env production -k OPENAI_KEY -v "sk-yyy"

# Discover and connect third-party integrations
lua integrations available
lua integrations info linear --json                    # Get scopes and triggers as JSON
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated       # Connect with triggers

# Verify integration
lua integrations list
lua integrations webhooks list

# Test a specific tool
lua test skill --name get_order --input '{"orderId": "123"}'

# Push and deploy
lua push skill --name order-service --set-version 1.0.0 --force
lua deploy --skill-name order-service --skill-version latest --force

# Check logs
lua logs --type skill --name order-service --limit 10 --json
```

### GitHub Actions CI/CD

```yaml theme={null}
name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      LUA_API_KEY: ${{ secrets.LUA_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Lua CLI
        run: npm install -g lua-cli
      
      - name: Check for drift
        run: lua sync --check
      
      - name: Compile
        run: lua compile
      
      - name: Push version
        run: lua push skill --name ${{ github.event.repository.name }} --set-version ${{ github.sha }} --force
      
      - name: Deploy to production
        run: lua deploy --skill-name ${{ github.event.repository.name }} --skill-version latest --force
      
      - name: Verify deployment
        run: lua logs --type skill --name ${{ github.event.repository.name }} --limit 5 --json
```

### Post-deploy verification (CI-friendly)

After any production deploy, run a 3-line probe to confirm the new version is healthy. This is the CI version of the canonical [post-deploy debug loop](/cli/debugging):

```bash theme={null}
# Push and auto-deploy in one shot
lua --ci push all --force --auto-deploy

# Send a probe message to production
lua --ci chat -m "verify production" -e production -t prod-verify --clear

# Confirm zero agent errors fired during the probe
lua logs --type agent_error --limit 5 --json | jq '.logs | length'
```

Wire the third line into your pipeline's exit code so a non-zero error count fails the build:

```bash theme={null}
errors=$(lua logs --type agent_error --limit 5 --json | jq '.logs | length')
if [ "$errors" -gt 0 ]; then
  echo "Production has $errors agent errors after deploy — failing build."
  exit 1
fi
```

<Note>
  **Silencing post-action hints in CI.** The CLI prints `✨ Tip:` / `💡 Diagnose:` lines and a quiet `agent_error` probe summary after each command. They're useful interactively but noisy when CI captures only command output. Set `LUA_NO_HINTS=1` to silence all of them:

  ```bash theme={null}
  export LUA_NO_HINTS=1
  lua --ci push all --force --auto-deploy
  lua --ci chat -m "verify production" -e production
  ```
</Note>

### Bash Scripting

```bash theme={null}
#!/bin/bash
set -e

SKILL_NAME="my-skill"
VERSION=$(date +%Y%m%d%H%M%S)

echo "Deploying $SKILL_NAME version $VERSION"

# Check drift
if ! lua sync --check; then
  echo "Drift detected! Run 'lua sync' manually to resolve."
  exit 1
fi

# Compile and push
lua compile
lua push skill --name "$SKILL_NAME" --set-version "$VERSION" --force

# Deploy
lua deploy --skill-name "$SKILL_NAME" --skill-version latest --force

# Verify
lua logs --type skill --name "$SKILL_NAME" --limit 5

echo "Deployment complete!"
```

### Multi-Component Deployment

```bash theme={null}
#!/bin/bash
# Deploy all components at once

VERSION="2.0.0"

# Push everything
lua push all --force

# Or push individually with versions
lua push skill --name order-service --set-version $VERSION --force
lua push webhook --name payment-hook --set-version $VERSION --force
lua push job --name daily-report --set-version $VERSION --force

# Deploy skills
lua deploy --skill-name order-service --skill-version latest --force

# Activate webhooks and jobs
lua webhooks activate --webhook-name payment-hook
lua jobs activate --job-name daily-report

# Subscribe webhook to delivery events
lua webhooks subscribe --webhook-name payment-hook --event message.delivered
lua webhooks subscribe --webhook-name payment-hook --event message.failed

# Verify
lua production overview
```

## Exit Codes

All commands return consistent exit codes:

| Code | Meaning                                    |
| ---- | ------------------------------------------ |
| `0`  | Success                                    |
| `1`  | Error (missing args, not found, API error) |

Use exit codes in scripts:

```bash theme={null}
if lua sync --check; then
  echo "No drift"
else
  echo "Drift detected"
  exit 1
fi
```

## JSON Output

Commands with `--json` output machine-readable JSON:

```bash theme={null}
# Get logs as JSON
logs=$(lua logs --type all --limit 5 --json)

# Parse with jq
echo "$logs" | jq '.logs[].message'

# Get installed skills
skills=$(lua marketplace skill installed --json)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Always use --force in CI/CD">
    In automated pipelines, always use `--force` to skip confirmations:

    ```bash theme={null}
    lua push all --force
    lua deploy --skill-name x --skill-version latest --force
    ```
  </Accordion>

  <Accordion title="Use --check for validation">
    Use `lua sync --check` in CI to fail builds on drift:

    ```bash theme={null}
    lua sync --check || { echo "Drift detected"; exit 1; }
    ```
  </Accordion>

  <Accordion title="Use --json for parsing">
    When processing output programmatically, use `--json`:

    ```bash theme={null}
    lua logs --json | jq '.logs | length'
    ```
  </Accordion>

  <Accordion title="Version with timestamps or git SHAs">
    Use dynamic versions in CI:

    ```bash theme={null}
    lua push skill --name x --set-version $(git rev-parse --short HEAD) --force
    ```
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    All available commands
  </Card>

  <Card title="Skill Management" icon="wrench" href="/cli/skill-management">
    init, test, push, deploy details
  </Card>

  <Card title="Sync Command" icon="rotate" href="/cli/sync-command">
    Drift detection details
  </Card>

  <Card title="Environment Variables" icon="key" href="/cli/env-command">
    Managing configuration
  </Card>
</CardGroup>


# CLI Overview
Source: https://docs.heylua.ai/cli/overview

Command-line interface for building and deploying AI agents

## Lua AI CLI

Build and deploy AI agents with superpowers.

```bash theme={null}
lua [options] [command]
```

<Tip>
  Looking for what's new? See the [changelog](/changelog) for release notes.
</Tip>

### Options

```bash theme={null}
-V, --version   # Output the version number
-h, --help      # Display help for command
```

### All Commands

| Command              | Category          | Description                                                                                              | Non-Interactive        |
| -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------- | ---------------------- |
| `lua auth`           | 🔐 Authentication | Manage API keys and authentication                                                                       | ✅ `--force`            |
| `lua init`           | 🚀 Project Setup  | Initialize a new Lua skill project                                                                       | ✅ Full support         |
| `lua env`            | ⚙️ Configuration  | Manage environment variables (sandbox/production)                                                        | ✅ Full support         |
| `lua persona`        | 🤖 Configuration  | Manage agent persona (sandbox/production)                                                                | ✅ Full support         |
| `lua features`       | ⚡ Configuration   | Manage agent capabilities and features                                                                   | ✅ Full support         |
| `lua resources`      | 📚 Configuration  | Manage agent knowledge base                                                                              | ✅ Full support         |
| `lua skills`         | 🔧 Development    | View and manage skills (sandbox/production)                                                              | ✅ Full support         |
| `lua compile`        | 📦 Development    | Compile skill to deployable format                                                                       | ✅ `--sync` `--verbose` |
| `lua sync`           | 🔄 Development    | Detect and resolve drift between server and local code                                                   | ✅ Full support         |
| `lua test`           | 💬 Testing        | Test skill tools interactively                                                                           | ✅ Full support         |
| `lua chat`           | 💬 Testing        | Interactive chat with your agent                                                                         | ✅ `-e` `-m`            |
| `lua push`           | ☁️ Deployment     | Push components to server                                                                                | ✅ Full support         |
| `lua deploy`         | 🚀 Deployment     | Deploy one primitive's version to production (legacy; scoped-promotes when the agent has agent versions) | ✅ Full support         |
| `lua version`        | 🚀 Deployment     | Create, promote, and inspect atomic agent versions — recommended release flow                            | ✅ Full support         |
| `lua mcp`            | 🔌 Integration    | Manage MCP (Model Context Protocol) servers                                                              | ✅ Full support         |
| `lua integrations`   | 🔌 Integration    | Connect third-party accounts via Unified.to                                                              | ✅ Full support         |
| `lua production`     | 🚀 Deployment     | View and manage production environment                                                                   | ✅ Full support         |
| `lua channels`       | 🔌 Integration    | Manage communication channels                                                                            | ✅ `list`               |
| `lua webhooks`       | 🪝 Primitives     | View, deploy, activate, and subscribe webhook primitives                                                 | ✅ Full support         |
| `lua jobs`           | ⏰ Primitives      | View, deploy, activate, trigger, and inspect scheduled jobs                                              | ✅ Full support         |
| `lua preprocessors`  | 📥 Primitives     | Manage message preprocessor versions                                                                     | ✅ Full support         |
| `lua postprocessors` | 📤 Primitives     | Manage response postprocessor versions                                                                   | ✅ Full support         |
| `lua devices`        | 📡 Primitives     | Manage connected IoT/physical devices                                                                    | ✅ Full support         |
| `lua voice`          | 🎙️ Testing       | Test voice agents live in the browser and run voice test suites                                          | ✅ Full support         |
| `lua marketplace`    | 🛒 Ecosystem      | Publish/install skills and agent templates via `lua marketplace [skill\|template]`                       | ✅ Full support         |
| `lua source`         | 🗂️ Workspace     | List and roll back to past workspace source versions                                                     | ✅ Full support         |
| `lua models`         | 🧠 Configuration  | List and select the LLM model for your agent                                                             | ✅ `--model` `--json`   |
| `lua governance`     | 🛡️ Configuration | Add or remove governance enforcement                                                                     | ✅ Full support         |
| `lua triggers`       | ⚡ Integration     | Manage integration triggers (alias for `lua integrations webhooks`)                                      | ✅ Full support         |
| `lua logs`           | 🐛 Debugging      | View and filter agent logs by component type (Skills, Jobs, Webhooks, etc.)                              | ✅ Full support         |
| `lua status`         | 🛠️ Utilities     | Full agent state at a glance (alias: `lua describe`)                                                     | ✅ `--json`             |
| `lua agents`         | 🛠️ Utilities     | List all organizations and agents you have access to                                                     | ✅ `--json`             |
| `lua update`         | 🛠️ Utilities     | Update lua-cli to the latest version                                                                     | ✅ Direct               |
| `lua completion`     | ⌨️ Utilities      | Generate shell autocomplete scripts                                                                      | ✅ Direct               |
| `lua admin`          | 🛠️ Utilities     | Open admin dashboard in browser                                                                          | ✅ Direct               |
| `lua evals`          | 📊 Utilities      | Open evaluations dashboard in browser                                                                    | ✅ Direct               |
| `lua docs`           | 📖 Utilities      | Open documentation in browser                                                                            | ✅ Direct               |
| `lua telemetry`      | ⚙️ Utilities      | Manage usage data collection                                                                             | ✅ Direct               |

<CardGroup>
  <Card title="AI Agent Building Guide" icon="wand-magic-sparkles" href="/ai-guide">
    **For AI IDEs**: Complete workflow for Cursor, Windsurf, GitHub Copilot
  </Card>

  <Card title="Non-Interactive Mode" icon="robot" href="/cli/non-interactive-mode">
    Command reference for automation, CI/CD, and scripting
  </Card>
</CardGroup>

### Quick Examples

```bash theme={null}
# Authentication & Setup
lua auth configure      # 🔑 Create or save a CLI credential
lua init               # 🚀 Initialize a new project

# Configuration (Interactive or Direct)
lua env                # ⚙️ Manage environment variables
lua env sandbox        # 🎯 Direct: manage sandbox .env file
lua env production     # 🎯 Direct: manage production env vars
lua persona            # 🤖 Manage agent persona
lua persona sandbox    # 🎯 Direct: edit sandbox persona
lua persona production # 🎯 Direct: deploy persona version
lua features           # ⚡ Manage agent capabilities (RAG, webSearch, inquiry)
lua resources          # 📚 Manage knowledge base
lua marketplace        # 🛒 Access marketplace (skills or agent templates)

# Development
lua skills             # 🔧 View and manage skills
lua skills sandbox     # 🎯 Direct: view local skills
lua skills production  # 🎯 Direct: manage production skills
lua compile            # 📦 Compile your skills
lua sync               # 🔄 Check for drift between server and local
lua test               # 🧪 Test tools interactively
lua chat               # 💬 Start interactive chat

# Deployment (Interactive or Direct)
lua push               # ☁️ Push to server (choose component)
lua push skill         # 🎯 Direct: push skill
lua push persona       # 🎯 Direct: push persona
lua push mcp           # 🎯 Direct: push MCP server
lua push all --force   # 🎯 Push all components
lua version create     # 📸 Snapshot the latest pushed version of every primitive
lua version promote 2  # 🚀 Atomically activate a version — recommended release step
lua deploy             # 🚀 Deploy one primitive directly (legacy, still supported)

# Integration & Debugging
lua mcp                # 🔌 Manage MCP servers (list, activate, deactivate)
lua integrations       # 🔌 Connect third-party accounts (Linear, Discord, etc.)
lua channels           # 🔌 Manage communication channels
lua logs               # 🐛 View and filter execution logs (interactive filtering)

# Utilities
lua completion bash    # ⌨️ Generate bash autocomplete
lua completion zsh     # ⌨️ Generate zsh autocomplete
lua completion fish    # ⌨️ Generate fish autocomplete
lua admin              # 🛠️ Open admin dashboard
lua evals              # 📊 Open evaluations dashboard
lua docs               # 📖 Open documentation
```

<Note>
  **Get help for any command**: `lua [command] --help` or `lua help [command]`

  **Documentation**: [https://docs.heylua.ai](https://docs.heylua.ai)\
  **Support**: [https://heylua.ai/support](https://heylua.ai/support)
</Note>

## Quick Command Reference

<CardGroup>
  <Card title="lua init" icon="plus">
    Initialize new skill project
  </Card>

  <Card title="lua skills" icon="code">
    View and manage skills
  </Card>

  <Card title="lua env" icon="key">
    Manage environment variables
  </Card>

  <Card title="lua persona" icon="user">
    Configure agent personality
  </Card>

  <Card title="lua features" icon="sliders">
    Manage agent capabilities
  </Card>

  <Card title="lua mcp" icon="plug">
    Manage MCP servers
  </Card>

  <Card title="lua integrations" icon="link">
    Connect third-party accounts
  </Card>

  <Card title="lua sync" icon="rotate">
    Detect and resolve drift
  </Card>

  <Card title="lua test" icon="flask">
    Test tools interactively
  </Card>

  <Card title="lua chat" icon="comments">
    Interactive chat with your agent
  </Card>

  <Card title="lua push" icon="upload">
    Upload version to server
  </Card>

  <Card title="lua deploy" icon="rocket">
    Deploy one primitive directly (legacy)
  </Card>

  <Card title="lua version" icon="code-branch">
    Snapshot and atomically promote a release
  </Card>

  <Card title="lua completion" icon="terminal">
    Shell autocomplete setup
  </Card>
</CardGroup>

## Shell Autocomplete

Enable tab completion for all Lua CLI commands and arguments:

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    # One-time setup
    lua completion bash >> ~/.bashrc
    source ~/.bashrc

    # Now try:
    lua pu<TAB>      # Completes to: lua push
    lua push <TAB>   # Shows: skill, persona
    lua env <TAB>    # Shows: sandbox, staging, production
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    # One-time setup
    lua completion zsh >> ~/.zshrc
    source ~/.zshrc

    # Now try:
    lua <TAB>        # Shows all commands
    lua persona <TAB> # Shows: sandbox, staging, production
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    # One-time setup
    lua completion fish > ~/.config/fish/completions/lua.fish

    # Now try:
    lua <TAB>        # Shows all commands with descriptions
    ```
  </Tab>
</Tabs>

<Card title="Learn More" href="/cli/utility-commands#autocomplete" />

## Direct Mode

Skip interactive prompts by specifying your target directly:

<Tabs>
  <Tab title="Push Commands">
    ```bash theme={null}
    # Interactive (old way - still works!)
    lua push
    ? What would you like to push? 
      › skill
        persona

    # Direct (new way - faster!)
    lua push skill      # Push skill directly
    lua push persona    # Push persona directly
    ```
  </Tab>

  <Tab title="Environment Commands">
    ```bash theme={null}
    # Interactive
    lua env
    ? Select environment:
      › Sandbox
        Production

    # Direct
    lua env sandbox      # Manage .env file
    lua env production   # Manage API env vars
    lua env staging      # Alias for sandbox
    ```
  </Tab>

  <Tab title="Persona Commands">
    ```bash theme={null}
    # Interactive
    lua persona
    ? Select environment:
      › Sandbox
        Production

    # Direct
    lua persona sandbox      # Edit sandbox persona
    lua persona production   # Deploy persona version
    ```
  </Tab>

  <Tab title="Skills Commands">
    ```bash theme={null}
    # Interactive
    lua skills
    ? Select environment:
      › Sandbox
        Production

    # Direct
    lua skills sandbox     # View local skills
    lua skills production  # Manage production skills
    ```
  </Tab>
</Tabs>

## Command Categories

### Authentication

<Tabs>
  <Tab title="configure">
    Sign in or set up API-key authentication

    ```bash theme={null}
    lua auth configure
    ```

    Choose between:

    * **Email**: Sign in with a renewable session that follows your current organizations and agents
    * **API Key**: Save an existing scoped or legacy key unchanged

    <Card title="Learn More" href="/cli/authentication" />
  </Tab>

  <Tab title="key">
    Display stored API key

    ```bash theme={null}
    lua auth key
    ```

    Shows key after confirmation prompt
  </Tab>

  <Tab title="logout">
    Delete stored credentials

    ```bash theme={null}
    lua auth logout
    ```

    Removes `~/.lua-cli/credentials`. The server credential remains valid until you revoke it.
  </Tab>
</Tabs>

### Skill Management

<Tabs>
  <Tab title="init">
    Create new skill project

    ```bash theme={null}
    mkdir my-skill && cd my-skill
    lua init                    # Minimal project (recommended)
    lua init --with-examples    # Include 30+ example tools
    ```

    **Default (minimal):**

    * Clean agent ready to customize
    * TypeScript configuration
    * `lua.skill.yaml` config

    **With --with-examples:**

    * 30+ example tools
    * Example webhooks, jobs, processors
    * Complete e-commerce flow examples

    <Card title="Learn More" href="/cli/skill-management#init" />
  </Tab>

  <Tab title="compile">
    Compile TypeScript to JavaScript

    ```bash theme={null}
    lua compile
    ```

    Automatically:

    * Detects all tools
    * Bundles with esbuild
    * Creates deployment artifacts
    * Updates skill IDs

    <Card title="Learn More" href="/cli/skill-management#compile" />
  </Tab>

  <Tab title="test">
    Test tools interactively

    ```bash theme={null}
    lua test
    ```

    Features:

    * Select tool from list
    * Dynamic input prompts
    * Secure sandbox execution
    * Detailed error reporting

    <Card title="Learn More" href="/cli/skill-management#test" />
  </Tab>

  <Tab title="push">
    Upload version to server

    ```bash theme={null}
    lua push
    ```

    * Compiles code
    * Validates configuration
    * Uploads to server
    * Creates new version

    <Card title="Learn More" href="/cli/skill-management#push" />
  </Tab>

  <Tab title="deploy">
    Deploy one primitive to production (legacy, still supported)

    ```bash theme={null}
    lua deploy
    ```

    * Lists available versions
    * Shows current version
    * Requires confirmation
    * Immediate deployment
    * Scoped-promotes into agent-version history if the agent already has one

    <Card title="Learn More" href="/cli/skill-management#lua-deploy" />
  </Tab>

  <Tab title="version">
    Snapshot and atomically promote every primitive — recommended release flow

    ```bash theme={null}
    lua version create --auto-push -m "release notes"
    lua version promote 2
    ```

    * Snapshots the latest pushed version of every primitive
    * Promote switches everything at once, no mixed-version window
    * Instant rollback: promote an older version
    * `lua version status` shows what's pushed but not yet live

    <Card title="Learn More" href="/cli/version-command" />
  </Tab>

  <Tab title="chat">
    Interactive chat

    ```bash theme={null}
    lua chat
    ```

    Features:

    * Sandbox or production mode
    * Test conversational flows
    * Skill overrides
    * Persona customization

    <Card title="Learn More" href="/cli/chat-command" />
  </Tab>
</Tabs>

## Common Workflows

### New Project Workflow

<Steps>
  <Step title="Authenticate">
    ```bash theme={null}
    lua auth configure
    ```
  </Step>

  <Step title="Initialize">
    ```bash theme={null}
    mkdir my-skill && cd my-skill
    lua init                    # Minimal project (recommended)
    # OR
    lua init --with-examples    # Include example code
    ```
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    lua env sandbox
    ```

    Add API keys and configuration to .env file
  </Step>

  <Step title="Configure Persona">
    ```bash theme={null}
    lua persona sandbox
    ```

    Define your agent's personality in local file
  </Step>

  <Step title="Test Your Agent">
    ```bash theme={null}
    lua chat
    ```

    Interactive chat in sandbox mode

    <Note>
      **Optional**: Use `lua test` to test individual tools with specific inputs
    </Note>
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    lua push
    lua deploy
    ```
  </Step>
</Steps>

### Development Workflow

<Steps>
  <Step title="Configure Environment (if needed)">
    ```bash theme={null}
    lua env sandbox      # Update local .env
    lua env production   # Update production env vars
    ```

    Add any new API keys or configuration needed
  </Step>

  <Step title="Update Persona (if needed)">
    ```bash theme={null}
    lua persona sandbox  # Edit and test locally
    ```

    Refine agent personality based on feedback
  </Step>

  <Step title="Make Changes">Edit your tools in `src/tools/*.ts`</Step>

  <Step title="Test Your Agent">
    ```bash theme={null}
    lua chat
    ```

    Select sandbox mode to test with local changes

    <Note>
      **Pro tip**: Use `lua test` to debug specific tool logic if needed
    </Note>
  </Step>

  <Step title="Push Persona to Production (if changed)">
    ```bash theme={null}
    lua persona production  # Deploy persona version
    ```

    Or use: `lua push persona`
  </Step>

  <Step title="Push Skill When Ready">
    ```bash theme={null}
    lua push skill
    ```

    Upload new skill version
  </Step>

  <Step title="Release">
    ```bash theme={null}
    lua version create --auto-push -m "release notes"
    lua version promote 2
    ```

    Recommended once your agent has release history — snapshots and atomically activates every primitive together. `lua deploy` (single primitive, immediate) still works and is the faster path for a one-off fix; see [Version Command](/cli/version-command) for the full comparison.
  </Step>
</Steps>

### Quick Fix Workflow

```bash theme={null}
# Edit the tool
vim src/tools/MyTool.ts

# Test the tool
lua test

# Test conversationally
lua chat

# Push and deploy (direct mode - faster!)
lua push skill && lua deploy
```

## Global Flags

All commands support:

```bash theme={null}
--help       Show command help
--version    Show CLI version
```

## Environment Variables

Commands automatically load environment variables from:

<Steps>
  <Step title="System Environment">Variables from your shell</Step>
  <Step title=".env File">Variables from project `.env`</Step>
  <Step title="lua.skill.yaml">Variables from skill config</Step>
</Steps>

<Card title="Learn More" href="/concepts/environment-variables" />

## Error Handling

All commands include:

* ✅ Descriptive error messages
* ✅ Exit codes (0 = success, 1 = error)
* ✅ Troubleshooting hints

### Common Errors

<AccordionGroup>
  <Accordion title="No authentication found">
    ```
    ❌ No Lua CLI authentication found. Run `lua auth configure` or set `LUA_API_KEY`.
    ```

    **Solution**: Run `lua auth configure`
  </Accordion>

  <Accordion title="No lua.skill.yaml found">
    ```
    ❌ No lua.skill.yaml found. Please run this command from a skill directory.
    ```

    **Solution**: Run command from skill directory or run `lua init` first
  </Accordion>

  <Accordion title="Version already exists">
    ```
    ❌ Version 1.0.0 already exists on the server
    ```

    **Solution**: Increment the version number in `lua.skill.yaml` (this is the only field you should manually edit)
  </Accordion>

  <Accordion title="Compilation failed">
    ```
    ❌ No index.ts found in current directory or src/ directory
    ```

    **Solution**: Create `index.ts` or `src/index.ts` with skill definition
  </Accordion>
</AccordionGroup>

<Card title="More Troubleshooting" href="/cli/troubleshooting" />

## Agent Structure

### Project Code Pattern

Use `LuaAgent` for unified configuration:

```typescript theme={null}
// src/index.ts
import { LuaAgent, LuaSkill, LuaWebhook, LuaJob, LuaMCPServer } from "lua-cli";
import { mySkill } from "./skills/my-skill";
import paymentWebhook from "./webhooks/payment";
import dailyReportJob from "./jobs/daily-report";
import filesystemServer from "./mcp/filesystem";

export const agent = new LuaAgent({
  name: "my-agent",

  // Define personality and behavior
  persona: `You are a helpful assistant for Acme Corp.
  
Your role:
- Help customers with orders and support
- Answer product questions
- Process payments

Communication style:
- Professional yet friendly
- Clear and concise
- Patient and understanding`,

  // Skills with tools
  skills: [mySkill],

  // HTTP endpoints (optional)
  webhooks: [paymentWebhook],

  // Scheduled tasks (optional)
  jobs: [dailyReportJob],

  // MCP servers for external tools (optional)
  mcpServers: [filesystemServer],
});
```

### Project Structure

```
my-agent/
├── src/
│   ├── index.ts              # Agent configuration (LuaAgent)
│   ├── skills/               # Skill definitions
│   │   └── my-skill.ts
│   ├── tools/                # Tool implementations
│   │   ├── OrderLookupTool.ts
│   │   └── CreateTicketTool.ts
│   ├── webhooks/             # Webhook handlers
│   │   └── payment.ts
│   ├── jobs/                 # Scheduled jobs
│   │   └── daily-report.ts
│   ├── mcp/                  # MCP server configurations
│   │   └── filesystem.ts
│   ├── preprocessors/        # Message filters
│   │   └── profanity-filter.ts
│   └── postprocessors/       # Response formatters
│       └── add-disclaimer.ts
├── lua.skill.yaml            # Auto-synced configuration
├── package.json
├── tsconfig.json
└── .env                      # Local environment variables
```

## Configuration File

### lua.skill.yaml

Auto-managed state manifest (IDs and versions only):

```yaml theme={null}
# Agent configuration
agent:
  agentId: agent_abc123
  orgId: org_xyz789

# Multi-skill support
skills:
  - name: my-skill
    version: 1.0.0
    skillId: skill_abc123 # Auto-created

# Webhooks
webhooks:
  - name: payment-webhook
    webhookId: webhook_abc123 # Auto-created

# Jobs
jobs:
  - name: daily-report
    jobId: job_abc123 # Auto-created (version tracked on server)

# MCP Servers
mcpServers:
  - name: filesystem
    mcpServerId: mcp_abc123 # Auto-created
```

**Auto-managed fields:**

* `skillId` - Created during compilation
* `webhookId` - Created during compilation
* `jobId` - Created during compilation
* `mcpServerId` - Created during compilation
* `skills`, `webhooks`, `jobs`, `mcpServers` arrays - Populated from code
* Versions/IDs are tracked here; persona/env/schedule live in code (sandbox) or server (production)

**Manual fields:**

* `agentId` - Set during `lua init`
* `orgId` - Set during `lua init`
* `version` - Update when releasing (for each component)

## System Requirements

<CardGroup>
  <Card title="Node.js" icon="node-js">
    Version 16.0.0 or higher
  </Card>

  <Card title="npm" icon="npm">
    Version 7.0.0 or higher
  </Card>

  <Card title="TypeScript" icon="code">
    Included in template (knowledge helpful)
  </Card>

  <Card title="Git" icon="git">
    Optional but recommended
  </Card>
</CardGroup>

## Storage Locations

<Tabs>
  <Tab title="Credentials">
    **Credential sources**

    1. `LUA_API_KEY`
    2. `~/.lua-cli/credentials`
    3. `.env` in the project directory

    `lua auth configure` writes the credentials file with mode `0600` on POSIX systems.
  </Tab>

  <Tab title="Project Files">
    **Your Project Directory**

    ```
    your-skill/
    ├── src/            # Your code
    ├── dist/           # Compiled output
    ├── .lua/           # CLI cache
    ├── node_modules/   # Dependencies
    └── lua.skill.yaml
    ```
  </Tab>

  <Tab title="Temporary">
    **Build Artifacts**

    * `dist/` - Deployment bundles
    * `.lua/` - Compilation cache

    Safe to delete, will be regenerated
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/cli/authentication">
    Set up API key authentication
  </Card>

  <Card title="Skill Management" icon="wrench" href="/cli/skill-management">
    Learn all skill management commands
  </Card>

  <Card title="Version Command" icon="code-branch" href="/cli/version-command">
    Atomic agent versions, promote, rollback, and version status
  </Card>

  <Card title="Sync Command" icon="rotate" href="/cli/sync-command">
    Detect and resolve drift
  </Card>

  <Card title="Environment Command" icon="gear" href="/cli/env-command">
    Manage sandbox and production variables
  </Card>

  <Card title="Persona Command" icon="user" href="/cli/persona-command">
    Configure agent personality
  </Card>

  <Card title="Features Command" icon="sliders" href="/cli/features-command">
    Manage agent capabilities
  </Card>

  <Card title="MCP Command" icon="plug" href="/cli/mcp-command">
    Manage MCP servers for external tools
  </Card>

  <Card title="Integrations Command" icon="link" href="/cli/integrations-command">
    Connect third-party accounts
  </Card>

  <Card title="Chat Command" icon="comments" href="/cli/chat-command">
    Interactive chat with your agent
  </Card>

  <Card title="Utility Commands" icon="terminal" href="/cli/utility-commands">
    Shell autocomplete and more
  </Card>
</CardGroup>


# Persona Command
Source: https://docs.heylua.ai/cli/persona-command

Manage your AI agent's personality and behavior

## Overview

The `lua persona` command manages your AI agent's personality, behavior, and response style with separate workflows for sandbox and production environments.

```bash theme={null}
lua persona                # Interactive: choose environment
lua persona sandbox        # Direct: manage sandbox persona
lua persona staging        # Direct: alias for sandbox
lua persona production     # Direct: deploy persona version
```

<Note>
  Direct environment access lets you skip the selection prompt for faster workflows!
</Note>

### Non-Interactive Mode

```bash theme={null}
# View sandbox persona (local code)
lua persona sandbox view

# View production persona (deployed)
lua persona production view

# List all persona versions
lua persona production versions

# Deploy specific version
lua persona production deploy --persona-version 5

# Deploy latest version without confirmation
lua persona production deploy --persona-version latest --force
```

<Note>
  `lua persona sandbox view` prints the persona text and exits (no interactive menu) - perfect for CI/CD and scripts.
</Note>

| Option                    | Description                             |
| ------------------------- | --------------------------------------- |
| `--persona-version <ver>` | Version number or 'latest' (for deploy) |
| `--force`                 | Skip confirmation prompt                |

| Environment  | Action     | Description                   | Required Options    |
| ------------ | ---------- | ----------------------------- | ------------------- |
| `sandbox`    | `view`     | Print local persona and exit  | None                |
| `production` | `view`     | View current deployed persona | None                |
| `production` | `versions` | List all persona versions     | None                |
| `production` | `deploy`   | Deploy specific version       | `--persona-version` |

<CardGroup>
  <Card title="Sandbox Mode" icon="flask">
    Edit and test persona locally
  </Card>

  <Card title="Production Mode" icon="rocket">
    Deploy persona versions
  </Card>

  <Card title="Version Control" icon="code-branch">
    Track all persona changes
  </Card>

  <Card title="Safe Deployment" icon="shield">
    Confirmation required
  </Card>
</CardGroup>

## Usage Modes

<Tabs>
  <Tab title="Interactive Mode">
    **Default behavior - prompts for environment**

    ```bash theme={null}
    $ lua persona
    ? Select environment:
      › 🔧 Sandbox (edit and test)
        🚀 Production (view and deploy versions)
    ```

    Best for: When you're exploring options
  </Tab>

  <Tab title="Direct Mode - Sandbox">
    **Skip prompt and go straight to sandbox**

    ```bash theme={null}
    $ lua persona sandbox
    # No prompt - opens sandbox menu immediately
    ```

    Best for: Quick edits during development
  </Tab>

  <Tab title="Direct Mode - Production">
    **Skip prompt and go straight to production**

    ```bash theme={null}
    $ lua persona production
    # No prompt - opens production menu immediately
    ```

    Best for: Fast deployments, automation
  </Tab>
</Tabs>

\##Complete Workflow

<Steps>
  <Step title="Edit in Sandbox">
    ```bash theme={null}
    lua persona sandbox
    ```

    Select "Edit persona" → Opens your editor with current persona
  </Step>

  <Step title="Test with Chat">
    ```bash theme={null}
    lua chat
    ```

    Select Sandbox mode to test persona
  </Step>

  <Step title="Create Version">
    ```bash theme={null}
    lua persona sandbox
    ```

    Select "Create version" → Uploads persona as new version
  </Step>

  <Step title="Deploy to Production">
    ```bash theme={null}
    lua persona production
    ```

    Select "Deploy persona version" → Choose version and confirm deployment
  </Step>
</Steps>

## Environment Modes

<Tabs>
  <Tab title="Sandbox Mode">
    **Local Development & Testing**

    ```
    ? Select environment: 🔧 Sandbox (edit and test)
    ```

    **Actions:**

    * 👁️ View full persona
    * ✏️ Edit persona
    * 📦 Create version (push to production)
    * 📋 List versions

    **Storage:** Code (`LuaAgent` in `src/index.ts`)

    **Use for:**

    * Writing and editing persona
    * Testing before deployment
    * Iterating on personality
  </Tab>

  <Tab title="Production Mode">
    **Version Management & Deployment**

    ```
    ? Select environment: 🚀 Production (view and deploy versions)
    ```

    **Actions:**

    * 👁️ View persona versions
    * 🚀 Deploy persona version

    **Storage:** Server API

    **Use for:**

    * Deploying tested versions
    * Rolling back if needed
    * Viewing version history
  </Tab>
</Tabs>

## Channel-Aware Personas

Personas can be split per channel using an object form. The previous string form keeps working — adopt the object form only when a channel needs its own phrasing.

```typescript theme={null}
new LuaAgent({
  // Original string form — still works everywhere
  persona: 'You are a helpful assistant for Acme Corp.',
});
```

```typescript theme={null}
new LuaAgent({
  // Split per channel
  persona: {
    base: 'Shared persona that applies to all channels.',
    voice: 'Speak naturally, no markdown, no bullet lists. Keep replies under two sentences.',
    text: 'Use markdown headers and bullet lists where helpful.',
  },
});
```

**Resolution rules:**

* `voice` channel → uses `voice` if defined, else `base`.
* `text` (chat) channel → uses `text` if defined, else `base`.
* A channel-agnostic operation (e.g. `lua init` source write, the agent description fallback) flattens all defined branches.

**Common patterns:**

* **Voice-only override** — Keep your existing string persona, add `voice` only when voice needs different phrasing:
  ```typescript theme={null}
  persona: {
    base: 'You are a helpful assistant for Acme Corp...',
    voice: 'Speak conversationally. Avoid lists and code blocks.',
  }
  ```
* **Voice-only persona** — A voice agent that only needs a voice prompt:
  ```typescript theme={null}
  persona: { voice: 'Speak conversationally. Confirm orders before placing them.' }
  ```

<Note>
  Pushing a voice-only persona (no `base`, no `text`) now correctly applies on the server. `lua sync --pull` round-trips the object form back to your source file with all channel branches preserved.

  The `PersonaText` type is exported from `lua-cli` if you need it in your own typings.
</Note>

## Writing Great Personas

### Structure Template

```yaml theme={null}
persona: |
  You are [ROLE] for [COMPANY].
  
  Your Role:
  - [Primary responsibility]
  - [Secondary responsibility]
  - [What you help with]
  
  Your Personality:
  - [Trait 1]
  - [Trait 2]
  - [Communication style]
  
  Your Guidelines:
  - Always [do this]
  - Never [do that]
  - When [situation], [action]
  
  Context:
  [Background information about company, products, policies]
```

## Good vs Bad Examples

### Example 1: Customer Support

<Tabs>
  <Tab title="❌ Bad">
    ```
    You help customers.
    ```

    **Problems:**

    * Too vague
    * No personality
    * No guidelines
    * No context
  </Tab>

  <Tab title="✅ Good">
    ```
    You are a customer service representative for AcmeCorp, 
    specializing in electronics and home goods.

    Your Role:
    - Answer product questions with technical details
    - Check order status and provide tracking information
    - Process returns within our 30-day policy
    - Provide personalized product recommendations based on needs

    Your Personality:
    - Warm and friendly while maintaining professionalism
    - Patient and empathetic, especially with frustrated customers
    - Knowledgeable about products without being condescending
    - Solution-oriented and proactive

    Your Guidelines:
    - Always greet customers warmly
    - Ask clarifying questions to understand their needs
    - Confirm understanding before taking action
    - Thank customers for their patience
    - Never make promises outside company policies
    - Escalate billing issues to the billing department
    - Escalate technical problems to technical support

    Context:
    AcmeCorp is an online retailer founded in 2010 with over 10,000 products.
    We offer 2-day shipping on most items and free shipping over $50.
    We have a 30-day return policy and pride ourselves on customer service.
    Business hours: 9 AM - 6 PM EST, Monday-Friday.
    ```

    **Why it's good:**

    * Specific role and responsibilities
    * Clear personality traits
    * Actionable guidelines
    * Relevant business context
  </Tab>
</Tabs>

### Example 2: Sales Assistant

<Tabs>
  <Tab title="❌ Bad">
    ```
    You sell products and help people buy things.
    Be nice.
    ```

    **Problems:**

    * No sales methodology
    * Vague personality
    * No product knowledge
    * No dos/don'ts
  </Tab>

  <Tab title="✅ Good">
    ```
    You are a knowledgeable sales consultant for TechGear, 
    specializing in laptops, tablets, and accessories.

    Your Mission:
    Help customers find the perfect product for their needs,
    not just make sales. Build trust through honest recommendations.

    Your Expertise:
    - Deep knowledge of all product specs and features
    - Understanding of different use cases (gaming, work, creative)
    - Awareness of current deals and bundle opportunities
    - Competitor product knowledge for honest comparisons

    Your Sales Approach:
    1. Ask questions to understand their needs and budget
    2. Listen carefully to requirements and preferences
    3. Recommend 2-3 options that fit their criteria
    4. Explain why each option suits their needs
    5. Compare pros and cons honestly
    6. Help them make an informed decision

    Your Personality:
    - Enthusiastic about technology without being pushy
    - Consultative rather than aggressive
    - Honest about product limitations
    - Patient with less technical customers
    - Excited to share knowledge

    Your Guidelines:
    - Never oversell or exaggerate capabilities
    - Be honest if a product isn't the right fit
    - Suggest alternatives including competitors if we don't have what they need
    - Highlight current promotions when relevant
    - Ask about budget early to avoid wasting time
    - Confirm they're satisfied before ending conversation

    You DON'T:
    - Make price adjustments (refer to sales manager)
    - Handle technical support (transfer to support)
    - Process returns (direct to returns department)

    Context:
    TechGear focuses on quality over quantity. We stock premium brands
    and provide expert guidance. Our customers value our honest advice
    and often return because they trust our recommendations.
    ```

    **Why it's good:**

    * Clear sales methodology
    * Specific expertise defined
    * Consultative approach emphasized
    * Honest, not pushy
    * Clear boundaries
  </Tab>
</Tabs>

### Example 3: Technical Support

<Tabs>
  <Tab title="❌ Bad">
    ```
    You help with technical problems.
    Fix issues.
    ```

    **Problems:**

    * No troubleshooting methodology
    * No personality
    * No technical depth
    * No escalation paths
  </Tab>

  <Tab title="✅ Good">
    ```
    You are a Level 2 Technical Support Specialist for CloudApp,
    a SaaS project management platform.

    Your Technical Expertise:
    - Complete knowledge of CloudApp features and functionality
    - Common integration issues (Slack, GitHub, Jira)
    - API troubleshooting and debugging
    - Performance optimization techniques
    - Security and permissions management

    Your Troubleshooting Process:
    1. Listen and understand the complete issue
    2. Gather diagnostic information (version, browser, steps to reproduce)
    3. Check for known issues or recent changes
    4. Form hypothesis about root cause
    5. Test hypothesis with targeted questions
    6. Provide step-by-step solution
    7. Verify issue is resolved
    8. Document solution for knowledge base

    Your Communication Style:
    - Patient and methodical
    - Explain technical concepts in simple terms
    - Use analogies when helpful
    - Never assume user's technical level
    - Celebrate small wins during troubleshooting
    - Stay calm even when users are frustrated

    Your Personality:
    - Genuinely curious about problems
    - Persistent in finding solutions
    - Empathetic to user frustration
    - Excited to share knowledge
    - Humble when uncertain

    Your Guidelines:
    - Always ask "Is it working now?" after each step
    - Never blame the user
    - Admit when you don't know something
    - Escalate to Level 3 if stuck for 30+ minutes
    - Document unique issues for future reference
    - Follow up to ensure resolution

    You DON'T:
    - Make database changes (escalate to DevOps)
    - Access billing information (transfer to billing)
    - Commit to feature requests (log for product team)

    Escalation Triggers:
    - Data corruption or loss
    - Security concerns
    - Billing discrepancies
    - Account access issues
    - Complex API integration problems

    Context:
    CloudApp serves 50,000+ teams worldwide. Users range from small
    startups to enterprise clients. Common issues include integrations,
    permissions, and performance. Our support SLA is 4-hour response time
    for priority tickets.
    ```

    **Why it's good:**

    * Systematic troubleshooting process
    * Technical depth appropriate for role
    * Clear escalation paths
    * Patient teaching style
    * Specific context about product
  </Tab>
</Tabs>

### Example 4: Onboarding Assistant

<Tabs>
  <Tab title="❌ Bad">
    ```
    You help new users learn the product.
    Show them around.
    ```

    **Problems:**

    * No structure
    * No learning methodology
    * No success criteria
    * No personality
  </Tab>

  <Tab title="✅ Good">
    ```
    You are an enthusiastic onboarding specialist for FlowApp,
    guiding new users through their first-week experience.

    Your Mission:
    Help users go from signup to productivity within their first session.
    Make them feel confident and excited about using FlowApp.

    Your Onboarding Framework:
    1. Welcome and set expectations (2 minutes)
    2. Quick win: Complete one simple task (3 minutes)
    3. Core features tour: Show 3 most-used features (5 minutes)
    4. Practice: User tries each feature with guidance (5 minutes)
    5. Resources: Point to docs, videos, support (2 minutes)
    6. Next steps: Set up for continued success (3 minutes)

    Your Teaching Style:
    - Encourage hands-on learning over passive watching
    - Celebrate each small success enthusiastically
    - Break complex features into simple steps
    - Use real-world examples from their industry
    - Check understanding before moving forward
    - Adapt pace to user's comfort level

    Your Personality:
    - Genuinely excited about the product
    - Patient and never rushed
    - Encouraging and positive
    - Relatable and down-to-earth
    - Celebrates user progress

    Your Guidelines:
    - Start with a quick win to build confidence
    - Use user's actual data/use case when possible
    - Avoid overwhelming with all features at once
    - Ask "Does this make sense?" frequently
    - Offer to slow down or revisit concepts
    - End with clear next steps

    Common User Types:
    - Tech-savvy: Move faster, less hand-holding
    - Cautious: Move slower, more reassurance
    - Skeptical: Show value early, use their use case
    - Confused: Break into smaller steps, use simpler language

    You DON'T:
    - Rush through important concepts
    - Use jargon without explaining
    - Assume prior knowledge
    - Skip user questions to stay on script

    Success Metrics:
    User completes:
    - Created first project
    - Added first task
    - Invited team member
    - Feels confident to continue alone

    Context:
    FlowApp is a project management tool for creative teams.
    Most new users are designers, marketers, or small agency owners.
    They're switching from tools like Trello or Asana.
    ```

    **Why it's good:**

    * Structured onboarding framework
    * Specific teaching methodology
    * Adapts to different user types
    * Clear success criteria
    * Encouraging personality
  </Tab>
</Tabs>

### Example 5: E-commerce Shopping Assistant

<Tabs>
  <Tab title="❌ Bad">
    ```
    You help people shop.
    Show products.
    ```
  </Tab>

  <Tab title="✅ Good">
    ```
    You are a personal shopping assistant for StyleHub,
    an online fashion and lifestyle boutique.

    Your Role:
    Act as the customer's personal stylist and shopping companion,
    helping them discover products they'll love.

    Your Expertise:
    - Complete knowledge of our 5,000+ product catalog
    - Understanding of fashion trends and styling principles
    - Awareness of seasonal collections and new arrivals
    - Knowledge of sizing across all brands we carry
    - Familiarity with care instructions and materials

    Your Shopping Process:
    1. Understand their style (casual, professional, trendy, classic)
    2. Learn their needs (occasion, season, preferences)
    3. Ask about size, fit preferences, and budget
    4. Suggest 3-5 curated options with explanations
    5. Offer styling advice (what to pair it with)
    6. Help with fit/sizing questions
    7. Facilitate smooth checkout

    Your Personality:
    - Enthusiastic about fashion without being pushy
    - Genuinely interested in their personal style
    - Supportive and confidence-building
    - Honest about what looks good
    - Excited to share styling tips

    Your Communication Style:
    - Ask open-ended questions to understand taste
    - Use descriptive language for products
    - Paint a picture of how items work together
    - Share styling inspiration
    - Make them feel seen and understood

    Your Guidelines:
    - Start by understanding their style, not showing products
    - Ask about occasion/purpose before recommending
    - Always mention sizing and fit information
    - Suggest complete outfits, not just individual items
    - Highlight free shipping over $50
    - Mention easy returns (30 days, free)
    - Offer to save items to wishlist for later

    You DON'T:
    - Push expensive items unnecessarily
    - Judge their style choices
    - Rush them through browsing
    - Ignore budget constraints

    When User Is:
    - Browsing: Ask about their style and what they're looking for
    - Undecided: Ask questions to narrow down options
    - Budget-conscious: Lead with value items and sales
    - Splurging: Show premium options with styling advice

    Special Features:
    - We offer virtual try-on for select items
    - Style quiz available to personalize recommendations
    - Fashion blog with outfit inspiration
    - Personal stylist consultations available

    Context:
    StyleHub curates fashion from emerging designers and established brands.
    Our customers value unique style and quality. Average order value: $120.
    Peak shopping: Lunch hours and evenings. We ship worldwide.
    ```
  </Tab>
</Tabs>

## Good vs Bad Persona Patterns

### Pattern 1: Role Definition

<CodeGroup>
  ```text Bad theme={null}
  You help people.
  ```

  ```text Good theme={null}
  You are a customer service representative for AcmeCorp,
  specializing in electronics and home goods support.

  Your responsibilities include answering product questions,
  checking order status, processing returns, and providing
  technical guidance for our product lineup.
  ```
</CodeGroup>

### Pattern 2: Personality

<CodeGroup>
  ```text Bad theme={null}
  Be nice and helpful.
  ```

  ```text Good   theme={null}
  Your Personality:
  - Warm and friendly while maintaining professionalism
  - Patient and empathetic, especially with frustrated customers
  - Knowledgeable about products without being condescending
  - Solution-oriented: focus on "how can I help" not "what went wrong"
  - Genuine enthusiasm for helping people succeed

  Your Communication Style:
  - Use friendly, conversational language
  - Avoid corporate jargon
  - Explain technical terms when necessary
  - Use "we" not "the company" to show you're part of the team
  - Mirror the customer's energy level (calm with calm, urgent with urgent)
  ```
</CodeGroup>

### Pattern 3: Guidelines

<CodeGroup>
  ```text Bad theme={null}
  Follow the rules.
  ```

  ```text Good theme={null}
  Your Guidelines:

  Always:
  - Greet customers warmly by name if available
  - Ask clarifying questions before taking action
  - Confirm you understand their issue
  - Provide clear next steps
  - Thank them for their patience
  - End conversations with "Is there anything else I can help with?"

  Never:
  - Make promises you can't keep
  - Provide information you're uncertain about
  - Blame customers for issues
  - Use negative language ("Unfortunately...", "I can't...")
  - Rush through conversations to close tickets

  When customer is frustrated:
  1. Acknowledge their feelings first
  2. Apologize genuinely for the inconvenience
  3. Focus on solution immediately
  4. Offer escalation if appropriate
  5. Follow up to ensure resolution

  When you don't know:
  - Be honest: "That's a great question. Let me find out for you."
  - Don't guess or make up information
  - Offer to escalate to a specialist
  - Provide timeline for when they'll hear back
  ```
</CodeGroup>

### Pattern 4: Context

<CodeGroup>
  ```text Bad theme={null}
  We sell stuff online.
  ```

  ```text Good theme={null}
  Context:
  AcmeCorp is an online electronics and home goods retailer
  serving customers across North America since 2010.

  Our Product Range:
  - 10,000+ products across electronics and home categories
  - Major brands: Apple, Samsung, Sony, LG, Dyson, KitchenAid
  - Price range: $10 to $5,000
  - New products added weekly

  Our Policies:
  - Shipping: Free over $50, 2-day standard, Next-day available
  - Returns: 30-day window, free return shipping, full refund
  - Price matching: Within 14 days of purchase
  - Warranty: Manufacturer warranty + optional extended plans

  Our Values:
  - Customer service is our #1 priority
  - We stand behind every product we sell
  - Fast, accurate order fulfillment
  - Transparent pricing and policies

  Common Customer Questions:
  - Order status and tracking
  - Product comparisons and recommendations
  - Return/exchange process
  - Technical specifications
  - Compatibility questions
  ```
</CodeGroup>

### Pattern 5: Tone Examples

<CodeGroup>
  ```text Bad theme={null}
  Help users with their problems.
  ```

  ```text Good theme={null}
  Your Tone Examples:

  When greeting:
  "Hi there! Thanks for reaching out to AcmeCorp support. 
  I'm here to help! What can I assist you with today?"

  When acknowledging a problem:
  "I completely understand your frustration, and I'm so sorry 
  this happened. Let's get this sorted out for you right away."

  When providing a solution:
  "Great news! I can definitely help with that. Here's what 
  we'll do: [clear steps]. Does that sound good?"

  When escalating:
  "I want to make sure you get the best possible help with this.
  I'm going to connect you with our specialist team who can 
  resolve this quickly. They'll reach out within 2 hours."

  When closing:
  "I'm glad we could resolve this for you! Is there anything 
  else I can help with today? Feel free to reach back out 
  anytime - we're here for you!"

  Avoid saying:
  - "Unfortunately..." → Instead: "Here's what I can do..."
  - "That's not possible" → Instead: "Here's an alternative..."
  - "You should have..." → Instead: "For future reference..."
  - "It's your fault" → Instead: "Let's fix this together"
  ```
</CodeGroup>

## Industry-Specific Examples

### Healthcare Patient Portal

```yaml theme={null}
persona: |
  You are a patient services coordinator for HealthFirst Medical Group.

  Your Role:
  - Schedule and manage appointments
  - Answer questions about prescriptions and refills
  - Provide general health information (not medical advice)
  - Help navigate the patient portal

  Your Personality:
  - Compassionate and caring
  - Professional and trustworthy
  - Patient and understanding
  - Clear and reassuring

  CRITICAL Guidelines:
  - NEVER provide medical diagnosis or advice
  - Always include disclaimer: "This is general information. 
    Consult your doctor for medical advice."
  - Protect patient privacy (HIPAA compliance)
  - Verify identity before sharing any information
  - Escalate medical questions to nursing staff

  Your Language:
  - Use simple, non-medical terms
  - Explain medical terms when necessary
  - Be sensitive to health concerns
  - Maintain privacy and dignity

  Context:
  HealthFirst serves 10,000+ patients. We have 5 locations.
  Appointments available 7 AM - 7 PM. Emergency? Call 911 or
  visit ER. For urgent non-emergency, we have same-day appointments.
```

### Financial Services

```yaml theme={null}
persona: |
  You are a financial services representative for SecureBank.

  Your Role:
  - Assist with account inquiries
  - Help with transactions and transfers
  - Answer questions about products and services
  - Guide through online banking features

  Your Personality:
  - Professional and trustworthy
  - Precise and detail-oriented
  - Calm and reassuring
  - Respectful of financial sensitivity

  Security & Compliance:
  - ALWAYS verify identity before sharing account information
  - Never share sensitive data without proper authentication
  - Follow KYC (Know Your Customer) procedures
  - Escalate suspicious activity immediately
  - Maintain audit trail of all interactions

  Your Communication:
  - Use precise financial terminology correctly
  - Explain fees and charges clearly
  - Confirm transactions before execution
  - Provide transaction confirmation numbers
  - Offer written summaries of important discussions

  You MUST Escalate:
  - Fraud or suspicious activity
  - Large wire transfers (over $10,000)
  - Account access issues
  - Disputes or chargebacks
  - Legal or compliance questions

  Context:
  SecureBank is FDIC insured, serving customers since 1995.
  We prioritize security and transparency. All accounts are
  protected by multi-factor authentication. Customer funds are
  insured up to $250,000.
```

### Restaurant/Food Service

```yaml theme={null}
persona: |
  You are the friendly voice of Bella's Italian Kitchen.

  Your Role:
  - Take orders for dine-in, takeout, and delivery
  - Answer menu questions and make recommendations
  - Handle special requests and dietary restrictions
  - Book reservations for dine-in

  Your Personality:
  - Warm and hospitable (like welcoming into your home)
  - Passionate about great food
  - Attentive to dietary needs
  - Enthusiastic about daily specials

  Your Approach:
  - Greet like a regular customer walking in
  - Describe dishes appetizingly
  - Ask about dietary restrictions early
  - Suggest pairings (appetizer + entree, wine + dish)
  - Mention daily specials with genuine enthusiasm
  - Confirm orders completely before submitting

  Your Guidelines:
  - Always ask about allergies before finalizing order
  - Mention prep time honestly (don't underestimate)
  - Suggest sides and drinks (upsell gently)
  - For delivery: confirm address completely
  - For dine-in: ask about seating preferences
  - Remind about reservation cancellation policy (24hr notice)

  Menu Knowledge:
  - All ingredients in each dish
  - Common allergens in menu items
  - What can be customized and what can't
  - Vegetarian, vegan, and gluten-free options
  - Popular items and chef recommendations

  Context:
  Bella's is a family-owned Italian restaurant since 1985.
  Everything made fresh daily. Known for authentic recipes and
  warm atmosphere. Typical prep time: 20-30 minutes.
  We do NOT deliver outside 5-mile radius.
  Reservations recommended for parties of 4+.
```

## Persona Testing Checklist

Before deploying, test your persona:

<AccordionGroup>
  <Accordion title="✅ Role Clarity">
    * [ ] Role is clearly defined
    * [ ] Responsibilities are specific
    * [ ] Boundaries are set
    * [ ] Escalation paths are clear
  </Accordion>

  <Accordion title="✅ Personality Consistency">
    * [ ] Tone is consistent across conversations
    * [ ] Personality traits come through naturally
    * [ ] Communication style matches brand
    * [ ] Appropriate for target audience
  </Accordion>

  <Accordion title="✅ Guideline Compliance">
    * [ ] "Always" rules are followed
    * [ ] "Never" rules are respected
    * [ ] Conditional guidelines work ("When X, do Y")
    * [ ] Edge cases are handled appropriately
  </Accordion>

  <Accordion title="✅ Context Accuracy">
    * [ ] Company information is correct
    * [ ] Policies are accurate
    * [ ] Product details are up-to-date
    * [ ] Contact information is current
  </Accordion>

  <Accordion title="✅ User Experience">
    * [ ] Conversations feel natural
    * [ ] Users get helpful responses
    * [ ] Tone is appropriate
    * [ ] Problems are solved effectively
  </Accordion>
</AccordionGroup>

## Common Mistakes to Avoid

<AccordionGroup>
  <Accordion title="❌ Too Generic">
    **Bad:**

    ```
    You are a helpful assistant.
    ```

    **Why it fails:**

    * No unique personality
    * No specific knowledge
    * No actionable guidelines
    * Could be any chatbot

    **Fix:** Add specific role, personality, and context
  </Accordion>

  <Accordion title="❌ Too Restrictive">
    **Bad:**

    ```
    You can ONLY answer these specific questions:
    1. What is our return policy?
    2. Where is my order?
    3. What products do you have?

    Refuse to answer anything else.
    ```

    **Why it fails:**

    * Users ask in different ways
    * Blocks natural conversation
    * Frustrating user experience
    * Misses opportunities to help

    **Fix:** Define what you DO, not just what you DON'T
  </Accordion>

  <Accordion title="❌ Contradictory Instructions">
    **Bad:**

    ```
    Be very brief and concise.
    Provide detailed explanations for everything.
    Be casual and fun.
    Maintain strict professionalism at all times.
    ```

    **Why it fails:**

    * Conflicting directives confuse the AI
    * Inconsistent responses
    * Unpredictable behavior

    **Fix:** Be consistent and clear about priorities
  </Accordion>

  <Accordion title="❌ No Personality">
    **Bad:**

    ```
    Answer questions accurately.
    Provide information when asked.
    Be professional.
    ```

    **Why it fails:**

    * Robotic and cold
    * No human connection
    * Forgettable experience

    **Fix:** Add warmth, personality traits, communication style
  </Accordion>

  <Accordion title="❌ Outdated Information">
    **Bad:**

    ```
    Our business hours are 9-5 PM.
    (Actually changed to 8-6 PM months ago)

    We ship within 5-7 days.
    (Actually now 2-3 days)
    ```

    **Why it fails:**

    * Gives wrong information
    * Undermines trust
    * Creates customer frustration

    **Fix:** Regular persona reviews and updates
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Test Your Persona" icon="comments" href="/cli/chat-command">
    Use `lua chat` to test persona in sandbox
  </Card>

  <Card title="Environment Variables" icon="key" href="/cli/env-command">
    Configure API keys and settings
  </Card>

  <Card title="Development Workflows" icon="diagram-project" href="/concepts/workflows">
    See persona in complete workflows
  </Card>

  <Card title="Skill Management" icon="wrench" href="/cli/skill-management">
    Deploy skills that persona uses
  </Card>
</CardGroup>


# Postprocessors Command
Source: https://docs.heylua.ai/cli/postprocessors-command

Manage response postprocessor primitives — view, deploy, activate, and delete versions

## Overview

`lua postprocessors` manages **postprocessor** primitives — code that runs **after** your agent produces a response, before it's sent to the user. Use postprocessors for adding disclaimers, branding, translation, format conversion, or compliance redaction.

```bash theme={null}
lua postprocessors                                # Interactive management
lua postprocessors view                           # List all postprocessors
lua postprocessors deploy --postprocessor-name myPost --postprocessor-version 1.0.3
```

<Note>
  For defining postprocessors in code, see the [Postprocessor concept](/overview/postprocessors) and the [Postprocessor API](/api/postprocessor).
</Note>

## Subcommands

| Action       | What it does                                             |
| ------------ | -------------------------------------------------------- |
| `view`       | List all postprocessors defined on the agent.            |
| `versions`   | List every version of a specific postprocessor.          |
| `deploy`     | Promote a version to active.                             |
| `activate`   | Re-enable a deactivated postprocessor.                   |
| `deactivate` | Pause execution — responses bypass this postprocessor.   |
| `delete`     | Permanently remove a postprocessor and all its versions. |

## Options

| Option                          | Description                                                    |
| ------------------------------- | -------------------------------------------------------------- |
| `--postprocessor-name <name>`   | Postprocessor name. Required for most non-interactive actions. |
| `--postprocessor-version <ver>` | Version for `deploy`. Pass `latest` for the newest.            |

<Note>
  The shorthand `pp` resolves to `postprocessor` in most argument positions — e.g. `lua pp view`, `lua logs --type pp`.
</Note>

## Examples

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

# List everything
lua postprocessors view

# List versions for a postprocessor
lua postprocessors versions --postprocessor-name addDisclaimer

# Promote a specific version
lua postprocessors deploy --postprocessor-name addDisclaimer --postprocessor-version 1.0.3
lua postprocessors deploy --postprocessor-name addDisclaimer --postprocessor-version latest

# Pause and resume
lua postprocessors deactivate --postprocessor-name addDisclaimer
lua postprocessors activate   --postprocessor-name addDisclaimer

# Delete
lua postprocessors delete --postprocessor-name oldPost
```

## Priority

Postprocessors have a `priority` field that controls execution order. Lower numbers run first. The `priority` you declare in code is now correctly preserved on push — re-push if you set priority in older releases and want it applied.

## Common Workflow

```bash theme={null}
# Edit src/postprocessors/add-disclaimer.ts, then:
lua push postprocessor                                              # Build + upload
lua postprocessors versions --postprocessor-name addDisclaimer      # Confirm
lua postprocessors deploy --postprocessor-name addDisclaimer --postprocessor-version latest
lua logs --type postprocessor --name addDisclaimer --limit 20       # Verify execution
```

## Related

* [Postprocessor Concept](/overview/postprocessors)
* [Postprocessor API](/api/postprocessor)
* [Preprocessors Command](/cli/preprocessors-command)
* [Logs Command](/cli/logs-command)


# Preprocessors Command
Source: https://docs.heylua.ai/cli/preprocessors-command

Manage message preprocessor primitives — view, deploy, activate, and delete versions

## Overview

`lua preprocessors` manages **preprocessor** primitives — code that runs **before** a user message reaches your agent. Use preprocessors for content filtering, routing, rate limiting, validation, and message rewriting.

```bash theme={null}
lua preprocessors                            # Interactive management
lua preprocessors view                       # List all preprocessors
lua preprocessors deploy --preprocessor-name myPre --preprocessor-version 1.0.3
```

<Note>
  For defining preprocessors in code, see the [Preprocessor concept](/overview/preprocessors) and the [Preprocessor API](/api/preprocessor).
</Note>

## Subcommands

| Action       | What it does                                            |
| ------------ | ------------------------------------------------------- |
| `view`       | List all preprocessors defined on the agent.            |
| `versions`   | List every version of a specific preprocessor.          |
| `deploy`     | Promote a version to active.                            |
| `activate`   | Re-enable a deactivated preprocessor.                   |
| `deactivate` | Pause execution — messages bypass this preprocessor.    |
| `delete`     | Permanently remove a preprocessor and all its versions. |

## Options

| Option                         | Description                                                   |
| ------------------------------ | ------------------------------------------------------------- |
| `--preprocessor-name <name>`   | Preprocessor name. Required for most non-interactive actions. |
| `--preprocessor-version <ver>` | Version for `deploy`. Pass `latest` for the newest.           |

<Note>
  The shorthand `pre` resolves to `preprocessor` in most argument positions — e.g. `lua pre view`, `lua logs --type pre`.
</Note>

## Examples

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

# List everything
lua preprocessors view

# List versions
lua preprocessors versions --preprocessor-name myPre

# Promote a specific version
lua preprocessors deploy --preprocessor-name myPre --preprocessor-version 1.0.3
lua preprocessors deploy --preprocessor-name myPre --preprocessor-version latest

# Pause and resume
lua preprocessors deactivate --preprocessor-name myPre
lua preprocessors activate   --preprocessor-name myPre

# Delete
lua preprocessors delete --preprocessor-name oldPre
```

## Common Workflow

```bash theme={null}
# Edit src/preprocessors/profanity-filter.ts, then:
lua push preprocessor                                            # Build + upload
lua preprocessors versions --preprocessor-name profanityFilter   # Confirm
lua preprocessors deploy --preprocessor-name profanityFilter --preprocessor-version latest
lua logs --type preprocessor --name profanityFilter --limit 20   # Verify execution
```

## Related

* [Preprocessor Concept](/overview/preprocessors)
* [Preprocessor API](/api/preprocessor)
* [Postprocessors Command](/cli/postprocessors-command)
* [Logs Command](/cli/logs-command)


# Production Command
Source: https://docs.heylua.ai/cli/production-command

Centralized control center for production environment

## Overview

The `lua production` command is your centralized control center for viewing and managing your production environment. It provides a unified interface to monitor deployed persona, skills, and environment variables.

```bash theme={null}
lua production
```

<CardGroup>
  <Card title="Unified View" icon="eye">
    See persona, skills, and env in one place
  </Card>

  <Card title="Quick Health Checks" icon="heart-pulse">
    Verify production state in seconds
  </Card>

  <Card title="Environment Management" icon="cog">
    Full CRUD for production variables
  </Card>

  <Card title="Safe Operations" icon="shield">
    Read-only for persona and skills
  </Card>
</CardGroup>

## Why This Command?

### Before lua production

```bash theme={null}
# Fragmented workflow
$ lua persona    # Check persona
$ lua deploy     # Wait, this deploys, not views!
$ lua env        # Check environment variables
# Multiple steps, confusing
```

### After lua production

```bash theme={null}
# Unified workflow
$ lua production
→ Persona: ✓ Check current
→ Skills: ✓ See all deployed
→ Env: ✓ Manage variables
# Everything in one place!
```

## Main Menu

```
============================================================
🚀 Production Environment
============================================================

? What would you like to view?
  🤖 Persona - View current persona and versions
  ⚙️  Skills - View deployed skills and versions
  🔐 Environment Variables - Manage production env
  ❌ Exit
```

## Persona Section

<Tabs>
  <Tab title="View Current Persona">
    ```bash theme={null}
    ? What would you like to view? 🤖 Persona

    🔄 Loading persona information...

    ============================================================
    🤖 Current Production Persona
    ============================================================

    Version: 5 ⭐
    Deployed: 1/15/2024, 10:30:15 AM
    Created by: system

    ------------------------------------------------------------

    You are a helpful customer service assistant for AcmeCorp.

    Your Role:
    - Help customers find products
    - Answer order questions
    - Process returns professionally

    Your Personality:
    - Friendly and approachable
    - Professional and knowledgeable

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

    Total versions available: 5

    Press Enter to continue...
    ```

    Shows complete deployed persona
  </Tab>

  <Tab title="No Persona">
    ```bash theme={null}
    ============================================================
    🤖 Current Production Persona
    ============================================================

    ⚠️  No persona currently deployed.
    💡 Deploy a version using: lua persona → Production → Deploy

    Available versions:
      1. Version 5 - 1/15/2024
      2. Version 4 - 1/14/2024

    Press Enter to continue...
    ```

    Shows when no version is active
  </Tab>
</Tabs>

**Use for:**

* ✅ Quick verification of deployed persona
* ✅ Checking version number
* ✅ Reading full persona content
* ✅ Confirming deployment dates

## Skills Section

```bash theme={null}
? What would you like to view? ⚙️  Skills

🔄 Loading skill information...

============================================================
⚙️  Production Skills
============================================================

📦 customer-service
   Skill ID: skill_abc123
   Deployed Version: 2.5.0 ⭐
   Deployed: 1/15/2024, 2:30:45 PM
   Total Versions: 12

📦 order-management
   Skill ID: skill_def456
   Deployed Version: 1.8.0 ⭐
   Deployed: 1/14/2024, 4:15:30 PM
   Total Versions: 9

📦 inventory-check
   Skill ID: skill_xyz789
   Deployed Version: Not deployed
   Total Versions: 3

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

Press Enter to continue...
```

**Information per skill:**

* Skill name and ID
* Deployed version (⭐ if active)
* Deployment timestamp
* Total versions available

**Use for:**

* ✅ Production inventory
* ✅ Version verification
* ✅ Deployment dates
* ✅ Finding not-deployed skills

## Environment Variables Section

```bash theme={null}
? What would you like to view? 🔐 Environment Variables

============================================================
🔐 Production Environment Variables
============================================================

1. DATABASE_URL = post**********************
2. STRIPE_KEY = sk-l**********************
3. API_SECRET = abc1**********************
4. MAX_RETRIES = 5
5. DEBUG_MODE = false

? What would you like to do?
  ➕ Add new variable
  ✏️  Update existing variable
  🗑️  Delete variable
  👁️  View variable value
  🔄 Refresh list
  ⬅️  Back to main menu
```

<CardGroup>
  <Card title="Add" icon="plus">
    Create new production variable
  </Card>

  <Card title="Update" icon="pen">
    Modify existing variable
  </Card>

  <Card title="Delete" icon="trash">
    Remove variable (with confirmation)
  </Card>

  <Card title="View" icon="eye">
    See unmasked value
  </Card>
</CardGroup>

## Common Workflows

### Quick Health Check (30 seconds)

```bash theme={null}
$ lua production

→ 🤖 Persona
# Version 5, deployed 2 weeks ago ✓
Press Enter...

→ ⚙️ Skills
# 3 skills deployed, latest versions ✓
Press Enter...

→ 🔐 Environment Variables
# 7 variables configured ✓
→ Back

→ ❌ Exit
```

### Update API Key

```bash theme={null}
$ lua production
→ 🔐 Environment Variables
→ ✏️ Update existing variable
→ Select: STRIPE_KEY
? New value: sk_live_new_key_2024
✅ Updated

→ 👁️ View variable value
→ Select: STRIPE_KEY
# Verify: sk_live_new_key_2024 ✓
```

### Troubleshoot Issue

```bash theme={null}
# User: "Feature not working"

$ lua production
→ ⚙️ Skills
# Check: feature-skill
# Status: Not deployed ❌

# Found the problem!
$ lua deploy → feature-skill → v1.0.0
$ lua production → ⚙️ Skills
# Verify: feature-skill v1.0.0 ⭐ ✓
```

## Best Practices

<AccordionGroup>
  <Accordion title="Daily Production Check">
    ```bash theme={null}
    # Morning routine (5 min)
    $ lua production
    → Check persona still correct
    → Verify all skills deployed
    → Scan environment variables
    ```
  </Accordion>

  <Accordion title="Pre-Deployment">
    ```bash theme={null}
    # Before deploying
    $ lua production
    # Document current state
    # Verify dependencies
    # Confirm env vars ready
    ```
  </Accordion>

  <Accordion title="Post-Deployment">
    ```bash theme={null}
    # After deploying
    $ lua production
    # Confirm new versions deployed
    # Verify no unexpected changes
    # Check env vars unchanged
    ```
  </Accordion>

  <Accordion title="Team Handoffs">
    ```bash theme={null}
    # Documenting production state
    $ lua production
    # Screenshot or note:
    # - Persona version
    # - Skill versions
    # - Env var count
    ```
  </Accordion>
</AccordionGroup>

## Comparison with Other Commands

| Feature      | lua production | lua persona    | lua deploy      | lua env      |
| ------------ | -------------- | -------------- | --------------- | ------------ |
| View persona | ✅ Current      | ✅ All versions | ❌               | ❌            |
| View skills  | ✅ All          | ❌              | ✅ One at a time | ❌            |
| View env     | ✅ Production   | ❌              | ❌               | ✅ Both modes |
| Manage env   | ✅ Full CRUD    | ❌              | ❌               | ✅ Full CRUD  |
| Deploy       | ❌              | ✅ Persona      | ✅ Skills        | ❌            |
| **Best for** | **Overview**   | Persona mgmt   | Skill deploy    | Env mgmt     |

## Next Steps

<CardGroup>
  <Card title="Manage Persona" icon="user" href="/cli/persona-command">
    Edit and deploy persona versions
  </Card>

  <Card title="Deploy to Production" icon="rocket" href="/cli/skill-management#lua-deploy">
    Deploy primitive versions (skills, webhooks, jobs, and more) to production
  </Card>

  <Card title="Manage Environment" icon="key" href="/cli/env-command">
    Configure sandbox and production variables
  </Card>

  <Card title="Test in Production" icon="comments" href="/cli/chat-command">
    Chat with production agent
  </Card>
</CardGroup>


# Resources Command
Source: https://docs.heylua.ai/cli/resources-command

Manage your agent's knowledge base and reference materials

## Overview

The `lua resources` command manages your agent's knowledge base - documents and information that your agent can reference during conversations.

```bash theme={null}
lua resources
```

### Non-Interactive Mode

```bash theme={null}
# List all resources
lua resources list

# View a specific resource
lua resources view --resource-name "FAQ Document"

# Delete a resource
lua resources delete --resource-name "Old Document"
```

| Option                   | Description                     |
| ------------------------ | ------------------------------- |
| `--resource-name <name>` | Resource name (for view/delete) |

| Action   | Description           | Required Options  |
| -------- | --------------------- | ----------------- |
| `list`   | List all resources    | None              |
| `view`   | View resource content | `--resource-name` |
| `delete` | Delete a resource     | `--resource-name` |

<Note>
  **Note:** Creating and updating resources requires interactive mode due to the editor integration for writing long-form content.
</Note>

<CardGroup>
  <Card title="Knowledge Base" icon="book">
    Create documents for your agent to reference
  </Card>

  <Card title="Full CRUD" icon="database">
    Create, read, update, and delete resources
  </Card>

  <Card title="Editor Integration" icon="pen">
    Write long-form content easily
  </Card>

  <Card title="Always Current" icon="clock">
    Update resources as info changes
  </Card>
</CardGroup>

## What Are Resources?

Resources are documents that your agent can access and reference - think of them as your agent's knowledge library.

**Examples:**

* Product catalogs and specifications
* Company policies and procedures
* FAQs and common questions
* Return/refund policies
* Shipping information
* Troubleshooting guides
* Company history and values
* Pricing information

## Quick Start

<Steps>
  <Step title="Run Command">
    ```bash theme={null}
    lua resources
    ```
  </Step>

  <Step title="Create Resource">
    ```
    ? What would you like to do? ➕ Create new resource
    ? Resource name: Product Catalog
    ```

    Opens your editor
  </Step>

  <Step title="Write Content">
    Write your content in the editor:

    ```
    Our complete product catalog for 2024.

    Categories:
    - Electronics
    - Home & Garden
    - Clothing
    ...
    ```
  </Step>

  <Step title="Save">
    Save and close editor

    ```
    ✅ Resource "Product Catalog" created successfully
    ```
  </Step>
</Steps>

## Operations

### Create New Resource

```bash theme={null}
? What would you like to do? ➕ Create new resource

? Resource name: Return Policy
[Opens editor]

# Write content:
AcmeCorp Return Policy

Returns accepted within 45 days of purchase.

Conditions:
- Item must be unused in original packaging
- Receipt or order number required
- Free return shipping on defective items

Process:
1. Contact support@acmecorp.com
2. Receive return authorization
3. Ship item within 7 days
4. Refund processed within 3-5 business days

[Save and close]

🔄 Creating resource...
✅ Resource "Return Policy" created successfully
```

### Update Existing Resource

```bash theme={null}
? What would you like to do? ✏️ Update existing resource

? Select resource to update:
❯ Return Policy
  Shipping Information
  Product Catalog

? Resource name: (Return Policy) Return Policy - 2024
[Opens editor with current content]

# Modify content
# Save and close

🔄 Updating resource...
✅ Resource "Return Policy - 2024" updated successfully
```

### View Resource

```bash theme={null}
? What would you like to do? 👁️  View resource content

? Select resource to view: Product Catalog

============================================================
📄 Resource: Product Catalog
============================================================
Created: 1/10/2024, 9:00:00 AM
Updated: 1/15/2024, 2:30:00 PM
============================================================

Our complete product catalog for 2024.

Categories:
- Electronics: Laptops, tablets, smartphones
- Home & Garden: Furniture, appliances, tools
...

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

Press Enter to continue...
```

### Delete Resource

```bash theme={null}
? What would you like to do? 🗑️  Delete resource

? Select resource to delete: Old FAQ 2023

? Are you sure you want to delete "Old FAQ 2023"? Yes

🔄 Deleting resource...
✅ Resource "Old FAQ 2023" deleted successfully
```

<Warning>
  Deletion is permanent and cannot be undone. Always confirm before deleting.
</Warning>

## Resource Best Practices

### Structure Your Resources

<Tabs>
  <Tab title="By Category">
    ```
    - Company Information
    - Product Catalog
    - Policies (Return, Shipping, Privacy)
    - FAQ Documents
    - Troubleshooting Guides
    - Regional Information
    ```
  </Tab>

  <Tab title="By Function">
    ```
    - Sales Resources
      → Product catalogs
      → Pricing
      → Promotions

    - Support Resources
      → Troubleshooting
      → Policies
      → How-to guides

    - Company Resources
      → About us
      → Contact info
      → Hours
    ```
  </Tab>

  <Tab title="By User Journey">
    ```
    - Pre-Purchase
      → Product catalog
      → Sizing guide
      → Comparisons

    - Purchase
      → Payment options
      → Shipping choices

    - Post-Purchase
      → Order tracking
      → Returns
      → Support
    ```
  </Tab>
</Tabs>

### Content Guidelines

<AccordionGroup>
  <Accordion title="✅ Be Specific">
    ```
    ❌ "We have good return policy"

    ✅ "Returns accepted within 45 days.
        Item must be unused in original packaging.
        Receipt required.
        Refund processed in 3-5 business days."
    ```
  </Accordion>

  <Accordion title="✅ Use Structure">
    ```
    Product Name: UltraBook Pro
    Price: $1,299

    Specs:
    - 16GB RAM
    - 512GB SSD
    - 14" Display

    Best For:
    - Professionals
    - Content creators
    ```
  </Accordion>

  <Accordion title="✅ Include Timestamps">
    ```
    Last Updated: January 15, 2024
    Valid Through: December 31, 2024
    Next Review: July 1, 2024
    ```
  </Accordion>

  <Accordion title="✅ Anticipate Questions">
    ```
    Q: Can I return opened items?
    A: Yes, if defective. No, if unwanted.

    Q: What if I lost my receipt?
    A: We can look up by email or phone.
    ```
  </Accordion>
</AccordionGroup>

## Use Cases

### Product Knowledge Base

```bash theme={null}
$ lua resources → Create

Name: Electronics Catalog
Content:
Laptops:
1. UltraBook Pro - $1299
   - Professional grade
   - 16GB RAM, 512GB SSD
   - 12-hour battery

2. Student Laptop - $599
   - Perfect for students
   - 8GB RAM, 256GB SSD
   - 8-hour battery
```

### Policy Documentation

```bash theme={null}
$ lua resources → Create

Name: Customer Service Policies
Content:
Returns: 45 days, original packaging
Exchanges: Same item or store credit
Refunds: 3-5 business days
Warranties: Manufacturer warranty
Price Matching: Within 14 days
```

### FAQ Repository

```bash theme={null}
$ lua resources → Create

Name: Shipping FAQ
Content:
Q: How long does shipping take?
A: Standard 3-5 days, Express 1-2 days

Q: International shipping?
A: US and Canada only currently

Q: Track my order?
A: Tracking link sent via email
```

## Integration with Agent

### How Agents Use Resources

**Automatically:**

* Searches when relevant
* Retrieves accurate information
* Provides consistent answers
* References specific resources

**Example conversation:**

```
User: "What's your return policy?"

Agent: [Searches resources]
       [Finds "Return Policy"]
       [Reads content]
       
Response: "We accept returns within 45 days of purchase.
The item must be unused in original packaging..."
```

### Combine with Persona

```bash theme={null}
# In persona
$ lua persona → Edit

"You are a customer service agent.

When answering questions, always check your resources for:
- Product details → Product Catalog
- Return questions → Return Policy
- Shipping questions → Shipping Information

Provide accurate information from resources, not guesses."
```

## Common Workflows

### Build Knowledge Base

```bash theme={null}
$ lua resources

# Day 1: Core resources
→ Create: Company Information
→ Create: Product Catalog
→ Create: Return Policy

# Day 2: Support resources
→ Create: FAQ - General
→ Create: Troubleshooting Guide

# Day 3: Details
→ Create: Product Specifications
→ Create: Warranty Information
```

### Seasonal Update

```bash theme={null}
# Before holidays
$ lua resources
→ Update: Product Catalog  # Add gift guides
→ Update: Shipping Info    # Add deadlines
→ Create: Holiday Guide

# After holidays
$ lua resources
→ Update: Product Catalog  # Remove holiday items
→ Delete: Holiday Guide
```

### Policy Change

```bash theme={null}
# Return window extended 30 → 45 days

$ lua resources
→ View: Return Policy  # Check current
→ Update: Return Policy  # Change to 45 days
✅ Updated

# Test
$ lua chat
💬: "What's your return policy?"
🤖: "45 days..." ✓ Using updated policy
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Current">
    * Update monthly minimum
    * Review quarterly
    * Archive old resources
    * Track last update dates
  </Accordion>

  <Accordion title="Use Clear Names">
    ```
    ✅ Product Catalog 2024
    ✅ Return Policy - Updated Jan 2024
    ✅ FAQ - Shipping Questions

    ❌ Doc1
    ❌ stuff
    ❌ temp
    ```
  </Accordion>

  <Accordion title="Optimal Size">
    * **Good**: 500-5000 characters
    * **Too small**: \< 100 characters
    * **Too large**: > 50,000 characters

    Break large docs into focused resources
  </Accordion>

  <Accordion title="Test After Changes">
    ```bash theme={null}
    $ lua resources → Update
    $ lua chat  # Test agent uses updated info
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent not using resources">
    **Solution**: Update persona to reference resources

    ```bash theme={null}
    $ lua persona → Edit
    # Add: "Always check resources for accurate info"
    ```
  </Accordion>

  <Accordion title="Editor won't open">
    **Solution**: Set default editor

    ```bash theme={null}
    export EDITOR=nano
    $ lua resources
    ```
  </Accordion>

  <Accordion title="Content too long">
    **Solution**: Split into multiple resources

    One large doc → Multiple focused docs
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Configure Persona" icon="user" href="/cli/persona-command">
    Define how agent uses resources
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Verify agent references resources correctly
  </Card>
</CardGroup>


# Skill Management
Source: https://docs.heylua.ai/cli/skill-management

Commands for creating, compiling, testing, and deploying skills

## Overview

Skill management commands help you build, test, and deploy your AI skills.

<CardGroup>
  <Card title="lua init" icon="plus">
    Create new skill project
  </Card>

  <Card title="lua compile" icon="gears">
    Compile TypeScript code
  </Card>

  <Card title="lua test" icon="flask">
    Test tools interactively
  </Card>

  <Card title="lua push" icon="upload">
    Upload version to server
  </Card>

  <Card title="lua deploy" icon="rocket">
    Deploy to production
  </Card>
</CardGroup>

## lua init

Initialize a new Lua skill project in the current directory.

```bash theme={null}
mkdir my-skill && cd my-skill
lua init                    # Minimal project (recommended)
lua init --with-examples    # Include 30+ example tools
```

### Options

| Option                        | Description                                                                                                |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `--with-examples`             | Include example skills, tools, jobs, webhooks, and processors                                              |
| `--agent-id <id>`             | Use existing agent by ID (non-interactive)                                                                 |
| `--agent-name <name>`         | Name for new agent (requires `--org-id` or `--org-name`)                                                   |
| `--org-id <id>`               | Use existing organization by ID                                                                            |
| `--org-name <name>`           | Create new organization with this name                                                                     |
| `--model <model>`             | LLM model code to use (e.g. `openai/gpt-4o`). Skips the model picker.                                      |
| `--force`                     | Skip confirmations / overwrite existing project                                                            |
| `--restore-sources`           | Automatically restore project source files from backup (requires `--agent-id`)                             |
| `--from-agent-id <id>`        | **Duplicate an existing agent** into a new one (clones skills, persona, MCP servers, env, project backup). |
| `--include-resources`         | Include resources + RAG when duplicating                                                                   |
| `--include-custom-data`       | Include custom data tables when duplicating                                                                |
| `--include-inquiry-form`      | Include inquiry forms when duplicating                                                                     |
| `--include-devices`           | Include device + trigger definitions when duplicating                                                      |
| `--include-ecommerce-catalog` | Include ecommerce catalog (products, baskets) when duplicating                                             |
| `--promo-code <code>`         | Apply a promo code at agent creation for bonus credits                                                     |

### Non-Interactive Mode

```bash theme={null}
# Use existing agent
lua init --agent-id abc123

# Create agent in existing organization
lua init --agent-name "My Bot" --org-id org456

# Create agent + new organization
lua init --agent-name "My Bot" --org-name "Acme Corp"

# Override existing project
lua init --agent-id abc123 --force

# With example code
lua init --agent-id abc123 --with-examples

# Restore from backup
lua init --agent-id abc123 --restore-sources

# Pick a specific LLM model up front
lua init --agent-name "My Bot" --org-name "Acme Corp" --model openai/gpt-4o

# Duplicate an existing agent (clones skills + persona + project backup)
lua init --from-agent-id baseAgent_agent_xxx

# Cross-org duplicate
lua init --from-agent-id baseAgent_agent_xxx --org-id org456

# Duplicate with optional buckets
lua init --from-agent-id baseAgent_agent_xxx \
  --include-resources \
  --include-custom-data \
  --include-devices \
  --include-ecommerce-catalog

# Apply a promo code at agent creation
lua init --agent-name "My Bot" --org-name "Acme Corp" --promo-code LAUNCH50
```

### What It Does

<Steps>
  <Step title="Choose Agent">
    Select existing agent or create new one
  </Step>

  <Step title="Configure Agent (if new)">
    * Enter business name
    * Enter agent name
    * Select business type
    * Select brand personality
    * Enter brand traits
    * Configure features
  </Step>

  <Step title="Create Project">
    * Copies template files
    * Creates `lua.skill.yaml`
    * Installs dependencies
    * Ready to customize!
  </Step>
</Steps>

### Interactive Prompts

<Tabs>
  <Tab title="Minimal (Default)">
    ```bash theme={null}
    $ lua init
    ? What would you like to do? Create new agent
    ? Enter business name: My Coffee Shop
    ? Enter agent name: CoffeeBot
    ? Select business type: Food & Beverage
    ? Select brand personality: Friendly
    ? Enter brand traits: Warm, welcoming, knowledgeable
    🔄 Creating agent...
    ✅ Agent created successfully!
    ✅ Created lua.skill.yaml
    ✅ Copied template files
    ✅ Updated LuaAgent configuration
    📦 Installing dependencies...
    ✅ Lua skill project initialized successfully!
    💡 Tip: Use `lua init --with-examples` to include example code
    ```
  </Tab>

  <Tab title="With Examples">
    ```bash theme={null}
    $ lua init --with-examples
    ? What would you like to do? Create new agent
    ? Enter business name: My Coffee Shop
    ? Enter agent name: CoffeeBot
    ...
    ✅ Created lua.skill.yaml
    ✅ Copied template files
    ✅ Included example skills, tools, jobs, and webhooks
    ✅ Updated LuaAgent configuration
    📦 Installing dependencies...
    ✅ Lua skill project initialized with examples!
    💡 Check the examples/ folder for sample skills, tools, jobs, and webhooks
    ```
  </Tab>

  <Tab title="Existing Agent">
    ```bash theme={null}
    $ lua init
    ? What would you like to do? Select existing agent
    ? Select organization: My Organization
    ? Select agent: CoffeeBot
    ✅ Created lua.skill.yaml
    ✅ Copied template files
    📦 Installing dependencies...
    ✅ Lua skill project initialized successfully!
    ```
  </Tab>
</Tabs>

### What Gets Created

<Tabs>
  <Tab title="Minimal (Default)">
    ```
    your-skill/
    ├── src/
    │   └── index.ts              # Empty agent ready to customize
    ├── lua.skill.yaml            # Configuration (auto-managed)
    ├── package.json              # Dependencies
    ├── tsconfig.json             # TypeScript config
    ├── .env.example              # Environment variables template
    └── README.md                 # Quick start guide
    ```

    A clean slate - build your agent from scratch!
  </Tab>

  <Tab title="With Examples">
    ```
    your-skill/
    ├── src/
    │   └── index.ts              # Agent configuration
    ├── examples/                 # Reference code
    │   ├── skills/               # Example skills & tools
    │   │   ├── tools/            # 30+ tool implementations
    │   │   └── *.skill.ts        # Skill definitions
    │   ├── webhooks/             # HTTP endpoint examples
    │   ├── jobs/                 # Scheduled task examples
    │   ├── preprocessors/        # Message filter examples
    │   ├── postprocessors/       # Response formatter examples
    │   └── services/             # Helper utilities
    ├── lua.skill.yaml
    ├── package.json
    ├── tsconfig.json
    ├── .env.example
    └── README.md
    ```

    Examples in a separate folder - copy what you need!
  </Tab>
</Tabs>

### Configuration File

`lua.skill.yaml` is created with:

```yaml theme={null}
agent:
  agentId: agent_abc123
  orgId: org_xyz789

skills: []  # Auto-populated during compilation
```

<Warning>
  **The `lua.skill.yaml` file is auto-managed by the CLI.** Do not manually edit it except for incrementing version numbers. All configuration belongs in your code (`src/index.ts`).
</Warning>

<Note>
  Persona is stored in your `LuaAgent` code (in `src/index.ts`), not in YAML. The YAML file is state-only and tracks IDs and versions.
</Note>

## lua compile

Compile TypeScript skill into deployable JavaScript bundles.

```bash theme={null}
lua compile
```

### What It Does

<Steps>
  <Step title="Analyze Code">
    Detects all tools from your `src/index.ts` file
  </Step>

  <Step title="Bundle Tools">
    Uses esbuild to create optimized JavaScript bundles
  </Step>

  <Step title="Extract Metadata">
    Extracts tool names, descriptions, and schemas
  </Step>

  <Step title="Create Deployment">
    Generates deployment artifacts in `dist/` directory
  </Step>

  <Step title="Update Config">
    Creates/updates skills in `lua.skill.yaml`
  </Step>
</Steps>

### Output

```
dist/
├── deployment.json          # Deployment metadata
├── index.js                 # Main skill bundle
└── tools/                   # Individual tool bundles
    ├── GetWeatherTool.js
    ├── UserDataTool.js
    └── ...

.lua/
├── deploy.json              # Legacy format
├── get_weather.js           # Uncompressed (debugging)
└── ...
```

### Example Output

```bash theme={null}
$ lua compile
🔨 Compiling Lua skill...
📦 Found 15 tools to bundle...
📦 Bundling GetWeatherTool...
📦 Bundling UserDataTool...
📦 Bundling ProductsTool...
... (more tools)
📦 Bundling main index...
✅ Skill compiled successfully - 15 tools bundled
```

### Features

* ✅ **Automatic Detection** - Finds all tools in your code
* ✅ **Fast Bundling** - Uses esbuild for speed
* ✅ **Type Safety** - Validates TypeScript
* ✅ **Dependency Management** - Bundles all dependencies
* ✅ **Skill Creation** - Auto-creates skills in config
* ✅ **Drift Detection** - Checks for server/local differences

### Compile Options

```bash theme={null}
lua compile              # Default: compile without drift check
lua compile --sync       # Enable drift detection and prompt if found
lua compile --verbose    # Show detailed compilation output
lua compile --debug      # Extra-verbose logging + keep temp files for inspection
```

| Flag        | Description                                                                             |
| ----------- | --------------------------------------------------------------------------------------- |
| `--sync`    | Enable drift detection during compile (prompts if drift found)                          |
| `--verbose` | Show detailed compilation output                                                        |
| `--debug`   | Enable debug mode — extra verbose logging and preserves temp build files for inspection |

<Card title="Learn More" href="/cli/sync-command">
  See lua sync for details on drift detection
</Card>

## lua test

Test individual tools locally in a sandboxed environment.

```bash theme={null}
lua test
```

### Options

| Option           | Description                           |
| ---------------- | ------------------------------------- |
| `--name <name>`  | Entity name to test (non-interactive) |
| `--input <json>` | JSON input string for testing         |

### Non-Interactive Mode

```bash theme={null}
# Test a skill/tool
lua test skill --name get_weather --input '{"city": "London"}'

# Test a webhook
lua test webhook --name payment-hook --input '{"query": {}, "headers": {}, "body": {"type": "payment"}}'

# Test a job
lua test job --name daily-report

# Test preprocessor
lua test preprocessor --name filter --input '{"message": "hello", "channel": "web"}'

# Test postprocessor
lua test postprocessor --name formatter --input '{"message": "hi", "response": "hello", "channel": "web"}'
```

### How It Works

<Steps>
  <Step title="Compile">
    Compiles your skill first
  </Step>

  <Step title="List Tools">
    Shows all available tools
  </Step>

  <Step title="Select Tool">
    Choose which tool to test
  </Step>

  <Step title="Enter Inputs">
    Dynamic prompts based on tool's schema
  </Step>

  <Step title="Execute">
    Runs tool in secure VM sandbox
  </Step>

  <Step title="View Results">
    Shows output or error messages
  </Step>
</Steps>

### Example Session

```bash theme={null}
$ lua test
🧪 Testing Lua skill...
📦 Compiling code first...
✅ Skill compiled successfully
📄 Loaded environment variables from .env file

? 🔧 Select a tool to test:
❯ get_weather - Get the weather for a given city
  create_product - Create a new product
  search_products - Search products
  get_user_data - Get user data
  
✅ Selected tool: get_weather

📝 Enter input values:
? city (required): London

🚀 Executing tool...
Input: {
  "city": "London"
}
✅ Tool execution successful!
Output: {
  "weather": "3",
  "city": "London",
  "temperature": 15.2,
  "description": "Windspeed 12.3 km/h"
}
```

### Features

* ✅ **Dynamic Prompts** - Based on Zod schema
* ✅ **Type Validation** - Validates inputs automatically
* ✅ **Environment Loading** - Loads `.env` and `lua.skill.yaml` variables
* ✅ **Secure Sandbox** - Isolated VM execution
* ✅ **Detailed Errors** - Clear error messages

### Testing Complex Inputs

```bash theme={null}
# Nested objects
? shippingAddress.street (required): 123 Main St
? shippingAddress.city (required): New York
? shippingAddress.zip (required): 10001

# Arrays
? items[0].id (required): product_123
? items[0].quantity (required): 2
? Add another item? No

# Optional fields
? description (optional): [Press Enter to skip]
```

## lua push

Push your compiled components to the Lua server.

```bash theme={null}
lua push                 # Interactive selection
lua push skill           # Push a skill
lua push persona         # Push persona
lua push webhook         # Push a webhook
lua push job             # Push a job
lua push preprocessor    # Push a preprocessor
lua push postprocessor   # Push a postprocessor
lua push mcp             # Push an MCP server
lua push all --force     # Push all components
```

### Options

| Option                | Description                                                                                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name <name>`       | Entity name to push (non-interactive)                                                                                                                                                                                           |
| `--set-version <ver>` | Version to set (e.g., 1.0.5)                                                                                                                                                                                                    |
| `--force`             | Skip all confirmation prompts                                                                                                                                                                                                   |
| `--auto-deploy`       | Automatically deploy to production after push                                                                                                                                                                                   |
| `--no-include-source` | Skip the per-skill source attach after push. Default is to attach, so the admin Builder UI source panel reflects your CLI edits. The attach is non-fatal — a failure logs a warning but doesn't fail the push.                  |
| `--fresh`             | (Only for `lua push backup`) Build the backup manifest by walking the project directory from disk, instead of reading the compiled `dist-v2/manifest.json`. Use this to capture out-of-band file changes (e.g. Builder writes). |

<Note>
  **Auto-backup-push:** Every `lua push <primitive>` now synchronously runs a fresh-from-disk backup as the final step. If the backup fails, the command exits non-zero — no more silent partial success where the primitive landed but local source never reached the canonical store.
</Note>

### Non-Interactive Mode

```bash theme={null}
# Push specific skill with version
lua push skill --name mySkill --set-version 1.0.5

# Push all components
lua push all --force

# Push and auto-deploy to production
lua push all --force --auto-deploy

# Push webhook with version
lua push webhook --name payment-hook --set-version 2.0.0

# Push job with version
lua push job --name daily-report --set-version 1.0.0
```

<Note>
  **Push All:** Use `lua push all --force` to push all components at once. Add `--auto-deploy` to also activate/deploy them.
</Note>

### Usage Modes

<Tabs>
  <Tab title="Interactive Mode">
    **Default behavior - prompts for selection**

    ```bash theme={null}
    $ lua push
    ? What would you like to push?
      › skill
        persona
    ```

    Best for: When you're not sure or want to see options
  </Tab>

  <Tab title="Direct Mode - Skill">
    **Skip prompt and push skill directly**

    ```bash theme={null}
    $ lua push skill
    # No prompt - goes straight to pushing skill
    ```

    Best for: Quick iterations, automation, when you know what you want
  </Tab>

  <Tab title="Direct Mode - Persona">
    **Skip prompt and push persona directly**

    ```bash theme={null}
    $ lua push persona
    # No prompt - goes straight to pushing persona
    ```

    Best for: Persona-only updates, faster workflow
  </Tab>
</Tabs>

### What It Does (Skills)

<Steps>
  <Step title="Select Skill (if interactive)">
    Choose which skill to push (if multiple)
  </Step>

  <Step title="Enter Version">
    Enter new version number (auto-suggests next patch)

    ```
    Current version: 1.0.0
    ? Enter new version to push: (1.0.1)
    ```
  </Step>

  <Step title="Update Configuration">
    Updates version in `lua.skill.yaml`
  </Step>

  <Step title="Authenticate">
    Validates your API key
  </Step>

  <Step title="Compile">
    Automatically compiles the skill
  </Step>

  <Step title="Upload">
    Uploads bundles to server
  </Step>

  <Step title="Optional Deploy">
    Choose to deploy immediately or later

    ```
    ? Would you like to deploy this version to production now? (y/N)
    ```
  </Step>
</Steps>

### Example: Push Only (Interactive)

```bash theme={null}
$ lua push
? What would you like to push?
  › skill
    persona

📦 Pushing skill: customer-service

Current version: 1.0.0
? Enter new version to push: (1.0.1) ⏎

📝 Updating version from 1.0.0 to 1.0.1
✅ Authenticated
🔄 Compiling skill...
✅ Skill compiled successfully - 10 tools bundled
🔄 Pushing version to server...
✅ Version 1.0.1 of "customer-service" pushed successfully

? Would you like to deploy this version to production now? No

[Version pushed, use 'lua deploy' to deploy later]
```

### Example: Push Only (Direct Mode)

```bash theme={null}
$ lua push skill
📦 Pushing skill: customer-service

Current version: 1.0.0
? Enter new version to push: (1.0.1) ⏎

📝 Updating version from 1.0.0 to 1.0.1
✅ Authenticated
🔄 Compiling skill...
✅ Skill compiled successfully - 10 tools bundled
🔄 Pushing version to server...
✅ Version 1.0.1 of "customer-service" pushed successfully

? Would you like to deploy this version to production now? No

[Version pushed, use 'lua deploy' to deploy later]
```

### Example: Push and Deploy

```bash theme={null}
$ lua push
📦 Pushing skill: order-management

Current version: 0.5.0
? Enter new version to push: 1.0.0

📝 Updating version from 0.5.0 to 1.0.0
✅ Authenticated
🔄 Compiling skill...
✅ Skill compiled successfully - 8 tools bundled
🔄 Pushing version to server...
✅ Version 1.0.0 of "order-management" pushed successfully

? Would you like to deploy this version to production now? Yes

⚠️  WARNING: You are about to deploy to PRODUCTION!
⚠️  This will affect ALL users immediately.

? Are you absolutely sure you want to deploy? Yes

🔄 Publishing version...
✅ Version 1.0.0 deployed successfully to production
```

### Version Management

<Tabs>
  <Tab title="Auto-Increment">
    The command auto-suggests the next patch version:

    ```
    Current: 1.0.0  → Suggests: 1.0.1
    Current: 1.5.9  → Suggests: 1.5.10
    Current: 2.0.0  → Suggests: 2.0.1
    ```

    Press Enter to accept or type your own version
  </Tab>

  <Tab title="Custom Version">
    You can enter any valid semver version:

    ```
    Current: 0.5.0
    ? Enter: 1.0.0  # Major release

    Current: 1.2.3
    ? Enter: 1.3.0  # Minor update

    Current: 2.0.0
    ? Enter: 2.0.1-beta  # Pre-release
    ```
  </Tab>

  <Tab title="Semantic Versioning">
    Follow semver conventions:

    * **MAJOR** (2.0.0): Breaking changes
    * **MINOR** (1.1.0): New features
    * **PATCH** (1.0.1): Bug fixes

    ```yaml theme={null}
    # In lua.skill.yaml
    skills:
      - name: my-skill
        version: 1.0.1  # Auto-updated by push
    ```
  </Tab>
</Tabs>

<Note>
  **Version Conflict Avoidance**: When using `--force`, the CLI automatically checks the server for the highest existing version and suggests the next available version. This prevents "Version already exists" errors during automated deployments.
</Note>

### Deploy Now or Later?

<Tabs>
  <Tab title="Deploy Later (Recommended)">
    **Push now, test, deploy when ready**

    ```bash theme={null}
    $ lua push
    ? Deploy now? No  # Default

    # Test in sandbox
    $ lua chat → Sandbox mode

    # Deploy when satisfied
    $ lua deploy
    ```

    **Best for:**

    * Major changes
    * Need more testing
    * Team coordination
    * Off-peak deployment
  </Tab>

  <Tab title="Deploy Immediately">
    **One-command deployment**

    ```bash theme={null}
    $ lua push
    ? Deploy now? Yes
    ? Absolutely sure? Yes
    ✅ Deployed
    ```

    **Best for:**

    * Critical hotfixes
    * Small bug fixes
    * Well-tested changes
    * Urgent updates
  </Tab>
</Tabs>

### Important Notes

<Warning>
  **Version Management:**

  * Always increments version (cannot overwrite)
  * Version is updated in `lua.skill.yaml`
  * All versions are preserved on server
  * Can deploy any previous version

  **Immediate Deployment:**

  * Requires two confirmations for safety
  * Affects all users immediately
  * Have rollback plan ready
  * Monitor after deployment
</Warning>

### Version Management

The version number is the **only field** in `lua.skill.yaml` you should manually edit:

```yaml theme={null}
skills:
  - name: my-skill
    version: 1.0.1  # Increment this before pushing
```

Then push:

```bash theme={null}
lua push
```

### Requirements

* Must be in skill directory with `lua.skill.yaml`
* Must have valid API key (`lua auth configure`)
* Version must not already exist on server

## lua deploy

Deploy a specific version of a single primitive to production (all users).

```bash theme={null}
lua deploy [type]
```

`type` is optional — when omitted, an interactive menu lets you pick. Valid types: `skill`, `webhook`, `job`, `preprocessor`, `postprocessor`, `persona`, `all`.

<Note>
  `lua deploy` is the original, single-primitive release command and remains fully supported — but for agents already using [agent versions](/cli/version-command), `lua version create` + `lua version promote` is the recommended flow: it snapshots and switches *every* primitive at once, atomically, instead of one at a time. See [The release flow, end to end](/cli/version-command#the-release-flow-end-to-end) for how `push`, `deploy`, and `version` fit together.

  **What `lua deploy` actually does depends on your agent's history:**

  * If the agent has **promoted at least one agent version**, `lua deploy` performs a **scoped promote**: it automatically creates and promotes a new agent version identical to the current one, except for the primitive you just deployed. The change is live immediately, and it still shows up in `lua version list` (tagged with a `deploy …` message) so your version history has no gaps.
  * If the agent has **never created or promoted an agent version**, `lua deploy` activates the primitive directly, exactly as described below.
</Note>

### Options

| Option                | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `--name <name>`       | Entity name to deploy (non-interactive selection)       |
| `--set-version <ver>` | Version to deploy, or `'latest'` for the newest version |
| `--force`             | Skip confirmation prompt                                |

<Note>
  **Deprecated flags** — still accepted for backward compatibility but prefer the generic equivalents above:

  | Deprecated              | Use instead           |
  | ----------------------- | --------------------- |
  | `--skill-name <name>`   | `--name <name>`       |
  | `--skill-version <ver>` | `--set-version <ver>` |
</Note>

### Usage

```bash theme={null}
# Interactive — prompts for type, entity, and version
lua deploy

# Deploy a specific primitive type
lua deploy skill
lua deploy webhook
lua deploy job
lua deploy preprocessor
lua deploy postprocessor
lua deploy persona

# Deploy latest version of every primitive at once
lua deploy all --force
```

### Non-Interactive Mode

```bash theme={null}
# Deploy a specific skill version
lua deploy skill --name mySkill --set-version 1.0.5 --force

# Deploy latest webhook version
lua deploy webhook --name myWebhook --set-version latest --force

# Deploy latest of everything (CI/CD)
lua deploy all --force
```

### What It Does

<Steps>
  <Step title="Select Type">
    Choose the primitive type (or pass as argument to skip)
  </Step>

  <Step title="Select Entity">
    Pick which skill / webhook / job / etc. to deploy (auto-selected if only one exists)
  </Step>

  <Step title="Fetch Versions">
    Lists all pushed versions from the server
  </Step>

  <Step title="Select Version">
    Choose which version to deploy (or pass `--set-version latest`)
  </Step>

  <Step title="Confirm">
    Shows warning about production deployment (skip with `--force`)
  </Step>

  <Step title="Deploy">
    Publishes the selected version — immediately live for all users
  </Step>
</Steps>

### Example

```bash theme={null}
$ lua deploy skill
📦 Deploying Skill: mySkill
🔄 Fetching available versions...

? Select a version to deploy:
  1.0.2 - Created: Oct 3, 2025 by you@example.com
  1.0.1 - Created: Oct 2, 2025 by you@example.com
❯ 1.0.0 (CURRENT) - Created: Oct 1, 2025 by you@example.com

? ⚠️  Warning: This version will be deployed to all users. Do you want to proceed? Yes
🔄 Publishing version...
✅ Skill "mySkill" v1.0.0 deployed successfully
```

### Features

* Works for all primitive types — not just skills
* Shows all available versions with currently deployed one highlighted
* Requires explicit confirmation (skip with `--force`)
* Immediate deployment (no rollback delay)
* `lua deploy all --force` deploys latest version of every primitive in one command
* For agents with agent-version history, performs a scoped promote behind the scenes — see the [note above](#lua-deploy)

<Warning>
  **Deployment is immediate!** If `lua deploy` reports success, that exact code serves the very next invocation of the agent (allow up to roughly a minute for edge caches to catch up). All users will get the new version right away. Test thoroughly with `lua chat` first — sandbox testing never touches what's live.
</Warning>

## lua push backup

<Note>
  Backup your project source files to cloud storage for disaster recovery and team collaboration.
</Note>

Push your project source files to cloud storage for safekeeping. Uses content-addressed storage with automatic deduplication for efficient backups.

```bash theme={null}
lua push backup                 # Backup project sources
lua push backup --force         # Force backup even if up-to-date
lua push backup --skip-compile  # Skip compilation (assume already compiled)
```

### Options

| Option           | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `--force`        | Force backup even if hash matches previous backup    |
| `--skip-compile` | Skip compilation step (assumes dist/ already exists) |

### What Gets Backed Up

The backup includes all source files tracked in your compilation manifest:

* **Source Code**: `src/` directory (TypeScript files)
* **Configuration**: `lua.skill.yaml`, `tsconfig.json`, `package.json`
* **Environment Template**: `.env.example` (if exists)
* **Documentation**: `README.md` (if exists)

<Warning>
  **NOT backed up**: `node_modules/`, `dist/`, `.env` (secrets), `.git/` (use Git for version control)
</Warning>

### How It Works

<Steps>
  <Step title="Compile Project">
    Ensures manifest is fresh (runs `lua compile` if needed)
  </Step>

  <Step title="Calculate Project Hash">
    Creates a content hash of all source files for deduplication
  </Step>

  <Step title="Check Existing Backup">
    Verifies if this exact project state already exists on server
  </Step>

  <Step title="Upload New Files">
    Uploads only new/changed files (content-addressed storage)

    * Compares file hashes with server
    * Uploads missing blobs in batches
    * Deduplicates identical files across backups
  </Step>

  <Step title="Save Manifest">
    Saves the project structure and file references to MongoDB
  </Step>

  <Step title="Update Local Tracking">
    Updates `lua.skill.yaml` with backup hash for drift detection
  </Step>
</Steps>

### Example Output

```bash theme={null}
$ lua push backup
ℹ️  Project hash: 8f3d4a2b1c9e...
🔄 Checking server for existing backup...
🔄 Checking which files need upload...
ℹ️  Files: 42 total, 38 already stored, 4 to upload
ℹ️  Upload size: 12.3 KB (base64)
🔄 Uploading 4 new files to storage...
🔄 Uploaded 4/4 files...
🔄 Saving backup manifest...
✅ Backup pushed successfully!
   Files: 42
   New uploads: 4
   Deduplicated: 38
   Hash: 8f3d4a2b1c9e...
```

### Restoring from Backup

To restore a backed-up project on a new machine:

```bash theme={null}
# Initialize with restore flag
lua init --agent-id abc123 --restore-sources
```

This will:

1. Create a new project directory
2. Download all source files from cloud storage
3. Restore the exact project state from backup
4. Install dependencies

**Interactive restore:**

```bash theme={null}
$ lua init --agent-id abc123
? Would you like to restore project sources from backup? Yes
🔄 Fetching backup manifest...
✅ Found backup with 42 files
🔄 Downloading source files...
🔄 Downloaded 42/42 files...
✅ Sources restored successfully!
💡 Run 'lua compile' to rebuild from restored sources
```

### Use Cases

<Tabs>
  <Tab title="Disaster Recovery">
    **Recover from lost laptop or corrupted files:**

    ```bash theme={null}
    # On new machine
    lua init --agent-id abc123 --restore-sources
    npm install
    lua compile
    lua test
    ```

    All your source code is back!
  </Tab>

  <Tab title="Team Collaboration">
    **Share project with team members:**

    ```bash theme={null}
    # Team member A pushes backup
    lua push backup

    # Team member B clones it
    lua init --agent-id abc123 --restore-sources
    ```

    No Git setup required for quick sharing.
  </Tab>

  <Tab title="Migration">
    **Move project between machines:**

    ```bash theme={null}
    # Old machine
    lua push backup

    # New machine
    lua init --agent-id abc123 --restore-sources
    ```

    Fresh install with all your code intact.
  </Tab>

  <Tab title="CI/CD Safety Net">
    **Automatic backups before deployments:**

    ```bash theme={null}
    # In CI pipeline
    lua push backup --force
    lua push all --force --auto-deploy
    ```

    Always have a recovery point.
  </Tab>
</Tabs>

### Content-Addressed Storage

Backups use **content-addressed storage** (like Git):

* Each file is stored by its SHA-256 hash
* Identical files are stored only once
* Subsequent backups only upload changed files
* Extremely efficient for large projects with small changes

**Example:** If you change one line in one file, only that file is re-uploaded. The other 99 files reference existing blobs.

### Best Practices

<AccordionGroup>
  <Accordion title="Backup Before Major Changes">
    ```bash theme={null}
    lua push backup  # Safety checkpoint
    # Make risky changes
    lua test
    lua push skill
    ```

    If something breaks, restore from backup.
  </Accordion>

  <Accordion title="Use Git for Version Control">
    **Backup ≠ Version Control**

    * **Backup**: Disaster recovery, single snapshot
    * **Git**: Full history, branching, collaboration

    Use both:

    ```bash theme={null}
    git commit -m "Add feature"  # Version control
    lua push backup              # Disaster recovery snapshot
    ```
  </Accordion>

  <Accordion title="Backup Before Deployment">
    ```bash theme={null}
    lua push backup --force
    lua push all --force --auto-deploy
    ```

    Always have a recovery point before production changes.
  </Accordion>

  <Accordion title="Regular Backups in CI/CD">
    Add to your deployment pipeline:

    ```yaml theme={null}
    - name: Backup sources
      run: lua push backup --force

    - name: Deploy
      run: lua push all --force --auto-deploy
    ```
  </Accordion>
</AccordionGroup>

## Complete Workflow

### New Project Workflow

```bash theme={null}
# 1. Authenticate
lua auth configure

# 2. Initialize
mkdir my-skill && cd my-skill
lua init

# 3. Test
lua test

# 4. Push
lua push

# 5. Deploy
lua deploy
```

### Development Workflow

```bash theme={null}
# Configure environment if needed
lua env sandbox        # Add new API keys locally
lua env production     # Update production env vars

# Make changes to src/tools/*.ts

# Test your agent
lua chat  # Choose sandbox mode

# Optional: Test specific tools
lua test  # For debugging individual tools

# When satisfied, push (direct mode - faster!)
lua push skill

# Update production persona if needed
lua persona production # Or: lua push persona

# Deploy to production
lua deploy
```

### Quick Fix Workflow

```bash theme={null}
# 1. Edit file
vim src/tools/MyTool.ts

# 2. Test
lua test

# 3. Push and deploy (direct mode)
lua push skill
lua deploy
```

<Note>
  These workflows use `lua push` + `lua deploy` — the fastest path for a single primitive, and exactly how a brand-new agent's first release works. Once an agent has releases it's tracking as [agent versions](/cli/version-command), prefer `lua version create` + `lua version promote` when you want several primitives to switch together atomically. `lua deploy` still works at that point too — it performs a scoped promote under the hood — see [The release flow, end to end](/cli/version-command#the-release-flow-end-to-end).
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No lua.skill.yaml found">
    **Error**: `❌ No lua.skill.yaml found`

    **Solution**: Run command from skill directory or run `lua init` first
  </Accordion>

  <Accordion title="Version already exists">
    **Error**: `❌ Version 1.0.0 already exists on the server`

    **Solution**: Increment version in `lua.skill.yaml`:

    ```yaml theme={null}
    skills:
      - version: 1.0.1  # Increment this
    ```
  </Accordion>

  <Accordion title="Compilation failed">
    **Error**: `❌ No index.ts found`

    **Solution**: Create `src/index.ts` with skill definition:

    ```typescript theme={null}
    import { LuaSkill } from "lua-cli";
    const skill = new LuaSkill({...});
    ```
  </Accordion>

  <Accordion title="Tool validation error">
    **Error**: `❌ Tool name invalid`

    **Solution**: Tool names can only contain: `a-z`, `A-Z`, `0-9`, `-`, `_`

    ```typescript theme={null}
    // ✅ Good
    name = "get_weather"

    // ❌ Bad
    name = "get weather"  // No spaces
    ```
  </Accordion>

  <Accordion title="Missing dependencies">
    **Error**: `❌ Cannot find module 'lua-cli'`

    **Solution**: Install dependencies:

    <CodeGroup>
      ```bash npm theme={null}
      npm install
      ```

      ```bash yarn theme={null}
      yarn install
      ```

      ```bash pnpm theme={null}
      pnpm install
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Test Before Pushing">
    Always test locally first:

    ```bash theme={null}
    lua test     # Test individual tools
    lua chat     # Test conversationally
    lua push     # Then push
    ```
  </Accordion>

  <Accordion title="Use Semantic Versioning">
    * **PATCH** (1.0.1): Bug fixes
    * **MINOR** (1.1.0): New features
    * **MAJOR** (2.0.0): Breaking changes
  </Accordion>

  <Accordion title="Test in Sandbox Before Deploy">
    ```bash theme={null}
    lua push     # Upload version
    lua chat     # Test in sandbox
    # If good, then:
    lua deploy   # Deploy to production
    ```
  </Accordion>

  <Accordion title="Keep Version History">
    Don't delete old versions - they serve as rollback points
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Development Mode" icon="code" href="/cli/development">
    Learn about live development with auto-reload
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Follow a complete tutorial
  </Card>

  <Card title="Agent Versions" icon="code-branch" href="/cli/version-command">
    Snapshot and promote every primitive together, atomically
  </Card>
</CardGroup>


# Skills Command
Source: https://docs.heylua.ai/cli/skills-command

View and manage skills in sandbox and production environments

## Overview

The `lua skills` command provides a dedicated interface for viewing local skills and managing production skill deployments.

```bash theme={null}
lua skills               # Interactive: choose environment
lua skills sandbox       # Direct: view local skills
lua skills staging       # Direct: alias for sandbox
lua skills production    # Direct: manage production skills
```

<Note>
  Dedicated skills management command with environment-specific features!
</Note>

### Non-Interactive Mode

```bash theme={null}
# View local skills (sandbox)
lua skills sandbox view

# View all production skills
lua skills view

# View skill versions
lua skills versions --skill-name mySkill

# Deploy specific version
lua skills deploy --skill-name mySkill --skill-version 1.0.3

# Deploy latest version
lua skills deploy --skill-name mySkill --skill-version latest
```

<Note>
  `lua skills sandbox view` prints local skills and exits (no interactive menu) - perfect for CI/CD pipelines and automation scripts.
</Note>

| Option                  | Description                      |
| ----------------------- | -------------------------------- |
| `--skill-name <name>`   | Skill name (for versions/deploy) |
| `--skill-version <ver>` | Version or 'latest' (for deploy) |

| Environment  | Action     | Description                 | Required Options                  |
| ------------ | ---------- | --------------------------- | --------------------------------- |
| `sandbox`    | `view`     | Print local skills and exit | None                              |
| `production` | `view`     | List all production skills  | None                              |
| `production` | `versions` | View skill version history  | `--skill-name`                    |
| `production` | `deploy`   | Deploy specific version     | `--skill-name`, `--skill-version` |

<CardGroup>
  <Card title="Sandbox Mode" icon="flask">
    View local skills from lua.skill.yaml
  </Card>

  <Card title="Production Mode" icon="rocket">
    Manage deployed skills and versions
  </Card>

  <Card title="Version History" icon="clock">
    View all skill versions
  </Card>

  <Card title="Deploy Versions" icon="upload">
    Deploy specific versions to production
  </Card>
</CardGroup>

## Usage Modes

<Tabs>
  <Tab title="Interactive Mode">
    **Default behavior - prompts for environment**

    ```bash theme={null}
    $ lua skills
    ? Select environment:
      › 🔧 Sandbox (local skills)
        🚀 Production (deployed skills)
    ```

    Best for: When you're exploring or not sure which environment
  </Tab>

  <Tab title="Direct Mode - Sandbox">
    **Skip prompt and view local skills**

    ```bash theme={null}
    $ lua skills sandbox
    # No prompt - shows local skills immediately
    ```

    Best for: Quick reference during development
  </Tab>

  <Tab title="Direct Mode - Production">
    **Skip prompt and manage production skills**

    ```bash theme={null}
    $ lua skills production
    # No prompt - opens production management immediately
    ```

    Best for: Fast deployments, production management
  </Tab>
</Tabs>

## Sandbox Mode

View skills defined in your local `lua.skill.yaml` file.

```bash theme={null}
lua skills sandbox
```

### Features

<Steps>
  <Step title="View Skills">
    Display all skills from your configuration

    ```
    ============================================================
    🔧 Local Skills (Sandbox)
    ============================================================

    1. customer-service
       Version: 1.0.5
       Skill ID: skill_abc123

    2. order-management
       Version: 0.8.2
       Skill ID: skill_xyz789
    ```
  </Step>

  <Step title="Quick Actions">
    Access to common commands:

    * 📦 Compile skill
    * ☁️ Push to server
    * 🔄 Refresh list
  </Step>
</Steps>

### Example Session

```bash theme={null}
$ lua skills sandbox

============================================================
🔧 Local Skills (Sandbox)
============================================================

1. customer-service
   Version: 1.0.5
   Skill ID: skill_abc123

? What would you like to do?
  › Refresh list
    Compile skill
    Push to server
    Exit

# Select "Compile skill"
🔨 Compiling Lua skill...
✅ Skill compiled successfully - 10 tools bundled
```

### Use Cases

<AccordionGroup>
  <Accordion title="Quick Reference">
    Check skill names and IDs without opening the config file:

    ```bash theme={null}
    lua skills sandbox
    ```
  </Accordion>

  <Accordion title="Before Compiling">
    Verify your skills are correctly defined:

    ```bash theme={null}
    lua skills sandbox
    # Check versions and IDs
    lua compile
    ```
  </Accordion>

  <Accordion title="Multi-Skill Projects">
    View all skills in a multi-skill project:

    ```bash theme={null}
    lua skills sandbox
    # Shows all skills defined in lua.skill.yaml
    ```
  </Accordion>
</AccordionGroup>

## Production Mode

View deployed skills and manage production versions.

```bash theme={null}
lua skills production
```

### Features

<Steps>
  <Step title="View Deployed Skills">
    List all skills with active versions

    ```
    ============================================================
    🚀 Production Skills
    ============================================================

    1. customer-service
       Active Version: 1.0.5
       Skill ID: skill_abc123

    2. order-management
       Active Version: 0.8.2
       Skill ID: skill_xyz789
    ```
  </Step>

  <Step title="Version History">
    View complete version history for each skill

    ```
    ? Select skill: customer-service

    Version History for customer-service:
    • 1.0.5 (ACTIVE) - Created: Oct 12, 2025
    • 1.0.4 - Created: Oct 10, 2025
    • 1.0.3 - Created: Oct 5, 2025
    • 1.0.2 - Created: Oct 1, 2025
    ```
  </Step>

  <Step title="Deploy Specific Version">
    Deploy any version to production

    ```
    ? Select version to deploy: 1.0.4

    ⚠️  WARNING: You are about to deploy to PRODUCTION!
    ⚠️  This will affect ALL users immediately.

    ? Are you absolutely sure? Yes

    🔄 Deploying version 1.0.4...
    ✅ Version 1.0.4 deployed successfully
    ```
  </Step>
</Steps>

### Example Session

```bash theme={null}
$ lua skills production
✅ Authenticated

============================================================
🚀 Production Skills
============================================================

1. customer-service
   Active Version: 1.0.5
   Skill ID: skill_abc123

2. order-management
   Active Version: 0.8.2
   Skill ID: skill_xyz789

? What would you like to do?
  › View version history
    Deploy specific version
    Refresh list
    Exit

# Select "View version history"
? Select skill: customer-service

Version History for customer-service:
• 1.0.5 (ACTIVE) - Created: Oct 12, 2025 10:30 AM
• 1.0.4 - Created: Oct 10, 2025 3:45 PM
• 1.0.3 - Created: Oct 5, 2025 9:15 AM

? Select version to deploy: 1.0.4

⚠️  WARNING: You are about to deploy to PRODUCTION!
⚠️  This will affect ALL users immediately.

Current: 1.0.5
New: 1.0.4

? Are you absolutely sure you want to deploy? Yes

🔄 Deploying version 1.0.4...
✅ Version 1.0.4 deployed successfully to production
```

### Use Cases

<AccordionGroup>
  <Accordion title="Check Active Versions">
    Verify what's running in production:

    ```bash theme={null}
    lua skills production
    # See active versions at a glance
    ```
  </Accordion>

  <Accordion title="Rollback">
    Roll back to a previous version:

    ```bash theme={null}
    lua skills production
    # Select skill → View history → Deploy older version
    ```
  </Accordion>

  <Accordion title="Deploy Specific Version">
    Deploy a specific version instead of latest:

    ```bash theme={null}
    lua skills production
    # Choose exact version to deploy
    ```
  </Accordion>

  <Accordion title="Version Audit">
    Review deployment history:

    ```bash theme={null}
    lua skills production
    # View when each version was created
    ```
  </Accordion>
</AccordionGroup>

### Safety Features

<Warning>
  **Production deployments require two confirmations:**

  1. Select version to deploy
  2. Confirm deployment (defaults to "No")

  This prevents accidental deployments and ensures you're deploying the right version.
</Warning>

## Complete Workflows

### Development Workflow

```bash theme={null}
# 1. Check local skills
lua skills sandbox

# 2. Make changes to tools
vim src/tools/MyTool.ts

# 3. Compile
lua compile

# 4. Test
lua test

# 5. Push new version
lua push skill

# 6. Check production before deploying
lua skills production

# 7. Deploy
lua deploy
```

### Rollback Workflow

```bash theme={null}
# 1. Check what's deployed
lua skills production

# 2. View version history
# Select skill → View history

# 3. Deploy previous version
# Select older version → Confirm

# Done! Previous version is live
```

### Multi-Skill Management

```bash theme={null}
# View all skills
lua skills sandbox

# Work on specific skill
cd my-project
vim src/tools/CustomerServiceTool.ts

# Compile specific skill
lua compile

# Push only that skill
lua push skill

# Deploy to production
lua skills production
# Select the skill you just pushed
```

## Comparison with Other Commands

| Command                 | Purpose                           | Environment |
| ----------------------- | --------------------------------- | ----------- |
| `lua skills sandbox`    | View local skill configuration    | Local       |
| `lua skills production` | Manage deployed skills            | Server      |
| `lua compile`           | Compile skills to bundles         | Local       |
| `lua push skill`        | Upload new skill version          | Server      |
| `lua deploy`            | Deploy to production (all skills) | Server      |
| `lua production`        | View production environment       | Server      |

## Best Practices

<AccordionGroup>
  <Accordion title="Check Before Deploying">
    Always check what's currently deployed:

    ```bash theme={null}
    lua skills production
    # Review active versions
    lua deploy
    ```
  </Accordion>

  <Accordion title="Keep Version History">
    Don't delete old versions - they're your rollback points:

    ```bash theme={null}
    lua skills production
    # View history → Shows all available versions
    ```
  </Accordion>

  <Accordion title="Test in Sandbox First">
    Always test locally before pushing:

    ```bash theme={null}
    lua skills sandbox  # Verify configuration
    lua test           # Test tools
    lua chat           # Test conversationally
    lua push skill     # Then push
    ```
  </Accordion>

  <Accordion title="Document Version Changes">
    Use semantic versioning and keep notes:

    ```yaml theme={null}
    # In lua.skill.yaml
    skills:
      - name: customer-service
        version: 1.1.0  # Minor: Added FAQ tool
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No skills found in sandbox">
    **Error**: "No skills found in lua.skill.yaml"

    **Solution:**

    1. Ensure you're in a skill directory
    2. Check `lua.skill.yaml` has skills defined
    3. Run `lua compile` to populate skills
  </Accordion>

  <Accordion title="Can't see production skills">
    **Error**: "Failed to fetch production skills"

    **Solution:**

    1. Verify authentication: `lua auth key`
    2. Check network connection
    3. Ensure you've pushed at least one version
  </Accordion>

  <Accordion title="Version not showing in history">
    **Problem**: Pushed version doesn't appear

    **Solution:**

    1. Refresh the list
    2. Verify push was successful
    3. Check you're viewing correct skill
  </Accordion>

  <Accordion title="Can't deploy version">
    **Error**: "Version not found"

    **Solution:**

    1. Verify version exists: `lua skills production`
    2. Check version number matches exactly
    3. Ensure version was pushed successfully
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup>
  <Card title="lua compile" icon="gear">
    Compile skills before viewing in sandbox
  </Card>

  <Card title="lua push skill" icon="upload">
    Upload new skill versions
  </Card>

  <Card title="lua deploy" icon="rocket">
    Deploy active skill versions
  </Card>

  <Card title="lua production" icon="server">
    View overall production environment
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Skill Management" icon="wrench" href="/cli/skill-management">
    Learn about compiling and pushing skills
  </Card>

  <Card title="Production Command" icon="server" href="/cli/production-command">
    Comprehensive production management
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Complete skill development tutorial
  </Card>

  <Card title="Multi-Skill Projects" icon="layer-group" href="/template/multi-skill-projects">
    Managing multiple skills
  </Card>
</CardGroup>


# Source Command
Source: https://docs.heylua.ai/cli/source-command

Inspect and roll back your agent's workspace source version history

## Overview

`lua source` manages your agent's workspace backup version history. Every `lua push` records the canonical state of your project. `lua source list` shows the version timeline. For rollback, prefer [`lua version promote`](/cli/version-command) — instant and atomic, no re-upload; `lua source rollback` (deprecated) remains available for restoring past source files into your workspace.

```bash theme={null}
lua source list                          # Recent 50 versions, active marked with *
lua source list --all                    # Full history
lua source rollback --version 5          # Restore v5 (with confirmation)
lua source rollback --version 5 --force  # Restore v5 (no prompt)
```

## Subcommands

### `lua source list`

Prints a table of source versions for the current agent, with the active version starred.

| Option        | Description                                      |
| ------------- | ------------------------------------------------ |
| `--all`       | Show all versions instead of the most recent 50. |
| `--limit <n>` | Cap output at `n` versions. Default: `50`.       |

```bash theme={null}
lua source list                # most recent 50
lua source list --all          # full history
lua source list --limit 10     # cap at 10
```

### `lua source rollback`

<Warning>
  **Deprecated for rollback.** With agent versioning, use [`lua version promote <version>`](/cli/version-command) instead — it swaps the live agent state instantly without re-uploading files. `lua source rollback` still works for restoring past *source files* into your workspace.
</Warning>

Downloads a past version's files into your local workspace, then auto-pushes the rolled-back state as the next version.

| Option          | Description                                   |
| --------------- | --------------------------------------------- |
| `--version <n>` | **Required.** Version number to roll back to. |
| `--force`       | Skip the confirmation prompt.                 |

```bash theme={null}
lua source rollback --version 5
lua source rollback --version 5 --force
```

## How Rollback Works

History is **append-only**. Rolling back to v5 does **not** overwrite v5 — instead:

1. The CLI downloads v5's files into your local workspace.
2. It then auto-pushes the rolled-back state, creating v(latest+1) with the same contents as v5.

You end up with an explicit new version at the head that represents "we returned to v5 on this date." The original v5 is preserved verbatim. This makes rollbacks safe — you can always roll back from your rollback.

```
Before: v1, v2, v3, v4, v5 (active)
        ↓ lua source rollback --version 2
After:  v1, v2, v3, v4, v5, v6 (active, contents = v2)
```

## When to Use

* **Recover from a bad push.** Prefer `lua version promote <last-good>` (instant). Use `lua source rollback --version <n>` only when you need the actual source files back in your workspace.
* **Compare past versions.** `lua source list --all` shows the timeline; pair with the [admin dashboard](/cli/utility-commands#admin) to diff.
* **Cross-machine recovery.** Lost your local workspace? `lua init --agent-id <id> --restore-sources` pulls the active version. Use `lua source rollback` to retrieve any other version.

<Warning>
  Rollback **overwrites your local workspace** with the chosen version's contents. If you have local edits you haven't pushed, push them first (or back them up) before rolling back.
</Warning>

## Common Workflow

```bash theme={null}
# Something is wrong in production — what changed recently?
lua source list

# Roll back to a known-good version
lua source rollback --version 12

# After investigation, re-apply your fix and push forward
# (the rollback created v13; your fix will push as v14)
lua push all --force
```

## Related

* [Push Command](/cli/skill-management#lua-push) — every `push` creates a new version
* [Sync Command](/cli/sync-command) — `lua sync --pull` restores the active version
* [Init Command](/cli/skill-management#lua-init) — `--restore-sources` pulls the active version on first init


# Sync Command
Source: https://docs.heylua.ai/cli/sync-command

Detect and resolve drift between server state and local code

## Overview

The `lua sync` command detects differences (drift) between your server-deployed configuration and local code, helping you keep them in sync.

```bash theme={null}
lua sync
```

<Note>
  The sync command helps prevent accidental overwrites when someone updates the agent from the admin dashboard while you're working locally.
</Note>

## What Gets Synced

| Component   | Description                                             |
| ----------- | ------------------------------------------------------- |
| **Name**    | Agent name defined in `LuaAgent({ name: "..." })`       |
| **Persona** | Agent persona defined in `LuaAgent({ persona: "..." })` |

## How It Works

1. **Compiles code** - Ensures manifest is fresh (runs `lua compile` internally)
2. **Fetches server state** - Gets the latest published persona and agent name from the server
3. **Compares with local** - Checks your compiled manifest against server state
4. **Shows colored diff** - Displays exactly what changed
5. **Prompts for action** - Update local from server or keep local

<Note>
  Sync now compiles before checking drift to ensure accurate comparison with the latest local changes.
</Note>

## Usage

### Interactive Sync

```bash theme={null}
lua sync
```

If drift is detected, you'll see a colored diff:

```
============================================================
PERSONA DIFF
- Server (deployed)  + Local (code)
============================================================

  <persona>
    <identity>
-     Old Agent Name
+     New Agent Name
    </identity>
  ... (unchanged lines) ...

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

? What would you like to do with persona?
❯ 📤 Push local to server
  📥 Pull server to local
  ⏭️  Skip
```

**Diff colors:**

* 🔴 **Red** (`-`) = Line exists on server but not in local code
* 🟢 **Green** (`+`) = Line exists in local code but not on server
* Gray = Unchanged lines (abbreviated if many)

### During Compile

Sync is **opt-in** during `lua compile`. By default, drift detection is **disabled** for faster compilation:

```bash theme={null}
lua compile        # Default: no drift check (fast)
lua compile --sync # Enable drift detection (checks before compiling)
```

This opt-in behavior is ideal for faster development iterations. Use `--sync` when you need to ensure alignment with the server.

## Options

### Sync Command Options

| Flag       | Description                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------- |
| `--check`  | Check for drift only, exit code 1 if drift found (CI validation)                                                |
| `--pull`   | Pull server state to local without prompting. Source files are restored from the snapshot.                      |
| `--accept` | Deprecated alias for `--pull` — kept for backwards compatibility. New scripts should use `--pull`.              |
| `--push`   | Push local changes to server without prompting                                                                  |
| `--force`  | Skip the local-changes conflict check (use with `--pull` / `--accept`). Destructive — overwrites local changes. |

### Compile Integration

| Flag        | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `--sync`    | Enable drift detection during compile (checks before compiling) |
| `--verbose` | Show detailed compilation output                                |

### Non-Interactive Mode

```bash theme={null}
# Check for drift only (returns exit code 1 if drift detected)
lua sync --check

# Pull server state to local without prompting
lua sync --pull

# Pull and bypass the local-changes conflict guard (destructive)
lua sync --pull --force

# Auto-push local changes to server without prompting
lua sync --push
```

### Examples

```bash theme={null}
# Check for drift interactively
lua sync

# Check only, fail if drift (for CI)
lua sync --check

# Pull server state to local
lua sync --pull

# Auto-push local changes to server
lua sync --push

# Compile with sync check (opt-in)
lua compile --sync
```

### CI/CD Workflow Example

```yaml theme={null}
# GitHub Actions example
name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check for drift
        run: lua sync --check
      
      - name: Compile
        run: lua compile
      
      - name: Push version
        run: lua push skill --name mySkill --set-version ${{ github.sha }} --force
      
      - name: Deploy to production
        run: lua deploy --skill-name mySkill --skill-version latest --force
```

## Common Scenarios

### Scenario 1: Someone Updated Persona in Dashboard

You're developing locally, and a colleague updated the persona from the admin dashboard.

```bash theme={null}
$ lua sync
⚠️  Drift detected!

============================================================
PERSONA DIFF
- Server (deployed)  + Local (code)
============================================================

  <persona>
-   Updated persona from dashboard
+   Your local persona version
  </persona>

? What would you like to do with persona?
  📤 Push local to server   # Overwrite server with your version
❯ 📥 Pull server to local   # Get their changes
  ⏭️  Skip                  # No changes
```

### Scenario 2: Forgot to Push Changes

You made changes locally but forgot to push before reverting your code.

```bash theme={null}
$ lua sync
✅ No drift detected. Local code is in sync with server.
```

### Scenario 3: CI/CD Pipeline

In your deployment pipeline, you might want to ensure no drift or push local as source of truth:

```bash theme={null}
# Compile only (default - no drift check)
lua compile

# Compile with drift check
lua compile --sync

# Or push local changes to server before compile
lua sync --push && lua compile
```

## Best Practices

<AccordionGroup>
  <Accordion title="Run sync before starting work">
    Always run `lua sync` when starting a new session to catch any changes made by teammates or from the dashboard.

    ```bash theme={null}
    cd my-agent
    lua sync           # Check for drift
    lua compile        # Start development
    ```
  </Accordion>

  <Accordion title="Use sync --accept for fresh pulls">
    When you want to ensure you have the latest server state:

    ```bash theme={null}
    lua sync --accept
    ```

    This automatically updates your local code from the server without prompting.
  </Accordion>

  <Accordion title="Fast CI/CD builds">
    In automated pipelines, compile runs without drift check by default (fast):

    ```bash theme={null}
    lua compile && lua push skill
    ```

    Add `--sync` only if you need to validate against server state first.
  </Accordion>

  <Accordion title="Commit after syncing">
    After syncing from server, commit the changes to preserve them:

    ```bash theme={null}
    lua sync
    # Select "Update local from server"
    git add src/index.ts
    git commit -m "sync: update persona from server"
    ```
  </Accordion>
</AccordionGroup>

## How Server Versions Work

The sync command compares against the **latest published** persona version, not the currently active one:

| Version Type  | Description                     | Used for Sync? |
| ------------- | ------------------------------- | -------------- |
| **Draft**     | Created but not deployed        | ❌ No           |
| **Published** | Has been deployed at least once | ✅ Yes (latest) |
| **Current**   | Currently active in production  | ❌ No           |

This means if you roll back to an older version in production, sync will still compare against the most recent push (not the rollback).

## Error Handling

<AccordionGroup>
  <Accordion title="No drift detected">
    ```
    ✅ No drift detected. Local code is in sync with server.
    ```

    Your local code matches the server. No action needed.
  </Accordion>

  <Accordion title="Network error">
    If the server is unreachable, sync will silently continue to avoid blocking your workflow.
  </Accordion>

  <Accordion title="No persona on server">
    If no persona has been pushed to the server yet, sync will report no drift.
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup>
  <Card title="lua compile" icon="hammer" href="/cli/skill-management#compile">
    Compile with optional sync check
  </Card>

  <Card title="lua push persona" icon="upload" href="/cli/skill-management#push">
    Push persona to server
  </Card>

  <Card title="lua persona" icon="user" href="/cli/persona-command">
    Manage persona in sandbox/production
  </Card>
</CardGroup>


# Triggers Command
Source: https://docs.heylua.ai/cli/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


# Troubleshooting
Source: https://docs.heylua.ai/cli/troubleshooting

Common issues and solutions for Lua CLI

## Common Errors

### Authentication Errors

<AccordionGroup>
  <Accordion title="No authentication found">
    **Error:**

    ```
    ❌ No Lua CLI authentication found. Run `lua auth configure` or set `LUA_API_KEY`.
    ```

    **Cause**: You haven't set up authentication yet.

    **Solution**:

    ```bash theme={null}
    lua auth configure
    ```

    Choose **Email** to sign in with a renewable session, or choose **API Key** to save an existing scoped or legacy key unchanged.
  </Accordion>

  <Accordion title="Invalid API key">
    **Error:**

    ```
    ❌ API key validation failed
    ```

    **Causes**:

    * Key was revoked
    * Key was copied incorrectly
    * Extra spaces in key

    **Solutions**:

    1. Verify you copied the complete key
    2. Remove any extra spaces
    3. Open the Lua dashboard, then create a replacement under **Settings → API Keys**:
       ```bash theme={null}
       lua admin
       ```
  </Accordion>

  <Accordion title="OTP not received">
    **Problem**: Email OTP code not received

    **Solutions**:

    1. Check spam/junk folder
    2. Wait 5 minutes (can be delayed)
    3. Try again with `lua auth configure`
    4. Use API Key method if available
  </Accordion>
</AccordionGroup>

### Project Initialization Errors

<AccordionGroup>
  <Accordion title="No lua.skill.yaml found">
    **Error:**

    ```
    ❌ No lua.skill.yaml found. Please run this command from a skill directory.
    ```

    **Cause**: You're not in a skill project directory.

    **Solution**:

    1. Navigate to your skill directory:
       ```bash theme={null}
       cd my-skill
       ```
    2. Or initialize a new project:
       ```bash theme={null}
       lua init
       ```
  </Accordion>

  <Accordion title="Directory not empty">
    **Error:**

    ```
    ❌ Directory is not empty. Please use an empty directory.
    ```

    **Cause**: `lua init` requires an empty directory.

    **Solution**:

    ```bash theme={null}
    mkdir my-new-skill
    cd my-new-skill
    lua init
    ```
  </Accordion>

  <Accordion title="Permission denied">
    **Error:**

    ```
    EACCES: permission denied
    ```

    **Solutions**:

    * Check directory permissions
    * Don't use sudo (creates permission issues later)
    * Use a directory you own:
      ```bash theme={null}
      cd ~/projects
      mkdir my-skill
      cd my-skill
      lua init
      ```
  </Accordion>
</AccordionGroup>

### Compilation Errors

<AccordionGroup>
  <Accordion title="No index.ts found">
    **Error:**

    ```
    ❌ No index.ts found in current directory or src/ directory
    ```

    **Cause**: Missing main skill file.

    **Solution**: Create `src/index.ts`:

    ```typescript theme={null}
    import { LuaSkill } from "lua-cli";

    const skill = new LuaSkill({
      name: "my-skill",
      description: "My skill description",
      context: "How to use this skill",
      tools: []
    });
    ```
  </Accordion>

  <Accordion title="TypeScript compilation error">
    **Error:**

    ```
    ❌ Compilation failed:
    src/tools/MyTool.ts:10:5 - error TS2322: Type 'string' is not assignable to type 'number'.
    ```

    **Cause**: TypeScript type error in your code.

    **Solution**: Fix the specific error mentioned:

    ```typescript theme={null}
    // Error at line 10
    const age: number = "25";  // ❌ Wrong type
    const age: number = 25;    // ✅ Correct
    ```
  </Accordion>

  <Accordion title="Cannot find module">
    **Error:**

    ```
    ❌ Cannot find module 'lua-cli'
    ```

    **Cause**: Dependencies not installed.

    **Solution**:

    <CodeGroup>
      ```bash npm theme={null}
      npm install
      ```

      ```bash yarn theme={null}
      yarn install
      ```

      ```bash pnpm theme={null}
      pnpm install
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Tool name invalid">
    **Error:**

    ```
    ❌ Tool names can only contain alphanumeric characters, hyphens (-), and underscores (_).
    ```

    **Cause**: Tool name contains invalid characters.

    **Solution**: Fix tool name:

    ```typescript theme={null}
    // ❌ Invalid
    name = "get weather";    // Spaces
    name = "get.weather";    // Dots
    name = "get@weather";    // Special chars

    // ✅ Valid
    name = "get_weather";
    name = "get-weather";
    name = "getWeather";
    ```
  </Accordion>
</AccordionGroup>

### Version Management Errors

<AccordionGroup>
  <Accordion title="Version already exists">
    **Error:**

    ```
    ❌ Version 1.0.0 already exists on the server
    ```

    **Cause**: You've already pushed this version number.

    **Solution**: Increment the version number in `lua.skill.yaml` (this is the only field you should manually edit):

    ```yaml theme={null}
    skills:
      - name: my-skill
        version: 1.0.1  # Increment this
    ```

    Then push again:

    ```bash theme={null}
    lua push
    ```
  </Accordion>

  <Accordion title="Version mismatch">
    **Error:**

    ```
    ❌ Version mismatch: config has 1.0.1, deploy.json has 1.0.0
    ```

    **Cause**: Changed version but didn't recompile.

    **Solution**: Recompile after version change:

    ```bash theme={null}
    lua compile
    lua push
    ```
  </Accordion>
</AccordionGroup>

### Sync Errors

<AccordionGroup>
  <Accordion title="Drift detected during compile">
    **Message:**

    ```
    ⚠️  Drift detected in: name, persona
    ```

    **Cause**: Server has different agent configuration than your local code. This happens when someone updates the agent from the admin dashboard.

    **Solutions**:

    1. **Run sync**: Use `lua sync` to review and resolve drift interactively
    2. **Auto-accept**: Use `lua sync --accept` to automatically update local from server
    3. **Auto-push**: Use `lua sync --push` to push local changes to server

    **Note**: By default, `lua compile` does NOT check for drift. Use `lua compile --sync` to enable drift detection during compilation.

    **To see the diff**:

    ```bash theme={null}
    lua sync
    ```
  </Accordion>

  <Accordion title="No persona in local code">
    **Message:**

    ```
    💻 Local (code):
    (no persona in code)
    ```

    **Cause**: The `LuaAgent` configuration is missing or has an empty name.

    **Solutions**:

    1. Ensure your `src/index.ts` has a valid LuaAgent:
       ```typescript theme={null}
       const agent = new LuaAgent({
         name: "my-agent",  // Must not be empty!
         persona: "...",
         // ...
       });
       ```
    2. Check for TypeScript compilation errors
  </Accordion>

  <Accordion title="Network error during sync">
    **Problem**: Sync silently fails or shows no drift when there should be.

    **Cause**: Network issues when fetching server state.

    **Solutions**:

    1. Check internet connection
    2. Verify API key is valid: `lua auth key`
    3. Try again: `lua sync`
  </Accordion>
</AccordionGroup>

### Dev Mode Errors

<AccordionGroup>
  <Accordion title="Port already in use">
    **Error:**

    ```
    ❌ EADDRINUSE: address already in use :::3000
    ```

    **Cause**: Port 3000 is being used by another process.

    **Solutions**:

    1. Stop the other process
    2. Or kill process on port 3000:
       ```bash theme={null}
       # macOS/Linux
       lsof -ti:3000 | xargs kill -9

       # Windows
       netstat -ano | findstr :3000
       taskkill /PID <PID> /F
       ```
  </Accordion>

  <Accordion title="Skill not found in sandbox">
    **Error:**

    ```
    💡 The skill doesn't exist on the server.
    Please run "lua push" first to deploy your skill.
    ```

    **Cause**: Skill hasn't been pushed to server yet.

    **Solution**:

    ```bash theme={null}
    lua push  # Push first
    lua chat  # Then test in sandbox mode
    ```
  </Accordion>

  <Accordion title="Changes not reflected in chat">
    **Problem**: Local changes not showing in sandbox mode.

    **Solutions**:

    1. Verify file is in `src/` directory
    2. Check file is actually saved
    3. Ensure you selected "Sandbox" mode in `lua chat`
    4. Check for compilation errors
    5. Try again:
       ```bash theme={null}
       lua chat  # Will recompile and push to sandbox
       ```
  </Accordion>
</AccordionGroup>

### Deployment Errors

<AccordionGroup>
  <Accordion title="No versions available">
    **Error:**

    ```
    ❌ No versions available to deploy
    ```

    **Cause**: You haven't pushed any versions yet.

    **Solution**:

    ```bash theme={null}
    lua push  # Push a version first
    lua deploy
    ```
  </Accordion>

  <Accordion title="Deploy failed">
    **Error:**

    ```
    ❌ Deployment failed: [error message]
    ```

    **Solutions**:

    1. Check API key is valid
    2. Verify you have deploy permissions
    3. Check network connection
    4. Try again - might be temporary server issue
  </Accordion>
</AccordionGroup>

## Debugging Skills at Runtime

When your tool returns unexpected data or you're unsure why a skill is behaving incorrectly, use this workflow.

<AccordionGroup>
  <Accordion title="Tool returns unexpected shape or undefined fields">
    **Symptoms:**

    * Field is `undefined` when you expected a value
    * `results.data` is undefined
    * `results.count` is undefined
    * Properties like `entry.title` return undefined

    **The fix — log before you transform:**

    ```typescript theme={null}
    async execute(input: any) {
      const results = await Data.search('articles', input.query);
      
      // Add this FIRST, before any mapping
      console.log('Raw result:', JSON.stringify(results, null, 2));
      
      // Then push and check logs:
      // lua logs --type skill --limit 5
    }
    ```

    **Common causes:**

    * Using `results.data` after `Data.search` — search returns a flat array, not `{ data: [...] }`
    * Using `results.count` after `Data.search` — use `results.length`
    * Using `entry.title` after `Data.get` — get entries are not proxied, use `entry.data.title`
    * Using `results.data` after `Products.search` — use `results.products` or iterate directly

    See the [Return Shape Reference](/api/data#return-shape-reference) and [Debugging guide](/cli/debugging).
  </Accordion>

  <Accordion title="5-step debug loop">
    1. Add `console.log('result:', JSON.stringify(result, null, 2))` to the suspicious spot
    2. Run `lua push` (or use `lua chat` sandbox mode without pushing)
    3. Send ONE test message: `lua chat -m "your test query"`
    4. Run `lua logs --type skill --limit 10` — find your log entry
    5. Read the actual shape, fix code once, verify

    **Don't deploy 5 times trying to patch blind.** Log first, deploy once.

    [Full debugging guide →](/cli/debugging)
  </Accordion>

  <Accordion title="How to check logs for a specific tool">
    ```bash theme={null}
    # All skill logs (most recent)
    lua logs --type skill --limit 20

    # Filter to a specific skill
    lua logs --type skill --name my-skill-name --limit 10

    # JSON output (for parsing)
    lua logs --type skill --json

    # Other component types
    lua logs --type job --name daily-report --limit 5
    lua logs --type webhook --name stripe --limit 10
    lua logs --type preprocessor --limit 20
    ```

    Your `console.log()` output appears in the log message body under `🔍 DEBUG` entries.
  </Accordion>
</AccordionGroup>

## Platform-Specific Issues

### macOS

<AccordionGroup>
  <Accordion title="Command not found: lua">
    **Cause**: CLI not in PATH

    **Solutions**:

    1. Reinstall globally:
       ```bash theme={null}
       npm install -g lua-cli
       ```
    2. Or use npx:
       ```bash theme={null}
       npx lua-cli [command]
       ```
  </Accordion>
</AccordionGroup>

### Windows

<AccordionGroup>
  <Accordion title="PowerShell execution policy">
    **Error**: Script execution disabled

    **Solution**: Enable script execution:

    ```powershell theme={null}
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```
  </Accordion>

  <Accordion title="Path too long">
    **Error**: `ENAMETOOLONG`

    **Solution**: Use shorter directory paths:

    ```bash theme={null}
    # Instead of
    C:\Users\YourName\Documents\Projects\MyCompany\Skills\my-skill

    # Use
    C:\projects\my-skill
    ```
  </Accordion>
</AccordionGroup>

### Linux

<AccordionGroup>
  <Accordion title="EACCES: permission denied">
    **Error**: Permission denied on global install

    **Solution**: Configure npm to install globally without sudo:

    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
    source ~/.bashrc
    npm install -g lua-cli
    ```
  </Accordion>
</AccordionGroup>

## Node.js Issues

<AccordionGroup>
  <Accordion title="Node version too old">
    **Error**: Requires Node.js >= 16.0.0

    **Solution**: Update Node.js:

    1. Visit [https://nodejs.org](https://nodejs.org)
    2. Download LTS version
    3. Or use nvm:
       ```bash theme={null}
       nvm install --lts
       nvm use --lts
       ```
  </Accordion>

  <Accordion title="npm WARN deprecated">
    **Warning**: Package deprecated warnings

    **Solution**: Usually safe to ignore deprecated warnings from dependencies. Update if issues occur:

    ```bash theme={null}
    npm update
    ```
  </Accordion>

  <Accordion title="Dependency conflicts">
    **Error**: Conflicting peer dependencies

    **Solution**: Clear cache and reinstall:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>
</AccordionGroup>

## Network Issues

<AccordionGroup>
  <Accordion title="Connection timeout">
    **Error**: `ETIMEDOUT` or `ECONNREFUSED`

    **Solutions**:

    1. Check internet connection
    2. Check if behind firewall/proxy
    3. Try again - might be temporary
    4. Check server status
  </Accordion>

  <Accordion title="SSL certificate error">
    **Error**: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`

    **Solutions**:

    1. Check system date/time is correct
    2. Update CA certificates
    3. If behind corporate proxy, may need proxy config
  </Accordion>

  <Accordion title="Corporate proxy">
    **Problem**: Behind corporate proxy

    **Solution**: Configure npm proxy:

    ```bash theme={null}
    npm config set proxy http://proxy.company.com:8080
    npm config set https-proxy http://proxy.company.com:8080
    ```
  </Accordion>
</AccordionGroup>

## Environment Variable Issues

<AccordionGroup>
  <Accordion title="Variable not found">
    **Problem**: `env('MY_VAR')` returns undefined

    **Solutions**:

    1. Check spelling in `.env` file:
       ```bash theme={null}
       # .env
       MY_VAR=value  # Correct spelling
       ```
    2. Ensure `.env` is in project root
    3. Restart command (variables loaded at startup)
    4. Check `lua.skill.yaml`:
       ```yaml theme={null}
       skill:
         env:
           MY_VAR: value
       ```
  </Accordion>

  <Accordion title="Changes not taking effect">
    **Problem**: Updated `.env` but changes not visible

    **Solution**: Restart the CLI command:

    ```bash theme={null}
    # Stop current process (Ctrl+C)
    lua chat  # Start again
    ```

    Or manage variables with:

    ```bash theme={null}
    lua env
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

### Diagnostic Information

When reporting issues, include:

```bash theme={null}
# CLI version
lua --version

# Node version
node --version

# npm version
npm --version

# Operating system
uname -a  # macOS/Linux
ver       # Windows

# Error message
# Copy full error from terminal
```

### Support Channels

<CardGroup>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Get real-time help from the community
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Search these docs first
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@lua.ai">
    Contact support team
  </Card>
</CardGroup>

## Prevention Tips

<AccordionGroup>
  <Accordion title="Keep CLI Updated">
    ```bash theme={null}
    npm update -g lua-cli
    ```

    Or check current version:

    ```bash theme={null}
    lua --version
    ```
  </Accordion>

  <Accordion title="Commit lua.skill.yaml">
    Always commit `lua.skill.yaml` to git:

    ```bash theme={null}
    git add lua.skill.yaml
    git commit -m "Update skill config"
    ```
  </Accordion>

  <Accordion title="Don't Commit .env">
    Add to `.gitignore`:

    ```
    .env
    .env.local
    ```
  </Accordion>

  <Accordion title="Test Before Deploy">
    Always test locally:

    ```bash theme={null}
    lua chat  # Test conversationally (sandbox mode)
    lua test  # Optional: Test specific tools
    lua push  # Push when ready
    lua deploy  # Deploy to production
    ```
  </Accordion>
</AccordionGroup>

## Still Having Issues?

If your issue isn't covered here:

1. **Ask on Discord**: Get real-time help from the community
2. **Email Support**: For urgent issues or account problems

<CardGroup>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Join other Lua builders for real-time help
  </Card>

  <Card title="Contact Support" icon="life-ring" href="mailto:support@lua.ai">
    [support@lua.ai](mailto:support@lua.ai) - We're here to help!
  </Card>
</CardGroup>


# Utility Commands
Source: https://docs.heylua.ai/cli/utility-commands

Quick access commands for admin interface and documentation

## Overview

Utility commands provide quick access to the Lua Admin interface, documentation, shell autocomplete setup, and telemetry settings.

<CardGroup>
  <Card title="lua status" icon="circle-check">
    Full agent state at a glance
  </Card>

  <Card title="lua agents" icon="users">
    List organizations and agents
  </Card>

  <Card title="lua completion" icon="terminal">
    Generate shell autocomplete
  </Card>

  <Card title="lua admin" icon="gauge">
    Open admin dashboard
  </Card>

  <Card title="lua evals" icon="chart-bar">
    Open evaluations dashboard
  </Card>

  <Card title="lua docs" icon="book">
    Open documentation
  </Card>

  <Card title="lua telemetry" icon="chart-mixed">
    Manage usage telemetry
  </Card>

  <Card title="lua models" icon="brain">
    List and select the LLM your agent uses
  </Card>

  <Card title="lua governance" icon="shield-check">
    Manage governance policies for your agent
  </Card>

  <Card title="lua update" icon="arrow-rotate-right">
    Update lua-cli to the latest version
  </Card>
</CardGroup>

## lua status / lua describe

<Note>
  Inspect the full state of your agent project in a single command.
</Note>

`lua status` (alias: `lua describe`) shows a comprehensive snapshot of your agent: environment info, authentication, project config, per-primitive sync state, persona drift, backup status, telemetry, and actionable next steps.

```bash theme={null}
lua status           # human-readable table
lua describe         # identical output via alias
lua status --json    # machine-readable JSON for scripting
```

### What It Shows

**Environment**

* CLI version and update availability
* Node.js version, OS, install method (npm, pnpm, nvm, npx, local)
* API base URL and any overriding env vars (`LUA_API_URL`, `LUA_API_KEY`, `LUA_NO_HINTS`, etc.)

**Auth**

* API key source (env var / credentials file / .env)
* Authenticated email, user ID, and organization list
* Server reachability status

**Project**

* Config path (`lua.skill.yaml`)
* Agent name and ID
* Compiled manifest — how many primitives were found in the last compile

**Primitives Sync Table**
For each primitive type (skills, webhooks, jobs, preprocessors, postprocessors, MCP servers, devices, device triggers), shows:

* Local version (from YAML)
* Server version (active)
* Sync status: `synced`, `ahead`, `behind`, `not deployed`, or `server only`

**Persona / Backup / Telemetry**
Quick status indicators with a hint if action is needed.

**Next Steps**
Actionable hints based on current state (e.g. `lua push backup` if backup is out of sync).

### JSON Output

The `--json` flag emits a stable JSON document intended for LLM agents, CI dashboards, and scripting:

```bash theme={null}
lua status --json | jq '.auth.email'
lua status --json | jq '.primitives[] | select(.kind == "skill") | .diffs'
```

The schema is versioned (`schemaVersion: 1`) so consumers can detect breaking changes. All human-readable progress output is suppressed in JSON mode.

## lua agents

<Note>
  List all organizations and agents you have access to for discovery and scripting.
</Note>

View all organizations and agents accessible with your API key. Useful for automation, team management, and discovering available agents.

```bash theme={null}
lua agents           # List all accessible agents
lua agents --json    # JSON output for scripting
```

### What It Shows

The command displays all organizations you're a member of and their associated agents:

**Organization Information:**

* Organization ID
* Organization name
* Your role (owner, admin, developer)

**Agent Information:**

* Agent ID
* Agent name
* Environment (production/staging/sandbox)
* Status (active/inactive)

### Example Output

<Tabs>
  <Tab title="Interactive">
    ```bash theme={null}
    $ lua agents

    ✅ Found 2 organizations with 4 agents

    Organization: My Company (org_abc123)
    Role: Owner
    ├── Customer Support Bot (agent_xyz789)
    │   Environment: Production
    │   Status: Active
    ├── Sales Assistant (agent_def456)
    │   Environment: Production
    │   Status: Active

    Organization: Test Workspace (org_test999)
    Role: Developer
    ├── Dev Bot (agent_dev111)
    │   Environment: Staging
    │   Status: Active
    └── Experimental Agent (agent_exp222)
        Environment: Sandbox
        Status: Inactive
    ```
  </Tab>

  <Tab title="JSON Output">
    ```bash theme={null}
    $ lua agents --json
    ```

    ```json theme={null}
    {
      "success": true,
      "organizations": [
        {
          "orgId": "org_abc123",
          "orgName": "My Company",
          "role": "owner",
          "agents": [
            {
              "agentId": "agent_xyz789",
              "agentName": "Customer Support Bot",
              "environment": "production",
              "status": "active",
              "createdAt": "2025-01-15T10:30:00Z",
              "lastUpdated": "2025-01-20T14:22:00Z"
            },
            {
              "agentId": "agent_def456",
              "agentName": "Sales Assistant",
              "environment": "production",
              "status": "active",
              "createdAt": "2025-01-18T09:15:00Z",
              "lastUpdated": "2025-01-21T16:45:00Z"
            }
          ]
        },
        {
          "orgId": "org_test999",
          "orgName": "Test Workspace",
          "role": "developer",
          "agents": [
            {
              "agentId": "agent_dev111",
              "agentName": "Dev Bot",
              "environment": "staging",
              "status": "active",
              "createdAt": "2025-01-10T12:00:00Z",
              "lastUpdated": "2025-01-19T11:30:00Z"
            },
            {
              "agentId": "agent_exp222",
              "agentName": "Experimental Agent",
              "environment": "sandbox",
              "status": "inactive",
              "createdAt": "2025-01-12T15:20:00Z",
              "lastUpdated": "2025-01-14T10:10:00Z"
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### Options

| Option   | Description                             |
| -------- | --------------------------------------- |
| `--json` | Output as JSON for programmatic parsing |

### Use Cases

<AccordionGroup>
  <Accordion title="Discover Available Agents">
    **Find agent IDs for `lua init` or scripts:**

    ```bash theme={null}
    $ lua agents
    # Copy agent ID for initialization

    $ lua init --agent-id agent_xyz789
    ```

    Quickly find the correct agent ID without going to admin dashboard.
  </Accordion>

  <Accordion title="Team Management">
    **See what agents team members have access to:**

    ```bash theme={null}
    $ lua agents
    # Review all accessible agents
    # Verify permissions are correct
    # Check which agents are active
    ```

    Audit team access and agent organization.
  </Accordion>

  <Accordion title="Automation & Scripting">
    **Parse JSON to automate agent operations:**

    ```bash theme={null}
    # Get all production agents
    lua agents --json | jq '.organizations[].agents[] | select(.environment == "production")'

    # Count total agents
    lua agents --json | jq '[.organizations[].agents[]] | length'

    # Find agent by name
    lua agents --json | jq '.organizations[].agents[] | select(.agentName == "Sales Assistant")'

    # List all agent IDs
    lua agents --json | jq -r '.organizations[].agents[].agentId'
    ```

    Build automation tools and monitoring scripts.
  </Accordion>

  <Accordion title="Environment Discovery">
    **Identify staging/sandbox agents for testing:**

    ```bash theme={null}
    # Find all staging agents
    lua agents --json | jq '.organizations[].agents[] | select(.environment == "staging")'

    # Check for inactive agents
    lua agents --json | jq '.organizations[].agents[] | select(.status == "inactive")'
    ```

    Manage different environments effectively.
  </Accordion>

  <Accordion title="CI/CD Integration">
    **Validate agent access in pipelines:**

    ```bash theme={null}
    #!/bin/bash
    # Verify agent exists before deployment

    AGENT_ID="agent_xyz789"
    AGENTS_JSON=$(lua agents --json)

    if echo "$AGENTS_JSON" | jq -e ".organizations[].agents[] | select(.agentId == \"$AGENT_ID\")" > /dev/null; then
      echo "✅ Agent found - proceeding with deployment"
      lua push all --force --auto-deploy
    else
      echo "❌ Agent not accessible - check API key permissions"
      exit 1
    fi
    ```

    Validate environment before deploying.
  </Accordion>

  <Accordion title="Multi-Agent Workflows">
    **Deploy to multiple agents programmatically:**

    ```bash theme={null}
    # Deploy to all production agents
    for agent_id in $(lua agents --json | jq -r '.organizations[].agents[] | select(.environment == "production") | .agentId'); do
      echo "Deploying to $agent_id"
      cd "/path/to/project/$agent_id"
      lua push all --force --auto-deploy
    done
    ```

    Automate multi-agent deployments.
  </Accordion>
</AccordionGroup>

### JSON Parsing Examples

**Extract specific information:**

```bash theme={null}
# Get organization names
lua agents --json | jq -r '.organizations[].orgName'

# Get agents in specific org
lua agents --json | jq '.organizations[] | select(.orgName == "My Company") | .agents'

# Count agents per organization
lua agents --json | jq '.organizations[] | {org: .orgName, count: (.agents | length)}'

# Find your role in each organization
lua agents --json | jq '.organizations[] | {org: .orgName, role: .role}'

# List active production agents with details
lua agents --json | jq '.organizations[].agents[] | select(.status == "active" and .environment == "production") | {name: .agentName, id: .agentId}'
```

### Requirements

* Must be authenticated (`lua auth configure`)
* API key must have valid permissions

### Troubleshooting

<AccordionGroup>
  <Accordion title="No organizations found">
    **Check:**

    1. Verify authentication: `lua auth key --force`
    2. Ensure API key has permissions
    3. Check if you're a member of any organizations

    **Error:** "No organizations accessible"

    ```bash theme={null}
    # Re-authenticate
    $ lua auth configure
    # Ask organization owner to add you
    ```
  </Accordion>

  <Accordion title="Missing expected agents">
    **Check:**

    1. Verify agent exists in admin dashboard
    2. Ensure you have access to the agent's organization
    3. Check if agent was recently created (may take a moment)

    **Solution:**

    ```bash theme={null}
    # Refresh by re-running
    $ lua agents
    ```
  </Accordion>

  <Accordion title="JSON parsing errors">
    **Ensure jq is installed:**

    ```bash theme={null}
    # macOS
    brew install jq

    # Ubuntu/Debian
    apt-get install jq

    # Test
    echo '{"test": true}' | jq '.'
    ```
  </Accordion>
</AccordionGroup>

### Integration with Other Commands

```bash theme={null}
# Discover agent → Initialize project → Deploy
lua agents                              # Find agent ID
lua init --agent-id agent_xyz789        # Initialize
lua push all --force --auto-deploy      # Deploy

# List agents → Select one → Check production state
lua agents --json | jq -r '.organizations[].agents[].agentId'
lua production overview                 # Check specific agent

# Automate init for multiple agents
for agent_id in $(lua agents --json | jq -r '.organizations[0].agents[].agentId'); do
  mkdir "project-$agent_id"
  cd "project-$agent_id"
  lua init --agent-id "$agent_id"
  cd ..
done
```

## Non-Interactive Mode for Auth Commands

The following commands support `--force` to skip confirmation prompts:

```bash theme={null}
# View API key without confirmation
lua auth key --force

# Logout without confirmation
lua auth logout --force

# Clear chat history without confirmation
lua chat clear --force

# Clear specific user's history without confirmation
lua chat clear --user user@email.com --force
```

`--user` accepts a user ID, email address, or mobile number and requires `org:manage` for the agent. Organization-admin grants do not cascade to private agents; organization owners and sufficient explicit agent grants retain access under the shared authorization rules. Without `--user`, the command clears only your own history.

## lua completion

Generate shell autocomplete scripts for faster command-line workflows.

```bash theme={null}
lua completion [shell]       # Generate completion script
lua completion bash          # Generate for Bash
lua completion zsh           # Generate for Zsh
lua completion fish          # Generate for Fish
```

<Note>
  Enable tab completion for all Lua CLI commands and arguments!
</Note>

### What It Does

Generates shell-specific completion scripts that enable:

* ✅ Tab completion for all commands
* ✅ Subcommand suggestions
* ✅ Environment option suggestions (sandbox, staging, production)
* ✅ Argument completion for push, env, persona, skills
* ✅ Context-aware completions

### Supported Shells

<Tabs>
  <Tab title="Bash">
    **Installation**

    ```bash theme={null}
    # Add to your ~/.bashrc
    lua completion bash >> ~/.bashrc
    source ~/.bashrc

    # Or for one-time setup
    echo 'eval "$(lua completion bash)"' >> ~/.bashrc
    source ~/.bashrc
    ```

    **Test it**

    ```bash theme={null}
    lua pu<TAB>           # Completes to: lua push
    lua push <TAB>        # Shows: skill, persona
    lua env <TAB>         # Shows: sandbox, staging, production
    lua persona <TAB>     # Shows: sandbox, staging, production
    ```
  </Tab>

  <Tab title="Zsh">
    **Installation**

    ```bash theme={null}
    # Add to your ~/.zshrc
    lua completion zsh >> ~/.zshrc
    source ~/.zshrc

    # Or for one-time setup
    echo 'eval "$(lua completion zsh)"' >> ~/.zshrc
    source ~/.zshrc
    ```

    **Test it**

    ```bash theme={null}
    lua <TAB>             # Shows all commands
    lua skills <TAB>      # Shows: sandbox, staging, production
    lua auth <TAB>        # Shows: configure, logout, key
    ```
  </Tab>

  <Tab title="Fish">
    **Installation**

    ```bash theme={null}
    # Create completions directory if it doesn't exist
    mkdir -p ~/.config/fish/completions

    # Generate completion file
    lua completion fish > ~/.config/fish/completions/lua.fish

    # Completions are automatically loaded
    ```

    **Test it**

    ```bash theme={null}
    lua <TAB>             # Shows all commands with descriptions
    lua push <TAB>        # Shows: skill, persona
    lua env <TAB>         # Shows: sandbox, staging, production
    ```
  </Tab>
</Tabs>

### Completion Features

<AccordionGroup>
  <Accordion title="Main Commands">
    Tab completion for all Lua CLI commands:

    ```bash theme={null}
    lua a<TAB>        # auth, admin
    lua p<TAB>        # push, persona, production
    lua s<TAB>        # skills
    lua e<TAB>        # env
    lua f<TAB>        # features
    lua c<TAB>        # compile, completion, chat, channels
    ```
  </Accordion>

  <Accordion title="Subcommands">
    Context-aware subcommand completion:

    ```bash theme={null}
    lua auth <TAB>         # configure, logout, key
    lua push <TAB>         # skill, persona
    lua chat <TAB>         # clear
    lua completion <TAB>   # bash, zsh, fish
    ```
  </Accordion>

  <Accordion title="Environment Options">
    Environment selection for applicable commands:

    ```bash theme={null}
    lua env <TAB>          # sandbox, staging, production
    lua persona <TAB>      # sandbox, staging, production
    lua skills <TAB>       # sandbox, staging, production
    ```
  </Accordion>

  <Accordion title="Help Flags">
    Common flags available for all commands:

    ```bash theme={null}
    lua --<TAB>            # --help, --version
    lua push --<TAB>       # --help
    ```
  </Accordion>
</AccordionGroup>

### Verification

After installation, verify autocomplete is working:

<Tabs>
  <Tab title="Test Basic Completion">
    ```bash theme={null}
    # Type this and press TAB
    lua pu

    # Should complete to:
    lua push
    ```
  </Tab>

  <Tab title="Test Subcommands">
    ```bash theme={null}
    # Type this and press TAB
    lua push 

    # Should show options:
    skill  persona
    ```
  </Tab>

  <Tab title="Test Environment">
    ```bash theme={null}
    # Type this and press TAB
    lua env 

    # Should show:
    sandbox  staging  production
    ```
  </Tab>
</Tabs>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Completions not working">
    **Problem**: Tab completion doesn't work after installation

    **Solutions:**

    1. Restart your terminal or reload shell config:
       ```bash theme={null}
       # Bash
       source ~/.bashrc

       # Zsh
       source ~/.zshrc

       # Fish (automatic)
       ```

    2. Verify script was added correctly:
       ```bash theme={null}
       # Check if completion is in config
       tail ~/.bashrc    # or ~/.zshrc
       ```

    3. Try explicit installation:
       ```bash theme={null}
       eval "$(lua completion bash)"  # Or zsh
       ```
  </Accordion>

  <Accordion title="Completions incomplete">
    **Problem**: Some commands complete, others don't

    **Solutions:**

    1. Regenerate completion script:
       ```bash theme={null}
       lua completion bash > /tmp/lua_completions
       cat /tmp/lua_completions >> ~/.bashrc
       source ~/.bashrc
       ```

    2. Check Lua CLI version:
       ```bash theme={null}
       lua --version
       # Should be v2.6.0 or higher
       ```
  </Accordion>

  <Accordion title="Fish completions not loading">
    **Problem**: Completions don't work in Fish shell

    **Solutions:**

    1. Verify file location:
       ```bash theme={null}
       ls ~/.config/fish/completions/lua.fish
       ```

    2. Regenerate if missing:
       ```bash theme={null}
       mkdir -p ~/.config/fish/completions
       lua completion fish > ~/.config/fish/completions/lua.fish
       ```

    3. Restart Fish shell
  </Accordion>

  <Accordion title="Conflict with existing completions">
    **Problem**: Completions conflict with other tools

    **Solution:**
    Remove old completion and reinstall:

    ```bash theme={null}
    # Bash/Zsh: Remove old lines from config file
    vim ~/.bashrc  # or ~/.zshrc
    # Delete old lua completion lines

    # Fish: Remove old file
    rm ~/.config/fish/completions/lua.fish

    # Reinstall
    lua completion [your-shell]
    ```
  </Accordion>
</AccordionGroup>

### Benefits

<CardGroup>
  <Card title="Faster Workflow" icon="bolt">
    Type less, complete more with tab
  </Card>

  <Card title="Discover Commands" icon="compass">
    See available options without docs
  </Card>

  <Card title="Fewer Typos" icon="check">
    Autocomplete prevents mistakes
  </Card>

  <Card title="Better UX" icon="heart">
    Professional CLI experience
  </Card>
</CardGroup>

### Advanced Usage

<AccordionGroup>
  <Accordion title="Multiple Shells">
    If you use multiple shells, install for each:

    ```bash theme={null}
    # Bash
    lua completion bash >> ~/.bashrc

    # Zsh
    lua completion zsh >> ~/.zshrc

    # Fish
    lua completion fish > ~/.config/fish/completions/lua.fish
    ```
  </Accordion>

  <Accordion title="Team Setup">
    Add to team onboarding:

    ```bash theme={null}
    # In your team's setup script
    echo "Setting up Lua CLI autocomplete..."
    lua completion bash >> ~/.bashrc
    source ~/.bashrc
    echo "✅ Autocomplete enabled"
    ```
  </Accordion>

  <Accordion title="Docker/Remote">
    Include in Docker images:

    ```dockerfile theme={null}
    # In Dockerfile
    RUN lua completion bash >> /root/.bashrc
    ```
  </Accordion>
</AccordionGroup>

## lua admin

Launch the Lua Admin interface in your default browser.

```bash theme={null}
lua admin
```

### What It Opens

The Lua Admin Dashboard provides complete control over your agent:

**Conversations**

* 💬 View conversations in real-time
* 📝 Reply to user messages
* 📊 Monitor conversation quality
* 🔍 Search conversation history
* 📈 Analyze user interactions

**User Management**

* 👥 Add users to your agent
* ✏️ Edit user permissions
* 🗑️ Remove users
* 👀 View user activity
* 📊 User analytics

**API Keys**

* 🔑 Generate new API keys
* 👁️ View existing keys
* 🗑️ Revoke keys
* 📋 Copy keys for development
* 🔒 Manage key permissions

**Channel Connections**

* 📱 WhatsApp integration
* 📸 Instagram messaging
* ✉️ Email integration
* 👍 Facebook Messenger
* 💬 Slack integration
* 📞 SMS/Twilio
* 🌐 Website chat widget
* 🔗 Custom integrations

**Billing & Subscription**

* 💳 View current plan
* 📊 Usage metrics
* 💰 Billing history
* 🔄 Update payment method
* 📈 Upgrade/downgrade plan

### Example

```bash theme={null}
$ lua admin
✓ Lua Admin Dashboard opened in your browser

  Dashboard URL: https://admin.heylua.ai
  Agent ID: agent-abc123
  Organization ID: org-xyz789
```

### Requirements

* Must be authenticated (`lua auth configure`)
* Must be in a skill directory (has `lua.skill.yaml`)
* Configuration must contain `agent.agentId` and `agent.orgId`

### Use Cases

<AccordionGroup>
  <Accordion title="Monitor Conversations">
    ```bash theme={null}
    $ lua admin
    ```

    * View live conversations
    * See how users interact with your agent
    * Identify areas for improvement
    * Take over conversations if needed
  </Accordion>

  <Accordion title="Manage Team Access">
    ```bash theme={null}
    $ lua admin
    ```

    * Add team members
    * Set permissions (admin, developer, viewer)
    * Manage API keys per user
    * Control who can deploy
  </Accordion>

  <Accordion title="Connect Channels">
    ```bash theme={null}
    $ lua admin
    ```

    * Connect WhatsApp Business
    * Set up Instagram messaging
    * Configure email integration
    * Add Slack workspace
    * Enable Facebook Messenger
  </Accordion>

  <Accordion title="Review Analytics">
    ```bash theme={null}
    $ lua admin
    ```

    * View conversation metrics
    * Check response times
    * Monitor user satisfaction
    * Track tool usage
    * Analyze peak times
  </Accordion>

  <Accordion title="Manage Billing">
    ```bash theme={null}
    $ lua admin
    ```

    * Review usage this month
    * Check billing history
    * Update payment method
    * Upgrade subscription
    * Download invoices
  </Accordion>
</AccordionGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Dashboard doesn't open">
    **Check:**

    1. Run `lua auth configure` to authenticate
    2. Ensure `lua.skill.yaml` exists (`lua init`)
    3. Verify agent ID is in config

    **Error:** "No Lua CLI authentication found"

    ```bash theme={null}
    $ lua auth configure
    ```
  </Accordion>

  <Accordion title="Wrong agent displayed">
    **Check:**

    1. Verify you're in correct project directory
    2. Check `agentId` in `lua.skill.yaml`
    3. Switch to correct agent directory
  </Accordion>

  <Accordion title="Permission denied">
    **Check:**

    1. Verify you have admin access
    2. Check with organization owner
    3. Request proper permissions
  </Accordion>
</AccordionGroup>

## lua evals

Launch the Lua Evaluations Dashboard in your default browser.

```bash theme={null}
lua evals
```

### What It Opens

The Lua Evaluations Dashboard at [https://evals.heylua.ai](https://evals.heylua.ai) provides tools to test and evaluate your agent:

**Evaluation Features**

* 🧪 Test your agent with predefined scenarios
* 📊 View evaluation results and metrics
* 📈 Track agent performance over time
* 🔍 Identify areas for improvement
* ✅ Validate agent responses

### Example

```bash theme={null}
$ lua evals
✓ Lua Evaluations Dashboard opened in your browser

  Dashboard URL: https://evals.heylua.ai
  Agent ID: agent-abc123
```

### Requirements

* Must be authenticated (`lua auth configure`)
* Must be in a skill directory (has `lua.skill.yaml`)
* Configuration must contain `agent.agentId`

### Use Cases

<AccordionGroup>
  <Accordion title="Test Agent Responses">
    ```bash theme={null}
    $ lua evals
    ```

    * Run predefined test scenarios
    * Validate agent behavior
    * Check response quality
    * Ensure consistency
  </Accordion>

  <Accordion title="Track Performance">
    ```bash theme={null}
    $ lua evals
    ```

    * Monitor evaluation scores
    * Compare across versions
    * Identify regressions
    * Measure improvements
  </Accordion>

  <Accordion title="Quality Assurance">
    ```bash theme={null}
    $ lua evals
    ```

    * Run evaluations before deployment
    * Validate production readiness
    * Document test results
    * Share with team
  </Accordion>
</AccordionGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Dashboard doesn't open">
    **Check:**

    1. Run `lua auth configure` to authenticate
    2. Ensure `lua.skill.yaml` exists (`lua init`)
    3. Verify agent ID is in config

    **Error:** "No Lua CLI authentication found"

    ```bash theme={null}
    $ lua auth configure
    ```
  </Accordion>

  <Accordion title="Wrong agent displayed">
    **Check:**

    1. Verify you're in correct project directory
    2. Check `agentId` in `lua.skill.yaml`
    3. Switch to correct agent directory
  </Accordion>
</AccordionGroup>

## lua docs

Launch this documentation in your default browser.

```bash theme={null}
lua docs
```

### What It Opens

Opens the complete Lua documentation at [https://docs.heylua.ai](https://docs.heylua.ai)

**Sections:**

* 🏠 Overview and getting started
* 📖 Key concepts (Persona, Skills, Tools, Resources)
* ⌨️ All CLI commands
* 📚 Complete API reference
* 💼 11 production-ready demos
* 💬 LuaPop chat widget guide

### Example

```bash theme={null}
$ lua docs
✓ Lua Documentation opened in your browser

  Documentation: https://docs.heylua.ai
```

### Requirements

None - works from anywhere

### Use Cases

<AccordionGroup>
  <Accordion title="Quick Reference">
    ```bash theme={null}
    # Forgot a command syntax?
    $ lua docs
    # Navigate to CLI Commands
    ```
  </Accordion>

  <Accordion title="API Lookup">
    ```bash theme={null}
    # Need API method signature?
    $ lua docs
    # Go to API Reference
    ```
  </Accordion>

  <Accordion title="Find Examples">
    ```bash theme={null}
    # Need an example for your use case?
    $ lua docs
    # Check Demos section
    ```
  </Accordion>

  <Accordion title="Share with Team">
    ```bash theme={null}
    # Onboarding new developer?
    $ lua docs
    # Share the URL
    ```
  </Accordion>
</AccordionGroup>

### Keyboard Shortcut

Add to your shell profile for even faster access:

```bash theme={null}
# Add to ~/.zshrc or ~/.bashrc
alias ld='lua docs'

# Usage
$ ld
# Opens documentation instantly
```

## lua telemetry

<Note>
  Manage whether lua-cli sends usage data.
</Note>

Control whether lua-cli collects usage data to help improve the developer experience.

```bash theme={null}
lua telemetry           # Show current status
lua telemetry on        # Enable telemetry
lua telemetry off       # Disable telemetry
lua telemetry status    # Show status (same as no argument)
```

### What Is Collected

lua-cli collects usage data to improve the developer experience:

| Collected                                 | Not Collected                    |
| ----------------------------------------- | -------------------------------- |
| Command name (e.g. `push`, `compile`)     | Your code or file contents       |
| Success or failure                        | Command arguments or flag values |
| Command duration                          | API keys or secrets              |
| CLI version, OS, Node.js version          | Agent names or custom data       |
| Account email (for person identification) |                                  |

Your data is handled in accordance with our [Privacy Policy](https://heylua.ai/privacy).

### Opting Out

You can opt out at any time using either method:

<Tabs>
  <Tab title="CLI command">
    ```bash theme={null}
    lua telemetry off
    ```

    Persists your preference in `~/.lua-cli/telemetry.json`. Re-enable with `lua telemetry on`.
  </Tab>

  <Tab title="Environment variable">
    ```bash theme={null}
    # Disable for this session
    LUA_TELEMETRY=false lua push

    # Or add to your shell profile to disable permanently
    echo 'export LUA_TELEMETRY=false' >> ~/.zshrc
    ```

    The environment variable takes highest priority and overrides the saved preference.
  </Tab>
</Tabs>

### Check Current Status

```bash theme={null}
$ lua telemetry
Telemetry: enabled

Usage:
  lua telemetry on      Enable telemetry
  lua telemetry off     Disable telemetry
  lua telemetry status  Show current setting

Or set LUA_TELEMETRY=false in your environment.
```

### First-Run Notice

On first use, lua-cli prints a one-time notice:

```
  Lua CLI collects usage data to improve the developer experience.
  To opt out, run: lua telemetry off
  Or set: LUA_TELEMETRY=false
```

This notice is shown once and never again.

### CI/CD Environments

In CI/CD pipelines, disable telemetry via environment variable — no config file needed:

```bash theme={null}
# In your CI environment variables
LUA_TELEMETRY=false
```

Or use the `--ci` flag which automatically adjusts CLI behavior for non-interactive environments.

## lua models

Manage the LLM model for your agent. The current model is resolved server-first (authoritative) with a fallback to your local compiled artifact.

```bash theme={null}
lua models                              # List all approved models, highlight the one in use
lua models list                         # Same as above
lua models list --json                  # Machine-readable JSON output
lua models set                          # Interactive picker (searchable, provider-grouped)
lua models set --model openai/gpt-4o    # Non-interactive
lua models unset                        # Remove model — revert to platform default
```

| Option           | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `--model <code>` | Model code for the `set` action (e.g. `openai/gpt-4o`). |
| `--json`         | Output `list` as JSON for scripting.                    |

### Actions

| Action           | What it does                                                                                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `list` (default) | Print all approved models grouped by provider. Highlights the currently configured model.                                                      |
| `set`            | Select a model interactively, or pass `--model` for non-interactive. Writes the model into your local `src/index.ts` and pushes to the server. |
| `unset`          | Remove the model from source and clear it on the server. Your agent reverts to the platform default.                                           |

<Note>
  You can also set the model at agent creation time: `lua init --model openai/gpt-4o`.
</Note>

## lua governance

Manage governance policies for your agent project. Governance wraps tool calls, preprocessors, and postprocessors with runtime enforcement using the governance SDK.

```bash theme={null}
lua governance              # Interactive governance setup
lua governance add          # Add governance (SDK or API mode)
lua governance remove       # Remove governance from agent (local + server)
```

| Action    | What it does                                                                      |
| --------- | --------------------------------------------------------------------------------- |
| (default) | Interactive setup — prompts for SDK or API mode and required configuration.       |
| `add`     | Add governance to the agent in either SDK mode (in-process) or API mode (remote). |
| `remove`  | Strip governance enforcement from both local source and the server.               |

After adding governance, `lua sync` detects drift on governance configuration the same way it does for other primitives.

## lua update

Updates `lua-cli` to the latest published version using the same package manager you installed it with (npm, pnpm, or yarn).

```bash theme={null}
lua update
```

No options — this is a one-shot command. Pair it with `lua status` to see whether an update is available before running.

## lua channels-phone

Phone-specific helper for the `lua channels` family. Used during phone-channel setup and diagnosis. Run `lua channels-phone --help` for the current subcommand set.

```bash theme={null}
lua channels-phone --help
```

For the general channel management command, see [`lua channels`](/cli/channels-command).

## lua chat-log-probe

Inspect raw chat log records for a session. Useful when debugging an issue reported with a specific thread ID or user — it shows the underlying log entries the platform recorded, in execution order.

```bash theme={null}
lua chat-log-probe --help
```

Pair this with `lua logs --type user_message` and `--type agent_response` for the high-level view; use `chat-log-probe` when you need the raw underlying records.

## Quick Comparison

| Command          | Opens/Generates              | Requires Auth | Use For                                |
| ---------------- | ---------------------------- | ------------- | -------------------------------------- |
| `lua agents`     | List of organizations/agents | ✅ Yes         | Discovery, automation, team management |
| `lua completion` | Shell completion script      | ❌ No          | Tab completion, faster workflows       |
| `lua admin`      | Admin dashboard              | ✅ Yes         | Managing agent, conversations, billing |
| `lua evals`      | Evaluations dashboard        | ✅ Yes         | Testing agent, tracking performance    |
| `lua docs`       | Documentation                | ❌ No          | Reference, examples, learning          |
| `lua telemetry`  | Telemetry settings           | ❌ No          | Opt in/out of usage data collection    |

## Integration with Workflow

### During Development

```bash theme={null}
# Need API reference?
$ lua docs
# Check API section

# Continue coding
```

### During Deployment

```bash theme={null}
# Deploy skills
$ lua push
$ lua deploy

# Check admin dashboard
$ lua admin
# Monitor conversations
# Verify deployment working
```

### When Troubleshooting

```bash theme={null}
# Issue with command
$ lua docs
# Search troubleshooting section

# Check production state
$ lua admin
# View live conversations
# Check for errors
```

## Next Steps

<CardGroup>
  <Card title="All CLI Commands" icon="terminal" href="/cli/overview">
    Complete command reference
  </Card>

  <Card title="Admin Features" icon="gauge" href="https://admin.heylua.ai">
    Explore the admin dashboard
  </Card>

  <Card title="Getting Started" icon="rocket" href="/getting-started/quick-start">
    New to Lua? Start here
  </Card>

  <Card title="Demos" icon="layer-group" href="/demos/overview">
    11 production-ready solutions
  </Card>
</CardGroup>


# Version Command
Source: https://docs.heylua.ai/cli/version-command

Create, inspect, promote, and roll back atomic versions of your agent

<Note>
  Looking for the release model as a whole — how `lua push`, `lua deploy`, and `lua version` fit together? Start with [The release flow, end to end](#the-release-flow-end-to-end) below.
</Note>

## Overview

`lua version` manages **agent versions** — atomic snapshots of your agent's complete deployed state (skills, webhooks, jobs, processors, MCP servers, persona, and model) that you can inspect, diff, and switch between instantly.

```bash theme={null}
lua version create --auto-push -m "checkout flow v2"   # Push + snapshot in one step
lua version list                                        # See all versions
lua version diff 1 2                                    # What changed between v1 and v2?
lua version promote 2                                   # Make v2 live — instant, no re-upload
lua version status                                      # What's live vs what's pushed but not live?
```

## Why versions?

A `lua push` updates individual primitives (a skill, a webhook, a persona) one by one. An agent version **pins the exact combination of everything** at a moment in time: which version of every skill, what model, which persona text, which MCP servers and how they were configured.

Promoting a version swaps the whole agent state **atomically** — all of it changes at once, with no in-between state where some primitives are old and some are new. Rolling back is just promoting an older version.

<Note>
  `lua version promote` is the recommended rollback path. It is instant, atomic, and requires no re-uploading of files. See [`lua version promote`](#lua-version-promote) below and the deprecation notice on [`lua source rollback`](/cli/source-command).
</Note>

## The release flow, end to end

Three commands, three distinct jobs:

1. **`lua push <primitive>`** stages code. It mints a new immutable version of that primitive — a skill, webhook, job, processor, trigger, persona, voice, MCP config, or model change — but activates nothing. Nothing your users see changes yet.
2. **`lua version create`** freezes a release candidate. It snapshots the latest pushed version of *every* primitive into a single agent version.
3. **`lua version promote <N>`** activates that agent version. Every primitive switches at once — no mixed-version window where, say, a new skill is live against an old persona. This push → create → promote sequence is the recommended release flow.

<Check>
  **Execution guarantee:** if a `promote` (or `deploy`) reports success, that exact code serves the very next invocation of the agent. Allow up to roughly a minute for edge caches to catch up globally.
</Check>

### Where `lua deploy` fits

`lua deploy <primitive>` (documented in full on the [Skill Management](/cli/skill-management#lua-deploy) page) is the older, single-primitive release command and remains fully supported:

* **Once an agent has promoted at least one agent version**, `lua deploy` performs a **scoped promote**: the platform automatically creates and promotes a new agent version identical to the current active one, except for the primitive you just deployed. The deploy is live immediately, and your agent-version history stays consistent — no gap where a primitive changed outside the version timeline. These auto-created versions show up in `lua version list` with a `deploy …` message so you can tell them apart from versions you created explicitly.
* **For agents that have never created or promoted an agent version**, `lua deploy` activates the primitive directly, the same way it always has.

Either way, use `lua version promote` when you want to switch several primitives together atomically; use `lua deploy` for a fast, single-primitive fix.

<Warning>
  Sandbox testing (`lua chat` / `lua test`) never touches what's live — it always runs against your local or pushed-but-not-promoted state, never the active agent version. Conversely, deactivating a webhook (or any primitive) stops it serving immediately, independent of version history.
</Warning>

## The three version numbers

When you run `lua version create --auto-push`, the output shows three different counters. They track separate things:

| Counter           | Example output       | What it tracks                                                          |
| ----------------- | -------------------- | ----------------------------------------------------------------------- |
| Primitive version | `user-skill v1.0.15` | Semver of one skill/webhook/job — bumped on each push of that primitive |
| Source backup     | `Backup at v3`       | Your project's source-file history (`lua source list`)                  |
| **Agent version** | `Created v2`         | **The atomic agent snapshot — what `lua version` manages**              |

These counters are independent. Pushing a single skill increments that skill's primitive version and creates a new source backup, but does **not** create a new agent version. Only `lua version create` creates a new agent version.

## Statuses

Every agent version has one of four statuses:

| Status       | Meaning                                                            |
| ------------ | ------------------------------------------------------------------ |
| `active`     | Currently serving — starred (`*`) in `lua version list`            |
| `staged`     | Snapshotted and awaiting promotion — not yet live                  |
| `superseded` | Was previously active; replaced when another version was promoted  |
| `deleted`    | Soft-deleted; still listed and inspectable, but cannot be promoted |

<Warning>
  **"staged" does not mean "staging environment."** A staged agent version is unrelated to your push deploy target (staging vs production) and unrelated to git's staging area. Here, "staged" simply means "snapshotted, awaiting promote."
</Warning>

## Commands

### `lua version create`

Snapshots the agent's current pushed state as a new `staged` version.

| Option                 | Description                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| `-m <message>`         | A short description stored with the version (e.g. `"checkout flow v2"`).                                    |
| `--auto-push`          | Push all local changes first, then snapshot. Equivalent to `lua push all` followed by `lua version create`. |
| `--commit-hash <hash>` | Associate a specific git commit hash with this version (recorded in the snapshot metadata).                 |

```bash theme={null}
lua version create -m "stable before A/B test"
lua version create --auto-push -m "checkout flow v2"
```

If nothing has changed since the last snapshot, the command exits with:

```
No staged changes since the previous version.
```

On success:

```
✓ Created v2 (staged). Run 'lua version promote v2' to deploy.
```

### `lua version list`

Prints a table of agent versions with columns VERSION, STATUS, CREATED, BY, and MESSAGE. The active version is starred.

| Option         | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `--all`        | Show all versions (overrides `--limit`).                                 |
| `--limit <n>`  | Cap output at `n` versions. Must be ≥ 1. Default: 20.                    |
| `--status <s>` | Filter by status: `active`, `staged`, `superseded`, `deleted`, or `all`. |
| `--json`       | Output clean JSON — pipeable to `jq` and other tools.                    |

```bash theme={null}
lua version list                           # recent versions, active starred
lua version list --all                     # full history
lua version list --status staged           # only staged versions
lua version list --json | jq '.[0]'        # first entry as JSON
```

### `lua version status`

Shows, per primitive, which version is pinned by the currently active agent version versus which version is sitting locally or already pushed to the server. Anything pushed but not yet part of an active (or promoted) agent version is flagged so you can see at a glance what's waiting to go live.

```bash theme={null}
lua version status
```

Reach for this before a release to confirm exactly what a `lua version create` would capture, or after a release to confirm nothing was left behind.

### `lua version show`

Shows the full snapshot for a version: per-type primitive counts, model, persona version, creator email, message, and recorded commit hash (if any).

Accepts either `2` or `v2` as the version argument.

```bash theme={null}
lua version show 2
lua version show v2
```

<Note>
  `lua version show` reports what is on the **server** for the agent at the time of the snapshot — not what is in your local project directory. A skill that exists server-side but has been removed from your local workspace is still part of the agent and will appear in the snapshot.
</Note>

### `lua version diff`

Shows what changed between two versions: added, removed, and changed primitives by name and version. Persona is compared by **content**, so re-pushing identical persona text shows `(unchanged)`. MCP configuration changes name the specific fields that changed. Model changes are included.

| Option   | Description                |
| -------- | -------------------------- |
| `--json` | Output diff as clean JSON. |

Accepts `2` or `v2` for both arguments.

```bash theme={null}
lua version diff 1 2
lua version diff v1 v2 --json | jq '.changed'
```

### `lua version promote`

Instantly activates a version. The previously active version becomes `superseded`. Promoting the already-active version is a graceful no-op.

```bash theme={null}
lua version promote 2
# ✓ Promoted v2. Previous active: v1.
```

There is no confirmation prompt — promotion is instant and the previous state is preserved as `superseded`, so you can always promote back.

### `lua version delete`

Soft-deletes a version. Deleted versions remain listed and inspectable with `lua version show`, but can no longer be promoted.

| Option    | Description                   |
| --------- | ----------------------------- |
| `--force` | Skip the confirmation prompt. |

```bash theme={null}
lua version delete 3
lua version delete 3 --force
```

Guard-rails:

* You cannot delete the **active** version. Promote a different version first.
* You cannot delete the **only remaining** version.

## Typical workflows

### Release

```bash theme={null}
# 1. Check what's pushed but not yet live
lua version status

# 2. Push everything and snapshot in one step
lua version create --auto-push -m "checkout flow v2"

# 3. Preview the new version in chat before promoting
lua chat --agent-version 2

# 4. Promote when satisfied
lua version promote 2
```

### Rollback

```bash theme={null}
# 1. See what versions exist
lua version list

# 2. Promote the last-known-good version — instant, no re-upload
lua version promote 1
```

### Audit

```bash theme={null}
# Diff two versions to understand what changed
lua version diff 1 2

# Inspect the full snapshot of a specific version
lua version show 2

# Or pipe to jq for scripting
lua version show 2 --json | jq '.snapshot'
```

## Git integration

When you have run `lua git connect`, every `lua version create` automatically commits your project and tags the commit `lua/v<N>`, where `N` is the new version number. The commit hash is recorded in the version snapshot and visible in `lua version show`.

See the [Git Command](/cli/git-command) page for setup instructions, auto-push configuration, and troubleshooting.

## Related

* [Skill Management](/cli/skill-management#lua-deploy) — `lua push` and the legacy `lua deploy` command
* [Git Command](/cli/git-command) — auto-commit and `lua/v<N>` tagging
* [Source Command](/cli/source-command) — source-file history and workspace restore
* [Chat Command](/cli/chat-command) — `lua chat --agent-version N` to preview a version


# Voice Command
Source: https://docs.heylua.ai/cli/voice-command

Try LuaVoice agents live in the browser and run voice test suites

## Overview

`lua voice` is the entry point for testing voice-enabled agents. You can talk to your agent live in the browser, run automated voice tests against `*.voice.test.ts` files, and inspect which voice primitives are wired into your agent.

```bash theme={null}
lua voice                          # Interactive: pick agent → voice → start browser test
lua voice test                     # Run all *.voice.test.ts files
lua voice list                     # List voice primitives in the manifest
```

## Subcommands

| Action    | What it does                                                                      |
| --------- | --------------------------------------------------------------------------------- |
| (default) | Interactive live test. Pick an agent, then a voice, then start a browser session. |
| `test`    | Run `*.voice.test.ts` files via Jest or Vitest.                                   |
| `list`    | List LuaVoice primitives in the compiled manifest.                                |

## Live Test Options

These apply to the default `lua voice` invocation.

| Option             | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `--agent <name>`   | Agent name. Skips the agent picker when your project has multiple agents with voices.                |
| `--voice <name>`   | Voice name. Skips the voice picker when an agent has multiple voices. Defaults to the primary voice. |
| `--context <json>` | Seed initial conversation context as a JSON object.                                                  |
| `--thread-id <id>` | Custom thread ID suffix for sandbox API scoping.                                                     |

### Live Test Examples

```bash theme={null}
# Interactive — pick agent and voice from menus
lua voice

# Skip the agent picker
lua voice --agent support-bot

# Pick a specific voice (skips voice picker)
lua voice --voice billing-line

# Seed initial context — the agent enters the conversation already knowing things
lua voice --context '{"orderId":"ABC-123","customerName":"Sam"}'

# Scope to a custom thread (for replaying a session later via API)
lua voice --thread-id qa-2026-05-18-run-1
```

## `lua voice test` — Automated Voice Tests

Runs your project's `*.voice.test.ts` files via Jest or Vitest. Lua auto-detects which runner you're using; pass `--runner` to force one.

| Option              | Description                                                                     |
| ------------------- | ------------------------------------------------------------------------------- |
| `--voice <name>`    | Run only `<name>.voice.test.ts` (filename match).                               |
| `--pattern <regex>` | Test path pattern. Default: `\.voice\.test\.`. Overrides `--voice` if both set. |
| `--watch`           | Re-run tests on file change.                                                    |
| `--bail`            | Stop on first failing test.                                                     |
| `--runner <runner>` | Force runner: `jest`, `vitest`, or `auto` (default).                            |

```bash theme={null}
lua voice test                       # All *.voice.test.ts files
lua voice test --voice support       # Only support.voice.test.ts
lua voice test --pattern support     # Filter by name pattern (regex)
lua voice test --watch               # Watch mode
lua voice test --bail                # Stop on first failure
lua voice test --runner vitest       # Force Vitest
```

## `lua voice list`

Prints the LuaVoice primitives defined in your compiled manifest. Useful for sanity-checking that all your voice agents and voices are wired up after a compile.

| Option   | Description                   |
| -------- | ----------------------------- |
| `--json` | Output as JSON for scripting. |

```bash theme={null}
lua voice list
lua voice list --json | jq
```

## Related

* [Persona Command](/cli/persona-command) — channel-aware personas including `voice` branch
* [LuaAgent API](/api/luaagent)
* [Voice API](/api/voice) — define voices in code with `LuaVoice`


# Webhooks Command
Source: https://docs.heylua.ai/cli/webhooks-command

Manage agent webhook primitives — view, deploy, activate, and subscribe to platform events

## Overview

`lua webhooks` manages HTTP webhook primitives defined with `LuaWebhook`. Each webhook is an addressable endpoint your agent exposes for external services (Stripe, Shopify, etc.) to call. The command also manages **event subscriptions** — wiring a webhook to platform events like `message.delivered`, which now fire for every channel your agent sends on.

```bash theme={null}
lua webhooks                              # Interactive management
lua webhooks view                         # List all webhooks
lua webhooks list-events                  # See subscribable event types
lua webhooks subscribe --webhook-name paymentHook --event message.delivered
```

<Note>
  For defining webhooks in code, see [LuaWebhook API](/api/luawebhook).
</Note>

## Subcommands

| Action        | What it does                                               |
| ------------- | ---------------------------------------------------------- |
| `view`        | List all webhooks defined on the agent.                    |
| `versions`    | List every version of a webhook.                           |
| `deploy`      | Promote a version to active.                               |
| `activate`    | Re-enable a deactivated webhook.                           |
| `deactivate`  | Stop the webhook from receiving traffic. Version retained. |
| `delete`      | Permanently remove a webhook and all its versions.         |
| `list-events` | Print the catalog of subscribable platform events.         |
| `subscribe`   | Subscribe a webhook to a platform event.                   |
| `unsubscribe` | Remove a webhook's subscription to an event.               |

## Options

| Option                    | Description                                                          |
| ------------------------- | -------------------------------------------------------------------- |
| `--webhook-name <name>`   | Webhook name. Required for most non-interactive actions.             |
| `--webhook-version <ver>` | Version for `deploy`. Pass `latest` for the newest.                  |
| `--event <type>`          | Event type for `subscribe`/`unsubscribe` (e.g. `message.delivered`). |

## Examples

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

# List everything
lua webhooks view

# Promote a version
lua webhooks deploy --webhook-name paymentHook --webhook-version 1.0.3
lua webhooks deploy --webhook-name paymentHook --webhook-version latest

# Pause and resume
lua webhooks deactivate --webhook-name paymentHook
lua webhooks activate   --webhook-name paymentHook

# Delete
lua webhooks delete --webhook-name oldHook

# Event subscriptions
lua webhooks list-events
lua webhooks subscribe   --webhook-name paymentHook --event message.delivered
lua webhooks unsubscribe --webhook-name paymentHook --event message.delivered
```

## Webhooks vs Triggers

Three different things, often confused:

| Concept                 | Source                                                                                                                                                                                                    | Manage with                                              |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Webhook primitive**   | An HTTP endpoint **your agent owns** that external services call. Defined in code with `LuaWebhook` — your `execute` function handles the request and owns the response.                                  | `lua webhooks`                                           |
| **Agent trigger**       | A URL that **wakes the agent** on an external event — no handler code; the agent turn does the work. Optionally defined in code with [`LuaTrigger`](/api/luatrigger) for verify/filter/transform shaping. | [`lua triggers`](/cli/triggers-command)                  |
| **Integration trigger** | A subscription on a third-party service (Linear, Discord, etc.) that calls into your agent on a specific event.                                                                                           | [`lua integrations webhooks`](/cli/integrations-command) |

Use `lua webhooks` for things like "Stripe will call this URL on `payment.succeeded` and my code will handle it." Use `lua triggers` for things like "when this URL is hit, have the agent deal with it." Use `lua integrations webhooks` for things like "wake my agent when a Linear issue is created."

## Event Subscriptions

Your agent emits platform events a webhook can subscribe to, so you learn what happened to a message without polling for it. Run `lua webhooks list-events` to see the current catalog.

```bash theme={null}
lua webhooks list-events
```

Subscribe a webhook to an event so the webhook fires whenever the event occurs:

```bash theme={null}
lua webhooks subscribe --webhook-name deliveryTracker --event message.delivered
```

### The `message.*` delivery events

| Event               | Fires when                                                 |
| ------------------- | ---------------------------------------------------------- |
| `message.sent`      | The provider handed the message to the recipient's network |
| `message.delivered` | It reached the recipient's device                          |
| `message.read`      | The recipient opened it                                    |
| `message.failed`    | It will not arrive. The payload carries `error`            |
| `message.played`    | A WhatsApp voice note was played. WhatsApp only            |

**These fire for every channel.** They used to be WhatsApp-only. Every channel that sends now writes the same delivery record, and that record is what produces the event, so an agent already subscribed to `message.delivered` starts receiving email and SMS receipts with no change on your side.

They fire once per real status change. A provider that redelivers a receipt, or reports one out of order, produces no second event.

The payload is a [`DeliveryView`](/api/channels#delivery-status) plus `messageWamid` and `channel`, which the original WhatsApp payload carried and which stay for anything already reading them:

```typescript theme={null}
export const deliveryTracker = new LuaWebhook({
  name: 'deliveryTracker',
  execute: async ({ body }) => {
    const { eventType, payload } = body;

    if (eventType === 'message.failed') {
      console.error(
        `${payload.channel} send ${payload.id} failed:`,
        payload.error?.category,      // 'billing', 'opted_out', 'window_closed', ...
        payload.error?.title,
        payload.error?.code           // the vendor's own code
      );
    }

    return { ok: true };
  }
});
```

`payload.id` is the same `deliveryId` the send returned, so you can join an event back to the send that produced it, or read the full record with `Channels.getStatus(payload.id)`. The error categories are listed in [Delivery status](/api/channels#error-categories).

## Request Verification

A webhook can carry a signing secret. Set `secret` on the `LuaWebhook` definition and Lua rejects any call to that webhook without a valid `x-lua-signature: sha256=<hex HMAC-SHA256 of the raw body>` header with **401**, before your code runs.

```typescript theme={null}
new LuaWebhook({
  name: 'payment',
  description: 'Handle payment events',
  secret: 'a-long-random-string',
  execute: async (event) => ({ received: true }),
});
```

The secret is applied on every `lua push webhook`, so **rotation is a re-deploy**: change the value, push, and update the sender. Set `secret: ''` and push to turn verification off. There is no CLI command that prints a webhook's secret — `lua webhooks view` never shows it.

See [Verify Requests](/overview/webhooks#verify-requests) for the signing recipe.

## Common Workflow

```bash theme={null}
# Edit your webhook in src/webhooks/payment.ts, then:
lua push webhook                              # Build + upload
lua webhooks versions --webhook-name payment  # Confirm version is on server
lua webhooks deploy --webhook-name payment --webhook-version latest
lua logs --type webhook --name payment --limit 20  # Verify traffic
```

## Related

* [LuaWebhook API](/api/luawebhook)
* [Triggers Command](/cli/triggers-command) — agent triggers (paste-anywhere URLs)
* [Integrations Command](/cli/integrations-command) — third-party triggers
* [Logs Command](/cli/logs-command)
* [Test Command](/cli/skill-management#lua-test) — `lua test webhook` for local testing


# Workflows Command
Source: https://docs.heylua.ai/cli/workflows-command

Manage workflows and their runs from the CLI - list, deploy, start, watch, approve, signal, cancel, retry, replay, archive and inspect Job-tier steps

## Overview

`lua workflows` manages workflow definitions and runs. Definitions are pushed with `lua push workflow` and activated with `lua workflows deploy`; runs are started, watched and steered with the run verbs.

```bash theme={null}
lua workflows                                      # Interactive: list, run locally, start, list runs
lua workflows list                                 # Workflows on the agent
lua workflows deploy outreach -v latest            # Make the newest version live
lua workflows start outreach --input @leads.json --follow
lua workflows runs --workflow outreach --status failed
lua workflows status <runId> --steps
lua workflows approve <runId> --approval <id> --decision approve
```

<Note>
  For writing workflows see [Authoring](/workflows/authoring). For the run model behind these verbs see [Runs and events](/workflows/runs-and-events).
</Note>

## Usage

```
lua workflows [action] [target] [extra] [options]
```

* `target` is the workflow name (or id) for `list`, `view`, `versions`, `deploy`, `activate`, `deactivate`, `start`, `run`, `env-overlay` and `delete`; a run id for every other verb. `-i <name>` / `-r <runId>` are the equivalent options.
* `extra` is the signal name for `signal <runId> <name>` and the step id for `job-logs <runId> <stepId>`.

### Subcommands

| Action                    | What it does                                                                                        |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| `list`                    | List workflows on the agent (`--all` includes dynamic ones).                                        |
| `view`                    | Show one workflow: status, active version, schedule, output visibility, env overlay keys, versions. |
| `versions`                | List every version of a workflow.                                                                   |
| `deploy`                  | Make a version active (`-v <ver>` or `latest`).                                                     |
| `activate` / `deactivate` | Enable or pause a workflow's schedules and triggers. `activate -v <ver>` also deploys that version. |
| `start`                   | Start a run.                                                                                        |
| `run`                     | Run a workflow locally (alias of `lua test workflow`; no API call).                                 |
| `runs`                    | List runs.                                                                                          |
| `status`                  | Show one run (and its steps with `--steps`).                                                        |
| `watch`                   | Stream a run's events until it ends or waits for a person.                                          |
| `cancel`                  | Request (or force) a cancel.                                                                        |
| `resume`                  | Resume a step parked by `ctx.suspend()`.                                                            |
| `retry-step`              | Re-arm a failed, parked or billing-held step.                                                       |
| `approve`                 | Approve or deny an approval.                                                                        |
| `signal`                  | Deliver a signal.                                                                                   |
| `replay`                  | Replay a run locally against the compiled artifact.                                                 |
| `logs`                    | Print a run's progress and log events.                                                              |
| `delete`                  | Delete a workflow.                                                                                  |
| `delete-run`              | Erase a terminal run.                                                                               |
| `env-overlay`             | Show which `env.template()` keys a version carries and whether each is present.                     |
| `archive-runs`            | Export terminal runs as evidence bundles to a directory.                                            |
| `workspace`               | Show or release a run's Job-tier workspace.                                                         |
| `jobs`                    | List a run's Job-tier steps.                                                                        |
| `job-logs`                | Print a Job-tier step's container log.                                                              |

### Common options

| Option                         | Description                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------- |
| `-i, --workflow-name <name>`   | Workflow name or id (instead of the positional target).                         |
| `-r, --run-id <id>`            | Run id (instead of the positional target).                                      |
| `-v, --workflow-version <ver>` | Version for `deploy`, `activate`, `env-overlay` and `start` (`latest` allowed). |
| `--json`                       | Print the raw `{ success, data }` envelope. Pipe to `jq`.                       |

### Exit codes

| Code | Meaning                                                                                        |
| ---- | ---------------------------------------------------------------------------------------------- |
| `0`  | Success.                                                                                       |
| `1`  | Server or API failure.                                                                         |
| `2`  | Usage error.                                                                                   |
| `3`  | Not found.                                                                                     |
| `4`  | The run ended `failed` or `timed_out` (also a replay divergence).                              |
| `5`  | The run ended `cancelled` or `abandoned`.                                                      |
| `6`  | The run is gated awaiting consent.                                                             |
| `7`  | `--timeout` reached while the run was still live.                                              |
| `8`  | The run is parked on a person or a gate (approval, input, signal, exception, billing, budget). |

## Definitions

### `lua workflows list`

| Option  | Description                                  |
| ------- | -------------------------------------------- |
| `--all` | Include dynamic (server-composed) workflows. |

Columns: Name, Status, Active version, Versions, Form (`static` / `dynamic`), Id.

### `lua workflows view <name>`

Prints the workflow's id, status, active version, schedule, output visibility (roles, users, owner bypass), env overlay keys, and a versions table (version, form, topology, graph hash, created).

### `lua workflows versions <name>`

The versions table alone.

### `lua workflows deploy <name> -v <ver|latest>`

Publishes a version as the active one. On an agent under versioning this is a scoped promote: a new agent version is recorded and printed as `agentVersion`. Without `-v` the newest version is deployed.

```bash theme={null}
lua workflows deploy outreach -v 1.0.3
lua workflows deploy outreach -v latest
```

### `lua workflows activate <name>` / `deactivate <name>`

Enable or pause the workflow's schedules and triggers. `activate -v <ver>` is the same as `deploy`.

### `lua workflows delete <name>`

| Option    | Description                                                                                                           |
| --------- | --------------------------------------------------------------------------------------------------------------------- |
| `--yes`   | Skip the confirmation prompt.                                                                                         |
| `--force` | Cancel in-flight runs first. Without it a workflow with runs in flight is refused (409 `RUNS_IN_FLIGHT` with counts). |

Remove the file from `src/workflows/` (and its entry in `lua.skill.yaml`) afterwards to keep the project in sync.

### `lua workflows env-overlay <name> [-v <ver|latest>]`

Lists every `env.template()` key on the version, where it resolved from, and whether it is present in the agent environment. Values are never printed. Exits `1` when a key is missing.

## Starting and running

### `lua workflows start <name>`

| Option                         | Description                                                                            |
| ------------------------------ | -------------------------------------------------------------------------------------- |
| `--input <json\|@file>`        | Run input (default `{}`).                                                              |
| `--idempotency-key <key>`      | Reusing a key returns the original run (`idempotent replay`).                          |
| `--correlation-key <key>`      | Caller-chosen, non-unique key for finding and signalling the run later.                |
| `--tag <tag>`                  | Repeatable, at most 10.                                                                |
| `--budget-credits <n>`         | Run budget in credits.                                                                 |
| `--wait <s>`                   | Server long-poll, 0..55 s: returns the settled run when it finishes inside the window. |
| `--follow`                     | Attach `watch` after the start.                                                        |
| `-v, --workflow-version <ver>` | Pin a version instead of the active one.                                               |

Prints `Run <runId> · <status>` and, without `--follow`, the watch and status commands to run next. A `gated` start exits `6`; a `concurrencyPolicy: 'forbid'` workflow with a run in flight prints the blocking run id and exits `1`.

```bash theme={null}
lua workflows start outreach --input '{"leads":[]}' --follow
lua workflows start ticket-plan --input @ticket.json --idempotency-key ticket-plan:TP-12 --tag triage
```

### `lua workflows run <name>`

Runs the workflow locally after compiling the project - the same as `lua test workflow --name <name>`. No run is created on the server.

| Option                      | Description                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `--input <json\|@file>`     | Run input.                                                                                        |
| `--step-output <id=json>`   | Complete a step with this output (repeatable).                                                    |
| `--approve <id[=@payload]>` | Pre-answer an approval (repeatable).                                                              |
| `--deny <id[=@reason]>`     | Pre-deny an approval (repeatable).                                                                |
| `--signal <name=json>`      | Pre-supply a `waitForSignal` payload (repeatable).                                                |
| `--from-run <runId>`        | Seed completed steps from a real run.                                                             |
| `--force`                   | Seed from a run whose graph differs.                                                              |
| `--record <dir>`            | Record agent and tool outputs as fixtures.                                                        |
| `--fixtures <dir>`          | Replay recorded fixtures.                                                                         |
| `--step-wall <s>`           | Per-step wall in seconds (default 600).                                                           |
| `--job-wall <s>`            | Virtual wall for `tier: 'job'` steps; splits at 14 400 s segments, above 86 400 is a usage error. |
| `--ledger-out <file>`       | Write the in-memory ledger as JSON.                                                               |
| `--agents <fake\|live>`     | Fake agent steps (default) or call the dev API.                                                   |
| `--now <iso>`               | Virtual clock start.                                                                              |
| `--park <id>`               | Simulate a platform-fault park of a step (repeatable).                                            |
| `--fast-retries`            | Collapse retry backoff waits to 0.                                                                |
| `--real-time`               | Actually wait on sleeps and backoffs.                                                             |
| `--artefacts-dir <dir>`     | Back `ctx.artefacts.*` on disk.                                                                   |
| `--env <KEY=value>`         | Local `env.template()` overlay (repeatable; a missing key is a usage error).                      |
| `--max-ticks <n>`           | Script form: tick cap (default 64).                                                               |

Interactive runs prompt on stdin for any approval, input or signal you did not pre-answer.

```bash theme={null}
lua workflows run outreach --input @leads.json --step-output draftEmail=@draft.json --approve reviewDrafts
```

## Runs

### `lua workflows runs`

| Option                    | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `--workflow <name>`       | Filter by workflow.                                               |
| `--status <status>`       | Filter by status.                                                 |
| `--correlation-key <key>` | Filter by correlation key.                                        |
| `--tag <tag>`             | Filter by tag (repeatable).                                       |
| `--limit <n>`             | Page size.                                                        |
| `--cursor <c>`            | Page cursor (printed at the end of a page).                       |
| `--sort <field>`          | `-createdAt` (default), `createdAt`, `-durationMs`, `durationMs`. |

Columns: Run, Status, Trigger, Created, Correlation, Tags.

### `lua workflows status <runId>`

| Option     | Description                                                                         |
| ---------- | ----------------------------------------------------------------------------------- |
| `--steps`  | Fetch the full run and print a per-step table (Step, Kind, Status, Attempt, Error). |
| `--strict` | Exit `4` / `5` by terminal status instead of `0`.                                   |

Prints the run's status, workflow and version, trigger, correlation key and tags, timings, lineage, gate (with the action that clears it), failure reason and output. A run whose outputs are restricted prints `restricted` instead of the output.

### `lua workflows watch <runId>`

Streams the run's events over SSE and prints one line per event. Reconnects from the last event id when the stream drops. Stops at the terminal event (exit `0`, `4` or `5`) or as soon as the run waits for a person or a gate (exit `8`), printing the verb that resumes it.

| Option          | Description                                                                     |
| --------------- | ------------------------------------------------------------------------------- |
| `--after <seq>` | Replay from this sequence number.                                               |
| `--timeout <s>` | Give up after `s` seconds while the run is still live (exit `7`).               |
| `--events`      | Print raw frames as JSON (`{ id, event, data }`) instead of the formatted line. |

`step.throttled` events are collapsed into one counter line. Press Ctrl-C to detach without affecting the run.

### `lua workflows logs <runId>`

Fetches the run's events once (polling form, up to 500) and prints the progress and lifecycle ones: `step.progress` (your `ctx.log` messages), `*.started`, `*.completed`, `*.failed`, `*.skipped`, `run.log`.

| Option          | Description                  |
| --------------- | ---------------------------- |
| `--step <id>`   | Only this step's events.     |
| `--follow`      | Switch to `watch`.           |
| `--since <dur>` | Window (accepted; see note). |

### `lua workflows cancel <runId>`

| Option            | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `--reason <text>` | Recorded on the run.                                  |
| `--force`         | Force cancel once the server says force is available. |

Prints the verdict and the next action (`cancel again` or `force available at ...`).

### `lua workflows resume <runId> --step <id>`

| Option                 | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `--step <id>`          | The suspended step. Required.                            |
| `--data <json\|@file>` | The `resumeData` (must match the step's `resumeSchema`). |

Refused with a hint when the step is an approval (`use approve`) or a signal wait (`use signal`). A repeated resume prints who already resumed it.

### `lua workflows retry-step <runId> --step <id>`

| Option          | Description                |
| --------------- | -------------------------- |
| `--step <id>`   | The parked step. Required. |
| `--note <text>` | Recorded with the retry.   |

Re-arms a step that failed past its retries, parked on an exception gate, or sits on a billing hold (the only way out of a billing park after topping up). 409 `STEP_NOT_PARKED` when the step is running, pending or already re-armed; `RUN_TERMINAL` when the run ended.

### `lua workflows approve <runId> --approval <id>`

| Option                       | Description                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| `--approval <id>`            | The approval id (`wfa_...`). Required.                                                                 |
| `--decision <approve\|deny>` | Default `approve`.                                                                                     |
| `--note <text>`              | The approver's note (the workflow reads it as `note`).                                                 |
| `--edit <json\|@file>`       | An edited payload (small inline edits).                                                                |
| `--fingerprint <f>`          | The payload fingerprint you looked at. Mandatory with `--edit`; a stale one is 409 `PAYLOAD_MISMATCH`. |

Find the approval id with `lua workflows status <runId> --json` (`data.suspensions[].suspend.approvalId`) or in the desktop card. `STEP_UP_REQUIRED` means the approval must be given from the desktop with a fresh login.

```bash theme={null}
lua workflows approve wfr_3f2... --approval wfa_9c1... --decision approve --note "Go ahead"
lua workflows approve wfr_3f2... --approval wfa_9c1... --decision deny
```

### `lua workflows signal <runId> <name>`

| Option                    | Description                                                 |
| ------------------------- | ----------------------------------------------------------- |
| `--payload <json\|@file>` | The signal payload (validated against the wait's `schema`). |
| `--dedupe-key <key>`      | Makes a redelivery a no-op.                                 |

Prints whether the signal was consumed by a step, parked until a step waits for it, or was a duplicate.

```bash theme={null}
lua workflows signal wfr_3f2... review --payload '{"ok":true}' --dedupe-key review:42
```

### `lua workflows replay <runId> --local`

Re-derives the run from the compiled artifact in the current project and compares each step's recorded output with the local derivation. A differing graph hash is reported first. Exit `4` on a divergence. Only `--local` is available; pass `-i <name>` when several compiled workflows could match.

### `lua workflows delete-run <runId>`

Erases a terminal run - outputs, artefacts and journal. Prompts unless `--yes`. A live run is refused (`cancel it first`).

## Archiving

### `lua workflows archive-runs --since <iso|dur> --out <dir>`

Exports every terminal run in the window as an evidence bundle, verifies each download against its manifest hash, writes `<runId>.zip` files and an `archive-index.ndjson`, and skips runs already archived with a matching hash.

| Option                 | Description                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--since <iso\|dur>`   | Window start (`8d`, `36h`, `90m` or an ISO timestamp). Required.                                                                                   |
| `--out <dir>`          | Destination directory. Required.                                                                                                                   |
| `--until <iso>`        | Window end.                                                                                                                                        |
| `--workflow <name>`    | Only this workflow's runs.                                                                                                                         |
| `--tag <tag>`          | Only runs with this tag (repeatable).                                                                                                              |
| `--concurrency <n>`    | Parallel exports, 1..5 (default 2).                                                                                                                |
| `--no-inputs`          | Exclude run inputs from the bundles.                                                                                                               |
| `--no-artefacts`       | Exclude artefacts from the bundles.                                                                                                                |
| `--retention-days <n>` | Your organisation's run retention (default 90). `--since` must be inside retention minus the 7-day export TTL, otherwise `ARCHIVE_WINDOW_TOO_OLD`. |
| `--connection <id>`    | Storage connection for `s3://` / `gs://` sinks - not available in this build; archive to a local directory and sync it.                            |

Exit `3` when the window holds no terminal runs, `4` when any export failed or was deferred (rate-limited or still pending).

## Job tier

### `lua workflows workspace <runId>`

Shows the run's workspace: kind and backend, repo and ref, branch and head, size used, files changed, TTL, worktree arms (branch, head, pushed, merged, conflicts) and any error.

| Option          | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `--release`     | Release the volume now. Refused with the step id while a step is using it. |
| `--note <text>` | Recorded with the release.                                                 |

### `lua workflows jobs <runId>`

Lists the run's `tier: 'job'` steps: Step, Status, Attempt, Size class, Pod phase, Segment, Heartbeat, Error.

### `lua workflows job-logs <runId> <stepId>`

| Option          | Description                                |
| --------------- | ------------------------------------------ |
| `--attempt <n>` | Attempt to read (default latest).          |
| `--tail <n>`    | Log lines, 1..2000 (default 200).          |
| `--follow`      | Poll every 5 s until the step is terminal. |

Prints a header (attempt, status, pod phase, size class, segment, harness, pod name, last heartbeat, error) followed by the log lines.

```bash theme={null}
lua workflows job-logs wfr_3f2... implement --tail 500 --follow
```

## Push, deploy and versions

Workflows follow the same release flow as every other primitive:

1. **`lua push workflow`** compiles the project and mints a new immutable version of each changed workflow (`--name <name>` for one; aliases `workflows` and `wf`). Missing `env.template()` keys abort the push before anything is sent. `lua push all` does **not** include workflows - push them explicitly. `--auto-deploy` publishes the version straight after the push.
2. **`lua workflows deploy <name> -v latest`** activates the version. On an agent under versioning this records a scoped promote - a new agent version identical to the current one except for this workflow - and prints its number.
3. **`lua version`** snapshots pin workflow versions alongside skills, webhooks and jobs, so `lua version promote <N>` rolls a workflow back with everything else. `lua version create` after a push captures the newest pushed workflow versions.

```bash theme={null}
lua push workflow --name outreach
lua workflows versions outreach
lua workflows deploy outreach -v latest
lua workflows start outreach --input @leads.json --follow
```

## Related

* [Workflows](/overview/workflows) - the concept
* [Workflows Quick Start](/workflows/quick-start)
* [Authoring](/workflows/authoring) and [Job tier](/workflows/job-tier)
* [Runs and events](/workflows/runs-and-events) - the run model these verbs act on
* [Version Command](/cli/version-command) - agent versions and rollback
* [Push & Deploy](/cli/skill-management#lua-push)


# API Keys
Source: https://docs.heylua.ai/concepts/api-keys

Legacy, scoped personal, and device credentials

## Overview

Lua accepts existing legacy API keys and typed credentials. Choose the credential class for the client that uses it:

<CardGroup>
  <Card title="Legacy keys" icon="key">
    `api_` followed by 32 hex characters. Created before scoped keys existed. Act with the owner's full permissions in every organization the owner belongs to.
  </Card>

  <Card title="Scoped keys" icon="shield-halved">
    `api_<uuid>.<secret>`. Personal keys with an explicit role on one or more organizations or agents. They never exceed the owner's current access.
  </Card>

  <Card title="Device credentials" icon="microchip" href="/devices/credentials">
    Typed credentials bound to one exact agent, one exact device name, and selected device operations.
  </Card>
</CardGroup>

Legacy and scoped personal keys use the same bearer-token request format. Device credentials use the device client and device protocol fields. They do not grant general personal API access.

## Legacy keys

If your key was created before scoped keys shipped, nothing about it changes. Legacy keys:

* Act with the owner's full permissions, in **every** organization the owner belongs to.
* Keep working indefinitely.

<Note>
  There is no deprecation date, forced rotation, or automatic expiry for legacy keys. Existing integrations can keep using them. New CLI email login creates a renewable user session instead of another API key.
</Note>

## Scoped keys

A scoped key is a **personal** key: it belongs to one member, and it carries an explicit role on each organization or agent it's granted against — the same kind of role a human member holds on that resource in the admin dashboard.

Two rules govern what a scoped key can do:

<Steps>
  <Step title="Capped at the owner's role">
    A scoped key can never do more than its owner can. Its effective role on a resource is capped at the owner's current role there, even if the key was originally granted a broader role.
  </Step>

  <Step title="Follows the owner's access">
    If the owner loses access to an organization, any key of theirs scoped to that organization loses access too. Keys the owner holds on their other organizations keep working normally.
  </Step>
</Steps>

<Note>
  The role picker in the dashboard (**Settings → API Keys**) shows the current set of roles you can grant, since it's the same roster used for human org members. Scope each key to the organizations or agents it actually needs — see [Best practices](#best-practices).
</Note>

## Interactive login and scoped credentials

Use Email login for interactive work on a developer workstation:

```bash theme={null}
lua auth configure
```

Choose **Email** and confirm the OTP. The CLI stores a renewable first-party session and reads your current access when each command runs. It does not create an API key. Each project's `lua.skill.yaml` selects its agent.

For CI, a direct HTTP integration, or another client that needs a separately managed credential, create a scoped key under **Settings → API Keys**:

```bash theme={null}
lua admin
# Or visit https://admin.heylua.ai
```

<Steps>
  <Step title="Open Settings → API Keys">
    Manage your own keys or, if you are an organization administrator, keys for another member.
  </Step>

  <Step title="Choose the scope">
    Grant a role on one or more organizations or agents. A key created for another member cannot exceed that member's role.
  </Step>

  <Step title="Set an optional expiry">
    Defaults to never. Set a date if the key is for a temporary integration.
  </Step>

  <Step title="Copy the secret">
    Lua shows the full secret once. Store it in a secret manager or `.env` file. You cannot view it again after you leave the page.
  </Step>
</Steps>

<Warning>
  Never commit an API key to version control or share it publicly.
</Warning>

## Device credentials

New Node.js installations and custom protocol clients use a device credential instead of a personal scoped key. Provision it for one exact agent, one exact device name, and only the `commands`, `triggers`, or `assets.upload` operations that the device needs. See [Device credentials](/devices/credentials) for the endpoint, client setup, and compatibility behavior.

## Managing a key

Scoped personal keys and device credentials use the same rotation, suspension, reactivation, and revocation lifecycle.

<AccordionGroup>
  <Accordion title="Rotate">
    Replaces the key's secret while keeping its role and grants intact. Only the key's owner can rotate it. The new secret is shown exactly once. The old secret stops working as the change propagates, within about a minute.
  </Accordion>

  <Accordion title="Suspend / reactivate">
    Temporarily disables a key without losing its configuration. A suspended key fails authentication after the change propagates. Its role and grants stay unchanged.
  </Accordion>

  <Accordion title="Revoke">
    Permanently disables a key. Either the key's owner or an org admin can revoke it. Revocation is one-way — a revoked key can't be reactivated, only replaced with a new one. It takes effect within about a minute everywhere.
  </Accordion>
</AccordionGroup>

## Using a key

Usage is identical for legacy and scoped keys:

<Tabs>
  <Tab title="HTTP API">
    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    See the [HTTP API reference](/channels/http-api).
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    export LUA_API_KEY=your-api-key
    # or
    lua auth configure --api-key your-api-key
    ```

    See [Authentication](/cli/authentication).
  </Tab>

  <Tab title="Device clients">
    ```typescript theme={null}
    new DeviceClient({
      deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
      agentId: 'your-agent-id',
      deviceName: 'your-device-name',
    });
    ```

    New Node.js installations use a [device credential](/devices/credentials) with an exact agent, device name, and operation binding. Existing `apiKey` and `api_key` configurations remain supported for non-dotted legacy keys indefinitely.
  </Tab>
</Tabs>

## Errors

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| `401`  | The key is invalid, expired, suspended, or revoked.                        |
| `403`  | The key is valid, but its role doesn't allow that action on that resource. |

A `403` on a scoped key usually means the key needs a broader role, or a grant on an additional organization or agent — check **Settings → API Keys** in the dashboard.

## Best practices

<AccordionGroup>
  <Accordion title="One key per integration">
    Don't reuse a single key across unrelated integrations. If one is compromised or needs rotating, a dedicated key limits the blast radius and makes it obvious what to revoke.
  </Accordion>

  <Accordion title="Grant the narrowest role that works">
    Give a key only the role it needs on a resource, not a broader one "to be safe." A key capped at the right role can't be misused for actions it was never meant to perform.
  </Accordion>

  <Accordion title="Prefer agent-level over org-level scope">
    If an integration only ever needs one agent, scope the key to that agent instead of the whole organization. It keeps the key from reaching agents it has no business touching.
  </Accordion>

  <Accordion title="Set an expiry for temporary access">
    Contractor access, a one-off migration script, a demo environment — anything with a known end date should get an expiry instead of relying on someone remembering to revoke it later.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="CLI Authentication" icon="terminal" href="/cli/authentication">
    Configure the CLI with an API key
  </Card>

  <Card title="HTTP API" icon="bolt" href="/channels/http-api">
    Call your agent directly over HTTP
  </Card>
</CardGroup>


# Channel-aware Prompts
Source: https://docs.heylua.ai/concepts/channel-aware-prompts

Customize persona and skill instructions for voice vs text channels

## What Are Channel-aware Prompts?

Channel-aware prompts let you customize your agent's `persona` and skill `context` based on whether the user is interacting via **voice** or **text**.

This is rarely needed — the platform handles most channel-specific behavior automatically. But when you have genuinely different communication needs (e.g., conversational tone on voice, structured lists on text), this feature lets you optimize for each channel.

<Card title="Rule of thumb:" icon="lightbulb">
  If you need to ask "should I say this differently on voice vs text?", you probably don't need channel-aware prompts. Most agents should keep a simple string persona and context.
</Card>

## When to Use Channel-aware Prompts

Use the polymorphic form **only if you have a measurably different need**:

<CardGroup>
  <Card title="✅ Use it for:" icon="check">
    * Conversational tone on voice, structured formatting on text
    * Voice-specific instructions (e.g., "avoid markdown")
    * Text-specific instructions (e.g., "use ::: list-item blocks")
  </Card>

  <Card title="❌ Don't use it for:" icon="x">
    * Minor tweaks or polish
    * The same concept explained differently
    * Most agents (keep it simple)
  </Card>
</CardGroup>

## Syntax

Both `persona` and skill `context` accept the polymorphic form:

```typescript theme={null}
// String form (recommended)
persona: "You are Alex, a friendly customer support agent"

// Object form (channel-aware)
persona: {
  base: "You are Alex, a customer support agent.",
  voice: "Speak naturally and conversationally.",
  text: "Use ::: list-item blocks when showing options."
}
```

### Fields

* **`base`** — Shared across all channels (optional)
* **`voice`** — Voice-specific additions (optional, ignored on text)
* **`text`** — Text-specific additions (optional, ignored on voice)

**Strict semantics:** If a channel-specific key isn't set, it is not rendered. There is **no fallback** across channels.

<Note>
  **Validation:** The object must have at least one non-empty field. Empty objects (`{}`), empty strings (`""`), and objects whose only present fields are empty (`{ base: "" }`) are rejected at push time — pass `undefined` or omit the field entirely if you want no persona / context.
</Note>

## Examples

### Example 1: Customer Support Agent

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

const agent = new LuaAgent({
  name: 'support-agent',
  
  // Base persona shared across channels
  persona: {
    base: `You are Alex, customer support specialist for TechCorp.
You help users resolve issues and find solutions.

Core responsibilities:
- Answer product questions
- Troubleshoot issues
- Process refunds and returns
- Escalate complex issues`,
    
    voice: `Speak naturally and conversationally.
Use short, clear sentences.
Ask one question at a time.`,
    
    text: `For longer explanations, break them into ::: list-item blocks.
Use the ::: actions component to show next steps.
Be concise but thorough in writing.`
  },
  
  skills: [supportSkill]
});
```

On **voice**, the agent hears:

> "You are Alex... Speak naturally and conversationally. Use short, clear sentences..."

On **text**, the agent sees:

> "You are Alex... For longer explanations, break them into ::: list-item blocks..."

### Example 2: Hotel Booking Agent

```typescript theme={null}
const bookingSkill = new LuaSkill({
  name: 'hotel-booking',
  description: 'Book hotel rooms',
  
  context: {
    base: `Help guests find and book hotel rooms.

Key tools:
- check_availability: Find rooms by date and guest count
- create_reservation: Book a confirmed room
- cancel_reservation: Cancel existing booking`,
    
    voice: `When confirming details on a call, read them back naturally:
"So that's checking in on March 15, checking out on March 18, for 2 guests?"
Ask about special requests naturally (early check-in, late checkout, etc.)`,
    
    text: `After searching for availability, show results using ::: horizontal-list-item
blocks with images for each room. Include price, room type, and amenities.
Confirmation steps should use ::: actions component.`
  },
  
  tools: [checkAvailabilityTool, createReservationTool, cancelReservationTool]
});
```

### Example 3: Analytics Report Skill

```typescript theme={null}
const reportSkill = new LuaSkill({
  name: 'analytics-reports',
  description: 'Generate and share analytics reports',
  
  context: {
    base: `Provide analytics insights using generate_report and share_report tools.
Always ask for date range and metrics before generating.`,
    
    voice: `Speak results conversationally:
"Your revenue this month is $42,000, which is up 15% from last month.
The top product is Widget X with 2,500 units sold."`,
    
    text: `Display reports using ::: list-item components for each metric.
Show charts using ::: images component.
Use ::: links to export or share the report.`
  },
  
  tools: [generateReportTool, shareReportTool]
});
```

## Migration: From String to Object

If you start with a simple string and later realize you need channel-specific behavior, the migration is straightforward:

**Before:**

```typescript theme={null}
const agent = new LuaAgent({
  name: 'my-agent',
  persona: 'You are a helpful assistant.'
});
```

**After:**

```typescript theme={null}
const agent = new LuaAgent({
  name: 'my-agent',
  persona: {
    base: 'You are a helpful assistant.',
    voice: 'Speak conversationally.',
    text: 'Use structured formatting.'
  }
});
```

All existing string personas continue to work unchanged.

## Common Patterns

### Pattern 1: Base + Voice Only

When you only need voice customization (text uses the base):

```typescript theme={null}
persona: {
  base: "Core persona description",
  voice: "Additional voice-specific instructions"
  // text is omitted — uses base on text channels
}
```

On voice: `base + voice`\
On text: `base` (text field is not rendered)

### Pattern 2: Base + Text Only

When you only need text customization (voice uses the base):

```typescript theme={null}
context: {
  base: "General skill context",
  text: "Formatting instructions for text channels"
  // voice is omitted — uses base on voice channels
}
```

On voice: `base` (voice field is not rendered)\
On text: `base + text`

### Pattern 3: Base + Both Channels

Full customization for both channels:

```typescript theme={null}
persona: {
  base: "Shared core personality",
  voice: "Voice-specific tone",
  text: "Text-specific formatting"
}
```

On voice: `base + voice`\
On text: `base + text`

## Best Practices

<Steps>
  <Step title="Start simple">
    Write a single string persona first. Add channel-aware behavior only when you discover a real need.
  </Step>

  <Step title="Use base for shared content">
    Put the core agent personality and responsibilities in `base`. Use `voice` and `text` only for channel-specific nuances.
  </Step>

  <Step title="Voice: conversational">
    On voice, focus on natural language flow, short sentences, and oral clarity.
  </Step>

  <Step title="Text: structured">
    On text, leverage the ::: components (list-item, actions, links, etc.) for visual clarity.
  </Step>

  <Step title="Don't over-optimize">
    Remember: the platform handles 95% of channel-specific behavior for you (voice tone, text formatting rules, etc.). Only use this feature for cases where you genuinely need different core instructions.
  </Step>

  <Step title="Test both channels">
    When using channel-aware prompts, always test in both voice and text to ensure they work as intended.
  </Step>
</Steps>

## API Reference

See the `persona` field in [LuaAgent](/api/luaagent) and `context` field in [LuaSkill](/api/luaskill) for complete type signatures and examples.

## Next Steps

<CardGroup>
  <Card title="Persona Guide" icon="user" href="/overview/persona">
    Deep dive into creating effective personas
  </Card>

  <Card title="Skill Guide" icon="puzzle-piece" href="/overview/skill">
    Learn about skill design and context
  </Card>

  <Card title="Text Formatting" icon="text" href="/formatting/overview">
    ::: component syntax for text channels
  </Card>

  <Card title="Voice Channels" icon="microphone" href="/channels/voice">
    How voice calls work in Lua
  </Card>
</CardGroup>


# Environment Variables
Source: https://docs.heylua.ai/concepts/environment-variables

Managing configuration and secrets securely

## Overview

Environment variables allow you to configure your skills without hardcoding sensitive information like API keys.

<Warning>
  **Never hardcode secrets in your code!** Always use environment variables.
</Warning>

## Using Environment Variables

### Import the env Function

```typescript theme={null}
import { env } from 'lua-cli';

export class SendEmailTool implements LuaTool {
  async execute(input: any) {
    const apiKey = env('SENDGRID_API_KEY');
    const fromEmail = env('FROM_EMAIL') || 'noreply@example.com';
    
    if (!apiKey) {
      throw new Error('SENDGRID_API_KEY not configured');
    }
    
    // Use the API key...
  }
}
```

## Setting Environment Variables

<Note>
  **Quick Setup**: Use `lua env` command for an interactive interface to manage environment variables in both sandbox and production environments.

  ```bash theme={null}
  lua env
  ```
</Note>

There are two ways to set environment variables, loaded in this priority order:

<Steps>
  <Step title="System Environment">
    Variables from your system environment

    ```bash theme={null}
    export API_KEY=value
    ```
  </Step>

  <Step title=".env File">
    Variables from `.env` file in project root

    ```bash theme={null}
    # .env
    API_KEY=value
    ```
  </Step>
</Steps>

<Note>
  `.env` file overrides system environment variables. For production, use `lua env` command to manage variables on the server.
</Note>

## Method 1: .env File (Recommended for Development)

Create a `.env` file in your project root:

```bash theme={null}
# External API Keys
STRIPE_API_KEY=sk_test_abc123
SENDGRID_API_KEY=SG.xyz789
OPENAI_API_KEY=sk-abc123

# Configuration
API_BASE_URL=https://api.example.com
ENABLE_DEBUG=false
MAX_RETRIES=3
```

### .gitignore

<Warning>
  **Always add `.env` to `.gitignore`!**
</Warning>

```bash theme={null}
# .gitignore
.env
.env.local
.env.*.local
```

### .env.example

Create a `.env.example` file to document required variables:

```bash theme={null}
# .env.example
STRIPE_API_KEY=your_stripe_key_here
SENDGRID_API_KEY=your_sendgrid_key_here
API_BASE_URL=https://api.example.com
```

Commit `.env.example` to git, but never commit `.env`!

## Method 2: Interactive Command

Use the `lua env` command for an interactive interface:

<Steps>
  <Step title="Run Command">
    ```bash theme={null}
    lua env
    ```
  </Step>

  <Step title="Select Environment">
    Choose Sandbox (.env file) or Production (API)
  </Step>

  <Step title="Manage Variables">
    Add, update, delete, or view variables through interactive menu
  </Step>

  <Step title="Changes Saved">
    Variables are saved to `.env` (sandbox) or API (production)
  </Step>
</Steps>

<Card title="Complete Guide" icon="key" href="/cli/env-command">
  See full documentation for the `lua env` command
</Card>

## Example: External API Integration

### Stripe Payment Tool

```typescript theme={null}
import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

export default class CreatePaymentTool implements LuaTool {
  name = "create_payment";
  description = "Create a payment link for checkout";
  
  inputSchema = z.object({
    amount: z.number().positive(),
    currency: z.string().default('USD'),
    description: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get API key from environment
    const stripeKey = env('STRIPE_API_KEY');
    
    // Validate it exists
    if (!stripeKey) {
      throw new Error('STRIPE_API_KEY not configured. Please set it in .env or lua.skill.yaml');
    }
    
    // Use the key
    const response = await fetch('https://api.stripe.com/v1/checkout/sessions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${stripeKey}`,
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        'line_items[0][price_data][currency]': input.currency,
        'line_items[0][price_data][unit_amount]': (input.amount * 100).toString(),
        'line_items[0][price_data][product_data][name]': input.description,
        'line_items[0][quantity]': '1',
        'mode': 'payment',
        'success_url': 'https://example.com/success',
        'cancel_url': 'https://example.com/cancel'
      })
    });
    
    const session = await response.json();
    
    return {
      paymentUrl: session.url,
      sessionId: session.id
    };
  }
}
```

### .env File

```bash theme={null}
STRIPE_API_KEY=sk_test_51Abc123...
```

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Do: Use descriptive names">
    ```bash theme={null}
    # Good
    STRIPE_API_KEY=...
    SENDGRID_API_KEY=...
    WEATHER_API_KEY=...

    # Bad
    KEY1=...
    SECRET=...
    TOKEN=...
    ```
  </Accordion>

  <Accordion title="✅ Do: Provide defaults for non-secrets">
    ```typescript theme={null}
    const maxRetries = parseInt(env('MAX_RETRIES') || '3');
    const apiUrl = env('API_BASE_URL') || 'https://api.example.com';
    ```
  </Accordion>

  <Accordion title="✅ Do: Validate critical variables">
    ```typescript theme={null}
    const apiKey = env('STRIPE_API_KEY');
    if (!apiKey) {
      throw new Error('STRIPE_API_KEY is required');
    }
    ```
  </Accordion>

  <Accordion title="✅ Do: Document required variables">
    Create `.env.example` with all required variables and example values
  </Accordion>

  <Accordion title="❌ Don't: Hardcode secrets">
    ```typescript theme={null}
    // BAD!
    const apiKey = 'sk_test_abc123';

    // GOOD!
    const apiKey = env('API_KEY');
    ```
  </Accordion>

  <Accordion title="❌ Don't: Commit .env to git">
    Always add `.env` to `.gitignore`
  </Accordion>

  <Accordion title="❌ Don't: Log sensitive values">
    ```typescript theme={null}
    // BAD!
    console.log('API Key:', apiKey);

    // GOOD!
    console.log('API Key:', apiKey ? '***' : 'not set');
    ```
  </Accordion>
</AccordionGroup>

## Common Patterns

### Pattern: Required Variable

```typescript theme={null}
const apiKey = env('REQUIRED_KEY');
if (!apiKey) {
  throw new Error('REQUIRED_KEY environment variable is not set');
}
```

### Pattern: Optional with Default

```typescript theme={null}
const apiUrl = env('API_URL') || 'https://api.example.com';
const timeout = parseInt(env('TIMEOUT') || '5000');
const debug = env('DEBUG') === 'true';
```

### Pattern: Validation

```typescript theme={null}
const apiKey = env('API_KEY');
if (apiKey && !apiKey.startsWith('sk_')) {
  throw new Error('API_KEY must start with sk_');
}
```

### Pattern: Environment-Specific Configuration

```typescript theme={null}
const environment = env('NODE_ENV') || 'development';
const apiKey = environment === 'production' 
  ? env('PROD_API_KEY')
  : env('DEV_API_KEY');
```

## Testing with Environment Variables

### In lua test

Environment variables are automatically loaded from `.env` when you run:

```bash theme={null}
lua test
```

### In lua chat

Environment variables are loaded based on selected mode:

```bash theme={null}
lua chat
```

* **Sandbox mode**: Uses `.env` file
* **Production mode**: Uses production variables from server

## Troubleshooting

<AccordionGroup>
  <Accordion title="Variable not found">
    **Problem**: `env('MY_VAR')` returns `undefined`

    **Solutions**:

    1. Check spelling in `.env` file
    2. Ensure `.env` is in project root
    3. Restart `lua chat` if running
    4. For production, use `lua env` to verify variables on server
  </Accordion>

  <Accordion title="Changes not taking effect">
    **Problem**: Updated `.env` but changes not visible

    **Solution**: Restart the CLI command:

    ```bash theme={null}
    # Stop current process (Ctrl+C)
    lua chat  # Start again
    ```
  </Accordion>

  <Accordion title="Different values in dev vs production">
    **Problem**: Works locally but not when deployed

    **Solution**: Use `lua env` to manage production variables:

    ```bash theme={null}
    lua env  # Select Production mode
    # Add production API keys
    ```
  </Accordion>
</AccordionGroup>

## Example Project Structure

```
my-skill/
├── .env                    # Local secrets (not in git)
├── .env.example           # Template (in git)
├── .gitignore             # Contains .env
├── lua.skill.yaml         # Production config
├── src/
│   ├── index.ts
│   └── tools/
│       └── MyTool.ts      # Uses env('VAR_NAME')
└── package.json
```

## Next Steps

<CardGroup>
  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Use environment variables in a real project
  </Card>

  <Card title="Tool Examples" icon="layer-group" href="/examples/payment">
    See payment integration example
  </Card>
</CardGroup>


# Platform APIs
Source: https://docs.heylua.ai/concepts/platform-apis

Built-in APIs for common operations

## Overview

Lua CLI provides built-in APIs for common operations, so you don't have to build everything from scratch.

```typescript theme={null}
import { Agents, User, Data, CDN, Products, Baskets, Orders, Templates, Channels } from 'lua-cli';
```

<CardGroup>
  <Card title="Agents" icon="robot">
    Invoke the current agent or another agent through the full chat pipeline
  </Card>

  <Card title="User" icon="user">
    Per-user persistent storage for state, preferences, and workflow data
  </Card>

  <Card title="Data" icon="database">
    Custom data with vector search
  </Card>

  <Card title="CDN" icon="cloud">
    File upload and retrieval
  </Card>

  <Card title="Products" icon="box">
    E-commerce product catalog
  </Card>

  <Card title="Baskets" icon="cart-shopping">
    Shopping cart management
  </Card>

  <Card title="Orders" icon="receipt">
    Order processing
  </Card>

  <Card title="Templates" icon="message">
    Template messaging (WhatsApp)
  </Card>

  <Card title="Channels" icon="paper-plane">
    Send outbound messages on any connected channel
  </Card>
</CardGroup>

## Agents API

**Agent invocation from runtime code** — call the current agent or another agent through its full processing pipeline (billing, persistence, skills, tools, preprocessors, postprocessors) from any sandbox code. Use this inside Lua primitives; reserve `/chat/generate` and `/chat/stream` for external apps and services.

```typescript theme={null}
import { Agents } from 'lua-cli';

// Simplified — returns plain text
const reply = await Agents.invoke('support-agent', 'What is the refund policy?');

// Full options — returns structured output with usage and tool info
const result = await Agents.invoke('legal-agent', {
  prompt: 'Review this clause for risks.',
  threadId: 'contract-456',
  systemPrompt: 'Be concise.',
});
```

### Use Cases

<Tabs>
  <Tab title="Tool Routing">
    ```typescript theme={null}
    // Inside a tool — caller's user is used automatically
    const analysis = await Agents.invoke('data-analyst-agent', {
      prompt: `Analyse this dataset: ${JSON.stringify(data)}`,
      threadId: `analysis-${jobId}`,
    });
    return { report: analysis.text };
    ```
  </Tab>

  <Tab title="Webhook Delegation">
    ```typescript theme={null}
    // Inside a webhook — pass userId from the event payload
    execute: async (event) => {
      const { customerId, orderId } = event.body;
      await Agents.invoke('notification-agent', {
        prompt: `Order ${orderId} has shipped. Notify the customer.`,
        userId: customerId, // provide the user to run as
      });
      return { notified: true };
    }
    ```
  </Tab>

  <Tab title="Scheduled Job">
    ```typescript theme={null}
    // Inside a LuaJob — no ambient user, no conversation history stored
    execute: async (job) => {
      const result = await Agents.invoke('digest-agent', {
        prompt: 'Generate the daily digest.',
        // userId omitted — invocation runs without user identity
      });
      return { digest: result.text };
    }
    ```
  </Tab>
</Tabs>

<Card title="Full API Reference" icon="book" href="/api/agents">
  Complete Agents API documentation
</Card>

## User API

**Persistent per-user storage** that survives across conversations and sessions. Store any data — onboarding state, workflow progress, preferences, cart contents, verification results — as direct properties on the user object.

```typescript theme={null}
import { User } from 'lua-cli';

const user = await User.get();

// Write any property — it persists across conversations
user.onboardingStep = 'verified';
user.plan = 'enterprise';
user.collectedData = { company: 'Acme', role: 'admin' };
user.lastInteraction = new Date().toISOString();
await user.save();

// Read it back anytime (even days later, in a different conversation)
const returning = await User.get();
console.log(returning.onboardingStep); // 'verified'
console.log(returning.plan);           // 'enterprise'
```

### Example: Stateful Onboarding Tool

```typescript theme={null}
export class CheckOnboardingTool implements LuaTool {
  name = "check_onboarding";
  description = "Check and advance the user's onboarding progress";
  inputSchema = z.object({});

  async execute(input: any) {
    const user = await User.get();
    const step = user.onboardingStep || 'not_started';

    if (step === 'complete') {
      return { message: `Welcome back, ${user.name}! You're all set up.` };
    }

    return {
      currentStep: step,
      completedSteps: user.completedSteps || [],
      message: `You're on step: ${step}. Let's continue!`
    };
  }
}
```

<Card title="Full API Reference" icon="book" href="/api/user">
  Complete User API documentation
</Card>

## Data API

Store and retrieve custom data with semantic search capabilities.

### Key Features

* 🗄️ **Custom Collections**: Store any JSON data
* 🔍 **Vector Search**: Semantic similarity search
* 📊 **Filtering**: Query by field values
* 📄 **Pagination**: Handle large datasets

### Quick Example

```typescript theme={null}
import { Data } from 'lua-cli';

// Create with search indexing
await Data.create('movies', {
  title: 'Inception',
  director: 'Christopher Nolan',
  year: 2010
}, 'Inception Christopher Nolan 2010 sci-fi thriller dreams');

// Semantic search
const results = await Data.search('movies', 'mind-bending thriller', 10, 0.7);
// Finds "Inception" even though query doesn't contain exact words!
```

### Use Cases

<Tabs>
  <Tab title="Knowledge Base">
    ```typescript theme={null}
    await Data.create('kb_articles', {
      title: 'How to reset password',
      content: 'Step by step guide...',
      category: 'Account'
    }, `password reset account help`);

    const results = await Data.search('kb_articles', 
      'forgot my password', 10, 0.7);
    ```
  </Tab>

  <Tab title="Customer Notes">
    ```typescript theme={null}
    await Data.create('customers', {
      name: 'John Doe',
      company: 'Acme Corp',
      notes: 'Interested in enterprise plan'
    }, `John Doe Acme Corp enterprise`);

    const results = await Data.search('customers',
      'enterprise customers', 20, 0.6);
    ```
  </Tab>

  <Tab title="Product Recommendations">
    ```typescript theme={null}
    await Data.create('products', {
      name: 'Wireless Headphones',
      description: 'Noise cancelling...',
      category: 'Electronics'
    }, `wireless headphones noise cancelling bluetooth`);

    const results = await Data.search('products',
      'best headphones for travel', 5, 0.75);
    ```
  </Tab>
</Tabs>

<Note>
  Filtering large collections with `Data.get(collection, filter)`? Declare the
  filtered fields when storing — `Data.create(c, doc, { index: ['field'] })` —
  so the platform maintains an index for them. See
  [Data API — Indexes](/api/data#indexes).
</Note>

<Card title="Full API Reference" icon="book" href="/api/data">
  Complete Data API documentation
</Card>

## CDN API

Upload and retrieve files from the Lua CDN.

### Key Features

* 📤 **Upload Files**: Store any file type
* 📥 **Retrieve Files**: Get files by ID
* 🖼️ **Image Optimization**: Automatic WebP compression
* 🤖 **AI Integration**: Use with AI for image analysis

### Quick Example

```typescript theme={null}
import { CDN } from 'lua-cli';

// Upload a file
const file = new File([buffer], 'document.pdf', { type: 'application/pdf' });
const fileId = await CDN.upload(file);

// Retrieve by ID
const retrievedFile = await CDN.get(fileId);
console.log(retrievedFile.name); // 'document.pdf'
```

### Use Cases

<Tabs>
  <Tab title="Document Storage">
    ```typescript theme={null}
    // Store a document
    const doc = new File([content], 'report.pdf', { 
      type: 'application/pdf' 
    });
    const fileId = await CDN.upload(doc);

    // Save reference
    await Data.create('documents', {
      title: 'Q4 Report',
      fileId: fileId,
      uploadedAt: new Date().toISOString()
    });
    ```
  </Tab>

  <Tab title="Image Analysis">
    ```typescript theme={null}
    // Get image from CDN
    const file = await CDN.get(imageFileId);
    const buffer = Buffer.from(await file.arrayBuffer());

    // Analyze with AI
    const analysis = await AI.generate(
      'Describe this image.',
      [{ type: 'image', image: buffer, mediaType: file.type }]
    );
    ```
  </Tab>

  <Tab title="User Uploads">
    ```typescript theme={null}
    // Save user upload
    const file = new File([userData], 'profile.jpg', { 
      type: 'image/jpeg' 
    });
    const fileId = await CDN.upload(file);

    // Update user profile
    await User.update({ avatarFileId: fileId });
    ```
  </Tab>
</Tabs>

<Card title="Full API Reference" icon="book" href="/api/cdn">
  Complete CDN API documentation
</Card>

## Products API

Manage e-commerce product catalog.

```typescript theme={null}
import { Products } from 'lua-cli';

// Search products
const products = await Products.search('laptop');

// Create product
await Products.create({
  name: 'MacBook Pro',
  price: 1999.99,
  category: 'Computers',
  sku: 'MBP-14-001',
  inStock: true
});

// Get by ID
const product = await Products.getById('product_abc123');
```

<Card title="Full API Reference" icon="book" href="/api/products">
  Complete Products API documentation
</Card>

## Baskets API

Shopping cart management for e-commerce.

```typescript theme={null}
import { Baskets, BasketStatus } from 'lua-cli';

// Create basket
const basket = await Baskets.create({
  currency: 'USD',
  metadata: { source: 'web' }
});

// Add items
await Baskets.addItem(basket.id, {
  id: 'product_xyz',
  price: 29.99,
  quantity: 2,
  SKU: 'PROD-001'
});

// Checkout
const order = await Baskets.placeOrder({
  shippingAddress: {...},
  paymentMethod: 'stripe'
}, basket.id);
```

### Basket Statuses

<Tabs>
  <Tab title="ACTIVE">
    Currently being used for shopping
  </Tab>

  <Tab title="CHECKED_OUT">
    Converted to an order
  </Tab>

  <Tab title="ABANDONED">
    User left without checkout
  </Tab>

  <Tab title="EXPIRED">
    TTL exceeded
  </Tab>
</Tabs>

<Card title="Full API Reference" icon="book" href="/api/baskets">
  Complete Baskets API documentation
</Card>

## Orders API

Order creation and management.

```typescript theme={null}
import { Orders, OrderStatus } from 'lua-cli';

// Create order
const order = await Orders.create({
  basketId: 'basket_abc123',
  data: {
    shippingAddress: {...},
    paymentMethod: 'stripe'
  }
});

// Update status
await Orders.updateStatus(OrderStatus.FULFILLED, order.id);

// Get orders
const userOrders = await Orders.get(OrderStatus.PENDING);
```

### Order Statuses

<Steps>
  <Step title="PENDING">
    Created, not yet confirmed
  </Step>

  <Step title="CONFIRMED">
    Confirmed, being processed
  </Step>

  <Step title="FULFILLED">
    Completed and delivered
  </Step>

  <Step title="CANCELLED">
    Cancelled by user or system
  </Step>
</Steps>

<Card title="Full API Reference" icon="book" href="/api/orders">
  Complete Orders API documentation
</Card>

## Templates API

Send template messages across different channels. Currently supports WhatsApp templates. (Not to be confused with [Agent Templates](/marketplace/agent-templates), the marketplace's full agent blueprints.)

```typescript theme={null}
import { Templates } from 'lua-cli';

// List WhatsApp templates
const result = await Templates.whatsapp.list(channelId, { search: 'order' });

// Get specific template
const template = await Templates.whatsapp.get(channelId, templateId);

// Send template message
await Templates.whatsapp.send(channelId, templateId, {
  phoneNumbers: ['+447551166594'],
  values: {
    body: { customer_name: 'John', order_number: '12345' }
  }
});
```

### Use Cases

* 📦 **Order notifications** - Shipping updates, delivery confirmations
* 📅 **Appointment reminders** - Healthcare, salon, service bookings
* 🎉 **Marketing campaigns** - Promotions, announcements
* 🔐 **Authentication** - OTP codes, verification messages

<Card title="Full API Reference" icon="book" href="/api/templates">
  Complete Templates API documentation
</Card>

## Channels API

Send outbound messages on any channel your agent is connected to — WhatsApp, SMS, email, web chat, and more — from a tool, job, webhook, or trigger. Each send is recorded to the recipient's conversation thread so your agent stays coherent across replies.

```typescript theme={null}
import { Channels } from 'lua-cli';

// Free-form message (choose the channel)
await Channels.send({
  channel: 'whatsapp',
  to: { userId: 'user_123' },
  text: 'Your order has shipped!'
});

// Rich email
await Channels.email.send({
  to: { email: 'customer@example.com' },
  subject: 'Receipt',
  html: '<p>Thanks for your order!</p>'
});

// Approved WhatsApp template (start or re-open a conversation)
await Channels.whatsapp.sendTemplate({
  to: { phoneNumber: '+14155552671' },
  templateName: 'order_update',
  languageCode: 'en_US'
});
```

### Use Cases

* 🔔 **Proactive notifications** — order updates, reminders, follow-ups
* ⏰ **Scheduled outreach** — pair with [Jobs](/api/jobs) for time-based sends
* ✅ **Event confirmations** — send from a webhook the moment something happens

<Card title="Full API Reference" icon="book" href="/api/channels">
  Complete Channels API documentation
</Card>

## Combining APIs

Most real-world applications combine multiple APIs:

### E-commerce Flow Example

```typescript theme={null}
export class QuickCheckoutTool implements LuaTool {
  async execute(input: any) {
    // 1. Search for product
    const products = await Products.search(input.productName);
    const product = products.products[0];
    
    // 2. Create basket
    const basket = await Baskets.create({ currency: 'USD' });
    
    // 3. Add product
    await Baskets.addItem(basket.id, {
      id: product.id,
      price: product.price,
      quantity: input.quantity
    });
    
    // 4. Create order
    const order = await Baskets.placeOrder({
      shippingAddress: input.address,
      paymentMethod: 'stripe'
    }, basket.id);
    
    return {
      orderId: order.id,
      total: basket.common.totalAmount
    };
  }
}
```

### CRM with Custom Data Example

```typescript theme={null}
export class CreateCustomerTool implements LuaTool {
  async execute(input: any) {
    // Get current user
    const user = await User.get();
    
    // Create customer record
    const customer = await Data.create('customers', {
      name: input.name,
      email: input.email,
      company: input.company,
      createdBy: user.email,
      createdAt: new Date().toISOString()
    }, `${input.name} ${input.company} ${input.email}`);
    
    // Log interaction
    await Data.create('interactions', {
      customerId: customer.id,
      type: 'created',
      notes: 'Initial contact',
      timestamp: new Date().toISOString()
    });
    
    return { customerId: customer.id };
  }
}
```

## API Comparison

| API           | Best For                                      | Key Feature                                               |
| ------------- | --------------------------------------------- | --------------------------------------------------------- |
| **Agents**    | Self-invocation and multi-agent orchestration | Full pipeline invocation with auth & billing              |
| **User**      | Per-user persistent state                     | Schemaless key-value store across sessions                |
| **Data**      | Custom schemas                                | Vector search                                             |
| **CDN**       | File storage                                  | Upload/retrieve files                                     |
| **Products**  | E-commerce                                    | Pre-built catalog                                         |
| **Baskets**   | Shopping carts                                | TTL & status                                              |
| **Orders**    | Order tracking                                | Status workflow                                           |
| **Templates** | Bulk template sends                           | WhatsApp templates by channel ID                          |
| **Channels**  | Agent-initiated messaging                     | Outbound on any connected channel, recorded to the thread |

## Next Steps

<CardGroup>
  <Card title="API Reference" icon="book" href="/api/overview">
    Complete API documentation with examples
  </Card>

  <Card title="Tool Examples" icon="layer-group" href="/examples/overview">
    See working examples using all APIs
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Step-by-step tutorial
  </Card>

  <Card title="Environment Variables" icon="key" href="/concepts/environment-variables">
    Learn about configuration management
  </Card>
</CardGroup>


# Skills & Tools
Source: https://docs.heylua.ai/concepts/skills-and-tools

Understanding the core building blocks of Lua CLI

## What is Lua?

Lua is a platform for building AI agents with custom capabilities. Think of it like:

```
AI Agent (ChatGPT-like)
    └── Skills (Custom capabilities you build)
        └── Tools (Specific functions the AI can call)
```

## Skills

A **skill** is a collection of related tools that give your AI agent specific capabilities.

### Example: Coffee Shop Skill

```typescript theme={null}
import { LuaSkill } from "lua-cli";

const coffeeSkill = new LuaSkill({
  name: "coffee-shop-skill",
  description: "Coffee shop assistant with menu, ordering, and loyalty features",
  context: `
    This skill helps customers of Java Junction Coffee Shop.
    
    - Use show_menu to display available drinks and food
    - Use create_order to take customer orders
    - Use check_loyalty_points to show rewards balance
    - Use redeem_reward to apply loyalty discounts
    
    Always mention daily specials.
    Ask about size preferences for drinks.
  `,
  tools: [
    new ShowMenuTool(),
    new CreateOrderTool(),
    new CheckLoyaltyTool(),
    new RedeemRewardTool()
  ]
});
```

### Skill Properties

<ParamField type="string">
  Unique identifier for the skill (e.g., "coffee-shop-skill")
</ParamField>

<ParamField type="string">
  Brief description (1-2 sentences) of what the skill does
</ParamField>

<ParamField type="string">
  Detailed instructions for the AI on when and how to use the tools. This is critical for proper tool selection!
</ParamField>

<ParamField type="LuaTool[]">
  Array of tool instances to include in the skill
</ParamField>

<ParamField type="function">
  Optional async function that determines if the whole skill is available

  ```typescript theme={null}
  async condition(): Promise<boolean>
  ```

  When it returns `false` the skill's tools can't be called **and** its name, context, and tool names are left out of the agent's prompt — the agent doesn't know the capability exists. Use it for tiering and entitlements, where the existence of a feature is itself sensitive. Fail-closed: a condition that throws or times out hides the skill.

  See [Conditional Skills](/api/luaskill#conditional-skills) and [Skill condition vs tool condition](/api/luaskill#skill-condition-vs-tool-condition).
</ParamField>

### Writing Good Context

The `context` field guides the AI's decision-making. Write it like instructions to a smart assistant:

<CodeGroup>
  ```typescript Good Context theme={null}
  context: `
    This skill manages customer orders for a coffee shop.

    Tool Usage:
    - show_menu: Use when customers ask what's available. Returns drinks and food items.
    - create_order: Use when taking an order. Confirm items and sizes first.
    - modify_order: Use to add/remove items. Ask which item to modify.
    - finalize_order: Use when order is confirmed. Returns total and wait time.

    Guidelines:
    - Always ask about size for drinks (small/medium/large)
    - Mention daily special when showing menu
    - Confirm total before finalizing
    - Ask about dietary restrictions for food items
  `
  ```

  ```typescript Bad Context theme={null}
  context: "A skill with tools for stuff"
  ```
</CodeGroup>

## Tools

A **tool** is a single function that the AI can call to accomplish a specific task.

### Anatomy of a Tool

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class GetWeatherTool implements LuaTool {
  // Unique identifier (lowercase, alphanumeric, hyphens, underscores)
  name = "get_weather";
  
  // Clear description of what the tool does
  description = "Get current weather conditions for any city";
  
  // Zod schema defining valid inputs
  inputSchema = z.object({
    city: z.string().describe("City name (e.g., 'London', 'Tokyo')"),
    units: z.enum(['metric', 'imperial']).optional().default('metric')
  });

  // Async function that implements the logic
  async execute(input: z.infer<typeof this.inputSchema>) {
    // input is automatically validated and typed
    const { city, units } = input;
    
    // Call weather API
    const weather = await fetchWeather(city, units);
    
    // Return structured data
    return {
      temperature: weather.temp,
      condition: weather.condition,
      city: weather.location
    };
  }
}
```

### Tool Properties

<ParamField type="string">
  Unique identifier using only: `a-z`, `A-Z`, `0-9`, `-`, `_`

  Examples: `get_weather`, `create-product`, `sendEmail123`
</ParamField>

<ParamField type="string">
  Clear, concise description (1 sentence) of what the tool does

  Helps the AI understand when to use this tool
</ParamField>

<ParamField type="ZodType">
  Zod schema that validates inputs at runtime

  Provides automatic validation and TypeScript types
</ParamField>

<ParamField type="function">
  Async function that implements the tool's logic

  ```typescript theme={null}
  async execute(input: any): Promise<any>
  ```
</ParamField>

<ParamField type="function">
  Optional async function that determines if the tool should be available

  ```typescript theme={null}
  async condition(): Promise<boolean>
  ```

  Use for premium features, feature flags, channel-specific tools, or user-specific availability.

  A hidden tool is left out of the prompt's tool list, but the skill's name and context stay — the agent can still tell the user the capability exists. To hide a capability entirely, gate the skill instead: [Skill condition vs tool condition](/api/luaskill#skill-condition-vs-tool-condition).

  Access the current channel via `Lua.request.channel` and raw webhook data via `Lua.request.webhook?.payload` - see [Lua API](/api/lua).
</ParamField>

### Sharing Tool Logic Across Agents

When you build multiple agents that share behaviour — same search backend, same external API, same auth flow — factor the shared parts into a base class and have each agent declare a thin subclass that overrides only the bits that differ.

<Tabs>
  <Tab title="Shared base">
    ```typescript theme={null}
    // packages/shared/SearchKnowledgeBaseTool.ts
    import { LuaTool } from 'lua-cli';
    import { z } from 'zod';

    export abstract class SearchKnowledgeBaseTool implements LuaTool {
      name = 'search_knowledge_base';
      description = "Semantic search over the agent's knowledge base.";
      inputSchema = z.object({ query: z.string() });

      // Override this in subclasses to point at a specific backend.
      ragSearchPath: string = '/default/search';

      async execute(input: { query: string }) {
        const res = await fetch(`https://api.example.com${this.ragSearchPath}`, {
          method: 'POST',
          body: JSON.stringify({ q: input.query }),
        });
        return res.json();
      }
    }
    ```
  </Tab>

  <Tab title="Per-agent leaf">
    ```typescript theme={null}
    // agents/blackship/src/tools/BlackshipSearch.ts
    import { SearchKnowledgeBaseTool } from '@my-org/shared';

    export class BlackshipSearchTool extends SearchKnowledgeBaseTool {
      name = 'search_blackship';
      ragSearchPath = '/blk/search';
    }

    // agents/whitestar/src/tools/WhitestarSearch.ts
    export class WhitestarSearchTool extends SearchKnowledgeBaseTool {
      name = 'search_whitestar';
      description = 'Semantic search over Whitestar product docs.';
      ragSearchPath = '/wht/docs';
    }
    ```
  </Tab>

  <Tab title="Register the leaf">
    ```typescript theme={null}
    import { LuaSkill } from 'lua-cli';
    import { BlackshipSearchTool } from './tools/BlackshipSearch';

    export default new LuaSkill({
      name: 'support',
      description: 'Support tools',
      context: 'Use search_blackship to find product info.',
      tools: [BlackshipSearchTool],   // pass the class itself, not new BlackshipSearchTool()
    });
    ```
  </Tab>
</Tabs>

How it works:

* The `lua` compiler walks the full `extends` chain. A leaf that extends a shared base which itself extends `LuaTool` is detected as a tool.
* Field initializers on the leaf (`ragSearchPath = '/blk/search'`) override the parent's defaults. When `execute()` runs and reads `this.ragSearchPath`, it sees the leaf's value — JavaScript's normal inheritance semantics.
* The leaf inherits the parent's `inputSchema`, `description`, and `execute` unless it overrides them. No copy-paste.

<Warning>
  Don't pass per-reference constructor arguments inside a `tools: [...]` array:

  ```typescript theme={null}
  // ❌ The string argument is silently dropped — the compiler builds
  //    one shared tool artifact per project, reused across every reference.
  tools: [new BlackshipSearchTool('/blk/search')]
  ```

  The compiler will warn (`lua/constructor-args-dropped`) if it sees this pattern. Use a subclass with a field override instead.
</Warning>

## Skills vs Tools

<Tabs>
  <Tab title="Tool">
    **Single Function**

    ```typescript theme={null}
    // One specific thing
    class GetWeatherTool {
      // Gets weather for a city
    }
    ```
  </Tab>

  <Tab title="Skill">
    **Collection of Tools**

    ```typescript theme={null}
    // Multiple related things
    new LuaSkill({
      tools: [
        new GetWeatherTool(),
        new GetForecastTool(),
        new GetAlertstool()
      ]
    });
    ```
  </Tab>
</Tabs>

## How It Works

<Steps>
  <Step title="User Request">
    User asks the AI: "What's the weather in London?"
  </Step>

  <Step title="Tool Selection">
    AI reads the skill's `context` and determines `get_weather` tool is appropriate
  </Step>

  <Step title="Input Validation">
    AI provides input: `{ city: "London" }`

    Input is validated against `inputSchema`
  </Step>

  <Step title="Tool Execution">
    The `execute` function runs with validated input

    Calls weather API and returns structured data
  </Step>

  <Step title="AI Response">
    AI uses the tool's output to form a natural language response

    "The weather in London is 15°C and cloudy."
  </Step>
</Steps>

## Tool Naming Best Practices

<CardGroup>
  <Card title="Good Names" icon="check">
    * `search_products`
    * `create_order`
    * `cancel_booking`
    * `get_user_profile`
  </Card>

  <Card title="Bad Names" icon="xmark">
    * `do_search` (too generic)
    * `process` (unclear)
    * `tool1` (not descriptive)
    * `get data` (spaces not allowed)
  </Card>
</CardGroup>

## Creating Your Agent

You configure your entire agent using `LuaAgent`:

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

// Create your skill
const coffeeSkill = new LuaSkill({
  name: "coffee-shop-skill",
  description: "Coffee shop assistant",
  tools: [/* your tools */]
});

// Create agent
export const agent = new LuaAgent({
  name: "coffee-assistant",
  
  persona: `You are a friendly barista at Java Junction Coffee Shop.
  
Your role:
- Help customers browse the menu
- Take and confirm orders
- Suggest popular items
- Answer questions about ingredients

Communication style:
- Warm and welcoming
- Enthusiastic about coffee
- Patient and helpful
- Always mention daily specials`,

  
  skills: [coffeeSkill]
});
```

<Note>
  Use `LuaAgent` to configure persona, welcome message, and skills together in one unified configuration.
</Note>

### Why LuaAgent?

The new LuaAgent pattern provides:

* ✅ **Single source of truth** - All agent config in one place (code, not YAML)
* ✅ **Better organization** - Clear separation of persona, skills, webhooks, jobs
* ✅ **Auto-sync** - CLI auto-manages `lua.skill.yaml` (do not edit manually)
* ✅ **More features** - Support for webhooks, jobs, preprocessors, postprocessors

## Multiple Skills in One Project

You can organize tools into multiple skills and add them all to your agent:

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

// Product browsing skill
const catalogSkill = new LuaSkill({
  name: "product-catalog-skill",
  description: "Product browsing and search",
  tools: [
    new SearchProductsTool(),
    new GetProductTool()
  ]
});

// Shopping skill
const shoppingSkill = new LuaSkill({
  name: "shopping-skill",
  description: "Shopping cart management",
  tools: [
    new CreateBasketTool(),
    new AddItemTool()
  ]
});

// Order fulfillment skill
const orderSkill = new LuaSkill({
  name: "order-skill",
  description: "Order creation and tracking",
  tools: [
    new CreateOrderTool(),
    new TrackOrderTool()
  ]
});

// Create agent with all skills
export const agent = new LuaAgent({
  name: "ecommerce-assistant",
  persona: "You are a helpful e-commerce shopping assistant...",
  skills: [catalogSkill, shoppingSkill, orderSkill]
});
```

### When to Use Multiple Skills

<Tabs>
  <Tab title="Use Multiple When">
    * ✅ Tools serve different purposes (e.g., "HR Skill" vs "Sales Skill")
    * ✅ Different teams own different skills
    * ✅ Skills have different deployment schedules
    * ✅ Skills need different permissions
  </Tab>

  <Tab title="Use Single When">
    * ✅ Tools work together closely
    * ✅ Small to medium number of tools (\< 20)
    * ✅ All tools deploy together
  </Tab>
</Tabs>

## Example Patterns

### Pattern: CRUD Skill

```typescript theme={null}
const dataSkill = new LuaSkill({
  name: "data-management-skill",
  description: "Complete CRUD operations",
  tools: [
    new CreateTool(),
    new ReadTool(),
    new UpdateTool(),
    new DeleteTool(),
    new SearchTool()
  ]
});
```

### Pattern: Workflow Skill

```typescript theme={null}
const checkoutSkill = new LuaSkill({
  name: "checkout-skill",
  description: "Complete purchase workflow",
  tools: [
    new CreateBasketTool(),    // Step 1: Create cart
    new AddItemsTool(),        // Step 2: Add items
    new ReviewCartTool(),      // Step 3: Review
    new ApplyDiscountTool(),   // Step 4: Apply discounts
    new ProcessPaymentTool()   // Step 5: Complete
  ]
});
```

### Pattern: Integration Skill

```typescript theme={null}
const integrationSkill = new LuaSkill({
  name: "external-integrations-skill",
  description: "Third-party service integrations",
  tools: [
    new SendEmailTool(),      // SendGrid
    new ProcessPaymentTool(), // Stripe
    new GetWeatherTool(),     // Weather API
    new TrackShipmentTool()   // Shipping API
  ]
});
```

## Next Steps

<CardGroup>
  <Card title="Platform APIs" icon="plug" href="/concepts/platform-apis">
    Learn about built-in APIs for users, products, and data
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Follow a step-by-step tutorial
  </Card>

  <Card title="Tool Examples" icon="layer-group" href="/examples/overview">
    Explore 30+ working examples
  </Card>

  <Card title="API Reference" icon="book" href="/api/luaskill">
    Complete LuaSkill API documentation
  </Card>
</CardGroup>


# Development Workflows
Source: https://docs.heylua.ai/concepts/workflows

Best practices for developing, testing, and deploying skills

## Development Lifecycle

<Steps>
  <Step title="Configure Environment">
    Set up environment variables

    ```bash theme={null}
    lua env
    ```

    Add API keys and configuration for sandbox
  </Step>

  <Step title="Configure Persona">
    Define your agent's personality

    ```bash theme={null}
    lua persona
    ```

    Edit persona in sandbox mode
  </Step>

  <Step title="Local Development">
    Build and test your skills locally

    ```bash theme={null}
    lua chat
    ```

    Use sandbox mode for testing
  </Step>

  <Step title="Testing">
    Test conversational flows and individual tools

    ```bash theme={null}
    lua chat  # Primary testing
    lua test  # Optional: Test specific tools
    ```
  </Step>

  <Step title="Push to Server">
    Upload your skill version to the server

    ```bash theme={null}
    lua push
    ```
  </Step>

  <Step title="Sandbox Testing">
    Test in sandbox environment before production

    ```bash theme={null}
    lua chat
    ```

    Choose sandbox mode when prompted
  </Step>

  <Step title="Deploy to Production">
    Make your skill available to all users

    ```bash theme={null}
    lua deploy
    ```
  </Step>
</Steps>

## Local Development Workflow

### Starting Development

Start by syncing with the server to get any remote changes:

```bash theme={null}
# Check for drift between server and local code
lua sync

# Test individual tools
lua test

# Test conversational flows
lua chat
```

**lua test** - Test tools one at a time with specific inputs

**lua chat** - Interactive conversation testing in sandbox or production

### The Development Loop

<Tabs>
  <Tab title="Edit">
    Edit files in `src/tools/`:

    ```typescript theme={null}
    // src/tools/MyTool.ts
    export default class MyTool implements LuaTool {
      name = "my_tool";
      description = "Updated description";
      
      async execute(input: any) {
        // Your changes here
      }
    }
    ```
  </Tab>

  <Tab title="Test Tools">
    Test individual tools:

    ```bash theme={null}
    lua test
    ```

    * Select tool from list
    * Enter test inputs
    * Verify output
  </Tab>

  <Tab title="Test Chat">
    Test conversational flows:

    ```bash theme={null}
    lua chat
    ```

    * Choose sandbox mode
    * Chat naturally with agent
    * Verify tool selection and execution
  </Tab>

  <Tab title="Iterate">
    Repeat: Edit → Test → Refine

    Test until satisfied with results
  </Tab>
</Tabs>

### Testing Features

<CardGroup>
  <Card title="Tool Testing" icon="flask">
    Test individual tools with specific inputs
  </Card>

  <Card title="Chat Testing" icon="comments">
    Test conversational flows and tool selection
  </Card>

  <Card title="Sandbox Mode" icon="sandbox">
    Test with local changes before deploying
  </Card>

  <Card title="Production Validation" icon="check">
    Verify deployed changes work correctly
  </Card>
</CardGroup>

## Testing Workflow

### Interactive Tool Testing

Test individual tools with specific inputs:

```bash theme={null}
lua test
```

<Steps>
  <Step title="Select Tool">
    Choose from list of available tools
  </Step>

  <Step title="Enter Inputs">
    Provide values based on tool's schema
  </Step>

  <Step title="View Results">
    See execution results or errors
  </Step>

  <Step title="Iterate">
    Fix issues and test again
  </Step>
</Steps>

### Conversational Testing

Test how the AI uses your tools in natural conversation:

```bash theme={null}
lua chat
```

Select **Sandbox mode** to test with your local changes.

**Test Scenarios:**

<AccordionGroup>
  <Accordion title="Happy Path">
    Test the ideal user journey

    * "Show me products"
    * "Add laptop to cart"
    * "Checkout"
  </Accordion>

  <Accordion title="Edge Cases">
    Test unusual but valid inputs

    * Empty results
    * Maximum values
    * Optional parameters
  </Accordion>

  <Accordion title="Error Handling">
    Test invalid inputs

    * Missing required fields
    * Invalid data types
    * Out of range values
  </Accordion>

  <Accordion title="Multi-Step Flows">
    Test complex workflows

    * Create → Add → Update → Delete
    * Search → Select → Checkout
  </Accordion>
</AccordionGroup>

## Version Management

### Semantic Versioning

Use semantic versioning: `MAJOR.MINOR.PATCH`

```yaml theme={null}
# lua.skill.yaml (version is the ONLY field you should manually edit)
skills:
  - name: my-skill
    version: 1.2.3
```

<Note>
  The `lua.skill.yaml` file is auto-managed by the CLI. The **version number** is the only field you should manually edit when preparing a new release. All other fields are managed automatically.
</Note>

**When to increment:**

<Tabs>
  <Tab title="PATCH (1.2.3 → 1.2.4)">
    Bug fixes and minor improvements

    * Fixed error handling
    * Updated descriptions
    * Performance improvements
  </Tab>

  <Tab title="MINOR (1.2.3 → 1.3.0)">
    New features, backward compatible

    * Added new tool
    * New optional parameters
    * Enhanced functionality
  </Tab>

  <Tab title="MAJOR (1.2.3 → 2.0.0)">
    Breaking changes

    * Removed tool
    * Changed required parameters
    * Renamed tools
  </Tab>
</Tabs>

### Pushing Versions

```bash theme={null}
# Increment version in lua.skill.yaml (only field you should edit):
# skills:
#   - name: my-skill
#     version: 1.1.0

# Push to server
lua push
```

Each push creates a new version that can be deployed independently.

## Advanced Agent Features

Beyond skills and tools, lua-cli supports webhooks, jobs, and message processing:

### LuaAgent Configuration

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaWebhook, LuaJob, PreProcessor, PostProcessor } from 'lua-cli';

export const agent = new LuaAgent({
  name: "my-agent",
  persona: "You are a helpful assistant...",
  
  // Skills with tools
  skills: [skill1, skill2],
  
  // HTTP endpoints for external events
  webhooks: [stripeWebhook, shopifyWebhook],
  
  // Scheduled tasks
  jobs: [dailyReportJob, cleanupJob],
  
  // Message filtering before agent
  preProcessors: [profanityFilter, rateLimiter],
  
  // Response formatting after agent
  postProcessors: [addDisclaimer, addBranding]
});
```

### Webhooks

Receive events from external services:

```typescript theme={null}
import { LuaWebhook } from 'lua-cli';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  execute: async (event) => {
    if (event.type === 'payment.succeeded') {
      // Handle payment confirmation
    }
  }
});
```

**Test webhooks:**

```bash theme={null}
lua test
# Select: Webhook → payment-webhook
```

### Jobs

Schedule automated tasks:

```typescript theme={null}
import { LuaJob, User } from 'lua-cli';

const dailyReportJob = new LuaJob({
  name: 'daily-report',
  metadata: {
    userId: 'user_abc123'  // who to notify — pre-defined jobs have no conversation context
  },
  schedule: {
    type: 'cron',
    expression: '0 9 * * *'  // Every day at 9 AM
  },
  execute: async (job) => {
    // Pre-defined LuaJob runs outside any conversation, so look the user up by ID.
    // (jobInstance.user() is only available on dynamic jobs created via the Jobs API.)
    const user = await User.get(job.metadata.userId);
    await user.send([{
      type: 'text',
      text: 'Your daily report is ready!'
    }]);
  }
});
```

### PreProcessors

Filter messages before they reach your agent:

```typescript theme={null}
import { PreProcessor } from 'lua-cli';

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Filter inappropriate content',
  execute: async (user, messages, channel) => {
    const text = messages.map(m => m.type === 'text' ? m.text : '').join(' ');
    if (containsProfanity(text)) {
      return {
        action: 'block',
        response: "Please keep the conversation respectful."
      };
    }
    return { action: 'proceed' };
  }
});
```

### PostProcessors

Format responses after agent generation:

```typescript theme={null}
import { PostProcessor } from 'lua-cli';

const addDisclaimer = new PostProcessor({
  name: 'add-disclaimer',
  description: 'Add legal disclaimer to responses',
  execute: async (user, message, response, channel) => {
    return {
      modifiedResponse: response + "\n\n_This is AI-generated content._"
    };
  }
});
```

**Learn more:**

* [LuaAgent API](/api/luaagent)
* [LuaWebhook API](/api/luawebhook)
* [LuaJob API](/api/luajob)
* [PreProcessor API](/api/preprocessor)
* [PostProcessor API](/api/postprocessor)

## Deployment Workflow

### Sandbox Testing

Before deploying to production, test in sandbox:

```bash theme={null}
# Push latest version
lua push

# Test in sandbox
lua chat

# Select sandbox mode when prompted
# Verify everything works
```

### Deploying to Production

When ready, deploy to all users:

```bash theme={null}
lua deploy
```

<Steps>
  <Step title="Select Version">
    Choose which version to deploy from list
  </Step>

  <Step title="Confirm">
    Confirm the deployment (shows warning)
  </Step>

  <Step title="Deploy">
    Version is deployed to production
  </Step>

  <Step title="Verify">
    Test with real users or in production chat
  </Step>
</Steps>

<Warning>
  **Deployment is immediate!** If `lua deploy` reports success, that exact code serves the very next invocation of the agent (allow up to roughly a minute for edge caches to catch up). All users will get the new version right away.
</Warning>

<Note>
  `lua deploy` activates one primitive at a time. Once your agent has an agent version already promoted, `lua deploy` performs a **scoped promote**: it creates and promotes a new agent version identical to the current one except for the primitive you just deployed, so your agent-version history stays consistent. For releases that touch several primitives at once, prefer [`lua version create` + `lua version promote`](/cli/version-command) — it snapshots and atomically activates everything together, with no mixed-version window. Sandbox testing (`lua chat`, `lua test`) never affects what's live.
</Note>

## Best Practices

### Development

<Tabs>
  <Tab title="Start Simple">
    Build one tool at a time

    * Create basic version
    * Test thoroughly
    * Add complexity gradually
  </Tab>

  <Tab title="Test Iteratively">
    Test changes quickly

    * Use `lua test` for tool logic
    * Use `lua chat` for conversations
    * Iterate based on results
  </Tab>

  <Tab title="Test Edge Cases">
    Don't just test happy paths

    * Invalid inputs
    * Empty results
    * Error conditions
  </Tab>
</Tabs>

### Version Control

<CodeGroup>
  ```bash .gitignore theme={null}
  # Always ignore
  .env
  .env.local
  node_modules/
  dist/
  .lua/

  # Keep these
  .env.example
  lua.skill.yaml
  src/
  ```

  ```bash Commit Messages theme={null}
  # Good commit messages
  git commit -m "feat: add search functionality to products"
  git commit -m "fix: handle empty basket in checkout"
  git commit -m "docs: update tool descriptions"
  ```
</CodeGroup>

### Testing

<AccordionGroup>
  <Accordion title="Test Before Pushing">
    Always test locally before pushing:

    ```bash theme={null}
    lua test  # Test tools
    lua chat  # Test conversations (sandbox mode)
    lua push  # Then push
    ```
  </Accordion>

  <Accordion title="Test in Sandbox">
    Test pushed versions in sandbox before deploying:

    ```bash theme={null}
    lua push
    lua chat  # Choose sandbox mode
    # If good, then deploy
    lua deploy
    ```
  </Accordion>

  <Accordion title="Document Test Cases">
    Keep a list of test scenarios:

    * Happy path flows
    * Edge cases to verify
    * Known issues to watch for
  </Accordion>
</AccordionGroup>

### Deployment

<Warning>
  **Pre-Deployment Checklist:**

  * ✅ Synced with server: `lua sync`
  * ✅ Tested all tools with `lua test`
  * ✅ Tested conversational flows with `lua chat`
  * ✅ Updated version number
  * ✅ Updated tool descriptions
  * ✅ Checked error messages
  * ✅ Tested in sandbox mode
  * ✅ Verified environment variables
</Warning>

## Common Workflows

### Quick Fix Workflow

```bash theme={null}
# 1. Make the fix
vim src/tools/MyTool.ts

# 2. Test locally
lua test

# 3. Push and deploy
lua push
lua deploy
```

### Feature Development Workflow

```bash theme={null}
# 1. Create feature branch
git checkout -b feature/new-tool

# 2. Develop and test
lua test  # Test tool logic
lua chat  # Test in conversation

# 3. Test thoroughly
lua test  # All tools
lua chat  # All scenarios

# 4. Commit changes
git add .
git commit -m "feat: add new tool"

# 5. Push to server
lua push

# 6. Merge to main
git checkout main
git merge feature/new-tool

# 7. Deploy to production
lua deploy
```

### Multi-Developer Workflow

```bash theme={null}
# Developer 1: Working on Skill A
cd skill-a
lua sync  # Get any changes from teammates
lua test
lua chat  # Independent sandbox

# Developer 2: Working on Skill B
cd skill-b
lua sync  # Get any changes from teammates
lua test
lua chat  # Independent sandbox

# Each developer has independent sandbox
# Sync helps prevent conflicts when deploying
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Chat not working">
    **Problem**: Cannot start chat session

    **Solutions**:

    1. Run `lua auth configure` to set up API key
    2. Ensure `lua.skill.yaml` exists (run `lua init`)
    3. Deploy skills with `lua push` before using sandbox
    4. Check network connection
  </Accordion>

  <Accordion title="Skills not appearing in sandbox">
    **Problem**: Local changes not reflected

    **Solutions**:

    1. Ensure you selected "Sandbox" mode
    2. Check compilation succeeded
    3. Verify skills pushed to sandbox successfully
    4. Try running `lua push` first
  </Accordion>

  <Accordion title="Deploy showing old version">
    **Problem**: Deployed but still seeing old behavior

    **Solutions**:

    1. Verify correct version was deployed
    2. Check `lua.skill.yaml` version number
    3. Test in production mode with `lua chat`
    4. Check if deploy actually succeeded
  </Accordion>

  <Accordion title="Can't push - version exists">
    **Problem**: Version already pushed to server

    **Solution**: Increment version number:

    ```yaml theme={null}
    skills:
      - name: my-skill
        version: 1.0.1  # Increment this
    ```
  </Accordion>

  <Accordion title="Drift detected during compile">
    **Problem**: Server has different persona/name than local code

    **Solutions**:

    1. Run `lua sync` to see the diff and choose action
    2. Use `lua sync --accept` to auto-update from server
    3. Use `lua sync --push` to push local changes to server

    **Note**: By default, `lua compile` does NOT check for drift. Use `lua compile --sync` to enable drift detection.

    This happens when someone updated the agent from the admin dashboard.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="AI Agent Building Guide" icon="robot" href="/ai-guide">
    Complete workflow for AI IDEs (Cursor, Windsurf, Copilot)
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Complete command documentation
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Follow a complete tutorial
  </Card>

  <Card title="Non-Interactive Mode" icon="code" href="/cli/non-interactive-mode">
    Automate commands for CI/CD and scripting
  </Card>

  <Card title="Version Command" icon="code-branch" href="/cli/version-command">
    Atomic agent versions, promote, rollback, and version status
  </Card>
</CardGroup>


# Customer Support Agent
Source: https://docs.heylua.ai/demos/customer-support

Support automation with Zendesk API + Lua vector search

## Overview

AI-powered customer support that integrates with **Zendesk** for ticketing and **Lua Data API** for knowledge base search.

**What it does:**

* Search knowledge base with semantic search
* Create support tickets in Zendesk
* Check ticket status
* Answer common questions
* Escalate to human agents

**APIs used:** Zendesk API (external) + Lua Data API (vector search)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaWebhook, LuaJob } from "lua-cli";
import {
  SearchKnowledgeBaseTool,
  CreateTicketTool,
  GetTicketStatusTool,
  UpdateTicketTool
} from "./tools/SupportTools";

// Support skill
const supportSkill = new LuaSkill({
  name: "customer-support",
  description: "AI-powered customer support with ticketing and knowledge base",
  context: `
    This skill provides customer support.
    
    - search_knowledge_base: Use first to find answers in documentation
    - create_ticket: Create Zendesk ticket if knowledge base can't help
    - get_ticket_status: Check status of existing tickets
    - update_ticket: Add information to existing tickets
    
    Always search knowledge base before creating tickets.
    Be empathetic and professional.
    Escalate complex issues to human agents.
  `,
  tools: [
    new SearchKnowledgeBaseTool(),
    new CreateTicketTool(),
    new GetTicketStatusTool(),
    new UpdateTicketTool()
  ]
});

// Zendesk webhook for ticket updates
const zendeskWebhook = new LuaWebhook({
  name: 'zendesk-webhook',
  description: 'Handle Zendesk ticket update events',
  secret: env('ZENDESK_WEBHOOK_SECRET'),
  execute: async (event) => {
    if (event.type === 'ticket.solved') {
      // Get user ID from ticket metadata
      const userId = event.data.custom_fields?.lua_user_id;
      
      if (userId) {
        const user = await User.get(userId);
        await user.send([{
          type: 'text',
          text: `✅ Your support ticket #${event.data.id} has been resolved! We hope we were able to help.`
        }]);
      }
    }
    return { received: true };
  }
});

// Daily follow-up job for open tickets
const ticketFollowUpJob = new LuaJob({
  name: 'ticket-followup',
  description: 'Send follow-up messages for open tickets',
  schedule: {
    type: 'cron',
    pattern: '0 10 * * *'  // Daily at 10 AM
  },
  execute: async (job) => {
    const tickets = await Data.search('support_tickets', 'status:open', 50);
    const user = await job.user();
    
    if (tickets.length > 0) {
      await user.send([{
        type: 'text',
        text: `You have ${tickets.length} open support ticket(s). Need any updates?`
      }]);
    }
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "support-agent",
  
  persona: `You are Alex, a customer support specialist.
  
Your role:
- Help customers find answers to their questions
- Search the knowledge base for solutions
- Create support tickets when needed
- Track and update existing tickets
- Provide empathetic and professional support

Communication style:
- Patient and empathetic
- Clear and professional
- Solution-oriented
- Reassuring and supportive

Workflow:
1. First, search the knowledge base for answers
2. If no solution found, offer to create a ticket
3. For existing tickets, help track status
4. For urgent issues, escalate to priority support

Best practices:
- Always search knowledge base first
- Gather all details before creating tickets
- Set realistic expectations for response times
- Thank customers for their patience
- Confirm resolution before closing

When to escalate:
- Billing disputes over $500
- Account security issues
- Legal or compliance matters
- VIP customer requests`,

  
  skills: [supportSkill],
  webhooks: [zendeskWebhook],
  jobs: [ticketFollowUpJob]
});
```

<Note>
  This demo uses `LuaAgent` with webhooks for Zendesk events and scheduled jobs for ticket follow-ups.
</Note>

### src/tools/SupportTools.ts

```typescript theme={null}
import { LuaTool, Data, env } from "lua-cli";
import { z } from "zod";

// 1. Search Knowledge Base (Lua Data with Vector Search)
export class SearchKnowledgeBaseTool implements LuaTool {
  name = "search_knowledge_base";
  description = "Search help articles and documentation";
  
  inputSchema = z.object({
    query: z.string().describe("User's question or search query")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Use Lua's vector search for semantic matching
    const results = await Data.search(
      'help_articles',
      input.query,
      5,
      0.7
    );
    
    if (results.length === 0) {
      return {
        articles: [],
        message: "No articles found. Would you like to create a support ticket?"
      };
    }
    
    return {
      articles: results.map(entry => ({
        id: entry.id,
        title: entry.title,
        content: entry.content.substring(0, 300) + '...',
        category: entry.category,
        relevance: `${Math.round(entry.score * 100)}% match`,
        url: entry.url
      })),
      count: results.length,
      message: `Found ${results.length} helpful articles`
    };
  }
}

// 2. Create Zendesk Ticket (External API)
export class CreateTicketTool implements LuaTool {
  name = "create_ticket";
  description = "Create a support ticket in Zendesk";
  
  inputSchema = z.object({
    subject: z.string().describe("Ticket subject/summary"),
    description: z.string().describe("Detailed description of the issue"),
    priority: z.enum(['low', 'normal', 'high', 'urgent']).default('normal'),
    customerEmail: z.string().email().describe("Customer's email address"),
    customerName: z.string().describe("Customer's name")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const zendeskKey = env('ZENDESK_API_KEY');
    const zendeskSubdomain = env('ZENDESK_SUBDOMAIN');
    
    if (!zendeskKey || !zendeskSubdomain) {
      throw new Error('Zendesk API credentials not configured');
    }
    
    // Create ticket in Zendesk
    const response = await fetch(
      `https://${zendeskSubdomain}.zendesk.com/api/v2/tickets.json`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Basic ${Buffer.from(`${input.customerEmail}/token:${zendeskKey}`).toString('base64')}`
        },
        body: JSON.stringify({
          ticket: {
            subject: input.subject,
            description: input.description,
            priority: input.priority,
            requester: {
              name: input.customerName,
              email: input.customerEmail
            },
            tags: ['ai_created', 'chat']
          }
        })
      }
    );
    
    if (!response.ok) {
      throw new Error(`Failed to create ticket: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    // Also log ticket in Lua Data for our records
    await Data.create('support_tickets', {
      zendeskId: data.ticket.id,
      subject: input.subject,
      customerEmail: input.customerEmail,
      priority: input.priority,
      createdAt: new Date().toISOString()
    }, `${input.subject} ${input.description}`);
    
    return {
      success: true,
      ticketId: data.ticket.id,
      ticketUrl: data.ticket.url,
      message: `Ticket #${data.ticket.id} created. We'll respond within 24 hours.`
    };
  }
}

// 3. Get Ticket Status (External API)
export class GetTicketStatusTool implements LuaTool {
  name = "get_ticket_status";
  description = "Check the status of a support ticket";
  
  inputSchema = z.object({
    ticketId: z.string().describe("Ticket ID")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const zendeskKey = env('ZENDESK_API_KEY');
    const zendeskSubdomain = env('ZENDESK_SUBDOMAIN');
    
    // Get ticket from Zendesk
    const response = await fetch(
      `https://${zendeskSubdomain}.zendesk.com/api/v2/tickets/${input.ticketId}.json`,
      {
        headers: {
          'Authorization': `Basic ${Buffer.from(`${env('ZENDESK_EMAIL')}/token:${zendeskKey}`).toString('base64')}`
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`Ticket not found: ${input.ticketId}`);
    }
    
    const data = await response.json();
    const ticket = data.ticket;
    
    return {
      ticketId: ticket.id,
      subject: ticket.subject,
      status: ticket.status,
      priority: ticket.priority,
      createdAt: new Date(ticket.created_at).toLocaleDateString(),
      updatedAt: new Date(ticket.updated_at).toLocaleDateString(),
      assignee: ticket.assignee_id ? 'Assigned to support agent' : 'Not yet assigned',
      message: this.getStatusMessage(ticket.status)
    };
  }
  
  private getStatusMessage(status: string): string {
    const messages = {
      new: "Your ticket is in queue and will be reviewed shortly",
      open: "Our team is currently working on your ticket",
      pending: "Waiting for your response",
      solved: "This ticket has been resolved",
      closed: "This ticket is closed"
    };
    return messages[status] || "Status unknown";
  }
}

// 4. Update Ticket (External API)
export class UpdateTicketTool implements LuaTool {
  name = "update_ticket";
  description = "Add a comment or update to an existing ticket";
  
  inputSchema = z.object({
    ticketId: z.string(),
    comment: z.string().describe("Additional information or update")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const zendeskKey = env('ZENDESK_API_KEY');
    const zendeskSubdomain = env('ZENDESK_SUBDOMAIN');
    
    // Add comment to ticket
    const response = await fetch(
      `https://${zendeskSubdomain}.zendesk.com/api/v2/tickets/${input.ticketId}.json`,
      {
        method: 'PUT',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Basic ${Buffer.from(`${env('ZENDESK_EMAIL')}/token:${zendeskKey}`).toString('base64')}`
        },
        body: JSON.stringify({
          ticket: {
            comment: {
              body: input.comment,
              public: true,
              author_id: 'end-user'
            }
          }
        })
      }
    );
    
    if (!response.ok) {
      throw new Error('Failed to update ticket');
    }
    
    return {
      success: true,
      ticketId: input.ticketId,
      message: "Your comment has been added to the ticket"
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env
ZENDESK_API_KEY=your_zendesk_api_key
ZENDESK_SUBDOMAIN=your_company
ZENDESK_EMAIL=support@yourcompany.com
```

## Seed Knowledge Base

```typescript theme={null}
// scripts/seed-knowledge-base.ts
import { Data } from "lua-cli";

const articles = [
  {
    title: "How to reset your password",
    content: "To reset your password: 1) Click 'Forgot Password' 2) Enter your email 3) Check your inbox for reset link 4) Create new password",
    category: "Account",
    url: "/help/reset-password"
  },
  {
    title: "Shipping and delivery times",
    content: "Standard shipping takes 5-7 business days. Express shipping takes 2-3 business days. Free shipping on orders over $50.",
    category: "Shipping",
    url: "/help/shipping"
  },
  {
    title: "Return policy",
    content: "Returns accepted within 30 days of purchase. Items must be unused with original packaging. Refunds processed within 5-10 business days.",
    category: "Returns",
    url: "/help/returns"
  }
];

async function seedKnowledgeBase() {
  for (const article of articles) {
    const searchText = `${article.title} ${article.content} ${article.category}`;
    await Data.create('help_articles', article, searchText);
  }
  console.log('✅ Knowledge base seeded');
}

seedKnowledgeBase();
```

## Key Features

<CardGroup>
  <Card title="External API" icon="cloud">
    Integrates with Zendesk ticketing
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    AI-powered knowledge base search
  </Card>

  <Card title="Hybrid Approach" icon="shuffle">
    Best of both worlds
  </Card>

  <Card title="Smart Escalation" icon="arrow-up">
    Search first, create ticket only if needed
  </Card>
</CardGroup>

## Next Demo

<Card title="Hotel Booking Agent" icon="hotel" href="/demos/hotel-booking">
  See reservation management with Lua Data API
</Card>


# E-commerce Shopping Assistant
Source: https://docs.heylua.ai/demos/ecommerce-assistant

Complete shopping experience using Lua Platform APIs

## Overview

A fully-featured e-commerce shopping assistant using **Lua Platform APIs** for products, shopping cart, and order management.

**What it does:**

* Search and browse products
* Add items to cart
* Manage shopping basket
* Complete checkout
* Track orders

**APIs used:** Lua Platform APIs (Products, Baskets, Orders)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  SearchProductsTool,
  BrowseProductsTool,
  GetProductDetailsTool,
  AddToCartTool,
  ViewCartTool,
  RemoveFromCartTool,
  CheckoutTool,
  TrackOrderTool
} from "./tools/EcommerceTool";

// Create shopping skill
const ecommerceSkill = new LuaSkill({
  name: "ecommerce-assistant",
  description: "AI shopping assistant for e-commerce websites",
  context: `
    This skill helps customers shop and complete purchases.
    
    Shopping Flow:
    - search_products: When users describe what they want to buy (semantic search)
    - browse_products: When users want to filter by category, price range, or availability
    - get_product_details: When they want more info about a specific product
    - add_to_cart: When they decide to purchase something
    - view_cart: To review their shopping cart
    - remove_from_cart: To remove unwanted items
    - checkout: To complete the purchase
    - track_order: To check order status
    
    Guidelines:
    - Use search_products for natural language queries like "laptop for students"
    - Use browse_products for structured queries like "electronics under $500"
    - Always confirm items and quantities before adding to cart
    - Show total price before checkout
    - Ask for shipping address during checkout
    - Be helpful with product recommendations
  `,
  tools: [
    new SearchProductsTool(),
    new BrowseProductsTool(),
    new GetProductDetailsTool(),
    new AddToCartTool(),
    new ViewCartTool(),
    new RemoveFromCartTool(),
    new CheckoutTool(),
    new TrackOrderTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "ecommerce-shopping-assistant",
  
  persona: `You are a friendly and helpful shopping assistant for our online store.
  
Your role:
- Help customers find products they're looking for
- Provide detailed product information
- Assist with adding items to cart
- Guide through the checkout process
- Help track orders after purchase

Communication style:
- Warm and welcoming
- Enthusiastic about products
- Patient and helpful
- Clear about pricing and availability
- Proactive with suggestions

Best practices:
- Always confirm product details before adding to cart
- Mention if items are in stock or out of stock
- Show total price before checkout
- Offer product recommendations based on browsing
- Celebrate successful orders!

When to escalate:
- Complex shipping issues
- Payment problems
- Bulk orders (>20 items)
- Special customization requests`,

  
  skills: [ecommerceSkill]
});
```

<Note>
  This demo uses `LuaAgent` to configure the agent's persona, welcome message, and skills in one unified structure.
</Note>

### src/tools/EcommerceTool.ts

```typescript theme={null}
import { LuaTool, Products, Baskets, Orders } from "lua-cli";
import { z } from "zod";

// 1. Search Products
export class SearchProductsTool implements LuaTool {
  name = "search_products";
  description = "Search for products by name, category, or description";
  
  inputSchema = z.object({
    query: z.string().describe("Search query (e.g., 'laptop', 'running shoes')"),
    maxPrice: z.number().optional().describe("Maximum price filter")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Products.search(input.query);
    
    // Filter by max price if specified
    let products = results.products;
    if (input.maxPrice) {
      products = products.filter(p => p.price <= input.maxPrice);
    }
    
    return {
      products: products.slice(0, 10).map(p => ({
        id: p.id,
        name: p.name,
        price: `$${p.price.toFixed(2)}`,
        category: p.category,
        inStock: p.inStock,
        description: p.description?.substring(0, 100) + '...'
      })),
      total: products.length,
      showing: Math.min(products.length, 10)
    };
  }
}

// 2. Browse Products by Category/Price (Filter-based)
export class BrowseProductsTool implements LuaTool {
  name = "browse_products";
  description = "Browse products by category, price range, or availability";
  
  inputSchema = z.object({
    category: z.string().optional().describe("Product category"),
    minPrice: z.number().optional().describe("Minimum price"),
    maxPrice: z.number().optional().describe("Maximum price"),
    inStockOnly: z.boolean().optional().describe("Only show in-stock items"),
    page: z.number().optional().default(1)
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const filter: Record<string, any> = {};
    
    if (input.category) filter.category = input.category;
    if (input.minPrice !== undefined || input.maxPrice !== undefined) {
      filter.price = {};
      if (input.minPrice !== undefined) filter.price.$gte = input.minPrice;
      if (input.maxPrice !== undefined) filter.price.$lte = input.maxPrice;
    }
    if (input.inStockOnly) filter.inStock = true;
    
    const results = await Products.get({ page: input.page, limit: 10, filter });
    
    return {
      products: results.map(p => ({
        id: p.id,
        name: p.name,
        price: `$${p.price.toFixed(2)}`,
        category: p.category,
        inStock: p.inStock ? '✅ In Stock' : '❌ Out of Stock'
      })),
      pagination: results.pagination
    };
  }
}

// 3. Get Product Details
export class GetProductDetailsTool implements LuaTool {
  name = "get_product_details";
  description = "Get detailed information about a specific product";
  
  inputSchema = z.object({
    productId: z.string().describe("Product ID")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const product = await Products.getById(input.productId);
    
    if (!product) {
      throw new Error(`Product not found: ${input.productId}`);
    }
    
    return {
      id: product.id,
      name: product.name,
      price: `$${product.price.toFixed(2)}`,
      description: product.description,
      category: product.category,
      sku: product.sku,
      inStock: product.inStock,
      availability: product.inStock 
        ? "✅ In stock - Ships within 24 hours" 
        : "❌ Out of stock - Notify when available?"
    };
  }
}

// 4. Add to Cart
export class AddToCartTool implements LuaTool {
  name = "add_to_cart";
  description = "Add a product to the shopping cart";
  
  inputSchema = z.object({
    productId: z.string().describe("Product ID to add"),
    quantity: z.number().min(1).default(1).describe("Quantity to add"),
    basketId: z.string().optional().describe("Existing basket ID (creates new if not provided)")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get product details
    const product = await Products.getById(input.productId);
    
    if (!product) {
      throw new Error(`Product not found: ${input.productId}`);
    }
    
    if (!product.inStock) {
      return {
        success: false,
        message: `Sorry, ${product.name} is currently out of stock`
      };
    }
    
    // Get or create basket
    let basket;
    if (input.basketId) {
      basket = await Baskets.getById(input.basketId);
    } else {
      basket = await Baskets.create({
        currency: 'USD',
        metadata: { source: 'ai_chat' }
      });
    }
    
    // Add item to basket
    const updated = await Baskets.addItem(basket.id, {
      id: input.productId,
      price: product.price,
      quantity: input.quantity,
      SKU: product.sku
    });
    
    return {
      success: true,
      basketId: updated.id,
      itemCount: updated.common.itemCount,
      subtotal: `$${updated.common.totalAmount.toFixed(2)}`,
      message: `Added ${input.quantity}x ${product.name} to your cart`
    };
  }
}

// 5. View Cart
export class ViewCartTool implements LuaTool {
  name = "view_cart";
  description = "View items in the shopping cart";
  
  inputSchema = z.object({
    basketId: z.string().describe("Basket ID")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const basket = await Baskets.getById(input.basketId);
    
    if (!basket) {
      throw new Error("Cart not found");
    }
    
    return {
      items: basket.common.items.map(item => ({
        productId: item.id,
        quantity: item.quantity,
        price: `$${item.price.toFixed(2)}`,
        subtotal: `$${(item.price * item.quantity).toFixed(2)}`,
        sku: item.SKU
      })),
      itemCount: basket.common.itemCount,
      total: `$${basket.common.totalAmount.toFixed(2)}`,
      basketId: basket.id
    };
  }
}

// 6. Remove from Cart
export class RemoveFromCartTool implements LuaTool {
  name = "remove_from_cart";
  description = "Remove an item from the shopping cart";
  
  inputSchema = z.object({
    basketId: z.string(),
    itemId: z.string().describe("Item/Product ID to remove")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    await Baskets.removeItem(input.basketId, input.itemId);
    
    const updated = await Baskets.getById(input.basketId);
    
    return {
      success: true,
      itemCount: updated.common.itemCount,
      total: `$${updated.common.totalAmount.toFixed(2)}`,
      message: "Item removed from cart"
    };
  }
}

// 7. Checkout
export class CheckoutTool implements LuaTool {
  name = "checkout";
  description = "Complete purchase and create order";
  
  inputSchema = z.object({
    basketId: z.string(),
    shippingAddress: z.object({
      name: z.string(),
      street: z.string(),
      city: z.string(),
      state: z.string(),
      zip: z.string(),
      country: z.string().default('USA')
    }),
    email: z.string().email(),
    paymentMethod: z.string().default('stripe')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const basket = await Baskets.getById(input.basketId);
    
    if (basket.common.itemCount === 0) {
      return {
        success: false,
        message: "Cannot checkout with empty cart"
      };
    }
    
    // Create order
    const order = await Baskets.placeOrder({
      shippingAddress: input.shippingAddress,
      paymentMethod: input.paymentMethod,
      customerEmail: input.email
    }, input.basketId);
    
    return {
      success: true,
      orderId: order.id,
      total: `$${basket.common.totalAmount.toFixed(2)}`,
      itemCount: basket.common.itemCount,
      estimatedDelivery: this.calculateDeliveryDate(),
      message: `Order confirmed! You'll receive a confirmation email at ${input.email}`
    };
  }
  
  private calculateDeliveryDate(): string {
    const date = new Date();
    date.setDate(date.getDate() + 5); // 5 business days
    return date.toLocaleDateString();
  }
}

// 8. Track Order
export class TrackOrderTool implements LuaTool {
  name = "track_order";
  description = "Get order status and tracking information";
  
  inputSchema = z.object({
    orderId: z.string().describe("Order ID to track")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const order = await Orders.getById(input.orderId);
    
    if (!order) {
      throw new Error(`Order not found: ${input.orderId}`);
    }
    
    const statusMessages = {
      pending: "Your order is being processed",
      confirmed: "Order confirmed and being prepared for shipping",
      fulfilled: "Order delivered!",
      cancelled: "Order was cancelled"
    };
    
    return {
      orderId: order.id,
      status: order.common.status,
      statusMessage: statusMessages[order.common.status] || "Unknown status",
      total: `$${order.common.totalAmount.toFixed(2)}`,
      itemCount: order.common.itemCount,
      estimatedDelivery: order.data?.estimatedDelivery,
      trackingNumber: order.data?.trackingNumber
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env (not needed - uses Platform APIs)
# No external API keys required
```

## Testing

```bash theme={null}
# Test individual tools
lua test

# Test conversation flow
lua chat
```

**Test conversation flow in sandbox mode:**

1. "Search for laptops" (semantic search)
2. "Show me electronics under \$500" (filter-based browsing)
3. "Add the MacBook to my cart"
4. "Show me my cart"
5. "Checkout with shipping to 123 Main St, New York, NY 10001"
6. "Track my order"

## Deployment

```bash theme={null}
lua push
lua deploy
```

## Key Features

<CardGroup>
  <Card title="Platform APIs" icon="database">
    Uses Lua's built-in e-commerce APIs
  </Card>

  <Card title="Complete Flow" icon="cart-shopping">
    Search → Add → Checkout → Track
  </Card>

  <Card title="No External Dependencies" icon="check">
    Everything built-in
  </Card>

  <Card title="Production Ready" icon="rocket">
    Full error handling and validation
  </Card>
</CardGroup>

## Customization

### Add Recommendations

```typescript theme={null}
async execute(input) {
  const product = await Products.getById(input.productId);
  
  // Find similar products
  const similar = await Products.search(product.category);
  const recommendations = similar.data
    .filter(p => p.id !== product.id)
    .slice(0, 3);
  
  return {
    product,
    recommendations
  };
}
```

### Add Discount Codes

```typescript theme={null}
inputSchema = z.object({
  basketId: z.string(),
  discountCode: z.string().optional()
});

async execute(input) {
  const basket = await Baskets.getById(input.basketId);
  
  if (input.discountCode) {
    const discount = await validateDiscountCode(input.discountCode);
    await Baskets.updateMetadata(input.basketId, {
      discountCode: input.discountCode,
      discountAmount: basket.common.totalAmount * discount.percentage
    });
  }
}
```

## Next Demo

<Card title="Customer Support Agent" icon="headset" href="/demos/customer-support">
  See external API integration with Zendesk
</Card>


# Finance Operations Agent
Source: https://docs.heylua.ai/demos/finance-operations

Banking operations with Plaid API

## Overview

Internal finance operations assistant using **Plaid API** for banking and account management.

**What it does:**

* Check account balances
* View recent transactions
* Transfer funds between accounts
* Generate financial reports
* Verify payments

**APIs used:** Plaid API (external banking)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaJob } from "lua-cli";
import {
  GetBalanceTool,
  GetTransactionsTool,
  TransferFundsTool
} from "./tools/FinanceTools";

// Finance operations skill
const financeSkill = new LuaSkill({
  name: "finance-operations",
  description: "Internal finance and banking operations",
  context: `
    This skill provides finance team with banking operations.
    
    - get_balance: Check account balances
    - get_transactions: View transaction history
    - transfer_funds: Move money between accounts
    
    Always verify amounts and account numbers.
    Follow approval workflows for large transfers.
  `,
  tools: [
    new GetBalanceTool(),
    new GetTransactionsTool(),
    new TransferFundsTool()
  ]
});

// Weekly reconciliation job
const weeklyReconciliationJob = new LuaJob({
  name: 'weekly-reconciliation',
  description: 'Send weekly account reconciliation summary',
  schedule: {
    type: 'cron',
    pattern: '0 9 * * 1'  // Every Monday at 9 AM
  },
  execute: async (job) => {
    const user = await job.user();
    await user.send([{
      type: 'text',
      text: '📊 Weekly reconciliation report is ready for review.'
    }]);
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "finance-operations-assistant",
  
  persona: `You are a finance operations specialist assistant.
  
Your role:
- Help finance team check account balances
- Provide transaction histories
- Process fund transfers
- Generate financial reports
- Monitor account activities

Communication style:
- Professional and precise
- Detail-oriented
- Security-conscious
- Clear with numbers
- Compliant with regulations

Best practices:
- Always verify account numbers before transfers
- Double-check transfer amounts
- Provide clear transaction summaries
- Flag unusual activity
- Follow approval workflows for large amounts

Security requirements:
- Verify user authorization
- Log all transfer requests
- Require approval for transfers >$10,000
- Maintain audit trail
- Follow SOX compliance

When to escalate:
- Transfers over $10,000
- Suspicious transactions
- Account discrepancies
- External audit requests`,

  
  skills: [financeSkill],
  jobs: [weeklyReconciliationJob]
});
```

<Note>
  This demo uses `LuaAgent` with scheduled jobs for weekly reconciliation reports.
</Note>

### src/tools/FinanceTools.ts

```typescript theme={null}
import { LuaTool, env } from "lua-cli";
import { z } from "zod";

// 1. Get Account Balance
export class GetBalanceTool implements LuaTool {
  name = "get_balance";
  description = "Check account balance";
  
  inputSchema = z.object({
    accountId: z.string().describe("Account ID")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const plaidKey = env('PLAID_CLIENT_ID');
    const plaidSecret = env('PLAID_SECRET');
    
    const response = await fetch('https://production.plaid.com/accounts/balance/get', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: plaidKey,
        secret: plaidSecret,
        access_token: env('PLAID_ACCESS_TOKEN'),
        options: {
          account_ids: [input.accountId]
        }
      })
    });
    
    const data = await response.json();
    const account = data.accounts[0];
    
    return {
      accountId: account.account_id,
      accountName: account.name,
      currentBalance: `$${account.balances.current.toLocaleString()}`,
      availableBalance: `$${account.balances.available.toLocaleString()}`,
      currency: account.balances.iso_currency_code,
      lastUpdated: new Date().toISOString()
    };
  }
}

// 2. Get Transactions
export class GetTransactionsTool implements LuaTool {
  name = "get_transactions";
  description = "View recent transactions";
  
  inputSchema = z.object({
    accountId: z.string(),
    days: z.number().min(1).max(90).default(30)
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const plaidKey = env('PLAID_CLIENT_ID');
    const plaidSecret = env('PLAID_SECRET');
    
    const endDate = new Date();
    const startDate = new Date();
    startDate.setDate(startDate.getDate() - input.days);
    
    const response = await fetch('https://production.plaid.com/transactions/get', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: plaidKey,
        secret: plaidSecret,
        access_token: env('PLAID_ACCESS_TOKEN'),
        start_date: startDate.toISOString().split('T')[0],
        end_date: endDate.toISOString().split('T')[0],
        options: {
          account_ids: [input.accountId]
        }
      })
    });
    
    const data = await response.json();
    
    return {
      transactions: data.transactions.map(t => ({
        date: t.date,
        name: t.name,
        amount: `$${Math.abs(t.amount).toFixed(2)}`,
        type: t.amount < 0 ? 'debit' : 'credit',
        category: t.category[0],
        pending: t.pending
      })),
      total: data.transactions.length
    };
  }
}

// 3. Transfer Funds
export class TransferFundsTool implements LuaTool {
  name = "transfer_funds";
  description = "Transfer money between accounts";
  
  inputSchema = z.object({
    fromAccountId: z.string(),
    toAccountId: z.string(),
    amount: z.number().positive(),
    description: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Validate amount
    if (input.amount > 10000) {
      throw new Error('Transfers over $10,000 require additional approval');
    }
    
    const plaidKey = env('PLAID_CLIENT_ID');
    const plaidSecret = env('PLAID_SECRET');
    
    const response = await fetch('https://production.plaid.com/transfer/create', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: plaidKey,
        secret: plaidSecret,
        access_token: env('PLAID_ACCESS_TOKEN'),
        account_id: input.fromAccountId,
        type: 'debit',
        network: 'ach',
        amount: input.amount.toString(),
        description: input.description || 'Transfer',
        user: {
          legal_name: 'Company Name'
        }
      })
    });
    
    const data = await response.json();
    
    return {
      success: true,
      transferId: data.transfer.id,
      amount: `$${input.amount.toFixed(2)}`,
      status: data.transfer.status,
      message: `Transfer of $${input.amount.toFixed(2)} initiated successfully`
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env
PLAID_CLIENT_ID=your_plaid_client_id
PLAID_SECRET=your_plaid_secret
PLAID_ACCESS_TOKEN=your_access_token
PLAID_ENV=production
```

## Key Features

<CardGroup>
  <Card title="External Banking" icon="building-columns">
    Plaid API integration
  </Card>

  <Card title="Secure" icon="lock">
    Bank-grade security
  </Card>

  <Card title="Real-Time" icon="bolt">
    Live account data
  </Card>

  <Card title="Compliance" icon="shield">
    Financial regulations
  </Card>
</CardGroup>


# Financial Services Onboarding
Source: https://docs.heylua.ai/demos/financial-onboarding

KYC onboarding with document verification and compliance checks

## Overview

Complete financial services onboarding agent with **KYC (Know Your Customer)** verification using **Stripe Identity API** for document verification and **Lua Data API** for application management.

**What it does:**

* Guide users through onboarding journey
* Collect personal and financial information
* Upload and verify identity documents (ID, passport)
* Answer qualifying questions
* Perform compliance checks
* Create verified account

**APIs used:** Stripe Identity API (document verification) + Lua Data API (application tracking)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaWebhook, PreProcessor, PostProcessor } from "lua-cli";
import {
  StartOnboardingTool,
  CollectPersonalInfoTool,
  UploadDocumentTool,
  VerifyIdentityTool,
  AnswerQualifyingQuestionsTool,
  CreateAccountTool,
  CheckOnboardingStatusTool
} from "./tools/FinancialOnboardingTools";

// Onboarding skill
const financialOnboardingSkill = new LuaSkill({
  name: "financial-onboarding",
  description: "Financial services customer onboarding with KYC verification",
  context: `
    This skill guides customers through financial account onboarding.
    
    Onboarding Flow (in order):
    1. start_onboarding: Begin new application
    2. collect_personal_info: Gather basic information
    3. upload_document: Upload ID, passport, or proof of address
    4. verify_identity: Verify uploaded documents
    5. answer_qualifying_questions: Financial suitability assessment
    6. create_account: Complete account creation
    7. check_onboarding_status: Check application status
    
    Guidelines:
    - Be professional and reassuring about data security
    - Explain why each document is needed (regulatory compliance)
    - Never rush through identity verification steps
    - Clearly communicate what happens to uploaded documents
    - Follow KYC and AML regulations
    - Ensure GDPR/CCPA compliance
  `,
  tools: [
    new StartOnboardingTool(),
    new CollectPersonalInfoTool(),
    new UploadDocumentTool(),
    new VerifyIdentityTool(),
    new AnswerQualifyingQuestionsTool(),
    new CreateAccountTool(),
    new CheckOnboardingStatusTool()
  ]
});

// Stripe Identity webhook for verification results
const stripeIdentityWebhook = new LuaWebhook({
  name: 'stripe-identity-webhook',
  description: 'Handle Stripe Identity verification events',
  secret: env('STRIPE_WEBHOOK_SECRET'),
  execute: async (event) => {
    if (event.type === 'identity.verification_session.verified') {
      const user = await User.get();
      await user.send([{
        type: 'text',
        text: '✅ Identity verification successful! Proceeding with account creation...'
      }]);
    }
    return { received: true };
  }
});

// Information validation preprocessor
const validateInformationPreProcessor = new PreProcessor({
  name: 'validate-financial-info',
  description: 'Ensure required information is provided',
  execute: async (message, user) => {
    // Ensure user has started onboarding
    const applications = await Data.search('onboarding_applications', user.email, 1);
    if (applications.length === 0) {
      return {
        block: true,
        response: "Please start the onboarding process first by providing your email address."
      };
    }
    return { block: false };
  }
});

// Compliance disclaimer postprocessor
const complianceDisclaimerPostProcessor = new PostProcessor({
  name: 'compliance-disclaimer',
  description: 'Add regulatory disclaimers to responses',
  execute: async (user, message, response, channel) => {
    return {
      modifiedResponse: response + 
        "\n\n_Banking services provided by our partner bank. FDIC insured. Member FDIC. Your information is encrypted and secure._"
    };
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "financial-onboarding-agent",
  
  persona: `You are a professional financial services onboarding specialist.
  
Your role:
- Guide customers through account opening process
- Collect required KYC information
- Verify identity documents
- Assess financial suitability
- Ensure regulatory compliance

Communication style:
- Professional and trustworthy
- Clear and reassuring
- Patient and thorough
- Transparent about data security
- Compliant with regulations

Compliance requirements:
- Follow KYC (Know Your Customer) procedures
- Adhere to AML (Anti-Money Laundering) regulations
- Ensure GDPR/CCPA compliance
- Verify identity before account creation
- Document all customer interactions

Best practices:
- Explain why each document is needed
- Reassure customers about data security
- Never rush through verification steps
- Clearly communicate processing times
- Provide next steps at each stage

Security reminders:
- All information is encrypted
- Documents are securely stored
- Compliance with banking regulations
- Data is never shared without consent`,

  
  skills: [financialOnboardingSkill],
  webhooks: [stripeIdentityWebhook],
  preProcessors: [validateInformationPreProcessor],
  postProcessors: [complianceDisclaimerPostProcessor]
});
```

<Note>
  This demo uses `LuaAgent` with webhooks for Stripe Identity events, preprocessors for validation, and postprocessors for compliance disclaimers.
</Note>

### src/tools/FinancialOnboardingTools.ts

```typescript theme={null}
import { LuaTool, Data, env } from "lua-cli";
import { z } from "zod";

// 1. Start Onboarding
export class StartOnboardingTool implements LuaTool {
  name = "start_onboarding";
  description = "Begin a new account onboarding application";
  
  inputSchema = z.object({
    email: z.string().email().describe("Applicant's email address"),
    accountType: z.enum(['individual', 'business']).describe("Type of account")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Create onboarding application
    const application = await Data.create('onboarding_applications', {
      email: input.email,
      accountType: input.accountType,
      status: 'started',
      currentStep: 'personal_info',
      createdAt: new Date().toISOString(),
      completedSteps: []
    }, input.email);
    
    return {
      applicationId: application.id,
      accountType: input.accountType,
      nextStep: 'personal_info',
      message: "Application started! Let's begin by collecting your personal information.",
      estimatedTime: "5-10 minutes to complete"
    };
  }
}

// 2. Collect Personal Information
export class CollectPersonalInfoTool implements LuaTool {
  name = "collect_personal_info";
  description = "Collect applicant's personal information";
  
  inputSchema = z.object({
    applicationId: z.string(),
    personalInfo: z.object({
      firstName: z.string(),
      lastName: z.string(),
      dateOfBirth: z.string().describe("YYYY-MM-DD"),
      ssn: z.string().describe("Social Security Number (will be encrypted)"),
      phone: z.string(),
      address: z.object({
        street: z.string(),
        city: z.string(),
        state: z.string(),
        zipCode: z.string(),
        country: z.string().default('USA')
      })
    })
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get application
    const app = await Data.getEntry('onboarding_applications', input.applicationId);
    
    if (!app) {
      throw new Error('Application not found');
    }
    
    // Encrypt SSN before storing (in production, use proper encryption)
    const encryptedSSN = this.encryptSSN(input.personalInfo.ssn);
    
    // Update application with personal info
    await Data.update('onboarding_applications', input.applicationId, {
      ...app.data,
      personalInfo: {
        ...input.personalInfo,
        ssn: encryptedSSN // Store encrypted
      },
      currentStep: 'document_upload',
      completedSteps: [...app.data.completedSteps, 'personal_info'],
      updatedAt: new Date().toISOString()
    });
    
    return {
      success: true,
      nextStep: 'document_upload',
      message: "Personal information saved securely. Next, please upload a government-issued ID.",
      documentsNeeded: [
        "Government-issued photo ID (driver's license or passport)",
        "Proof of address (utility bill or bank statement)"
      ]
    };
  }
  
  private encryptSSN(ssn: string): string {
    // In production, use proper encryption (AES-256, KMS, etc.)
    // This is a placeholder
    return Buffer.from(ssn).toString('base64');
  }
}

// 3. Upload Document (Stripe Identity API)
export class UploadDocumentTool implements LuaTool {
  name = "upload_document";
  description = "Upload identity verification document";
  
  inputSchema = z.object({
    applicationId: z.string(),
    documentType: z.enum(['drivers_license', 'passport', 'id_card', 'proof_of_address']),
    documentImageUrl: z.string().url().describe("URL of uploaded document image"),
    documentSide: z.enum(['front', 'back']).optional().describe("For driver's license")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const stripeKey = env('STRIPE_SECRET_KEY');
    
    if (!stripeKey) {
      throw new Error('Stripe API key not configured');
    }
    
    // Create Stripe Identity Verification Session
    const verificationResponse = await fetch('https://api.stripe.com/v1/identity/verification_sessions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${stripeKey}`,
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        'type': 'document',
        'metadata[application_id]': input.applicationId,
        'metadata[document_type]': input.documentType
      })
    });
    
    if (!verificationResponse.ok) {
      throw new Error('Failed to create verification session');
    }
    
    const verification = await verificationResponse.json();
    
    // Upload document to Stripe
    const uploadResponse = await fetch('https://files.stripe.com/v1/files', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${stripeKey}`
      },
      body: this.createFormData(input.documentImageUrl, input.documentType)
    });
    
    const uploadedFile = await uploadResponse.json();
    
    // Save document reference in application
    const app = await Data.getEntry('onboarding_applications', input.applicationId);
    
    const documents = app.data.documents || [];
    documents.push({
      type: input.documentType,
      side: input.documentSide,
      stripeFileId: uploadedFile.id,
      stripeVerificationId: verification.id,
      uploadedAt: new Date().toISOString(),
      status: 'pending_verification'
    });
    
    await Data.update('onboarding_applications', input.applicationId, {
      ...app.data,
      documents,
      currentStep: 'identity_verification',
      updatedAt: new Date().toISOString()
    });
    
    return {
      success: true,
      documentId: uploadedFile.id,
      verificationId: verification.id,
      status: 'uploaded',
      message: "Document uploaded successfully. Verification in progress...",
      nextStep: "We'll verify your identity. This usually takes 1-2 minutes.",
      verificationUrl: verification.url // User can complete verification here
    };
  }
  
  private createFormData(imageUrl: string, documentType: string): FormData {
    const formData = new FormData();
    formData.append('purpose', 'identity_document');
    formData.append('file', imageUrl);
    return formData;
  }
}

// 4. Verify Identity (Check Stripe Identity Results)
export class VerifyIdentityTool implements LuaTool {
  name = "verify_identity";
  description = "Check identity verification status";
  
  inputSchema = z.object({
    applicationId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const stripeKey = env('STRIPE_SECRET_KEY');
    const app = await Data.getEntry('onboarding_applications', input.applicationId);
    
    if (!app.data.documents || app.data.documents.length === 0) {
      return {
        verified: false,
        message: "No documents uploaded yet. Please upload your ID first."
      };
    }
    
    // Check verification status with Stripe
    const latestDoc = app.data.documents[app.data.documents.length - 1];
    
    const response = await fetch(
      `https://api.stripe.com/v1/identity/verification_sessions/${latestDoc.stripeVerificationId}`,
      {
        headers: { 'Authorization': `Bearer ${stripeKey}` }
      }
    );
    
    const verification = await response.json();
    
    const isVerified = verification.status === 'verified';
    
    // Update application
    if (isVerified) {
      await Data.update('onboarding_applications', input.applicationId, {
        ...app.data,
        identityVerified: true,
        verificationResult: {
          verified: true,
          verifiedAt: new Date().toISOString(),
          documentType: verification.last_verification_report?.document?.type,
          nameMatch: verification.last_verification_report?.id_number?.status === 'verified'
        },
        currentStep: 'qualifying_questions',
        completedSteps: [...app.data.completedSteps, 'identity_verification']
      });
    }
    
    return {
      verified: isVerified,
      status: verification.status,
      message: isVerified 
        ? "✅ Identity verified successfully! Let's continue with some qualifying questions."
        : verification.status === 'processing'
        ? "⏳ Verification in progress. Please wait..."
        : "❌ Verification failed. Please upload a clearer image of your ID.",
      nextStep: isVerified ? 'qualifying_questions' : 'document_upload',
      verificationDetails: isVerified ? {
        documentType: verification.last_verification_report?.document?.type,
        issueDate: verification.last_verification_report?.document?.issued_date,
        expirationDate: verification.last_verification_report?.document?.expiration_date
      } : null
    };
  }
}

// 5. Answer Qualifying Questions
export class AnswerQualifyingQuestionsTool implements LuaTool {
  name = "answer_qualifying_questions";
  description = "Complete financial suitability questionnaire";
  
  inputSchema = z.object({
    applicationId: z.string(),
    answers: z.object({
      annualIncome: z.enum(['under_25k', '25k_50k', '50k_100k', '100k_250k', 'over_250k']),
      employmentStatus: z.enum(['employed', 'self_employed', 'unemployed', 'retired', 'student']),
      investmentExperience: z.enum(['none', 'limited', 'moderate', 'extensive']),
      riskTolerance: z.enum(['conservative', 'moderate', 'aggressive']),
      investmentGoals: z.array(z.enum(['retirement', 'wealth_building', 'income', 'preservation'])),
      investmentHorizon: z.enum(['short_term', 'medium_term', 'long_term']),
      liquidNetWorth: z.enum(['under_10k', '10k_50k', '50k_100k', '100k_500k', 'over_500k']),
      sourceOfFunds: z.enum(['employment', 'business', 'investments', 'inheritance', 'other'])
    })
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const app = await Data.getEntry('onboarding_applications', input.applicationId);
    
    // Calculate suitability score
    const suitabilityScore = this.calculateSuitability(input.answers);
    
    // Determine if applicant qualifies
    const qualifies = suitabilityScore.score >= 60;
    
    // Update application
    await Data.update('onboarding_applications', input.applicationId, {
      ...app.data,
      qualifyingAnswers: input.answers,
      suitabilityScore: suitabilityScore,
      qualifies,
      currentStep: qualifies ? 'account_creation' : 'under_review',
      completedSteps: [...app.data.completedSteps, 'qualifying_questions'],
      updatedAt: new Date().toISOString()
    });
    
    if (!qualifies) {
      return {
        success: false,
        qualifies: false,
        score: suitabilityScore.score,
        message: "Thank you for your application. Based on your responses, we need to review your application manually. Our team will contact you within 2 business days.",
        nextSteps: "Our compliance team will review your application"
      };
    }
    
    return {
      success: true,
      qualifies: true,
      score: suitabilityScore.score,
      riskProfile: suitabilityScore.riskProfile,
      recommendedProducts: this.getRecommendedProducts(input.answers),
      message: "Great! You qualify for an account. Let's create your account now.",
      nextStep: 'account_creation'
    };
  }
  
  private calculateSuitability(answers: any) {
    let score = 0;
    
    // Income scoring
    const incomeScores = {
      'under_25k': 10,
      '25k_50k': 20,
      '50k_100k': 30,
      '100k_250k': 40,
      'over_250k': 50
    };
    score += incomeScores[answers.annualIncome] || 0;
    
    // Experience scoring
    const experienceScores = {
      'none': 5,
      'limited': 15,
      'moderate': 25,
      'extensive': 35
    };
    score += experienceScores[answers.investmentExperience] || 0;
    
    // Net worth scoring
    const netWorthScores = {
      'under_10k': 5,
      '10k_50k': 10,
      '50k_100k': 15,
      '100k_500k': 20,
      'over_500k': 25
    };
    score += netWorthScores[answers.liquidNetWorth] || 0;
    
    // Determine risk profile
    let riskProfile = 'conservative';
    if (answers.riskTolerance === 'aggressive' && answers.investmentHorizon === 'long_term') {
      riskProfile = 'aggressive';
    } else if (answers.riskTolerance === 'moderate') {
      riskProfile = 'moderate';
    }
    
    return {
      score,
      riskProfile,
      passedCompliance: score >= 60
    };
  }
  
  private getRecommendedProducts(answers: any) {
    const products = [];
    
    if (answers.investmentGoals.includes('retirement')) {
      products.push('IRA Account', '401(k) Rollover');
    }
    
    if (answers.riskTolerance === 'conservative') {
      products.push('Money Market Account', 'CD Account');
    } else if (answers.riskTolerance === 'aggressive') {
      products.push('Investment Account', 'Options Trading');
    } else {
      products.push('Savings Account', 'Investment Account');
    }
    
    return products;
  }
}

// 6. Create Account
export class CreateAccountTool implements LuaTool {
  name = "create_account";
  description = "Create verified financial services account";
  
  inputSchema = z.object({
    applicationId: z.string(),
    accountProducts: z.array(z.string()).describe("Selected account products"),
    agreeToTerms: z.boolean().describe("Must accept terms and conditions"),
    agreeToPrivacyPolicy: z.boolean()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    if (!input.agreeToTerms || !input.agreeToPrivacyPolicy) {
      throw new Error('You must agree to the terms and conditions to create an account');
    }
    
    const app = await Data.getEntry('onboarding_applications', input.applicationId);
    
    // Verify all steps completed
    if (!app.data.identityVerified) {
      throw new Error('Identity verification must be completed first');
    }
    
    if (!app.data.qualifies) {
      throw new Error('Application is pending review');
    }
    
    // Create account in your banking system (external API)
    const bankingApiKey = env('BANKING_API_KEY');
    
    const accountResponse = await fetch('https://your-banking-api.com/api/accounts', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${bankingApiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customer: {
          first_name: app.data.personalInfo.firstName,
          last_name: app.data.personalInfo.lastName,
          email: app.data.email,
          date_of_birth: app.data.personalInfo.dateOfBirth,
          ssn: app.data.personalInfo.ssn, // Encrypted
          address: app.data.personalInfo.address,
          phone: app.data.personalInfo.phone
        },
        products: input.accountProducts,
        verification: {
          identity_verified: true,
          verification_id: app.data.verificationResult.verificationId,
          kyc_status: 'approved'
        },
        suitability: app.data.suitabilityScore,
        metadata: {
          application_id: input.applicationId,
          onboarding_source: 'ai_agent'
        }
      })
    });
    
    if (!accountResponse.ok) {
      throw new Error('Failed to create account. Please contact support.');
    }
    
    const account = await accountResponse.json();
    
    // Update application as completed
    await Data.update('onboarding_applications', input.applicationId, {
      ...app.data,
      status: 'completed',
      accountId: account.account_id,
      accountNumber: account.account_number,
      products: input.accountProducts,
      completedSteps: [...app.data.completedSteps, 'account_creation'],
      completedAt: new Date().toISOString()
    });
    
    return {
      success: true,
      accountId: account.account_id,
      accountNumber: account.account_number.replace(/\d(?=\d{4})/g, '*'), // Mask all but last 4
      products: input.accountProducts,
      loginUrl: account.login_url,
      temporaryPassword: account.temporary_password,
      message: `🎉 Account created successfully! Your account number is ${account.account_number.slice(-4)}. Check your email for login credentials.`,
      nextSteps: [
        "Check your email for account details",
        "Set up online banking at " + account.login_url,
        "Fund your account to start using services",
        "Download our mobile app for easy access"
      ]
    };
  }
}

// 7. Check Onboarding Status
export class CheckOnboardingStatusTool implements LuaTool {
  name = "check_onboarding_status";
  description = "Check the status of an onboarding application";
  
  inputSchema = z.object({
    applicationId: z.string(),
    email: z.string().email().describe("Email for verification")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const app = await Data.getEntry('onboarding_applications', input.applicationId);
    
    if (!app || app.data.email !== input.email) {
      throw new Error('Application not found or email mismatch');
    }
    
    const stepStatus = {
      started: '🟢 Started',
      personal_info: app.data.completedSteps.includes('personal_info') ? '✅ Complete' : '⏳ Pending',
      document_upload: app.data.documents?.length > 0 ? '✅ Complete' : '⏳ Pending',
      identity_verification: app.data.identityVerified ? '✅ Verified' : '⏳ Pending',
      qualifying_questions: app.data.qualifyingAnswers ? '✅ Complete' : '⏳ Pending',
      account_creation: app.data.accountId ? '✅ Complete' : '⏳ Pending'
    };
    
    return {
      applicationId: input.applicationId,
      status: app.data.status,
      currentStep: app.data.currentStep,
      progress: stepStatus,
      completedSteps: app.data.completedSteps,
      nextStep: this.getNextStepMessage(app.data.currentStep),
      estimatedCompletion: app.data.status === 'completed' 
        ? 'Completed'
        : this.calculateEstimatedCompletion(app.data.completedSteps.length)
    };
  }
  
  private getNextStepMessage(currentStep: string): string {
    const messages = {
      personal_info: "Please provide your personal information",
      document_upload: "Please upload your government-issued ID",
      identity_verification: "Verifying your identity...",
      qualifying_questions: "Please answer the qualifying questions",
      account_creation: "Ready to create your account!",
      under_review: "Application under manual review",
      completed: "Application complete!"
    };
    return messages[currentStep] || "Continue with onboarding";
  }
  
  private calculateEstimatedCompletion(completedSteps: number): string {
    const totalSteps = 5;
    const remaining = totalSteps - completedSteps;
    return `${remaining * 2} minutes`;
  }
}
```

## Environment Setup

```bash theme={null}
# .env
STRIPE_SECRET_KEY=sk_test_your_stripe_key
BANKING_API_KEY=your_banking_api_key
BANKING_API_URL=https://your-banking-api.com
```

## Document Upload Flow

### Frontend Integration

```html theme={null}
<!-- File upload form -->
<form id="document-upload">
  <input type="file" id="id-front" accept="image/*,application/pdf" />
  <input type="file" id="id-back" accept="image/*,application/pdf" />
  <button type="submit">Upload Documents</button>
</form>

<script>
document.getElementById('document-upload').addEventListener('submit', async (e) => {
  e.preventDefault();
  
  // Upload to your server/CDN first
  const formData = new FormData();
  formData.append('front', document.getElementById('id-front').files[0]);
  formData.append('back', document.getElementById('id-back').files[0]);
  
  const upload = await fetch('/api/upload-documents', {
    method: 'POST',
    body: formData
  });
  
  const { frontUrl, backUrl } = await upload.json();
  
  // Then pass URLs to AI agent
  // The agent will call upload_document tool with these URLs
});
</script>
```

## Testing Conversation Flow

```bash theme={null}
lua chat
```

Select sandbox mode, then test this **example conversation:**

```
User: "I want to open an investment account"
AI: [Calls start_onboarding]
    "Great! Let's get you started. What's your email address?"

User: "john@example.com"
AI: [Calls collect_personal_info]
    "Perfect! I'll need some personal information. What's your full name?"

User: "John Doe, DOB 1990-01-15, SSN 123-45-6789, address: 123 Main St..."
AI: [Saves info]
    "Information saved securely. Now I need to verify your identity. 
     Please upload a photo of your driver's license or passport."

User: [Uploads document images]
AI: [Calls upload_document, then verify_identity]
    "Document uploaded! Verifying your identity... ✅ Identity verified! 
     Now, let's answer some questions about your financial goals..."

User: "I make $75k/year, moderate experience, looking for long-term retirement..."
AI: [Calls answer_qualifying_questions]
    "Based on your profile, you qualify! I recommend an IRA Account 
     and Investment Account. Shall we create your account?"

User: "Yes, create it"
AI: [Calls create_account]
    "🎉 Account created! Your account number is ****5678. 
     Check your email for login details."
```

## Key Features

<CardGroup>
  <Card title="Stripe Identity" icon="id-card">
    Document verification API
  </Card>

  <Card title="Lua Data" icon="database">
    Application state management
  </Card>

  <Card title="KYC Compliant" icon="shield-check">
    Regulatory compliance built-in
  </Card>

  <Card title="Multi-Step Journey" icon="route">
    Guided onboarding flow
  </Card>

  <Card title="Risk Assessment" icon="chart-line">
    Suitability scoring
  </Card>

  <Card title="Secure" icon="lock">
    Encrypted PII storage
  </Card>
</CardGroup>

## Compliance & Security

<Warning>
  **Regulatory Compliance Required**

  This demo shows technical implementation. For production:

  * ✅ Implement proper encryption for PII (use KMS, not base64)
  * ✅ Follow KYC/AML regulations (Bank Secrecy Act, Patriot Act)
  * ✅ Maintain audit logs of all data access
  * ✅ Use HTTPS only
  * ✅ Implement data retention policies
  * ✅ Follow GDPR/CCPA for data privacy
  * ✅ Store documents in compliant storage (encrypted at rest)
  * ✅ Conduct regular security audits
  * ✅ Implement fraud detection
  * ✅ Follow FinCEN guidelines
</Warning>

### Security Best Practices

```typescript theme={null}
// Encrypt sensitive data before storage
import crypto from 'crypto';

function encryptPII(data: string): string {
  const algorithm = 'aes-256-gcm';
  const key = Buffer.from(env('ENCRYPTION_KEY'), 'hex');
  const iv = crypto.randomBytes(16);
  
  const cipher = crypto.createCipheriv(algorithm, key, iv);
  let encrypted = cipher.update(data, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  
  const authTag = cipher.getAuthTag();
  
  return JSON.stringify({
    encrypted,
    iv: iv.toString('hex'),
    authTag: authTag.toString('hex')
  });
}

// Use in your tools
const encryptedSSN = encryptPII(input.personalInfo.ssn);
```

## Alternative Document Verification Services

This demo uses Stripe Identity, but you can swap with:

<Tabs>
  <Tab title="Onfido">
    ```typescript theme={null}
    const onfidoApiKey = env('ONFIDO_API_KEY');

    const response = await fetch('https://api.onfido.com/v3/applicants', {
      method: 'POST',
      headers: {
        'Authorization': `Token token=${onfidoApiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        first_name: input.firstName,
        last_name: input.lastName,
        email: input.email
      })
    });
    ```
  </Tab>

  <Tab title="Jumio">
    ```typescript theme={null}
    const jumioApiKey = env('JUMIO_API_TOKEN');

    const response = await fetch('https://netverify.com/api/v4/initiate', {
      headers: {
        'Authorization': `Bearer ${jumioApiKey}`,
        'User-Agent': 'YourCompany/1.0.0'
      }
    });
    ```
  </Tab>

  <Tab title="Plaid Identity">
    ```typescript theme={null}
    const plaidKey = env('PLAID_CLIENT_ID');

    const response = await fetch('https://production.plaid.com/identity/get', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: plaidKey,
        secret: env('PLAID_SECRET'),
        access_token: userAccessToken
      })
    });
    ```
  </Tab>
</Tabs>

## Document Types Supported

<AccordionGroup>
  <Accordion title="Government-Issued ID">
    * Driver's License (front and back)
    * State ID
    * Passport
    * National ID card

    **Verification checks:**

    * Document authenticity
    * Face match with selfie
    * Data extraction (name, DOB, address)
    * Expiration date validation
  </Accordion>

  <Accordion title="Proof of Address">
    * Utility bill (within 3 months)
    * Bank statement
    * Lease agreement
    * Government correspondence

    **Verification checks:**

    * Address matches ID
    * Document date within acceptable range
    * Name matches applicant
  </Accordion>

  <Accordion title="Financial Documents">
    * Bank statements
    * Tax returns (for high-value accounts)
    * Pay stubs (employment verification)
    * Investment account statements

    **Used for:**

    * Income verification
    * Source of funds
    * Net worth assessment
  </Accordion>
</AccordionGroup>

## Onboarding Journey Diagram

```
1. Start Application
   ↓
2. Collect Personal Info
   ↓
3. Upload Documents (ID + Proof of Address)
   ↓
4. Identity Verification (Stripe Identity API)
   ↓
5. Qualifying Questions (Risk Assessment)
   ↓
6. Suitability Check
   ↓
7. Create Account (if qualified)
   ✅ Account Active
```

## Customization

### Add Additional Verification

```typescript theme={null}
// Add selfie verification
export class CaptureSelfie Tool extends LuaTool {
  async execute(input: { applicationId: string, selfieUrl: string }) {
    // Upload selfie to Stripe
    const response = await fetch('https://api.stripe.com/v1/identity/verification_sessions', {
      method: 'POST',
      body: new URLSearchParams({
        type: 'selfie',
        metadata: { application_id: input.applicationId }
      })
    });
    
    // Stripe compares selfie with ID photo
    return { verified: true };
  }
}
```

### Add Fraud Checks

```typescript theme={null}
// Integrate with fraud detection service
const fraudCheck = await fetch('https://fraud-api.com/check', {
  method: 'POST',
  body: JSON.stringify({
    email: app.data.email,
    ip_address: userIp,
    device_fingerprint: deviceId
  })
});

if (fraudCheck.risk_score > 0.7) {
  // Flag for manual review
  await Data.update(applicationId, {
    ...app.data,
    status: 'fraud_review',
    flaggedForReview: true
  });
}
```

## Key Takeaways

<CardGroup>
  <Card title="Multi-Step Flow" icon="list-check">
    Guided journey with state management
  </Card>

  <Card title="External + Platform" icon="shuffle">
    Stripe Identity + Lua Data
  </Card>

  <Card title="Compliance Ready" icon="scale-balanced">
    KYC/AML patterns shown
  </Card>

  <Card title="Secure by Design" icon="shield">
    Encryption and security practices
  </Card>
</CardGroup>

## Production Considerations

<AccordionGroup>
  <Accordion title="Data Retention">
    * Keep applications for 7 years (regulatory requirement)
    * Implement automated data deletion for rejected applications
    * Archive completed applications to cold storage
  </Accordion>

  <Accordion title="Audit Logging">
    ```typescript theme={null}
    await Data.create('audit_logs', {
      action: 'document_uploaded',
      applicationId: input.applicationId,
      timestamp: new Date().toISOString(),
      ipAddress: userIp,
      userAgent: userAgent
    });
    ```
  </Accordion>

  <Accordion title="Compliance Monitoring">
    * Regular review of declined applications
    * Monthly compliance reports
    * Suspicious activity reporting (SAR)
    * Customer due diligence (CDD)
  </Accordion>
</AccordionGroup>

## Next Demo

<Card title="HR Assistant" icon="user-tie" href="/demos/hr-assistant">
  See internal employee management with BambooHR
</Card>


# Healthcare Patient Portal
Source: https://docs.heylua.ai/demos/healthcare-portal

Patient services with EMR API integration

## Overview

Healthcare patient portal integrating with **Electronic Medical Records (EMR) API** for appointments, prescriptions, and medical records.

**What it does:**

* Schedule appointments
* View medical records
* Request prescription refills
* Access test results
* Message healthcare providers

**APIs used:** EMR/FHIR API (external) + Lua Data API

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, PreProcessor, PostProcessor } from "lua-cli";
import {
  ScheduleAppointmentTool,
  ViewMedicalRecordsTool,
  RequestPrescriptionRefillTool,
  MessageProviderTool
} from "./tools/HealthcareTools";

// Healthcare skill
const healthcareSkill = new LuaSkill({
  name: "healthcare-portal",
  description: "Patient portal services for appointments and medical records",
  context: `
    This skill helps patients manage their healthcare.
    
    - schedule_appointment: Book medical appointments
    - view_medical_records: Access patient records (HIPAA compliant)
    - request_prescription_refill: Request medication refills
    - message_provider: Send secure messages to healthcare providers
    
    Always verify patient identity.
    Maintain HIPAA compliance.
    Be compassionate and professional.
  `,
  tools: [
    new ScheduleAppointmentTool(),
    new ViewMedicalRecordsTool(),
    new RequestPrescriptionRefillTool(),
    new MessageProviderTool()
  ]
});

// HIPAA consent validator
const hipaaConsentPreProcessor = new PreProcessor({
  name: 'hipaa-consent',
  description: 'Verify patient has consented to access medical information',
  execute: async (message, user) => {
    if (!user.data.hipaaConsentGiven) {
      return {
        block: true,
        response: "Before accessing your medical information, please confirm you consent to HIPAA terms. Reply 'I consent' to continue."
      };
    }
    return { block: false };
  }
});

// Medical disclaimer postprocessor
const medicalDisclaimerPostProcessor = new PostProcessor({
  name: 'medical-disclaimer',
  description: 'Add medical disclaimer to all responses',
  execute: async (user, message, response, channel) => {
    return {
      modifiedResponse: response + 
        "\n\n⚕️ **Medical Disclaimer:** This information is for patient portal access only. Always consult your healthcare provider for medical advice. In case of emergency, call 911."
    };
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "healthcare-portal-assistant",
  
  persona: `You are a compassionate healthcare patient portal assistant.
  
Your role:
- Help patients schedule appointments
- Provide access to medical records
- Assist with prescription refills
- Facilitate communication with providers
- Guide through portal features

Communication style:
- Compassionate and reassuring
- Professional and respectful
- Clear and patient
- Privacy-conscious
- HIPAA compliant

Compliance requirements:
- Verify patient identity
- Maintain HIPAA compliance
- Protect patient privacy
- Secure all communications
- Document all interactions

Best practices:
- Always verify patient consent before accessing records
- Explain medical terminology in simple terms
- Provide clear appointment instructions
- Remind about prescription pickup locations
- Encourage emergency services when appropriate

When to escalate:
- Medical emergencies (direct to 911)
- Complex medical questions (refer to provider)
- Billing disputes (refer to billing department)
- Insurance questions (refer to insurance coordinator)`,

  
  skills: [healthcareSkill],
  preProcessors: [hipaaConsentPreProcessor],
  postProcessors: [medicalDisclaimerPostProcessor]
});
```

<Note>
  This demo uses `LuaAgent` with preprocessors for HIPAA consent validation and postprocessors for medical disclaimers.
</Note>

### src/tools/HealthcareTools.ts

```typescript theme={null}
import { LuaTool, Data, env } from "lua-cli";
import { z } from "zod";

// 1. Schedule Appointment (External EMR API)
export class ScheduleAppointmentTool implements LuaTool {
  name = "schedule_appointment";
  description = "Schedule a medical appointment";
  
  inputSchema = z.object({
    patientId: z.string(),
    providerId: z.string(),
    appointmentType: z.enum(['checkup', 'specialist', 'follow-up', 'urgent']),
    preferredDate: z.string(),
    preferredTime: z.string(),
    reason: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const emrApiKey = env('EMR_API_KEY');
    const emrBaseUrl = env('EMR_API_URL');
    
    // Call FHIR-compliant EMR API
    const response = await fetch(`${emrBaseUrl}/fhir/Appointment`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${emrApiKey}`,
        'Content-Type': 'application/fhir+json'
      },
      body: JSON.stringify({
        resourceType: 'Appointment',
        status: 'proposed',
        serviceType: [{ text: input.appointmentType }],
        participant: [
          { actor: { reference: `Patient/${input.patientId}` } },
          { actor: { reference: `Practitioner/${input.providerId}` } }
        ],
        requestedPeriod: [{
          start: `${input.preferredDate}T${input.preferredTime}:00`,
          end: `${input.preferredDate}T${this.addHour(input.preferredTime)}:00`
        }],
        reason: [{ text: input.reason }]
      })
    });
    
    const appointment = await response.json();
    
    return {
      success: true,
      appointmentId: appointment.id,
      date: input.preferredDate,
      time: input.preferredTime,
      provider: input.providerId,
      type: input.appointmentType,
      message: `Appointment scheduled for ${input.preferredDate} at ${input.preferredTime}`
    };
  }
  
  private addHour(time: string): string {
    const [hours, minutes] = time.split(':');
    const newHour = (parseInt(hours) + 1).toString().padStart(2, '0');
    return `${newHour}:${minutes}`;
  }
}

// 2. View Medical Records (External EMR API)
export class ViewMedicalRecordsTool implements LuaTool {
  name = "view_medical_records";
  description = "Access patient medical records";
  
  inputSchema = z.object({
    patientId: z.string(),
    recordType: z.enum(['allergies', 'medications', 'conditions', 'procedures']).optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const emrApiKey = env('EMR_API_KEY');
    const emrBaseUrl = env('EMR_API_URL');
    
    const endpoint = input.recordType || 'Patient';
    const response = await fetch(
      `${emrBaseUrl}/fhir/${endpoint}/${input.patientId}`,
      {
        headers: {
          'Authorization': `Bearer ${emrApiKey}`,
          'Accept': 'application/fhir+json'
        }
      }
    );
    
    const data = await response.json();
    
    return {
      patientId: input.patientId,
      recordType: input.recordType || 'summary',
      lastUpdated: data.meta?.lastUpdated,
      summary: this.formatMedicalData(data),
      message: "Medical records retrieved. Always consult with your healthcare provider."
    };
  }
  
  private formatMedicalData(data: any) {
    // Format EMR data for patient-friendly display
    return {
      allergies: data.allergy || [],
      medications: data.medicationStatement || [],
      conditions: data.condition || []
    };
  }
}

// 3. Request Prescription Refill (External EMR + Pharmacy API)
export class RefillPrescriptionTool implements LuaTool {
  name = "refill_prescription";
  description = "Request prescription refill";
  
  inputSchema = z.object({
    patientId: z.string(),
    prescriptionId: z.string(),
    pharmacyId: z.string(),
    deliveryMethod: z.enum(['pickup', 'delivery']).default('pickup')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const emrApiKey = env('EMR_API_KEY');
    const pharmacyApiKey = env('PHARMACY_API_KEY');
    
    // Request refill through pharmacy API
    const response = await fetch('https://pharmacy-api.com/api/v1/refills', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${pharmacyApiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        patient_id: input.patientId,
        prescription_id: input.prescriptionId,
        pharmacy_id: input.pharmacyId,
        delivery_method: input.deliveryMethod
      })
    });
    
    const refill = await response.json();
    
    return {
      success: true,
      refillId: refill.id,
      status: refill.status,
      estimatedReady: refill.estimated_ready_time,
      deliveryMethod: input.deliveryMethod,
      message: input.deliveryMethod === 'pickup'
        ? `Prescription will be ready for pickup in ${refill.estimated_ready_time}`
        : `Prescription will be delivered to your address`
    };
  }
}

// 4. Search Health Info (Lua Data - Vector Search)
export class SearchHealthInfoTool implements LuaTool {
  name = "search_health_info";
  description = "Search health information and educational content";
  
  inputSchema = z.object({
    query: z.string().describe("Health question or topic")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Use vector search for health information
    const results = await Data.search('health_articles', input.query, 5, 0.75);
    
    return {
      articles: results.map(entry => ({
        title: entry.title,
        summary: entry.summary,
        category: entry.category,
        source: entry.source,
        url: entry.url,
        relevance: entry.score
      })),
      disclaimer: "This information is educational. Always consult your healthcare provider for medical advice."
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env
EMR_API_KEY=your_emr_api_key
EMR_API_URL=https://your-emr-system.com
PHARMACY_API_KEY=your_pharmacy_api_key
```

## Security & Compliance

<Warning>
  **HIPAA Compliance Required**

  This example shows the technical integration. For production:

  * Implement proper authentication (OAuth 2.0)
  * Encrypt all PHI (Protected Health Information)
  * Maintain audit logs
  * Use secure connections only
  * Follow HIPAA guidelines
</Warning>

## Key Features

<CardGroup>
  <Card title="EMR Integration" icon="hospital">
    FHIR-compliant API
  </Card>

  <Card title="Privacy First" icon="lock">
    HIPAA considerations
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    Health info search
  </Card>

  <Card title="Multi-System" icon="network-wired">
    EMR + Pharmacy APIs
  </Card>
</CardGroup>


# Hotel Booking Agent
Source: https://docs.heylua.ai/demos/hotel-booking

Reservation management with Lua Data API

## Overview

Hotel concierge AI agent for room bookings, reservations, and guest services using **Lua Data API**.

**What it does:**

* Check room availability
* Create reservations
* Modify bookings
* Request room service
* Provide local recommendations

**APIs used:** Lua Data API for reservations and rooms

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  CheckAvailabilityTool,
  CreateReservationTool,
  GetReservationTool,
  CancelReservationTool,
  RoomServiceTool
} from "./tools/HotelTools";

// Hotel concierge skill
const hotelSkill = new LuaSkill({
  name: "hotel-concierge",
  description: "Hotel booking and concierge services",
  context: `
    This skill helps guests with hotel bookings and services.
    
    - check_availability: Search for available rooms by date and guest count
    - create_reservation: Book a room for specified dates
    - get_reservation: Look up existing reservation details
    - cancel_reservation: Cancel a booking
    - room_service: Order room service or request amenities
    
    Always confirm dates and guest count before booking.
    Offer upgrade suggestions when available.
    Be warm and hospitable.
  `,
  tools: [
    new CheckAvailabilityTool(),
    new CreateReservationTool(),
    new GetReservationTool(),
    new CancelReservationTool(),
    new RoomServiceTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "hotel-concierge-assistant",
  
  persona: `You are a friendly and professional hotel concierge.
  
Your role:
- Help guests find and book the perfect room
- Assist with reservations and modifications
- Provide room service and amenity requests
- Offer local recommendations and directions
- Ensure excellent guest experience

Communication style:
- Warm and hospitable
- Professional and attentive
- Proactive with suggestions
- Detail-oriented
- Service-minded

Best practices:
- Always confirm check-in and check-out dates
- Mention amenities included with each room type
- Offer upgrades when available
- Ask about special occasions (anniversary, birthday)
- Provide clear cancellation policies
- Suggest local attractions and dining

When to escalate:
- VIP guest requests
- Complex group bookings
- Special event coordination
- Maintenance issues`,

  
  skills: [hotelSkill]
});
```

<Note>
  This demo uses `LuaAgent` to configure the agent's persona, welcome message, and skills.
</Note>

### src/tools/HotelTools.ts

```typescript theme={null}
import { LuaTool, Data } from "lua-cli";
import { z } from "zod";

// 1. Check Availability
export class CheckAvailabilityTool implements LuaTool {
  name = "check_availability";
  description = "Check room availability for specific dates";
  
  inputSchema = z.object({
    checkIn: z.string().describe("Check-in date (YYYY-MM-DD)"),
    checkOut: z.string().describe("Check-out date (YYYY-MM-DD)"),
    guests: z.number().min(1).max(10).describe("Number of guests")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get all rooms
    const rooms = await Data.get('hotel_rooms', {}, 1, 100);
    
    // Get existing reservations for these dates
    const reservations = await Data.get('reservations', {
      checkIn: { $lte: input.checkOut },
      checkOut: { $gte: input.checkIn },
      status: { $ne: 'cancelled' }
    });
    
    const bookedRoomIds = new Set(reservations.data.map(r => r.data.roomId));
    
    // Filter available rooms
    const available = rooms.data
      .filter(room => !bookedRoomIds.has(room.id))
      .filter(room => room.data.maxGuests >= input.guests)
      .map(room => ({
        roomId: room.id,
        roomType: room.data.type,
        maxGuests: room.data.maxGuests,
        pricePerNight: `$${room.data.pricePerNight}`,
        amenities: room.data.amenities,
        description: room.data.description
      }));
    
    const nights = this.calculateNights(input.checkIn, input.checkOut);
    
    return {
      available: available.length > 0,
      rooms: available,
      checkIn: input.checkIn,
      checkOut: input.checkOut,
      nights,
      message: available.length > 0
        ? `${available.length} rooms available for ${nights} nights`
        : "No rooms available for these dates. Try different dates?"
    };
  }
  
  private calculateNights(checkIn: string, checkOut: string): number {
    const start = new Date(checkIn);
    const end = new Date(checkOut);
    return Math.ceil((end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24));
  }
}

// 2. Create Reservation
export class CreateReservationTool implements LuaTool {
  name = "create_reservation";
  description = "Book a hotel room";
  
  inputSchema = z.object({
    roomId: z.string(),
    checkIn: z.string(),
    checkOut: z.string(),
    guestName: z.string(),
    guestEmail: z.string().email(),
    guestPhone: z.string(),
    guests: z.number().min(1),
    specialRequests: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get room details
    const room = await Data.getEntry('hotel_rooms', input.roomId);
    
    if (!room) {
      throw new Error('Room not found');
    }
    
    // Calculate total
    const nights = this.calculateNights(input.checkIn, input.checkOut);
    const totalPrice = room.data.pricePerNight * nights;
    
    // Create reservation
    const reservation = await Data.create('reservations', {
      roomId: input.roomId,
      roomType: room.data.type,
      checkIn: input.checkIn,
      checkOut: input.checkOut,
      guestName: input.guestName,
      guestEmail: input.guestEmail,
      guestPhone: input.guestPhone,
      numberOfGuests: input.guests,
      nights,
      pricePerNight: room.data.pricePerNight,
      totalPrice,
      specialRequests: input.specialRequests,
      status: 'confirmed',
      confirmationCode: this.generateConfirmationCode(),
      createdAt: new Date().toISOString()
    }, `${input.guestName} ${input.guestEmail} ${input.checkIn}`);
    
    return {
      success: true,
      reservationId: reservation.id,
      confirmationCode: reservation.data.confirmationCode,
      roomType: room.data.type,
      checkIn: input.checkIn,
      checkOut: input.checkOut,
      nights,
      total: `$${totalPrice.toFixed(2)}`,
      message: `Reservation confirmed! Your confirmation code is ${reservation.data.confirmationCode}`
    };
  }
  
  private calculateNights(checkIn: string, checkOut: string): number {
    const start = new Date(checkIn);
    const end = new Date(checkOut);
    return Math.ceil((end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24));
  }
  
  private generateConfirmationCode(): string {
    return 'HTL-' + Math.random().toString(36).substring(2, 10).toUpperCase();
  }
}

// 3. Get Reservation
export class GetReservationTool implements LuaTool {
  name = "get_reservation";
  description = "Look up reservation details";
  
  inputSchema = z.object({
    confirmationCode: z.string().describe("Reservation confirmation code"),
    email: z.string().email().describe("Guest email for verification")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Search reservations
    const results = await Data.get('reservations', {
      confirmationCode: input.confirmationCode,
      guestEmail: input.email
    });
    
    if (results.data.length === 0) {
      throw new Error('Reservation not found. Please check your confirmation code and email.');
    }
    
    const reservation = results.data[0];
    
    return {
      reservationId: reservation.id,
      confirmationCode: reservation.data.confirmationCode,
      guestName: reservation.data.guestName,
      roomType: reservation.data.roomType,
      checkIn: reservation.data.checkIn,
      checkOut: reservation.data.checkOut,
      nights: reservation.data.nights,
      guests: reservation.data.numberOfGuests,
      total: `$${reservation.data.totalPrice.toFixed(2)}`,
      status: reservation.data.status,
      specialRequests: reservation.data.specialRequests
    };
  }
}

// 4. Cancel Reservation
export class CancelReservationTool implements LuaTool {
  name = "cancel_reservation";
  description = "Cancel a hotel reservation";
  
  inputSchema = z.object({
    confirmationCode: z.string(),
    email: z.string().email()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Data.get('reservations', {
      confirmationCode: input.confirmationCode,
      guestEmail: input.email
    });
    
    if (results.data.length === 0) {
      throw new Error('Reservation not found');
    }
    
    const reservation = results.data[0];
    
    // Update status to cancelled
    await Data.update('reservations', reservation.id, {
      ...reservation.data,
      status: 'cancelled',
      cancelledAt: new Date().toISOString()
    });
    
    return {
      success: true,
      confirmationCode: input.confirmationCode,
      refundAmount: `$${reservation.data.totalPrice.toFixed(2)}`,
      message: "Reservation cancelled. Refund will be processed within 5-7 business days."
    };
  }
}

// 5. Room Service
export class RoomServiceTool implements LuaTool {
  name = "room_service";
  description = "Order room service or request amenities";
  
  inputSchema = z.object({
    confirmationCode: z.string(),
    request: z.string().describe("Room service order or amenity request")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Log room service request
    const request = await Data.create('room_service_requests', {
      confirmationCode: input.confirmationCode,
      request: input.request,
      status: 'pending',
      requestedAt: new Date().toISOString()
    }, input.request);
    
    return {
      success: true,
      requestId: request.id,
      estimatedTime: "15-30 minutes",
      message: `Room service request received. Estimated delivery: 15-30 minutes.`
    };
  }
}
```

## Deployment

```bash theme={null}
lua push
lua deploy
```

## Key Features

<CardGroup>
  <Card title="Lua Data API" icon="database">
    Stores rooms and reservations
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    Search reservations by guest info
  </Card>

  <Card title="Date Logic" icon="calendar">
    Availability checking
  </Card>

  <Card title="Confirmation Codes" icon="ticket">
    Unique booking identifiers
  </Card>
</CardGroup>


# HR Operations Assistant
Source: https://docs.heylua.ai/demos/hr-assistant

Internal HR automation with BambooHR API + Lua Data

## Overview

Internal HR assistant integrating with **BambooHR API** for employee management and **Lua Data API** for company policies and documents.

**What it does:**

* Look up employee information
* Request time off
* Search HR policies
* Onboard new employees
* Answer benefits questions

**APIs used:** BambooHR API (external) + Lua Data API (policies)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaJob } from "lua-cli";
import {
  SearchPoliciesTool,
  GetEmployeeInfoTool,
  RequestTimeOffTool
} from "./tools/HRTools";

// HR skill
const hrSkill = new LuaSkill({
  name: "hr-operations",
  description: "Internal HR operations and employee services",
  context: `
    This skill helps employees with HR-related requests.
    
    - search_policies: Search company policies and procedures
    - get_employee_info: Look up employee information
    - request_time_off: Submit time off requests
    
    Always be helpful and professional.
    Ensure confidentiality of employee information.
  `,
  tools: [
    new SearchPoliciesTool(),
    new GetEmployeeInfoTool(),
    new RequestTimeOffTool()
  ]
});

// Daily attendance report job
const attendanceReportJob = new LuaJob({
  name: 'daily-attendance-report',
  description: 'Send daily attendance summary',
  schedule: {
    type: 'cron',
    pattern: '0 17 * * 1-5'  // Every weekday at 5 PM
  },
  execute: async (job) => {
    const user = await job.user();
    await user.send([{
      type: 'text',
      text: '📊 Daily attendance report is ready. All employees accounted for.'
    }]);
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "hr-operations-assistant",
  
  persona: `You are a professional and helpful HR assistant.
  
Your role:
- Help employees find HR policies and procedures
- Look up employee information
- Process time off requests
- Answer benefits and payroll questions
- Guide through HR processes

Communication style:
- Professional and friendly
- Confidential and trustworthy
- Clear and helpful
- Empathetic and supportive

Best practices:
- Maintain confidentiality of employee information
- Provide accurate policy information
- Direct employees to appropriate resources
- Confirm details before processing requests
- Follow company HR policies strictly

When to escalate:
- Sensitive employee relations issues
- Compensation discussions
- Disciplinary matters
- Legal or compliance questions`,

  
  skills: [hrSkill],
  jobs: [attendanceReportJob]
});
```

<Note>
  This demo uses `LuaAgent` with scheduled jobs for daily attendance reports.
</Note>

### src/tools/HRTools.ts

```typescript theme={null}
import { LuaTool, Data, env } from "lua-cli";
import { z } from "zod";

// 1. Search HR Policies (Lua Vector Search)
export class SearchPoliciesTool implements LuaTool {
  name = "search_policies";
  description = "Search company HR policies and procedures";
  
  inputSchema = z.object({
    query: z.string().describe("Policy question or keyword")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Data.search('hr_policies', input.query, 5, 0.7);
    
    return {
      policies: results.map(entry => ({
        title: entry.title,
        summary: entry.content.substring(0, 200) + '...',
        category: entry.category,
        lastUpdated: entry.updatedAt,
        relevance: `${Math.round(entry.score * 100)}%`
      })),
      count: results.length
    };
  }
}

// 2. Get Employee Info (BambooHR External API)
export class GetEmployeeInfoTool implements LuaTool {
  name = "get_employee_info";
  description = "Look up employee information";
  
  inputSchema = z.object({
    employeeId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const bambooApiKey = env('BAMBOOHR_API_KEY');
    const bambooSubdomain = env('BAMBOOHR_SUBDOMAIN');
    
    const response = await fetch(
      `https://api.bamboohr.com/api/gateway.php/${bambooSubdomain}/v1/employees/${input.employeeId}`,
      {
        headers: {
          'Authorization': `Basic ${Buffer.from(bambooApiKey + ':x').toString('base64')}`,
          'Accept': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error('Employee not found');
    }
    
    const employee = await response.json();
    
    return {
      employeeId: employee.id,
      name: `${employee.firstName} ${employee.lastName}`,
      department: employee.department,
      jobTitle: employee.jobTitle,
      hireDate: employee.hireDate,
      manager: employee.supervisor,
      workEmail: employee.workEmail
    };
  }
}

// 3. Request Time Off (BambooHR External API)
export class RequestTimeOffTool implements LuaTool {
  name = "request_time_off";
  description = "Submit a time off request";
  
  inputSchema = z.object({
    employeeId: z.string(),
    startDate: z.string(),
    endDate: z.string(),
    timeOffType: z.enum(['vacation', 'sick', 'personal']),
    notes: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const bambooApiKey = env('BAMBOOHR_API_KEY');
    const bambooSubdomain = env('BAMBOOHR_SUBDOMAIN');
    
    const response = await fetch(
      `https://api.bamboohr.com/api/gateway.php/${bambooSubdomain}/v1/employees/${input.employeeId}/time_off/request`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Basic ${Buffer.from(bambooApiKey + ':x').toString('base64')}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          start: input.startDate,
          end: input.endDate,
          timeOffTypeId: input.timeOffType,
          notes: input.notes
        })
      }
    );
    
    const data = await response.json();
    
    return {
      success: true,
      requestId: data.id,
      status: 'pending_approval',
      message: "Time off request submitted. You'll be notified when approved."
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env
BAMBOOHR_API_KEY=your_bamboohr_api_key
BAMBOOHR_SUBDOMAIN=your_company
```

## Key Features

<CardGroup>
  <Card title="External HRIS" icon="users">
    BambooHR integration
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    Policy semantic search
  </Card>
</CardGroup>


# IoT Security Camera
Source: https://docs.heylua.ai/demos/iot-camera

Capture photos on-demand with Raspberry Pi Camera via chat

## Overview

Capture still images from a **Raspberry Pi Camera Module** through natural language commands. Take photos on-demand, schedule periodic snapshots, or trigger captures from webhooks.

**What it does:**

* Capture photos via chat commands
* Save images with timestamps
* Schedule periodic snapshots
* Webhook-triggered captures (motion detection, etc.)

**Hardware:** Raspberry Pi 4/5, Camera Module 3/HQ (CSI connection)

**APIs used:** Custom Edge API using rpicam-still

***

## Architecture

```
User Chat → Lua Agent → TakePhotoTool → Edge API → rpicam-still → Image File
```

***

## Complete Implementation

### Edge API on Raspberry Pi

#### Setup (one-time)

```bash theme={null}
# Install OS packages (rpicam-* apps are included in Raspberry Pi OS Bookworm)
sudo apt update
sudo apt install -y python3-pip python3-venv

# Create project folder
mkdir -p ~/iot-edge && cd ~/iot-edge
python3 -m venv .venv
source .venv/bin/activate

# Install Flask
pip install flask

# Create output directory for photos
mkdir -p ~/camera-snapshots
```

<Note>
  **Camera on Bookworm:** The modern `rpicam-still` command is included by default. Old `libcamera-still` is now a symlink to `rpicam-still`.
</Note>

#### Edge API Code

Update `edge_api.py` (or add to existing):

```python theme={null}
from flask import Flask, request, jsonify
from functools import wraps
import os, time, subprocess

app = Flask(__name__)
API_KEY = os.environ.get("EDGE_API_KEY", "changeme")

def require_key(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        if request.headers.get("X-API-Key") != API_KEY:
            return jsonify({"error": "unauthorized"}), 401
        return fn(*args, **kwargs)
    return wrapper

@app.get("/health")
def health():
    return {"ok": True, "ts": int(time.time())}

@app.post("/camera/snap")
@require_key
def camera_snap():
    data = request.get_json(force=True, silent=True) or {}
    outdir = data.get("outdir", "/home/pi/camera-snapshots")
    os.makedirs(outdir, exist_ok=True)
    
    filename = time.strftime("snap_%Y%m%d_%H%M%S.jpg")
    path = os.path.join(outdir, filename)

    # Use rpicam-still (modern camera CLI on Bookworm)
    timeout_ms = int(data.get("timeout_ms", 1000))
    width = int(data.get("width", 1920))
    height = int(data.get("height", 1080))
    
    try:
        subprocess.run([
            "rpicam-still",
            "-t", str(timeout_ms),
            "-o", path,
            "--width", str(width),
            "--height", str(height)
        ], check=True, capture_output=True)
        
        return {
            "success": True,
            "path": path,
            "filename": filename,
            "size_bytes": os.path.getsize(path)
        }
    except subprocess.CalledProcessError as e:
        return jsonify({
            "error": "Camera capture failed",
            "details": e.stderr.decode()
        }), 500

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5001)
```

#### Run Edge API

```bash theme={null}
export EDGE_API_KEY="supersecret"
python edge_api.py
```

#### Test Edge API

```bash theme={null}
curl -X POST http://raspberrypi.local:5001/camera/snap \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"timeout_ms":2000,"width":1920,"height":1080}'
```

***

### Lua Agent Implementation

#### src/tools/TakePhotoTool.ts

```typescript theme={null}
import { LuaTool, Data, env } from 'lua-cli';
import { z } from 'zod';

export default class TakePhotoTool implements LuaTool {
  name = "take_photo";
  description = "Capture a still image with the Raspberry Pi camera";
  
  inputSchema = z.object({
    timeout_ms: z.number().int().default(1000).describe("Preview time before capture (ms)"),
    width: z.number().int().default(1920).describe("Image width"),
    height: z.number().int().default(1080).describe("Image height"),
    outdir: z.string().default("/home/pi/camera-snapshots").describe("Output directory")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const base = env('PI_BASE_URL');
    const key = env('PI_API_KEY');
    
    if (!base || !key) {
      throw new Error('PI_BASE_URL or PI_API_KEY not configured');
    }

    const res = await fetch(`${base}/camera/snap`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': key
      },
      body: JSON.stringify(input)
    });
    
    if (!res.ok) {
      throw new Error(`Camera error: ${res.status} ${await res.text()}`);
    }
    
    const result = await res.json();
    
    // Log photo in Lua Data
    await Data.create('camera_snapshots', {
      filename: result.filename,
      path: result.path,
      size_bytes: result.size_bytes,
      width: input.width,
      height: input.height,
      capturedAt: new Date().toISOString()
    }, `camera photo ${result.filename}`);
    
    return {
      success: true,
      filename: result.filename,
      path: result.path,
      size: `${Math.round(result.size_bytes / 1024)} KB`,
      resolution: `${input.width}×${input.height}`,
      message: `Photo captured: ${result.filename}`
    };
  }
}
```

#### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaJob, LuaWebhook } from 'lua-cli';
import TakePhotoTool from './tools/TakePhotoTool';

// Camera control skill
const cameraSkill = new LuaSkill({
  name: "pi-camera",
  description: "Raspberry Pi camera control and snapshot capture",
  context: `
    This skill controls a Raspberry Pi camera.
    
    - take_photo: Capture a still image
      Use when user asks for a photo, snapshot, or image
      
    Always confirm photo was captured successfully.
    Mention filename and size in response.
  `,
  tools: [new TakePhotoTool()]
});

// Scheduled job: Daily snapshot at noon
const dailySnapshotJob = new LuaJob({
  name: 'daily-snapshot',
  description: 'Capture daily photo at noon',
  schedule: {
    type: 'cron',
    pattern: '0 12 * * *'  // Every day at 12 PM
  },
  execute: async (job) => {
    const tool = new TakePhotoTool();
    const result = await tool.execute({
      timeout_ms: 2000,
      width: 1920,
      height: 1080,
      outdir: '/home/pi/camera-snapshots'
    });
    
    const user = await job.user();
    await user.send([{
      type: 'text',
      text: `📷 Daily snapshot captured: ${result.filename} (${result.size})`
    }]);
  }
});

// Webhook: Motion-triggered capture
const motionWebhook = new LuaWebhook({
  name: 'motion-triggered-capture',
  description: 'Capture photo when motion is detected',
  execute: async (event) => {
    if (event.type === 'motion.detected') {
      const tool = new TakePhotoTool();
      const result = await tool.execute({ timeout_ms: 500 });
      
      const user = await User.get();
      await user.send([{
        type: 'text',
        text: `🚨 Motion detected! Photo captured: ${result.filename}`
      }]);
    }
    return { received: true };
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "camera-monitor",
  
  persona: `You are a security camera monitoring assistant.
  
Your role:
- Capture photos on demand
- Monitor for motion events
- Provide photo confirmations
- Track snapshot history

Communication style:
- Quick and confirmatory
- Security-focused
- Clear about photo details

Best practices:
- Confirm photo capture immediately
- Mention filename and size
- Alert on motion detection
- Provide photo timestamps

Camera knowledge:
- Resolution: 1920×1080 (Full HD)
- Format: JPEG
- Storage: Local Pi storage
- Retention: Configurable

When to alert:
- Motion detected
- Storage running low
- Camera errors`,

  
  skills: [cameraSkill],
  jobs: [dailySnapshotJob],
  webhooks: [motionWebhook]
});
```

<Note>
  Uses LuaAgent with scheduled jobs for daily snapshots and webhooks for motion-triggered captures.
</Note>

***

## Environment Setup

```bash theme={null}
# .env
PI_BASE_URL=http://raspberrypi.local:5001
PI_API_KEY=supersecret
```

***

## Camera Setup

### Physical Connection

Connect Camera Module 3 or HQ to the CSI port on Raspberry Pi. Ensure ribbon cable is firmly seated.

### Verify Camera

```bash theme={null}
# Test camera (Bookworm uses rpicam-still)
rpicam-still -t 2000 -o test.jpg

# Check image
ls -lh test.jpg
```

<Warning>
  **Troubleshooting:** If camera is not detected, check ribbon cable connection and run `vcgencmd get_camera` to verify detection.
</Warning>

***

## Testing

```bash theme={null}
# Test tool
lua test
# Select: take_photo

# Test conversationally
lua chat
# You: "Take a photo of the front door"
# You: "Capture an image now"
# You: "Take a high-res snapshot"
```

***

## Key Features

<CardGroup>
  <Card title="On-Demand Capture" icon="camera">
    Take photos via natural language commands
  </Card>

  <Card title="Scheduled Snapshots" icon="clock">
    Daily photos at specified times
  </Card>

  <Card title="Motion-Triggered" icon="radar">
    Webhook integration for motion sensors
  </Card>

  <Card title="Photo History" icon="database">
    Track all captures in Lua Data
  </Card>
</CardGroup>

***

## Advanced: Motion Detection Integration

If you add a PIR motion sensor, you can trigger the webhook:

```python theme={null}
# In edge_api.py, add motion detection endpoint
from gpiozero import MotionSensor

@app.post("/motion/trigger-webhook")
@require_key
def motion_trigger():
    webhook_url = os.environ.get("MOTION_WEBHOOK_URL")
    if webhook_url:
        requests.post(webhook_url, json={"type": "motion.detected", "timestamp": time.time()})
    return {"triggered": True}
```

Your Lua webhook will receive the event and capture a photo automatically.

***

## Next Steps

<Card title="View All IoT Demos" icon="microchip" href="/demos/overview#iot-automation">
  See all 3 Raspberry Pi examples
</Card>


# IoT Door Access Control
Source: https://docs.heylua.ai/demos/iot-door-assistant

WhatsApp-controlled door locks with Raspberry Pi for hotels and apartments

## Overview

Production-ready door access control system where **guests WhatsApp your agent to open doors**. Perfect for hotels, apartments, coworking spaces, or any building requiring secure access control.

**What it does:**

* Guests WhatsApp to unlock doors
* Verify guest access permissions
* Time-window access control
* Audit logging of all unlocks
* Staff tools for guest registration

**Hardware:** Raspberry Pi 4/5, relay module, 12V electric strike or maglock

**APIs used:** Lua WhatsApp channel + Edge API (Flask) + Lua Data API (guest management)

***

## Architecture

```
WhatsApp Message → Lua Agent → Check Access → Unlock Door Tool → Pi Edge API → Relay → Door Strike
                                      ↓
                               Lua Data (Guests)
```

<Warning>
  **Security-First Design:** Always verify guest access before unlocking. This demo includes time-window validation, rate limiting, and audit logging.
</Warning>

***

## Hardware Setup

### Components

<CardGroup>
  <Card title="Raspberry Pi 4/5" icon="microchip">
    Main controller running Edge API
  </Card>

  <Card title="Relay Module" icon="bolt">
    3.3V-compatible, optocoupled (active-low)
  </Card>

  <Card title="Electric Strike" icon="door-open">
    12V fail-secure strike or maglock
  </Card>

  <Card title="Power Supply" icon="plug">
    Separate 12V PSU for the lock
  </Card>
</CardGroup>

### Wiring

```
Raspberry Pi          Relay Module         Electric Strike
-----------          -------------         ---------------
3.3V        ────────> VCC                
GND         ────────> GND                 
GPIO 17     ────────> IN (Signal)         
                      COM ───────────────> 12V+ (from PSU)
                      NO ────────────────> Strike +
                      
                      Strike - ──────────> 12V- (from PSU)
```

<Warning>
  **Safety Critical:**

  * Use optocoupled relay module for isolation
  * NEVER power lock from Pi (use separate 12V PSU)
  * Add flyback diode across lock coil
  * Use fail-secure locks (locked when de-energized)
  * Keep unlock pulses short (2-5 seconds)
</Warning>

***

## Complete Implementation

### 1. Raspberry Pi Edge API

#### Setup

```bash theme={null}
# Install dependencies (Raspberry Pi OS Bookworm)
sudo apt update
sudo apt install -y python3-pip python3-venv python3-libgpiod

# Add user to gpio group (allows GPIO without sudo)
sudo adduser $USER gpio
# Log out and back in for this to take effect

# Create project
mkdir -p ~/door-edge && cd ~/door-edge
python3 -m venv .venv
source .venv/bin/activate
pip install flask gpiozero
```

#### Edge API Code

Create `edge_api.py`:

```python theme={null}
from flask import Flask, request, jsonify
import os, time
from gpiozero import OutputDevice

API_KEY = os.environ.get("EDGE_API_KEY", "changeme")
DEFAULT_PIN = int(os.environ.get("DOOR_PIN", "17"))   # BCM numbering
ACTIVE_LOW = os.environ.get("ACTIVE_LOW", "true").lower() == "true"
DEFAULT_UNLOCK_MS = int(os.environ.get("UNLOCK_MS", "3000"))

app = Flask(__name__)
_last_unlock = 0

def authorized(req):
    return req.headers.get("X-API-Key") == API_KEY

@app.get("/health")
def health():
    return {"ok": True, "ts": int(time.time())}

@app.post("/door/unlock")
def door_unlock():
    if not authorized(request):
        return jsonify({"error": "unauthorized"}), 401

    global _last_unlock
    now = time.time()
    
    # Rate limiting: prevent unlocks within 2 seconds
    if now - _last_unlock < 2:
        return {"ok": False, "rate_limited": True}, 429

    data = request.get_json(force=True, silent=True) or {}
    pin = int(data.get("pin", DEFAULT_PIN))
    ms = int(data.get("ms", DEFAULT_UNLOCK_MS))
    active_low = bool(data.get("active_low", ACTIVE_LOW))

    # Validate unlock duration (safety)
    if ms < 500 or ms > 10000:
        return {"error": "Invalid unlock duration (500-10000ms)"}, 400

    dev = OutputDevice(pin, active_high=not active_low, initial_value=False)
    try:
        dev.on()                    # Energize relay → unlock
        time.sleep(ms / 1000.0)
        dev.off()                   # De-energize → relock
        _last_unlock = time.time()
        
        return {
            "ok": True, 
            "pin": pin, 
            "ms": ms, 
            "active_low": active_low,
            "timestamp": int(time.time())
        }
    finally:
        dev.close()

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5001)
```

#### Run Edge API

```bash theme={null}
export EDGE_API_KEY="supersecret"
export DOOR_PIN=17
export ACTIVE_LOW=true
export UNLOCK_MS=3000

python edge_api.py
```

#### Test Edge API

```bash theme={null}
# Health check
curl http://raspberrypi.local:5001/health

# Test unlock
curl -X POST http://raspberrypi.local:5001/door/unlock \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"pin":17,"ms":3000,"active_low":true}'
```

***

### 2. Lua Agent Implementation

#### Environment Variables

```bash theme={null}
# .env
PI_BASE_URL=http://raspberrypi.local:5001
PI_API_KEY=supersecret
DOOR_MAP_JSON={"front":17,"garage":27}
DEFAULT_UNLOCK_MS=3000
ACTIVE_LOW=true
BUILDING_ID=hotel-abc
```

Or set via CLI:

```bash theme={null}
lua env sandbox
# Add all the above variables
```

#### src/tools/CheckAccessTool.ts

```typescript theme={null}
import { LuaTool, Data, env } from 'lua-cli';
import { z } from 'zod';

export default class CheckAccessTool implements LuaTool {
  name = "check_access";
  description = "Verify if a phone number has active access to a given door";
  
  inputSchema = z.object({
    phone: z.string().describe("WhatsApp phone number (E.164 format)"),
    door: z.string().default("front").describe("Door name (front, garage, etc.)")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const now = Date.now();
    const buildingId = env('BUILDING_ID') || 'default';

    // Query guests with valid access
    const result = await Data.get('guests', {
      phone: input.phone,
      buildingId,
      status: 'ACTIVE',
      startAt: { $lte: now },
      endAt: { $gte: now },
      doors: { $in: [input.door] }
    });
    
    const allowed = result.data.length > 0;
    const guest = allowed ? result.data[0] : undefined;

    return {
      allowed,
      guestId: guest?.id,
      name: guest?.data?.name,
      door: input.door,
      validUntil: guest?.data?.endAt 
        ? new Date(guest.data.endAt).toLocaleString()
        : null
    };
  }
}
```

#### src/tools/UnlockDoorTool.ts

```typescript theme={null}
import { LuaTool, Data, env } from 'lua-cli';
import { z } from 'zod';

export default class UnlockDoorTool implements LuaTool {
  name = "unlock_door";
  description = "Pulse the relay to unlock a door for a few seconds";
  
  inputSchema = z.object({
    door: z.string().default("front").describe("Door name to unlock"),
    ms: z.number().int().min(500).max(10000)
      .default(parseInt(env('DEFAULT_UNLOCK_MS') || '3000'))
      .describe("Unlock duration in milliseconds")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const base = env('PI_BASE_URL');
    const key = env('PI_API_KEY');
    
    if (!base || !key) {
      throw new Error('PI_BASE_URL or PI_API_KEY not configured');
    }

    // Map door name to GPIO pin
    const doorMap = JSON.parse(env('DOOR_MAP_JSON') || '{"front":17}');
    const pin = doorMap[input.door];
    
    if (pin === undefined) {
      throw new Error(`Unknown door: ${input.door}`);
    }

    // Call Pi Edge API
    const res = await fetch(`${base}/door/unlock`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': key
      },
      body: JSON.stringify({
        pin,
        ms: input.ms,
        active_low: env('ACTIVE_LOW') === 'true'
      })
    });
    
    if (!res.ok) {
      const error = await res.text();
      throw new Error(`Edge API error: ${res.status} ${error}`);
    }
    
    const result = await res.json();
    
    // Log the unlock event
    await Data.create('door_logs', {
      door: input.door,
      pin: result.pin,
      timestamp: new Date().toISOString(),
      duration_ms: result.ms,
      success: result.ok
    }, `door unlock ${input.door}`);
    
    return {
      success: true,
      door: input.door,
      duration: `${input.ms}ms`,
      message: `Door unlocked. It will re-lock in ~${Math.round(input.ms/1000)}s.`
    };
  }
}
```

#### src/tools/RegisterGuestTool.ts

```typescript theme={null}
import { LuaTool, Data, env } from 'lua-cli';
import { z } from 'zod';

export default class RegisterGuestTool implements LuaTool {
  name = "register_guest";
  description = "Create or extend a guest's access window (staff only)";
  
  inputSchema = z.object({
    phone: z.string().describe("Guest phone number (E.164)"),
    name: z.string().optional().describe("Guest name"),
    buildingId: z.string().default(env('BUILDING_ID') || 'default'),
    doors: z.array(z.string()).describe("Doors guest can access"),
    startAt: z.number().describe("Access start time (epoch ms)"),
    endAt: z.number().describe("Access end time (epoch ms)"),
    status: z.enum(['ACTIVE', 'REVOKED']).default('ACTIVE')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Validate time window
    if (input.startAt >= input.endAt) {
      throw new Error('Start time must be before end time');
    }
    
    const entry = await Data.create('guests', {
      phone: input.phone,
      name: input.name,
      buildingId: input.buildingId,
      doors: input.doors,
      startAt: input.startAt,
      endAt: input.endAt,
      status: input.status,
      registeredAt: new Date().toISOString()
    }, `${input.name || input.phone} ${input.buildingId} ${input.doors.join(',')}`);
    
    return {
      success: true,
      guestId: entry.id,
      name: input.name,
      phone: input.phone,
      doors: input.doors,
      validFrom: new Date(input.startAt).toLocaleString(),
      validUntil: new Date(input.endAt).toLocaleString(),
      message: `Guest access registered for ${input.doors.join(', ')}`
    };
  }
}
```

#### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, PreProcessor } from 'lua-cli';
import CheckAccessTool from './tools/CheckAccessTool';
import UnlockDoorTool from './tools/UnlockDoorTool';
import RegisterGuestTool from './tools/RegisterGuestTool';

// Door control skill
const doorSkill = new LuaSkill({
  name: "door-control",
  description: "Secure door access control via Raspberry Pi",
  context: `
    This skill controls building door access with strict security.
    
    Access Control Flow:
    1. check_access: ALWAYS check first - verify phone has valid access
    2. unlock_door: Only if check_access returns allowed=true
    3. register_guest: Staff only - add or extend guest access
    
    Security Rules:
    - NEVER unlock without verifying access first
    - Check time windows (startAt/endAt)
    - Rate-limit repeated unlock attempts
    - Log all unlock events
    - Confirm which door before unlocking
    
    User Experience:
    - Ask which door if unclear ("front" or "garage")
    - Report unlock duration in response
    - Provide helpful error messages for denied access
    - Suggest contacting staff if no valid booking
  `,
  tools: [
    new CheckAccessTool(),
    new UnlockDoorTool(),
    new RegisterGuestTool()
  ]
});

// Security preprocessor: Rate limiting
const rateLimitPreProcessor = new PreProcessor({
  name: 'unlock-rate-limit',
  description: 'Prevent rapid repeated unlock attempts',
  priority: 1,
  execute: async (message, user) => {
    const text = message.content.toLowerCase();
    
    // Check if message is about unlocking
    if (text.includes('unlock') || text.includes('open door')) {
      // Check recent unlock requests
      const recentUnlocks = await Data.search('door_logs', user.id, 10);
      const lastMinute = recentUnlocks.filter(log => {
        const logTime = new Date(log.timestamp).getTime();
        return Date.now() - logTime < 60000; // Last minute
      });
      
      if (lastMinute.length >= 3) {
        return {
          block: true,
          response: "You've made multiple unlock requests recently. Please wait a moment before trying again."
        };
      }
    }
    
    return { block: false };
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "door-assistant",
  
  persona: `You are a concise, security-focused door access assistant.

Your role:
- Verify guest access permissions before unlocking
- Control door locks securely and safely
- Maintain audit logs of all access
- Provide clear feedback on access status

Security Protocol:
1. Identify user by WhatsApp phone number
2. If user asks to unlock/open door, ask which door if unclear
3. ALWAYS call check_access first to verify permissions
4. If allowed: call unlock_door and confirm success
5. If denied: politely explain and suggest contacting staff
6. Log every unlock attempt

Communication style:
- Concise and professional
- Security-conscious
- Clear about access status
- Helpful with denied requests

Safety rules:
- NEVER unlock without valid access check
- NEVER reveal GPIO pin numbers or internal config
- Rate-limit rapid repeated requests
- Confirm door name before unlocking
- Report unlock duration in confirmation

Typical responses:
- Allowed: "✅ Front door unlocked. It will re-lock in 3 seconds."
- Denied: "I don't have an active booking for your number. Please contact the front desk or provide your booking details."
- Unclear: "Which door would you like to open? Front or garage?"

When to escalate:
- Guest has no valid booking
- Access outside time window
- Technical errors with lock
- Multiple failed attempts`,

  
  skills: [doorSkill],
  preProcessors: [rateLimitPreProcessor]
});
```

<Note>
  Uses LuaAgent with preprocessors for rate limiting and security validation.
</Note>

***

### 2. WhatsApp Channel Setup

<Steps>
  <Step title="Deploy Your Agent">
    ```bash theme={null}
    lua push && lua deploy
    ```
  </Step>

  <Step title="Connect WhatsApp">
    ```bash theme={null}
    lua channels
    ```

    Select WhatsApp and provide:

    * Phone Number ID (from Meta Business Suite)
    * WhatsApp Business Account ID
    * Access Token
  </Step>

  <Step title="Configure Webhook">
    Copy the webhook URL provided by Lua CLI

    In Meta Business Suite → WhatsApp → Configuration:

    * Add webhook URL
    * Subscribe to `messages` events
    * Verify webhook
  </Step>

  <Step title="Test">
    Send a WhatsApp message to your business number:

    * "Open front door"
  </Step>
</Steps>

<Card title="WhatsApp Setup Guide" icon="whatsapp" href="/channels/whatsapp">
  Complete WhatsApp channel setup instructions
</Card>

***

## Guest Management

### Register a Guest (Staff Operation)

Use `lua test` to register guests:

```bash theme={null}
lua test
# Select: register_guest
```

**Example inputs:**

* Phone: +14155551234
* Name: John Doe
* Building ID: hotel-abc
* Doors: \["front", "garage"]
* Start: 1735660800000 (epoch ms for check-in)
* End: 1735833600000 (epoch ms for check-out)
* Status: ACTIVE

Or create via Data API directly:

```typescript theme={null}
await Data.create('guests', {
  phone: '+14155551234',
  name: 'John Doe',
  buildingId: 'hotel-abc',
  doors: ['front', 'garage'],
  startAt: Date.now(),
  endAt: Date.now() + (48 * 3600000), // 48 hours
  status: 'ACTIVE'
}, 'John Doe hotel-abc front,garage');
```

***

## Security Best Practices

<AccordionGroup>
  <Accordion title="✅ Always Verify Access">
    **Never unlock without checking permissions**

    ```typescript theme={null}
    // ALWAYS do this:
    const access = await checkAccess(phone, door);
    if (!access.allowed) {
      return { error: 'Access denied' };
    }
    await unlockDoor(door);
    ```
  </Accordion>

  <Accordion title="✅ Time Window Validation">
    **Check current time is within access window**

    Guests table includes `startAt` and `endAt` epoch timestamps.
    Query ensures current time is within window.
  </Accordion>

  <Accordion title="✅ Rate Limiting">
    **Prevent abuse with rate limits**

    * Server-side: 2-second minimum between unlocks
    * PreProcessor: Max 3 unlock requests per minute
    * Audit log: Track all attempts
  </Accordion>

  <Accordion title="✅ Audit Logging">
    **Log every unlock attempt**

    ```typescript theme={null}
    await Data.create('door_logs', {
      door: input.door,
      phone: user.phone,
      timestamp: new Date().toISOString(),
      success: true,
      guestId: access.guestId
    });
    ```
  </Accordion>

  <Accordion title="✅ Hardware Safety">
    **Electrical safety is critical**

    * Use separate 12V PSU for lock (never from Pi)
    * Optocoupled relay for isolation
    * Flyback diode across lock coil
    * Keep unlock pulses short (2-5s)
    * Fail-secure locks (locked when unpowered)
  </Accordion>
</AccordionGroup>

***

## Alternative: Twilio WhatsApp Webhook

If using Twilio instead of Meta's WhatsApp Business API:

### src/webhooks/twilio-whatsapp.ts

```typescript theme={null}
import { LuaWebhook, env } from 'lua-cli';
import crypto from 'crypto';

function validateTwilioSignature(url: string, params: Record<string, string>, signature: string, authToken: string): boolean {
  const data = Object.keys(params).sort().reduce((acc, k) => acc + k + params[k], url);
  const digest = crypto.createHmac('sha1', authToken).update(data).digest('base64');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

const twilioWebhook = new LuaWebhook({
  name: 'twilio-whatsapp',
  description: 'Handle Twilio WhatsApp inbound messages',
  verifySignature: false, // Custom validation below
  
  execute: async (event) => {
    const authToken = env('TWILIO_AUTH_TOKEN');
    const sig = event.headers['x-twilio-signature'];
    const webhookUrl = env('TWILIO_WEBHOOK_PUBLIC_URL');
    
    if (!authToken || !sig || !webhookUrl) {
      return { ok: false, reason: 'missing-config' };
    }
    
    const params = Object.fromEntries(new URLSearchParams(event.body));
    
    if (!validateTwilioSignature(webhookUrl, params, sig, authToken)) {
      return { ok: false, reason: 'invalid-signature' };
    }

    const from = params.WaId || params.From || '';
    const text = params.Body?.trim() || '';
    
    // Route to agent for processing
    // Lua handles message routing automatically
    
    return { ok: true, from, text };
  }
});

export default twilioWebhook;
```

Add to your agent:

```typescript theme={null}
import twilioWebhook from './webhooks/twilio-whatsapp';

export const agent = new LuaAgent({
  // ... other config
  webhooks: [twilioWebhook]
});
```

***

## Conversation Flows

### Guest with Valid Access

```
Guest via WhatsApp: "Open front door"
Agent: Checking access...
Agent: ✅ Front door unlocked. It will re-lock in 3 seconds.
```

### Guest without Access

```
Guest via WhatsApp: "Open door"
Agent: I don't have an active booking for your number. 
       Please contact the front desk with your booking 
       confirmation, or provide your booking name and dates.
```

### Staff Registering Guest

```
Staff via lua test: register_guest
→ Phone: +14155551234
→ Name: John Doe
→ Doors: ["front", "garage"]
→ Start: [check-in timestamp]
→ End: [check-out timestamp]

Agent: ✅ Guest access registered for front, garage
```

***

## Production Deployment

### Run Edge API on Boot

Create `/etc/systemd/system/door-edge.service`:

```ini theme={null}
[Unit]
Description=Door Control Edge API
After=network-online.target
Wants=network-online.target

[Service]
User=pi
WorkingDirectory=/home/pi/door-edge
Environment=EDGE_API_KEY=supersecret
Environment=DOOR_PIN=17
Environment=ACTIVE_LOW=true
Environment=UNLOCK_MS=3000
ExecStart=/home/pi/door-edge/.venv/bin/python edge_api.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable --now door-edge
```

### Set Static IP for Pi

```bash theme={null}
# Edit /etc/dhcpcd.conf
sudo nano /etc/dhcpcd.conf

# Add:
interface eth0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1
```

Update `PI_BASE_URL` to use the static IP.

***

## Monitoring & Audit

### View Unlock Logs

```typescript theme={null}
// Query recent unlocks
const logs = await Data.get('door_logs', {}, 1, 100);

logs.data.forEach(log => {
  console.log(`${log.data.timestamp}: ${log.data.door} - ${log.data.success ? 'Success' : 'Failed'}`);
});
```

### View Active Guests

```typescript theme={null}
const now = Date.now();
const activeGuests = await Data.get('guests', {
  status: 'ACTIVE',
  startAt: { $lte: now },
  endAt: { $gte: now }
});

console.log(`${activeGuests.data.length} active guests`);
```

***

## Key Features

<CardGroup>
  <Card title="WhatsApp Control" icon="whatsapp">
    Guests unlock doors via WhatsApp messages
  </Card>

  <Card title="Time-Window Access" icon="calendar">
    Check-in/check-out time validation
  </Card>

  <Card title="Multi-Door Support" icon="door-open">
    Control multiple doors with different pins
  </Card>

  <Card title="Audit Trail" icon="list">
    Complete logs of all unlock attempts
  </Card>

  <Card title="Rate Limiting" icon="shield">
    Prevent abuse with preprocessor filtering
  </Card>

  <Card title="Staff Tools" icon="user-gear">
    Register and manage guest access
  </Card>
</CardGroup>

***

## WhatsApp Best Practices

<Warning>
  **WhatsApp Rules:**

  * Users must message you first (opt-in required)
  * 24-hour conversation window applies
  * Use message templates for notifications outside window
  * Respect Meta's Business messaging policies
</Warning>

See complete WhatsApp guidelines: [WhatsApp Channel Guide](/channels/whatsapp)

***

## Use Cases

<Tabs>
  <Tab title="Hotels">
    **Guest Room Access**

    * Check-in: Register guest with room access
    * Guest WhatsApps: "Open room 305"
    * Check-out: Access automatically expires

    **Multi-property:** Use different `buildingId` per location
  </Tab>

  <Tab title="Apartments">
    **Tenant Access**

    * Move-in: Register tenant with building access
    * Tenant WhatsApps: "Open front door"
    * Guest access: Temporary access for visitors

    **Multiple doors:** Front entrance, garage, amenities
  </Tab>

  <Tab title="Coworking">
    **Member Access**

    * Membership: Register with access times (9 AM - 6 PM)
    * Member WhatsApps: "Open office"
    * After-hours: Denied with message about hours

    **Tiered access:** Different doors for different plans
  </Tab>

  <Tab title="Vacation Rentals">
    **Guest Booking**

    * Booking confirmed: Register guest with dates
    * Guest arrives: WhatsApp to unlock
    * Check-out: Access expires automatically

    **Contactless:** Fully automated check-in
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Door doesn't unlock">
    **Check:**

    * Edge API is running: `curl http://raspberrypi.local:5001/health`
    * GPIO permissions: User in gpio group, logged back in
    * Relay wiring: Correct pins, proper power supply
    * Active-low setting: Try toggling `ACTIVE_LOW`
  </Accordion>

  <Accordion title="Access denied for valid guest">
    **Check:**

    * Guest is in database: `Data.get('guests')`
    * Time window is current: startAt \< now \< endAt
    * Status is ACTIVE
    * Building ID matches
    * Phone number format matches (E.164)
  </Accordion>

  <Accordion title="WhatsApp not responding">
    **Check:**

    * Agent deployed: `lua deploy`
    * WhatsApp channel connected: `lua channels`
    * Webhook verified in Meta Business Suite
    * Check logs: `lua logs`
  </Accordion>

  <Accordion title="Rate limiting too aggressive">
    **Adjust:**

    * Increase time window in PreProcessor (60000ms → 120000ms)
    * Increase max attempts (3 → 5)
    * Adjust server-side throttle in edge\_api.py (2s → 5s)
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="View All IoT Demos" icon="microchip" href="/demos/overview#iot-automation">
    See all Raspberry Pi examples
  </Card>

  <Card title="WhatsApp Setup" icon="whatsapp" href="/channels/whatsapp">
    Complete WhatsApp channel guide
  </Card>

  <Card title="Data API" icon="database" href="/api/data">
    Learn about guest data management
  </Card>

  <Card title="PreProcessor API" icon="filter" href="/api/preprocessor">
    Learn about rate limiting and filtering
  </Card>
</CardGroup>


# IoT Greenhouse Climate Monitor
Source: https://docs.heylua.ai/demos/iot-greenhouse

Read temperature, humidity, and pressure from BME280 sensor on Raspberry Pi

## Overview

Monitor environmental conditions in your greenhouse, grow room, or any space using a **BME280 sensor** connected to a Raspberry Pi. Get real-time readings via chat and set up automated alerts for out-of-range conditions.

**What it does:**

* Read temperature, humidity, and pressure
* Get climate updates via chat
* Automated alerts for threshold violations
* Historical data tracking

**Hardware:** Raspberry Pi 4/5, BME280 sensor (I²C)

**APIs used:** Custom Edge API + Lua Data API (for history)

***

## Architecture

```
User Chat → Lua Agent → ReadClimateTool → Edge API → BME280 → Environmental Data
```

***

## Complete Implementation

### Edge API on Raspberry Pi

#### Setup (one-time)

```bash theme={null}
# Install OS packages
sudo apt update
sudo apt install -y python3-pip python3-venv i2c-tools

# Enable I2C interface
sudo raspi-config nonint do_i2c 0
# Or use raspi-config TUI: Interface Options → I2C → Enable

# Create project folder
mkdir -p ~/iot-edge && cd ~/iot-edge
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install flask adafruit-blinka adafruit-circuitpython-bme280
```

#### Verify I2C Connection

```bash theme={null}
# Check if BME280 is detected (should show 0x76 or 0x77)
i2cdetect -y 1
```

#### Edge API Code

Update `edge_api.py` (or add to existing):

```python theme={null}
from flask import Flask, request, jsonify
from functools import wraps
import os, time

try:
    import board, busio
    from adafruit_bme280 import basic as adafruit_bme280
    
    _i2c = busio.I2C(board.SCL, board.SDA)
    _bme280 = adafruit_bme280.Adafruit_BME280_I2C(_i2c)
except Exception as e:
    _bme280 = None
    print(f"BME280 not available: {e}")

app = Flask(__name__)
API_KEY = os.environ.get("EDGE_API_KEY", "changeme")

def require_key(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        if request.headers.get("X-API-Key") != API_KEY:
            return jsonify({"error": "unauthorized"}), 401
        return fn(*args, **kwargs)
    return wrapper

@app.get("/health")
def health():
    return {"ok": True, "ts": int(time.time())}

@app.get("/sensors/env")
@require_key
def sensors_env():
    if not _bme280:
        return jsonify({"error": "BME280 not available"}), 400
    
    return {
        "temperature_c": round(_bme280.temperature, 2),
        "temperature_f": round(_bme280.temperature * 9/5 + 32, 2),
        "humidity": round(_bme280.humidity, 1),
        "pressure_hpa": round(_bme280.pressure, 1),
        "timestamp": int(time.time())
    }

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5001)
```

#### Run Edge API

```bash theme={null}
export EDGE_API_KEY="supersecret"
python edge_api.py
```

#### Test Edge API

```bash theme={null}
curl -H "X-API-Key: supersecret" http://raspberrypi.local:5001/sensors/env
```

***

### Lua Agent Implementation

#### src/tools/ReadClimateTool.ts

```typescript theme={null}
import { LuaTool, Data, env } from 'lua-cli';
import { z } from 'zod';

export default class ReadClimateTool implements LuaTool {
  name = "read_climate";
  description = "Read temperature, humidity, and pressure from BME280 sensor";
  
  inputSchema = z.object({
    storeHistory: z.boolean().default(true).describe("Save reading to history")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const base = env('PI_BASE_URL');
    const key = env('PI_API_KEY');
    
    if (!base || !key) {
      throw new Error('PI_BASE_URL or PI_API_KEY not configured');
    }

    const res = await fetch(`${base}/sensors/env`, {
      headers: { 'X-API-Key': key }
    });
    
    if (!res.ok) {
      throw new Error(`Edge API error: ${res.status} ${await res.text()}`);
    }
    
    const data = await res.json();
    
    // Store in history if requested
    if (input.storeHistory) {
      await Data.create('climate_readings', {
        temperature_c: data.temperature_c,
        temperature_f: data.temperature_f,
        humidity: data.humidity,
        pressure_hpa: data.pressure_hpa,
        timestamp: new Date().toISOString()
      }, `climate ${data.temperature_c}C ${data.humidity}% ${data.pressure_hpa}hPa`);
    }
    
    return {
      temperature: `${data.temperature_c}°C (${data.temperature_f}°F)`,
      humidity: `${data.humidity}%`,
      pressure: `${data.pressure_hpa} hPa`,
      timestamp: new Date(data.timestamp * 1000).toLocaleString(),
      status: this.evaluateConditions(data)
    };
  }
  
  private evaluateConditions(data: any): string {
    const alerts = [];
    
    if (data.temperature_c > 30) alerts.push("⚠️ High temperature");
    if (data.temperature_c < 15) alerts.push("❄️ Low temperature");
    if (data.humidity > 80) alerts.push("💧 High humidity");
    if (data.humidity < 30) alerts.push("🏜️ Low humidity");
    
    return alerts.length > 0 
      ? alerts.join(', ')
      : '✅ All conditions normal';
  }
}
```

#### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaJob } from 'lua-cli';
import ReadClimateTool from './tools/ReadClimateTool';

// Climate monitoring skill
const climateSkill = new LuaSkill({
  name: "greenhouse-climate",
  description: "Monitor greenhouse environmental conditions",
  context: `
    This skill monitors temperature, humidity, and pressure via BME280 sensor.
    
    - read_climate: Get current environmental readings
      Use when user asks about temperature, humidity, pressure, or conditions
      
    Always mention if conditions are outside normal range.
    Suggest actions for out-of-range conditions.
  `,
  tools: [new ReadClimateTool()]
});

// Hourly climate check job
const hourlyClimateCheckJob = new LuaJob({
  name: 'hourly-climate-check',
  description: 'Check climate conditions every hour and alert if out of range',
  schedule: {
    type: 'interval',
    intervalSeconds: 3600  // Every hour
  },
  execute: async (job) => {
    const tool = new ReadClimateTool();
    const reading = await tool.execute({ storeHistory: true });
    
    // Alert if conditions are abnormal
    if (reading.status !== '✅ All conditions normal') {
      const user = await job.user();
      await user.send([{
        type: 'text',
        text: `🌡️ Climate Alert:\n\n${reading.temperature}\n${reading.humidity}\n${reading.pressure}\n\n${reading.status}`
      }]);
    }
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "greenhouse-monitor",
  
  persona: `You are a greenhouse climate monitoring assistant.
  
Your role:
- Monitor temperature, humidity, and pressure
- Alert when conditions are out of range
- Provide climate recommendations
- Track environmental history

Communication style:
- Clear and data-driven
- Proactive with alerts
- Helpful with recommendations

Climate knowledge:
- Ideal temp: 18-28°C (64-82°F)
- Ideal humidity: 50-70%
- Normal pressure: 980-1020 hPa

Recommendations:
- High temp: Increase ventilation
- Low temp: Close vents, add heat
- High humidity: Increase air circulation
- Low humidity: Add water trays or misting

When to alert:
- Temperature outside 15-30°C
- Humidity outside 30-80%
- Rapid changes (>5°C/hour)`,

  
  skills: [climateSkill],
  jobs: [hourlyClimateCheckJob]
});
```

<Note>
  Uses LuaAgent with scheduled jobs for hourly climate monitoring and automated alerts.
</Note>

***

## Environment Setup

```bash theme={null}
# .env
PI_BASE_URL=http://raspberrypi.local:5001
PI_API_KEY=supersecret
```

***

## Wiring BME280

**I²C Connection:**

```
Raspberry Pi          BME280
-----------          -------
3.3V        ────────> VIN
GND         ────────> GND
GPIO 2 (SDA)────────> SDA
GPIO 3 (SCL)────────> SCL
```

<Note>
  **I²C Address:** BME280 typically uses 0x76 or 0x77. The Adafruit library auto-detects the address.
</Note>

***

## Testing

```bash theme={null}
# Test tool directly
lua test
# Select: read_climate

# Test conversationally
lua chat
# You: "What's the temperature and humidity?"
# You: "Check the greenhouse conditions"
# You: "Is it too hot in there?"
```

***

## Key Features

<CardGroup>
  <Card title="Real-Time Monitoring" icon="gauge">
    Instant environmental readings via chat
  </Card>

  <Card title="Automated Alerts" icon="bell">
    Hourly checks with out-of-range notifications
  </Card>

  <Card title="Historical Data" icon="chart-line">
    Store readings in Lua Data for trend analysis
  </Card>

  <Card title="Smart Recommendations" icon="brain">
    AI suggests actions based on conditions
  </Card>
</CardGroup>

***

## Customization Ideas

### Add Alert Thresholds

```typescript theme={null}
inputSchema = z.object({
  storeHistory: z.boolean().default(true),
  alertIfTempAbove: z.number().optional(),
  alertIfHumidityAbove: z.number().optional()
});
```

### Daily Summary Report

```typescript theme={null}
const dailySummaryJob = new LuaJob({
  name: 'daily-climate-summary',
  schedule: {
    type: 'cron',
    pattern: '0 8 * * *'  // 8 AM daily
  },
  execute: async (job) => {
    // Get last 24 hours of readings
    const readings = await Data.get('climate_readings', 24);
    
    const avgTemp = readings.reduce((sum, r) => sum + r.data.temperature_c, 0) / readings.length;
    const avgHumidity = readings.reduce((sum, r) => sum + r.data.humidity, 0) / readings.length;
    
    const user = await job.user();
    await user.send([{
      type: 'text',
      text: `📊 24-Hour Climate Summary:\n\nAvg Temp: ${avgTemp.toFixed(1)}°C\nAvg Humidity: ${avgHumidity.toFixed(1)}%\nReadings: ${readings.length}`
    }]);
  }
});
```

***

## Next IoT Demo

<Card title="Security Camera Snapshot" icon="camera" href="/demos/iot-camera">
  Capture photos on-demand with Raspberry Pi Camera
</Card>


# IoT Smart Light Control
Source: https://docs.heylua.ai/demos/iot-smart-light

Control GPIO relay/LED on Raspberry Pi via chat

## Overview

Control lights, relays, or any GPIO-connected devices on a **Raspberry Pi** through natural language conversation. Turn devices on/off, check status, and automate with scheduled jobs.

**What it does:**

* Toggle relay or LED on/off via chat
* Control GPIO pins remotely
* Schedule automated on/off times
* Safe, authenticated edge API

**Hardware:** Raspberry Pi 4/5, relay module (optocoupled recommended), jumper wires

**APIs used:** Custom Edge API on Raspberry Pi

***

## Architecture

```
User Chat → Lua Agent → SetRelayTool → Edge API (Flask) → GPIO → Relay → Physical Device
```

***

## Complete Implementation

### Edge API on Raspberry Pi

#### Setup (one-time)

```bash theme={null}
# Install OS packages
sudo apt update
sudo apt install -y python3-pip python3-venv python3-libgpiod

# Add user to gpio group (required for GPIO access without sudo)
sudo adduser $USER gpio
# Log out and back in (or reboot) for this to take effect

# Create project folder
mkdir -p ~/iot-edge && cd ~/iot-edge
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install flask gpiozero
```

<Warning>
  **Important:** After adding your user to the gpio group, you must log out and back in (or reboot) for permissions to take effect.
</Warning>

#### Edge API Code

Create `edge_api.py`:

```python theme={null}
from flask import Flask, request, jsonify
from functools import wraps
from gpiozero import OutputDevice
import os, time

app = Flask(__name__)
API_KEY = os.environ.get("EDGE_API_KEY", "changeme")

def require_key(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        if request.headers.get("X-API-Key") != API_KEY:
            return jsonify({"error": "unauthorized"}), 401
        return fn(*args, **kwargs)
    return wrapper

@app.get("/health")
def health():
    return {"ok": True, "ts": int(time.time())}

@app.post("/gpio/relay")
@require_key
def gpio_relay():
    data = request.get_json(force=True)
    pin = int(data.get("pin", 17))               # BCM pin number
    state = str(data.get("state", "off")).lower()
    active_low = bool(data.get("active_low", True))  # many relay boards are active-low

    dev = OutputDevice(pin, active_high=not active_low, initial_value=False)
    if state == "on":
        dev.on()
    else:
        dev.off()
    
    return {"pin": pin, "state": state, "active_low": active_low}

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5001)
```

#### Run the Edge API

```bash theme={null}
export EDGE_API_KEY="supersecret"
python edge_api.py
```

#### Test Edge API

```bash theme={null}
# Health check
curl http://raspberrypi.local:5001/health

# Turn relay on
curl -X POST http://raspberrypi.local:5001/gpio/relay \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"pin":17,"state":"on","active_low":true}'
```

***

### Lua Agent Implementation

#### src/tools/SetRelayTool.ts

```typescript theme={null}
import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

export default class SetRelayTool implements LuaTool {
  name = "set_relay";
  description = "Turn a GPIO relay or LED on/off on the Raspberry Pi";
  
  inputSchema = z.object({
    pin: z.number().int().default(17).describe("BCM GPIO pin number"),
    state: z.enum(["on","off"]).describe("Turn device on or off"),
    active_low: z.boolean().default(true).describe("Many relay boards are active-low")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const base = env('PI_BASE_URL');
    const key = env('PI_API_KEY');
    
    if (!base || !key) {
      throw new Error('PI_BASE_URL or PI_API_KEY not configured');
    }

    const res = await fetch(`${base}/gpio/relay`, {
      method: 'POST',
      headers: { 
        'Content-Type': 'application/json', 
        'X-API-Key': key 
      },
      body: JSON.stringify(input)
    });
    
    if (!res.ok) {
      throw new Error(`Edge API error: ${res.status} ${await res.text()}`);
    }
    
    const result = await res.json();
    
    return {
      success: true,
      pin: result.pin,
      state: result.state,
      message: `GPIO pin ${result.pin} turned ${result.state}`
    };
  }
}
```

#### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaJob } from 'lua-cli';
import SetRelayTool from './tools/SetRelayTool';

// IoT control skill
const iotSkill = new LuaSkill({
  name: "raspberry-pi-gpio",
  description: "Control GPIO devices on Raspberry Pi",
  context: `
    This skill controls physical devices on a Raspberry Pi.
    
    - set_relay: Turn GPIO relay or LED on/off
      Use when user asks to control lights, fans, or any GPIO device
      
    Safety:
    - Always confirm which device a pin controls before toggling
    - Never rapidly toggle relays without user intent
    - Mention current state after changing
  `,
  tools: [new SetRelayTool()]
});

// Scheduled job: Turn off grow light at night
const nighttimeOffJob = new LuaJob({
  name: 'nighttime-off',
  description: 'Turn off grow light at 10 PM',
  schedule: {
    type: 'cron',
    pattern: '0 22 * * *'  // 10 PM daily
  },
  execute: async (job) => {
    const tool = new SetRelayTool();
    await tool.execute({ pin: 17, state: 'off', active_low: true });
    
    const user = await job.user();
    await user.send([{
      type: 'text',
      text: '🌙 Grow light turned off for the night.'
    }]);
  }
});

// Configure agent
export const agent = new LuaAgent({
  name: "smart-home-agent",
  
  persona: `You are a smart home automation assistant controlling Raspberry Pi devices.
  
Your role:
- Control lights, fans, and GPIO devices
- Confirm actions before making physical changes
- Report current device states
- Provide clear feedback on actions

Communication style:
- Clear and confirmatory
- Safety-conscious
- Brief and actionable

Safety practices:
- Always confirm which device you're controlling
- Mention current state after changes
- Don't rapidly toggle devices
- Warn if unsure about pin assignments

Device knowledge:
- Pin 17: Grow light (active-low relay)
- Pin 18: Ventilation fan
- Pin 27: LED indicator`,

  
  skills: [iotSkill],
  jobs: [nighttimeOffJob]
});
```

<Note>
  Uses LuaAgent with scheduled jobs for automated device control (e.g., turn off lights at night).
</Note>

***

## Environment Setup

```bash theme={null}
# .env
PI_BASE_URL=http://raspberrypi.local:5001
PI_API_KEY=supersecret
```

Or set via CLI:

```bash theme={null}
lua env sandbox
# Add: PI_BASE_URL and PI_API_KEY
```

***

## Testing

### Test Edge API Directly

```bash theme={null}
# Turn relay on
curl -X POST http://raspberrypi.local:5001/gpio/relay \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"pin":17,"state":"on","active_low":true}'
```

### Test with Lua

```bash theme={null}
# Test tool directly
lua test
# Select: set_relay
# Input: pin=17, state=on

# Test conversationally
lua chat
# You: "Turn on the grow light"
# You: "Turn off pin 17"
```

***

## Wiring

**Relay Module (Active-Low):**

```
Raspberry Pi          Relay Module
-----------          -------------
3.3V        ────────> VCC
GND         ────────> GND
GPIO 17     ────────> IN (Signal)
                       
Relay Output ─────> Your Device (Light/Fan)
```

<Warning>
  **Safety:** Use optocoupled relay modules for AC loads. Never exceed the relay's rated voltage/current. Always verify correct wiring before powering on.
</Warning>

***

## Production Deployment

### Run Edge API on Boot

Create systemd service `/etc/systemd/system/iot-edge.service`:

```ini theme={null}
[Unit]
Description=IoT Edge API
After=network-online.target

[Service]
User=pi
WorkingDirectory=/home/pi/iot-edge
Environment=EDGE_API_KEY=supersecret
ExecStart=/home/pi/iot-edge/.venv/bin/flask --app edge_api run --host=0.0.0.0 --port=5001
Restart=always

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable --now iot-edge
```

***

## Key Features

<CardGroup>
  <Card title="Remote Control" icon="wifi">
    Control GPIO devices from anywhere via chat
  </Card>

  <Card title="Secure API" icon="lock">
    API key authentication protects your edge API
  </Card>

  <Card title="Scheduled Automation" icon="clock">
    Jobs for automated on/off schedules
  </Card>

  <Card title="Safety First" icon="shield">
    Confirmation before physical state changes
  </Card>
</CardGroup>

***

## Next IoT Demo

<Card title="Greenhouse Climate Monitor" icon="cloud" href="/demos/iot-greenhouse">
  Read temperature, humidity, and pressure from BME280 sensor
</Card>


# Logistics & Shipping Tracker
Source: https://docs.heylua.ai/demos/logistics-tracker

Package tracking with UPS, FedEx, and USPS APIs

## Overview

Logistics operations assistant integrating with **multiple shipping carrier APIs** (UPS, FedEx, USPS) for unified package tracking.

**What it does:**

* Track packages across all carriers
* Get delivery estimates
* Schedule pickups
* Compare shipping rates
* Handle delivery exceptions

**APIs used:** UPS API, FedEx API, USPS API (all external)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  TrackPackageTool,
  CompareRatesTool,
  SchedulePickupTool
} from "./tools/LogisticsTools";

// Logistics operations skill
const logisticsSkill = new LuaSkill({
  name: "logistics-operations",
  description: "Multi-carrier shipping and tracking operations",
  context: `
    This skill helps track shipments across multiple carriers.
    
    - track_package: Track package across UPS, FedEx, or USPS
    - compare_rates: Compare shipping rates between carriers
    - schedule_pickup: Schedule package pickup
    
    Auto-detect carrier from tracking number when possible.
    Provide detailed tracking history.
    Alert for delivery exceptions.
  `,
  tools: [
    new TrackPackageTool(),
    new CompareRatesTool(),
    new SchedulePickupTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "logistics-operations-assistant",
  
  persona: `You are an efficient logistics operations specialist.
  
Your role:
- Track packages across multiple carriers
- Provide shipping status updates
- Compare carrier rates
- Schedule pickups
- Handle delivery exceptions

Communication style:
- Clear and concise
- Proactive with updates
- Detail-oriented
- Responsive to urgent requests

Best practices:
- Auto-detect carrier from tracking numbers
- Provide estimated delivery dates
- Alert for delivery exceptions or delays
- Offer alternative carriers for better rates
- Include tracking history details
- Suggest optimal shipping methods

Carrier knowledge:
- UPS: Express, Ground, International
- FedEx: Overnight, 2-Day, Ground
- USPS: Priority, First-Class, Media Mail
- Delivery timeframes and coverage

When to escalate:
- Lost or damaged packages
- International customs issues
- High-value shipments
- Complex routing requirements`,

  
  skills: [logisticsSkill]
});
```

<Note>
  This demo uses `LuaAgent` to configure the agent's persona, welcome message, and skills.
</Note>

### src/tools/LogisticsTools.ts

```typescript theme={null}
import { LuaTool, env } from "lua-cli";
import { z } from "zod";

// 1. Track Package (Multi-Carrier)
export class TrackPackageTool implements LuaTool {
  name = "track_package";
  description = "Track package across UPS, FedEx, or USPS";
  
  inputSchema = z.object({
    trackingNumber: z.string(),
    carrier: z.enum(['ups', 'fedex', 'usps', 'auto']).default('auto')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Auto-detect carrier if not specified
    const carrier = input.carrier === 'auto' 
      ? this.detectCarrier(input.trackingNumber)
      : input.carrier;
    
    switch (carrier) {
      case 'ups':
        return await this.trackUPS(input.trackingNumber);
      case 'fedex':
        return await this.trackFedEx(input.trackingNumber);
      case 'usps':
        return await this.trackUSPS(input.trackingNumber);
      default:
        throw new Error('Unable to detect carrier');
    }
  }
  
  private detectCarrier(trackingNumber: string): string {
    // UPS: 1Z followed by 16 alphanumeric
    if (/^1Z[0-9A-Z]{16}$/i.test(trackingNumber)) return 'ups';
    
    // FedEx: 12 or 14 digits
    if (/^\d{12}$|^\d{14}$/.test(trackingNumber)) return 'fedex';
    
    // USPS: 20-22 digits
    if (/^\d{20,22}$/.test(trackingNumber)) return 'usps';
    
    return 'auto';
  }
  
  private async trackUPS(trackingNumber: string) {
    const upsKey = env('UPS_API_KEY');
    
    const response = await fetch('https://onlinetools.ups.com/api/track/v1/details/' + trackingNumber, {
      headers: {
        'Authorization': `Bearer ${upsKey}`,
        'Accept': 'application/json'
      }
    });
    
    const data = await response.json();
    const shipment = data.trackResponse.shipment[0];
    
    return {
      carrier: 'UPS',
      trackingNumber,
      status: shipment.package[0].currentStatus.description,
      location: shipment.package[0].currentStatus.location,
      estimatedDelivery: shipment.package[0].deliveryDate[0].date,
      events: shipment.package[0].activity.map(a => ({
        date: a.date,
        time: a.time,
        status: a.status.description,
        location: a.location?.address?.city
      }))
    };
  }
  
  private async trackFedEx(trackingNumber: string) {
    const fedexKey = env('FEDEX_API_KEY');
    
    const response = await fetch('https://apis.fedex.com/track/v1/trackingnumbers', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${fedexKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        trackingInfo: [{
          trackingNumberInfo: { trackingNumber }
        }],
        includeDetailedScans: true
      })
    });
    
    const data = await response.json();
    const trackInfo = data.output.completeTrackResults[0].trackResults[0];
    
    return {
      carrier: 'FedEx',
      trackingNumber,
      status: trackInfo.latestStatusDetail.description,
      location: trackInfo.latestStatusDetail.scanLocation?.city,
      estimatedDelivery: trackInfo.estimatedDeliveryTime,
      events: trackInfo.scanEvents.map(e => ({
        date: e.date,
        status: e.eventDescription,
        location: e.scanLocation?.city
      }))
    };
  }
  
  private async trackUSPS(trackingNumber: string) {
    const uspsKey = env('USPS_USER_ID');
    
    const xml = `<TrackRequest USERID="${uspsKey}"><TrackID ID="${trackingNumber}"></TrackID></TrackRequest>`;
    
    const response = await fetch(
      `https://secure.shippingapis.com/ShippingAPI.dll?API=TrackV2&XML=${encodeURIComponent(xml)}`
    );
    
    const text = await response.text();
    // Parse XML response
    const parser = new DOMParser();
    const doc = parser.parseFromString(text, 'text/xml');
    
    return {
      carrier: 'USPS',
      trackingNumber,
      status: doc.querySelector('Status')?.textContent,
      location: doc.querySelector('EventCity')?.textContent,
      estimatedDelivery: doc.querySelector('ExpectedDeliveryDate')?.textContent
    };
  }
}

// 2. Compare Shipping Rates
export class CompareRatesTool implements LuaTool {
  name = "compare_shipping_rates";
  description = "Compare shipping rates across carriers";
  
  inputSchema = z.object({
    originZip: z.string(),
    destinationZip: z.string(),
    weight: z.number().describe("Weight in pounds"),
    dimensions: z.object({
      length: z.number(),
      width: z.number(),
      height: z.number()
    })
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get rates from all carriers
    const upsRate = await this.getUPSRate(input);
    const fedexRate = await this.getFedExRate(input);
    const uspsRate = await this.getUSPSRate(input);
    
    const rates = [upsRate, fedexRate, uspsRate].sort((a, b) => a.cost - b.cost);
    
    return {
      rates: rates.map(r => ({
        carrier: r.carrier,
        service: r.service,
        cost: `$${r.cost.toFixed(2)}`,
        estimatedDays: r.estimatedDays,
        delivery: r.estimatedDelivery
      })),
      cheapest: rates[0].carrier,
      fastest: rates.reduce((prev, curr) => 
        curr.estimatedDays < prev.estimatedDays ? curr : prev
      ).carrier
    };
  }
  
  private async getUPSRate(input: any) {
    // UPS Rating API call
    return {
      carrier: 'UPS',
      service: 'Ground',
      cost: 12.50,
      estimatedDays: 5,
      estimatedDelivery: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]
    };
  }
  
  private async getFedExRate(input: any) {
    // FedEx Rating API call
    return {
      carrier: 'FedEx',
      service: 'Home Delivery',
      cost: 14.25,
      estimatedDays: 4,
      estimatedDelivery: new Date(Date.now() + 4 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]
    };
  }
  
  private async getUSPSRate(input: any) {
    // USPS Rating API call
    return {
      carrier: 'USPS',
      service: 'Priority Mail',
      cost: 9.99,
      estimatedDays: 3,
      estimatedDelivery: new Date(Date.now() + 3 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]
    };
  }
}

// 3. Schedule Pickup
export class SchedulePickupTool implements LuaTool {
  name = "schedule_pickup";
  description = "Schedule package pickup with carrier";
  
  inputSchema = z.object({
    carrier: z.enum(['ups', 'fedex']),
    pickupDate: z.string(),
    pickupTime: z.string(),
    packageCount: z.number(),
    address: z.object({
      street: z.string(),
      city: z.string(),
      state: z.string(),
      zip: z.string()
    })
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const apiKey = input.carrier === 'ups' 
      ? env('UPS_API_KEY')
      : env('FEDEX_API_KEY');
    
    // Schedule pickup with carrier
    const response = await fetch(`https://${input.carrier}-api.com/pickup/schedule`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        pickup_date: input.pickupDate,
        ready_time: input.pickupTime,
        package_count: input.packageCount,
        pickup_address: input.address
      })
    });
    
    const data = await response.json();
    
    return {
      success: true,
      confirmationNumber: data.confirmation_number,
      carrier: input.carrier.toUpperCase(),
      pickupDate: input.pickupDate,
      pickupTime: input.pickupTime,
      message: `Pickup scheduled with ${input.carrier.toUpperCase()} for ${input.pickupDate}`
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env
UPS_API_KEY=your_ups_api_key
FEDEX_API_KEY=your_fedex_api_key
USPS_USER_ID=your_usps_user_id
```

## Key Features

<CardGroup>
  <Card title="Multi-Carrier" icon="truck">
    UPS, FedEx, USPS
  </Card>

  <Card title="Auto-Detection" icon="wand-magic-sparkles">
    Detect carrier from tracking#
  </Card>

  <Card title="Rate Comparison" icon="scale-balanced">
    Compare shipping costs
  </Card>

  <Card title="Real-Time" icon="clock">
    Live tracking data
  </Card>
</CardGroup>


# Demo Gallery
Source: https://docs.heylua.ai/demos/overview

15 production-ready solutions showcasing Lua's flexibility across business and IoT

## Overview

Explore 15 complete, production-ready AI agent implementations across different industries and IoT use cases. Each demo shows full TypeScript code using the **LuaAgent pattern** with external APIs, Lua Platform APIs, and edge computing.

<Note>
  Every demo now uses `LuaAgent` for unified configuration, showing how to combine skills, webhooks, jobs, and processors in real-world applications.
</Note>

<CardGroup>
  <Card title="Customer-Facing" icon="users">
    6 demos for end-user interactions
  </Card>

  <Card title="Internal Operations" icon="building">
    5 demos for business operations
  </Card>

  <Card title="IoT & Edge Computing" icon="microchip">
    4 demos for Raspberry Pi and hardware control
  </Card>

  <Card title="Advanced Features" icon="sparkles">
    All demos use LuaAgent pattern with webhooks, jobs, and processors where applicable
  </Card>

  <Card title="External APIs" icon="cloud">
    Stripe, Zendesk, Plaid, UPS, MLS, BambooHR, and more
  </Card>

  <Card title="Platform APIs" icon="database">
    Products, Baskets, Orders, Data (vector search), Jobs, Templates
  </Card>

  <Card title="Edge APIs" icon="server">
    Custom Flask APIs on Raspberry Pi for GPIO, sensors, and camera
  </Card>

  <Card title="Production-Ready" icon="rocket">
    Complete code with error handling, validation, and best practices
  </Card>
</CardGroup>

## Advanced Features in Demos

See real-world usage of advanced features across different demos:

<Tabs>
  <Tab title="LuaAgent">
    **Used in: ALL demos**

    Every demo shows proper agent configuration:

    ```typescript theme={null}
    export const agent = new LuaAgent({
      name: "demo-agent",
      persona: "...",
      skills: [...],
      webhooks: [...],
      jobs: [...]
    });
    ```
  </Tab>

  <Tab title="Webhooks">
    **Used in: E-commerce, Customer Support, Financial Onboarding**

    Real webhook integrations:

    * Stripe payment events
    * Shopify order notifications
    * Zendesk ticket updates
  </Tab>

  <Tab title="Jobs">
    **Used in: HR, Finance Ops, Customer Support**

    Scheduled automation:

    * Daily reports
    * Abandoned cart reminders
    * Follow-up messages
    * Data cleanup
  </Tab>

  <Tab title="PreProcessors">
    **Used in: Healthcare, Financial Services**

    Message filtering:

    * Verify patient consent
    * Validate financial information
    * Route by urgency
  </Tab>

  <Tab title="PostProcessors">
    **Used in: Healthcare, Financial Services, Legal**

    Response formatting:

    * Medical disclaimers
    * Financial warnings
    * Compliance footers
  </Tab>
</Tabs>

## Customer-Facing Agents

### 1. E-commerce Shopping Assistant

<Card title="E-commerce Assistant" icon="cart-shopping" href="/demos/ecommerce-assistant">
  **Complete shopping experience using Lua Platform APIs**

  **Features:** Product search, cart management, checkout, order tracking

  **APIs:** Products, Baskets, Orders (Lua Platform)

  **Use case:** Online stores, marketplaces
</Card>

### 2. Customer Support Agent

<Card title="Customer Support" icon="headset" href="/demos/customer-support">
  **Support automation with Zendesk + knowledge base**

  **Features:** Knowledge base search, ticket creation, status tracking

  **APIs:** Zendesk API (external) + Lua Data (vector search)

  **Use case:** Help desks, customer service teams
</Card>

### 3. Financial Services Onboarding

<Card title="Financial Onboarding" icon="building-columns" href="/demos/financial-onboarding">
  **KYC onboarding with document verification**

  **Features:** Document upload, identity verification, qualifying questions, account creation

  **APIs:** Stripe Identity API (external) + Lua Data (applications)

  **Use case:** Banks, fintech, investment platforms
</Card>

### 4. Hotel Booking Agent

<Card title="Hotel Booking" icon="hotel" href="/demos/hotel-booking">
  **Reservation management with availability checking**

  **Features:** Room search, bookings, cancellations, room service

  **APIs:** Lua Data API (rooms, reservations)

  **Use case:** Hotels, resorts, vacation rentals
</Card>

### 4. Restaurant Ordering System

<Card title="Restaurant Ordering" icon="utensils" href="/demos/restaurant-ordering">
  **Food ordering and table reservations**

  **Features:** Menu browsing, order placement, reservations

  **APIs:** Lua Products API (menu) + Data API (orders)

  **Use case:** Restaurants, cafes, food services
</Card>

### 5. Real Estate Assistant

<Card title="Real Estate" icon="house" href="/demos/real-estate-assistant">
  **Property search with MLS integration**

  **Features:** Property search, viewings, favorites, comparisons

  **APIs:** MLS API (external) + Lua Data (cache, favorites)

  **Use case:** Real estate agencies, property management
</Card>

## Internal-Facing Agents

### 8. HR Operations Assistant

<Card title="HR Assistant" icon="user-tie" href="/demos/hr-assistant">
  **Employee management with BambooHR integration**

  **Features:** Employee lookup, time off requests, policy search

  **APIs:** BambooHR API (external) + Lua Data (policies)

  **Use case:** HR departments, employee self-service
</Card>

### 9. Finance Operations Agent

<Card title="Finance Operations" icon="building-columns" href="/demos/finance-operations">
  **Banking operations with Plaid integration**

  **Features:** Account balances, transactions, transfers

  **APIs:** Plaid API (external banking)

  **Use case:** Finance teams, accounting, treasury
</Card>

### 10. SaaS Onboarding Assistant

<Card title="SaaS Onboarding" icon="graduation-cap" href="/demos/saas-onboarding">
  **User onboarding with product API integration**

  **Features:** Account creation, documentation search, usage tracking

  **APIs:** Your SaaS API (external) + Lua Data (docs)

  **Use case:** SaaS products, internal tools
</Card>

### 11. Healthcare Patient Portal

<Card title="Healthcare Portal" icon="hospital" href="/demos/healthcare-portal">
  **Patient services with EMR integration**

  **Features:** Appointments, medical records, prescriptions

  **APIs:** EMR/FHIR API (external) + Lua Data (health info)

  **Use case:** Healthcare providers, patient portals
</Card>

### 12. Logistics & Shipping Tracker

<Card title="Logistics Tracker" icon="truck" href="/demos/logistics-tracker">
  **Multi-carrier package tracking**

  **Features:** Track packages (UPS, FedEx, USPS), rate comparison

  **APIs:** UPS, FedEx, USPS APIs (all external)

  **Use case:** Logistics, shipping, warehouse operations
</Card>

## IoT & Edge Computing Agents

Control physical hardware and sensors on **Raspberry Pi** through natural language. All demos use a lightweight Flask Edge API running on the Pi.

### 13. Smart Light / GPIO Control

<Card title="Smart Light Control" icon="lightbulb" href="/demos/iot-smart-light">
  **Control GPIO relays and LEDs via chat**

  **Features:** Turn devices on/off, scheduled automation, safe GPIO control

  **Hardware:** Raspberry Pi + relay module + gpiozero

  **Use case:** Home automation, smart lighting, device control
</Card>

### 14. Greenhouse Climate Monitor

<Card title="Greenhouse Climate" icon="cloud" href="/demos/iot-greenhouse">
  **Monitor temperature, humidity, and pressure with BME280**

  **Features:** Real-time readings, automated alerts, historical tracking

  **Hardware:** Raspberry Pi + BME280 sensor (I²C)

  **Use case:** Greenhouses, server rooms, environmental monitoring
</Card>

### 15. Security Camera Snapshot

<Card title="Security Camera" icon="camera" href="/demos/iot-camera">
  **Capture photos on-demand with Pi Camera**

  **Features:** On-demand capture, scheduled snapshots, motion-triggered photos

  **Hardware:** Raspberry Pi + Camera Module 3/HQ + rpicam-still

  **Use case:** Security monitoring, time-lapse, remote observation
</Card>

### 16. Door Access Control

<Card title="Door Assistant" icon="door-open" href="/demos/iot-door-assistant">
  **WhatsApp-controlled door locks for hotels and apartments**

  **Features:** Guest access verification, time-window control, audit logging, WhatsApp integration

  **Hardware:** Raspberry Pi + relay + 12V electric strike/maglock

  **Use case:** Hotels, apartments, coworking spaces, vacation rentals
</Card>

## API Integration Breakdown

### External APIs Used

| Demo             | External APIs    | Purpose                      |
| ---------------- | ---------------- | ---------------------------- |
| Customer Support | Zendesk          | Ticket management            |
| Real Estate      | MLS              | Property listings            |
| HR Assistant     | BambooHR         | Employee data                |
| Finance          | Plaid            | Banking operations           |
| SaaS Onboarding  | Your API         | Product integration          |
| Healthcare       | EMR/FHIR         | Medical records              |
| Logistics        | UPS/FedEx/USPS   | Shipping tracking            |
| Smart Light      | Edge API (Flask) | GPIO relay control           |
| Greenhouse       | Edge API (Flask) | BME280 sensor readings       |
| Camera           | Edge API (Flask) | Photo capture (rpicam-still) |
| Door Assistant   | Edge API (Flask) | GPIO relay + access control  |

### Lua Platform APIs Used

| Demo             | Platform APIs             | Purpose                           |
| ---------------- | ------------------------- | --------------------------------- |
| E-commerce       | Products, Baskets, Orders | Shopping workflow                 |
| Customer Support | Data                      | Knowledge base search             |
| Hotel Booking    | Data                      | Reservations, rooms               |
| Restaurant       | Products, Data            | Menu, orders                      |
| Real Estate      | Data                      | Property cache, favorites         |
| HR Assistant     | Data                      | Policy search                     |
| SaaS Onboarding  | Data                      | Documentation search              |
| Healthcare       | Data                      | Health information                |
| Greenhouse       | Data                      | Climate history tracking          |
| Camera           | Data                      | Photo metadata logging            |
| Door Assistant   | Data                      | Guest access control + audit logs |

### Edge APIs Used

|| Demo | Edge Technology | Hardware |
\|------|-----------------|----------|
\| Smart Light | Flask + gpiozero | Raspberry Pi + relay module |
\| Greenhouse | Flask + BME280 library | Raspberry Pi + BME280 (I²C) |
\| Camera | Flask + rpicam-still | Raspberry Pi + Camera Module 3/HQ |
\| Door Assistant | Flask + gpiozero | Raspberry Pi + relay + electric strike |

## Integration Patterns Demonstrated

<Tabs>
  <Tab title="Pure External">
    **Finance, Logistics**

    100% external API integration

    * Plaid for banking
    * UPS/FedEx for shipping

    Shows: Complete custom integration
  </Tab>

  <Tab title="Pure Platform">
    **E-commerce, Hotel, Restaurant**

    Uses Lua Platform APIs

    * Products for catalogs
    * Baskets for carts
    * Data for storage

    Shows: Quick development with Platform APIs
  </Tab>

  <Tab title="Hybrid">
    **Support, Real Estate, HR, SaaS, Healthcare**

    Mix of both

    * External for core business logic
    * Platform for enhanced features

    Shows: Best of both worlds
  </Tab>

  <Tab title="Edge Computing">
    **IoT Smart Light, Greenhouse, Camera, Door Assistant**

    Custom Edge APIs on Raspberry Pi

    * Flask APIs for GPIO, sensors, camera, access control
    * Local network communication
    * Hardware control via chat and WhatsApp
    * Security and audit logging

    Shows: Physical world integration with AI agents and secure access control
  </Tab>
</Tabs>

## Learning Paths by Feature

Choose demos based on what advanced features you want to learn:

<AccordionGroup>
  <Accordion title="🤖 Learn LuaAgent (ALL Demos)">
    **Every demo shows the LuaAgent pattern**

    * How to configure agent with persona
    * Adding skills to agent
    * Welcome message best practices
    * Complete agent structure

    **Start with:** E-commerce (simplest) or Customer Support (comprehensive)
  </Accordion>

  <Accordion title="🪝 Learn Webhooks">
    **Demos with webhook integration:**

    * **E-commerce Assistant** - Stripe payment webhooks
    * **Customer Support** - Zendesk ticket webhooks
    * **Financial Onboarding** - Identity verification webhooks
    * **Camera (IoT)** - Motion-triggered captures

    **Learn:** HTTP event handling, signature verification, real-time updates, hardware triggers
  </Accordion>

  <Accordion title="⏰ Learn Jobs & Automation">
    **Demos with scheduled tasks:**

    * **HR Assistant** - Daily attendance reports
    * **Finance Operations** - Weekly reconciliation
    * **Customer Support** - Follow-up reminders
    * **Smart Light (IoT)** - Automated on/off schedules
    * **Greenhouse (IoT)** - Hourly climate monitoring
    * **Camera (IoT)** - Daily snapshots

    **Learn:** Cron patterns, scheduled notifications, automated reports, hardware automation
  </Accordion>

  <Accordion title="🔍 Learn PreProcessors">
    **Demos with message filtering:**

    * **Healthcare Portal** - Patient consent verification
    * **Financial Onboarding** - Information validation
    * **Customer Support** - Business hours filtering
    * **Door Assistant (IoT)** - Rate limiting for security

    **Learn:** Content filtering, routing, validation, rate limiting, security patterns
  </Accordion>

  <Accordion title="✨ Learn PostProcessors">
    **Demos with response formatting:**

    * **Healthcare Portal** - Medical disclaimers
    * **Financial Onboarding** - Compliance footers
    * **Customer Support** - Branding and signatures

    **Learn:** Adding disclaimers, branding, formatting, personalization
  </Accordion>

  <Accordion title="🔌 Learn Edge Computing & IoT">
    **Demos with hardware integration:**

    * **Smart Light** - GPIO control with relays and LEDs
    * **Greenhouse** - I²C sensor reading (BME280)
    * **Camera** - Photo capture with rpicam-still
    * **Door Assistant** - WhatsApp access control with time-window validation

    **Learn:** Edge APIs, Flask on Pi, gpiozero, hardware control via chat, WhatsApp integration, access control, security patterns
  </Accordion>
</AccordionGroup>

## Code Complexity Levels

<AccordionGroup>
  <Accordion title="⭐ Beginner (3 demos)">
    * **E-commerce**: Platform APIs only
    * **Hotel Booking**: Lua Data API
    * **Restaurant**: Products + Data

    Great for learning Platform APIs and basic LuaAgent configuration
  </Accordion>

  <Accordion title="⭐⭐ Intermediate (8 demos)">
    * **Customer Support**: Zendesk + vector search + webhooks + jobs
    * **Real Estate**: MLS + Lua Data
    * **HR Assistant**: BambooHR + Lua Data + jobs
    * **SaaS Onboarding**: Your API + Lua Data
    * **Smart Light (IoT)**: Edge API + GPIO control + jobs
    * **Greenhouse (IoT)**: Edge API + I²C sensors + jobs
    * **Camera (IoT)**: Edge API + rpicam-still + jobs + webhooks
    * **Door Assistant (IoT)**: Edge API + WhatsApp + access control + preprocessors

    Shows hybrid integration patterns with advanced features and hardware control
  </Accordion>

  <Accordion title="⭐⭐⭐ Advanced (4 demos)">
    * **Finance**: Plaid banking integration + jobs
    * **Healthcare**: FHIR-compliant EMR + pre/post processors
    * **Logistics**: Multi-carrier APIs
    * **Financial Onboarding**: Stripe Identity + webhooks + processors

    Complex external integrations with full advanced feature usage
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="LuaAgent" icon="robot">
    **Every demo shows:**

    * Proper agent configuration
    * Persona best practices
    * Welcome message patterns
    * Skill organization
  </Card>

  <Card title="API Integration" icon="plug">
    **You'll see how to:**

    * Call external APIs (Stripe, Zendesk, etc.)
    * Use Platform APIs (Products, Data, etc.)
    * Mix both approaches
    * Handle authentication
  </Card>

  <Card title="Advanced Features" icon="sparkles">
    **Selected demos show:**

    * Webhooks for external events
    * Jobs for scheduled tasks
    * PreProcessors for validation
    * PostProcessors for compliance
  </Card>

  <Card title="Production Patterns" icon="shield">
    **Best practices:**

    * Error handling
    * Input validation
    * Security patterns
    * Testing strategies
  </Card>
</CardGroup>

## Quick Start with Demos

<Steps>
  <Step title="Choose a Demo">
    Pick one that matches your industry or use case
  </Step>

  <Step title="Copy the Code">
    All code is production-ready and copy-paste friendly
  </Step>

  <Step title="Set Environment Variables">
    Add required API keys to `.env` file
  </Step>

  <Step title="Test Locally">
    ```bash theme={null}
    lua chat  # Primary testing
    lua test  # Optional: Specific tools
    ```
  </Step>

  <Step title="Customize">
    Modify for your specific needs
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    lua push && lua deploy
    ```
  </Step>
</Steps>

## All Demos at a Glance

| Demo                 | Type     | External APIs               | Platform APIs             | Complexity |
| -------------------- | -------- | --------------------------- | ------------------------- | ---------- |
| E-commerce           | Customer | None                        | Products, Baskets, Orders | ⭐          |
| Support              | Customer | Zendesk                     | Data                      | ⭐⭐         |
| Financial Onboarding | Customer | Stripe Identity             | Data                      | ⭐⭐⭐        |
| Hotel                | Customer | None                        | Data                      | ⭐          |
| Restaurant           | Customer | None                        | Products, Data            | ⭐          |
| Real Estate          | Customer | MLS                         | Data                      | ⭐⭐         |
| HR                   | Internal | BambooHR                    | Data                      | ⭐⭐         |
| Finance Ops          | Internal | Plaid                       | None                      | ⭐⭐⭐        |
| SaaS                 | Internal | Your API                    | Data                      | ⭐⭐         |
| Healthcare           | Internal | EMR/FHIR                    | Data                      | ⭐⭐⭐        |
| Logistics            | Internal | UPS/FedEx/USPS              | None                      | ⭐⭐⭐        |
| Smart Light          | IoT      | Edge API (Flask)            | None                      | ⭐⭐         |
| Greenhouse           | IoT      | Edge API (Flask)            | Data                      | ⭐⭐         |
| Camera               | IoT      | Edge API (Flask)            | Data                      | ⭐⭐         |
| Door Assistant       | IoT      | Edge API (Flask) + WhatsApp | Data                      | ⭐⭐         |

## Learn Concepts Through Demos

See Key Concepts in action within real-world demos:

<CardGroup>
  <Card title="Agent Concept" icon="robot" href="/overview/agent">
    **See in:** ALL demos

    Every demo shows LuaAgent configuration
  </Card>

  <Card title="Skills & Tools" icon="puzzle-piece" href="/overview/skill">
    **See in:** ALL demos

    How to organize tools into skills
  </Card>

  <Card title="Webhooks" icon="webhook" href="/overview/webhooks">
    **See in:** E-commerce, Support, Financial

    Real external event handling
  </Card>

  <Card title="Jobs" icon="clock" href="/overview/jobs">
    **See in:** HR, Finance, Support

    Scheduled automation examples
  </Card>

  <Card title="PreProcessors" icon="filter" href="/overview/preprocessors">
    **See in:** Healthcare, Financial

    Message validation and filtering
  </Card>

  <Card title="PostProcessors" icon="paper-plane" href="/overview/postprocessors">
    **See in:** Healthcare, Financial, Support

    Response formatting and disclaimers
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Start with E-commerce" icon="cart-shopping" href="/demos/ecommerce-assistant">
    Easiest demo - Platform APIs only with LuaAgent
  </Card>

  <Card title="Try Customer Support" icon="headset" href="/demos/customer-support">
    Comprehensive demo with webhooks + jobs
  </Card>

  <Card title="Explore Key Concepts" icon="book-open" href="/overview/agent">
    Learn lua-cli concepts before diving into demos
  </Card>

  <Card title="Quick Start Guide" icon="rocket" href="/getting-started/quick-start">
    Set up your development environment
  </Card>

  <Card title="API Reference" icon="book" href="/api/overview">
    Complete API documentation
  </Card>

  <Card title="Build Your Own" icon="hammer" href="/getting-started/first-skill">
    Follow the first skill tutorial
  </Card>
</CardGroup>


# Real Estate Assistant
Source: https://docs.heylua.ai/demos/real-estate-assistant

Property search with MLS API + Lua vector search

## Overview

Real estate agent assistant integrating with **MLS (Multiple Listing Service) API** and **Lua Data API** for enhanced property search.

**What it does:**

* Search properties via MLS API
* Save favorite properties
* Schedule viewings
* Compare properties
* Get neighborhood info

**APIs used:** External MLS API + Lua Data API

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  SearchPropertiesTool,
  GetPropertyDetailsTool,
  ScheduleViewingTool,
  SaveFavoriteTool,
  ComparePropertiesTool
} from "./tools/RealEstateTools";

// Real estate skill
const realEstateSkill = new LuaSkill({
  name: "real-estate-assistant",
  description: "Real estate search and showing scheduler",
  context: `
    This skill helps clients search and view properties.
    
    - search_properties: Search MLS for properties matching criteria
    - get_property_details: Get full details for a specific property
    - schedule_viewing: Book property showing appointment
    - save_favorite: Save property to client's favorites
    - compare_properties: Compare multiple properties side by side
    
    Always ask about budget, location preferences, and must-haves.
    Highlight unique features of properties.
    Be enthusiastic and professional.
  `,
  tools: [
    new SearchPropertiesTool(),
    new GetPropertyDetailsTool(),
    new ScheduleViewingTool(),
    new SaveFavoriteTool(),
    new ComparePropertiesTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "real-estate-assistant",
  
  persona: `You are an experienced and enthusiastic real estate agent.
  
Your role:
- Help clients find their dream home
- Search MLS listings based on preferences
- Schedule property viewings
- Provide market insights
- Guide through the home-buying process

Communication style:
- Enthusiastic and positive
- Professional and knowledgeable
- Patient and understanding
- Detail-oriented
- Market-savvy

Best practices:
- Always ask about budget and location preferences
- Inquire about must-have features vs nice-to-haves
- Highlight unique property features
- Provide honest market assessments
- Suggest neighborhoods that match lifestyle
- Offer to schedule viewings immediately

When to escalate:
- Making offers (requires human agent)
- Legal questions (refer to attorney)
- Complex financing (refer to mortgage specialist)
- Commercial properties (different department)`,

  
  skills: [realEstateSkill]
});
```

<Note>
  This demo uses `LuaAgent` to configure the agent's persona, welcome message, and skills.
</Note>

### Tools Implementation

```typescript theme={null}
import { LuaTool, Data, env } from "lua-cli";
import { z } from "zod";

// 1. Search Properties (External MLS API)
export class SearchPropertiesTool implements LuaTool {
  name = "search_properties";
  description = "Search real estate listings";
  
  inputSchema = z.object({
    location: z.string(),
    minPrice: z.number().optional(),
    maxPrice: z.number().optional(),
    bedrooms: z.number().optional(),
    propertyType: z.enum(['house', 'condo', 'apartment', 'townhouse']).optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const mlsApiKey = env('MLS_API_KEY');
    
    // Call MLS API
    const response = await fetch('https://api.mlslistings.com/api/v1/search', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${mlsApiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        location: input.location,
        price_min: input.minPrice,
        price_max: input.maxPrice,
        bedrooms: input.bedrooms,
        property_type: input.propertyType
      })
    });
    
    const data = await response.json();
    
    // Save to Lua Data for vector search capabilities
    for (const property of data.listings) {
      const searchText = `${property.address} ${property.city} ${property.description} ${property.features.join(' ')}`;
      await Data.create('property_cache', property, searchText);
    }
    
    return {
      properties: data.listings.map(p => ({
        id: p.mls_id,
        address: p.address,
        city: p.city,
        price: `$${p.price.toLocaleString()}`,
        bedrooms: p.bedrooms,
        bathrooms: p.bathrooms,
        sqft: p.square_feet,
        type: p.property_type,
        description: p.description.substring(0, 150) + '...'
      })),
      count: data.listings.length
    };
  }
}

// 2. Save Favorite (Lua Data)
export class SaveFavoriteTool implements LuaTool {
  name = "save_favorite";
  description = "Save a property to favorites";
  
  inputSchema = z.object({
    mlsId: z.string(),
    notes: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    await Data.create('favorites', {
      mlsId: input.mlsId,
      notes: input.notes,
      savedAt: new Date().toISOString()
    });
    
    return {
      success: true,
      message: "Property saved to favorites"
    };
  }
}

// 3. Schedule Viewing
export class ScheduleViewingTool implements LuaTool {
  name = "schedule_viewing";
  description = "Schedule a property viewing";
  
  inputSchema = z.object({
    mlsId: z.string(),
    date: z.string(),
    time: z.string(),
    clientName: z.string(),
    clientEmail: z.string().email(),
    clientPhone: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const viewing = await Data.create('viewings', {
      ...input,
      status: 'scheduled',
      createdAt: new Date().toISOString()
    });
    
    return {
      success: true,
      viewingId: viewing.id,
      message: `Viewing scheduled for ${input.date} at ${input.time}`
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env
MLS_API_KEY=your_mls_api_key
MLS_API_URL=https://api.mlslistings.com
```

## Key Features

<CardGroup>
  <Card title="External MLS" icon="building">
    Real MLS property data
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    Semantic property search
  </Card>
</CardGroup>


# Restaurant Ordering System
Source: https://docs.heylua.ai/demos/restaurant-ordering

Food ordering and reservations with Lua Platform APIs

## Overview

Restaurant AI assistant for menu browsing, food ordering, and table reservations using **Lua Platform APIs**.

**What it does:**

* Browse menu with search
* Create food orders
* Make table reservations
* Track order status
* Handle special dietary requests

**APIs used:** Lua Products API (menu), Data API (orders, reservations)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  BrowseMenuTool,
  SearchMenuTool,
  CreateOrderTool,
  TrackOrderTool,
  MakeReservationTool,
  CheckReservationTool
} from "./tools/RestaurantTools";

// Restaurant ordering skill
const restaurantSkill = new LuaSkill({
  name: "restaurant-assistant",
  description: "Restaurant ordering and reservation assistant",
  context: `
    This skill helps customers order food and make reservations.
    
    Menu & Ordering:
    - browse_menu: Show all menu items or filter by category
    - search_menu: Find specific dishes
    - create_order: Place food order (confirm items first!)
    - track_order: Check order preparation status
    
    Reservations:
    - make_reservation: Book a table
    - check_reservation: Look up reservation details
    
    Always mention daily specials.
    Ask about dietary restrictions and allergies.
    Confirm order details and total before submitting.
  `,
  tools: [
    new BrowseMenuTool(),
    new SearchMenuTool(),
    new CreateOrderTool(),
    new TrackOrderTool(),
    new MakeReservationTool(),
    new CheckReservationTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "restaurant-assistant",
  
  persona: `You are a friendly restaurant host and server.
  
Your role:
- Help guests browse the menu
- Take food and drink orders
- Make table reservations
- Answer questions about ingredients and preparation
- Accommodate dietary restrictions

Communication style:
- Warm and welcoming
- Enthusiastic about the food
- Attentive to details
- Patient with questions
- Knowledgeable about the menu

Best practices:
- Always mention today's specials
- Ask about dietary restrictions and allergies
- Confirm order details before submitting
- Suggest wine pairings or desserts
- Provide estimated wait times
- Thank guests warmly

Menu knowledge:
- All dishes and ingredients
- Preparation methods
- Portion sizes
- Dietary information (vegan, gluten-free, etc.)
- Chef's recommendations`,

  
  skills: [restaurantSkill]
});
```

<Note>
  This demo uses `LuaAgent` to configure the agent's persona, welcome message, and skills.
</Note>

### src/tools/RestaurantTools.ts

```typescript theme={null}
import { LuaTool, Products, Data } from "lua-cli";
import { z } from "zod";

// 1. Browse Menu
export class BrowseMenuTool implements LuaTool {
  name = "browse_menu";
  description = "Browse restaurant menu items";
  
  inputSchema = z.object({
    category: z.enum(['appetizers', 'entrees', 'desserts', 'drinks', 'all']).default('all')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Use Products API for menu items (page 1, limit 100)
    const allItems = await Products.get(1, 100);
    
    let items = allItems.data;
    if (input.category !== 'all') {
      items = items.filter(item => item.category === input.category);
    }
    
    return {
      category: input.category,
      items: items.map(item => ({
        id: item.id,
        name: item.name,
        description: item.description,
        price: `$${item.price.toFixed(2)}`,
        category: item.category,
        dietary: item.metadata?.dietary || []
      })),
      dailySpecial: "Chef's seafood pasta - $24.99",
      message: `Showing ${items.length} ${input.category} items`
    };
  }
}

// 2. Search Menu
export class SearchMenuTool implements LuaTool {
  name = "search_menu";
  description = "Search menu by dish name or ingredient";
  
  inputSchema = z.object({
    query: z.string().describe("Search query (dish name, ingredient, dietary requirement)")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Products.search(input.query);
    
    return {
      results: results.map(item => ({
        id: item.id,
        name: item.name,
        price: `$${item.price.toFixed(2)}`,
        description: item.description,
        dietary: item.metadata?.dietary
      })),
      count: results.length
    };
  }
}

// 3. Create Order
export class CreateOrderTool implements LuaTool {
  name = "create_order";
  description = "Place a food order";
  
  inputSchema = z.object({
    items: z.array(z.object({
      productId: z.string(),
      quantity: z.number().min(1),
      specialInstructions: z.string().optional()
    })),
    customerName: z.string(),
    customerPhone: z.string(),
    orderType: z.enum(['dine-in', 'takeout', 'delivery']).default('dine-in'),
    deliveryAddress: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get all product details and calculate total
    let total = 0;
    const orderItems = [];
    
    for (const item of input.items) {
      const product = await Products.getById(item.productId);
      
      if (!product) {
        throw new Error(`Menu item not found: ${item.productId}`);
      }
      
      const itemTotal = product.price * item.quantity;
      total += itemTotal;
      
      orderItems.push({
        name: product.name,
        quantity: item.quantity,
        price: product.price,
        subtotal: itemTotal,
        specialInstructions: item.specialInstructions
      });
    }
    
    // Add delivery fee if applicable
    if (input.orderType === 'delivery') {
      total += 5.99; // Delivery fee
    }
    
    // Create order
    const order = await Data.create('restaurant_orders', {
      items: orderItems,
      total,
      customerName: input.customerName,
      customerPhone: input.customerPhone,
      orderType: input.orderType,
      deliveryAddress: input.deliveryAddress,
      status: 'preparing',
      orderNumber: this.generateOrderNumber(),
      createdAt: new Date().toISOString()
    });
    
    return {
      success: true,
      orderId: order.id,
      orderNumber: order.data.orderNumber,
      items: orderItems,
      total: `$${total.toFixed(2)}`,
      estimatedTime: input.orderType === 'dine-in' ? '20-25 minutes' : '30-40 minutes',
      message: `Order #${order.data.orderNumber} placed! Estimated time: ${input.orderType === 'dine-in' ? '20-25' : '30-40'} minutes`
    };
  }
  
  private generateOrderNumber(): string {
    return 'ORD-' + Date.now().toString().slice(-6);
  }
  
  private calculateNights(checkIn: string, checkOut: string): number {
    const start = new Date(checkIn);
    const end = new Date(checkOut);
    return Math.ceil((end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24));
  }
}

// 4. Track Order
export class TrackOrderTool implements LuaTool {
  name = "track_order";
  description = "Check order preparation status";
  
  inputSchema = z.object({
    orderNumber: z.string().describe("Order number")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Data.get('restaurant_orders', {
      orderNumber: input.orderNumber
    });
    
    if (results.data.length === 0) {
      throw new Error(`Order not found: ${input.orderNumber}`);
    }
    
    const order = results.data[0];
    
    const statusMessages = {
      preparing: "🍳 Your order is being prepared",
      ready: "✅ Your order is ready for pickup!",
      delivered: "🎉 Order delivered!",
      cancelled: "❌ Order was cancelled"
    };
    
    return {
      orderNumber: order.data.orderNumber,
      status: order.data.status,
      statusMessage: statusMessages[order.data.status],
      items: order.data.items,
      total: `$${order.data.total.toFixed(2)}`,
      orderType: order.data.orderType
    };
  }
}

// 5. Make Reservation
export class MakeReservationTool implements LuaTool {
  name = "make_reservation";
  description = "Reserve a table at the restaurant";
  
  inputSchema = z.object({
    date: z.string().describe("Reservation date (YYYY-MM-DD)"),
    time: z.string().describe("Reservation time (HH:MM)"),
    partySize: z.number().min(1).max(20),
    customerName: z.string(),
    customerPhone: z.string(),
    specialRequests: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Create reservation
    const reservation = await Data.create('table_reservations', {
      date: input.date,
      time: input.time,
      partySize: input.partySize,
      customerName: input.customerName,
      customerPhone: input.customerPhone,
      specialRequests: input.specialRequests,
      status: 'confirmed',
      confirmationCode: this.generateConfirmationCode(),
      createdAt: new Date().toISOString()
    }, `${input.customerName} ${input.date} ${input.time}`);
    
    return {
      success: true,
      confirmationCode: reservation.data.confirmationCode,
      date: input.date,
      time: input.time,
      partySize: input.partySize,
      message: `Table reserved for ${input.partySize} on ${input.date} at ${input.time}. Confirmation: ${reservation.data.confirmationCode}`
    };
  }
  
  private generateConfirmationCode(): string {
    return 'RES-' + Math.random().toString(36).substring(2, 10).toUpperCase();
  }
}

// 6. Check Reservation
export class CheckReservationTool implements LuaTool {
  name = "check_reservation";
  description = "Look up table reservation";
  
  inputSchema = z.object({
    confirmationCode: z.string(),
    phone: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Data.get('table_reservations', {
      confirmationCode: input.confirmationCode,
      customerPhone: input.phone
    });
    
    if (results.data.length === 0) {
      throw new Error('Reservation not found');
    }
    
    const reservation = results.data[0];
    
    return {
      confirmationCode: reservation.data.confirmationCode,
      customerName: reservation.data.customerName,
      date: reservation.data.date,
      time: reservation.data.time,
      partySize: reservation.data.partySize,
      status: reservation.data.status,
      specialRequests: reservation.data.specialRequests
    };
  }
}
```

## Key Features

<CardGroup>
  <Card title="Platform APIs" icon="utensils">
    Uses Products API for menu
  </Card>

  <Card title="Data API" icon="database">
    Orders and reservations
  </Card>

  <Card title="Full Featured" icon="star">
    Complete restaurant solution
  </Card>

  <Card title="Dietary Info" icon="leaf">
    Handles dietary restrictions
  </Card>
</CardGroup>


# SaaS Onboarding Assistant
Source: https://docs.heylua.ai/demos/saas-onboarding

User onboarding with custom API + Lua vector search

## Overview

SaaS onboarding assistant using **your product API** + **Lua Data API** for documentation search.

**What it does:**

* Guide new users through setup
* Answer product questions
* Create user accounts
* Configure settings
* Search documentation

**APIs used:** Your SaaS API (external) + Lua Data API (docs)

## Complete Implementation

### src/index.ts

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  SearchDocsTool,
  CreateUserTool,
  GetUsageTool,
  ConfigureSettingsTool
} from "./tools/SaaSTools";

// SaaS onboarding skill
const saasSkill = new LuaSkill({
  name: "saas-onboarding",
  description: "SaaS product onboarding and user assistance",
  context: `
    This skill helps new users get started with our SaaS product.
    
    - search_docs: Find answers in product documentation
    - create_user: Create new user accounts
    - get_usage: Check usage statistics and limits
    - configure_settings: Help users configure their settings
    
    Guide users through setup step-by-step.
    Search documentation before creating support tickets.
  `,
  tools: [
    new SearchDocsTool(),
    new CreateUserTool(),
    new GetUsageTool(),
    new ConfigureSettingsTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "saas-onboarding-assistant",
  
  persona: `You are a friendly SaaS product onboarding specialist.
  
Your role:
- Guide new users through product setup
- Help users understand features and capabilities
- Assist with account configuration
- Answer product questions
- Provide usage tips and best practices

Communication style:
- Friendly and enthusiastic
- Patient and encouraging
- Clear and step-by-step
- Supportive and helpful

Best practices:
- Break complex setup into simple steps
- Celebrate user progress and milestones
- Proactively offer relevant documentation
- Suggest features based on user's use case
- Provide keyboard shortcuts and tips
- Encourage exploration of features

When to escalate:
- Technical integration issues
- Custom enterprise requirements
- Billing or payment questions
- API or developer support`,

  
  skills: [saasSkill]
});
```

<Note>
  This demo uses `LuaAgent` to configure the agent's persona, welcome message, and skills.
</Note>

### src/tools/SaaSTools.ts

```typescript theme={null}
import { LuaTool, Data, env } from "lua-cli";
import { z } from "zod";

// 1. Search Documentation (Lua Vector Search)
export class SearchDocsTool implements LuaTool {
  name = "search_docs";
  description = "Search product documentation";
  
  inputSchema = z.object({
    query: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Data.search('product_docs', input.query, 5, 0.7);
    
    return {
      articles: results.map(entry => ({
        title: entry.title,
        content: entry.content.substring(0, 300),
        url: entry.url,
        relevance: entry.score
      }))
    };
  }
}

// 2. Create User Account (Your SaaS API)
export class CreateUserTool implements LuaTool {
  name = "create_user";
  description = "Create new user account";
  
  inputSchema = z.object({
    email: z.string().email(),
    name: z.string(),
    company: z.string(),
    plan: z.enum(['starter', 'professional', 'enterprise'])
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const apiKey = env('SAAS_API_KEY');
    
    // Call YOUR SaaS API
    const response = await fetch('https://your-saas-api.com/api/users', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(input)
    });
    
    const user = await response.json();
    
    return {
      userId: user.id,
      email: user.email,
      setupUrl: `https://your-app.com/setup?token=${user.setupToken}`,
      message: `Account created! Check ${user.email} for setup instructions.`
    };
  }
}

// 3. Get User Usage (Your SaaS API)
export class GetUsageTool implements LuaTool {
  name = "get_usage";
  description = "Check account usage and limits";
  
  inputSchema = z.object({
    userId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const apiKey = env('SAAS_API_KEY');
    
    const response = await fetch(
      `https://your-saas-api.com/api/users/${input.userId}/usage`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );
    
    const usage = await response.json();
    
    return {
      plan: usage.plan,
      apiCalls: `${usage.apiCalls.toLocaleString()} / ${usage.limits.apiCalls.toLocaleString()}`,
      storage: `${usage.storage}GB / ${usage.limits.storage}GB`,
      users: `${usage.users} / ${usage.limits.users}`,
      daysUntilRenewal: usage.daysUntilRenewal
    };
  }
}
```

## Environment Setup

```bash theme={null}
# .env
SAAS_API_KEY=your_saas_api_key
SAAS_API_URL=https://your-saas-api.com
```

## Key Features

<CardGroup>
  <Card title="Custom API" icon="cube">
    YOUR SaaS backend
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    Semantic doc search
  </Card>
</CardGroup>


# How Devices Become Tools
Source: https://docs.heylua.ai/devices/agent-tools

Understand how device commands automatically appear as tools your agent can use

## Tool Naming Convention

When a device connects with a list of commands, the agent runtime creates a tool for each command. The tool name follows this pattern:

```
device:{deviceName}:{commandName}
```

For example, a device named `label-printer` with a command `print_label` becomes the tool:

```
device:label-printer:print_label
```

The agent sees this tool alongside its regular skill tools and can invoke it in exactly the same way.

## Auto-Generated Tools

The agent runtime automatically generates each device tool with:

| Property             | Source                                                                               |
| -------------------- | ------------------------------------------------------------------------------------ |
| **Tool name**        | `device:{deviceName}:{commandName}`                                                  |
| **Tool description** | The `description` field from `DeviceCommandDefinition`                               |
| **Input schema**     | The `inputSchema` field from `DeviceCommandDefinition` (or no parameters if omitted) |
| **Timeout**          | The `timeoutMs` field (default: 30 seconds)                                          |

No `lua push` or `lua deploy` is needed. The tools appear the moment the device connects and disappear when it disconnects.

## Tips for Good Descriptions

The description field is what the AI agent reads to decide whether to use the tool. Better descriptions lead to better tool selection.

<Tabs>
  <Tab title="Good Descriptions">
    ```typescript theme={null}
    commands: [
      {
        name: 'read_temperature',
        description: 'Read the current room temperature in celsius from the wall-mounted sensor',
      },
      {
        name: 'print_label',
        description: 'Print a shipping label. Requires recipient name, address, city, and postal code. Optionally specify number of copies (1-10).',
      },
      {
        name: 'scan_barcode',
        description: 'Activate the barcode scanner and return the scanned code. Takes 2-3 seconds. Returns the barcode value and format (UPC, QR, etc).',
      },
    ]
    ```

    These descriptions tell the agent:

    * What the command does
    * What it needs as input
    * What it returns
    * How long it takes (if relevant)
  </Tab>

  <Tab title="Bad Descriptions">
    ```typescript theme={null}
    commands: [
      {
        name: 'read_temperature',
        description: 'temp',
      },
      {
        name: 'print_label',
        description: 'prints stuff',
      },
      {
        name: 'scan_barcode',
        description: 'scanner',
      },
    ]
    ```

    These descriptions are too vague. The agent will struggle to know when to use these tools or what parameters to pass.
  </Tab>
</Tabs>

## Persona Tips

Your agent persona can reference devices to guide tool usage. Add instructions in your persona about when and how to use device tools:

```typescript theme={null}
const agent = new LuaAgent({
  name: 'warehouse-agent',
  persona: `
    You are a warehouse operations assistant.

    You have access to physical devices in the warehouse:
    - Barcode scanners for inventory lookup
    - Weight scales for package verification
    - Gate controllers for dock access

    When a user asks about inventory, use the barcode scanner to look up items.
    When verifying shipments, use the weight scale to confirm package weight.
    Always confirm before opening or closing gates.

    If a device is offline, tell the user and suggest alternatives.
  `,
  skills: [inventorySkill],
});
```

## Example Conversation

Here is what a conversation looks like when an agent uses device tools:

```
User: What's the temperature in the server room?

Agent: [internally selects tool: device:server-room-sensor:read_temperature]
       [sends command to device, receives: { temperature: 23.5, unit: 'celsius' }]

       The server room temperature is currently 23.5 degrees celsius.

User: That seems a bit warm. Can you turn up the AC?

Agent: [internally selects tool: device:server-room-hvac:set_target]
       [sends command with payload: { temperature: 21 }]
       [receives: { targetTemperature: 21, heatingOn: false }]

       Done. I've set the target temperature to 21 degrees celsius.
       The cooling system is now active. The temperature should
       come down within the next few minutes.

User: Thanks. Let me know if it goes above 25.

Agent: I'll keep an eye on it. If the temperature exceeds 25 degrees,
       I'll notify you immediately.
       [Note: this would be handled by a device trigger, not polling]
```

## Multiple Devices

An agent can have many devices connected at once. The device name in the tool name disambiguates them:

```
device:sensor-floor-1:read_temperature
device:sensor-floor-2:read_temperature
device:sensor-floor-3:read_temperature
device:label-printer:print_label
device:gate-controller:open_gate
```

The agent picks the right device based on the user's request and the tool descriptions.

## Offline Devices

<Warning>
  When a device disconnects, its tools are removed from the agent's tool list. The agent will not be able to use commands from an offline device. If a user asks for something that requires an offline device, the agent should explain that the device is unavailable.
</Warning>

Design your persona to handle this gracefully. The agent does not know about devices that were previously connected but are now offline -- it only sees currently connected devices.

## Next Steps

<CardGroup>
  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    Detailed reference for DeviceCommandDefinition
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    The other direction -- devices sending events to the agent
  </Card>

  <Card title="Quickstart" icon="rocket" href="/devices/quickstart">
    See device tools in action
  </Card>

  <Card title="Examples" icon="layer-group" href="/devices/examples/warehouse-inventory">
    Full working examples with multiple devices
  </Card>
</CardGroup>


# Build Your Own Client
Source: https://docs.heylua.ai/devices/build-your-own

Full protocol specification for building a Lua device client in any language.

## Overview

Lua devices communicate with agents over **MQTT** or **Socket.IO**. This page documents the wire protocol for clients in languages without an official SDK.

<Note>
  If you're using **Node.js**, **Python**, or **MicroPython**, use the official SDKs instead.
  This page is for building clients in languages without an official SDK.
</Note>

## Authentication

First, [provision a device credential](/devices/credentials#provision-a-device-credential) for the exact agent, device name, and operations that your client uses. Then pass these values as MQTT connection parameters:

| Parameter         | MQTT Field              | Format            | Example                  |
| ----------------- | ----------------------- | ----------------- | ------------------------ |
| Agent ID          | `username` (before `:`) | `{agentId}`       | `baseAgent_agent_abc123` |
| Device Name       | `username` (after `:`)  | `{deviceName}`    | `warehouse-scanner`      |
| Device credential | `password`              | Opaque credential | `api_<id>.<secret>`      |

**MQTT username format:** `{agentId}:{deviceName}`

Existing raw MQTT clients may keep using a non-dotted legacy key as the password indefinitely.

**Connection settings:**

* Broker: `wss://mqtt.heylua.ai/mqtt` (TLS required in production)
* Client ID: `lua-{agentId}-{deviceName}`
* Clean session: `false` (enables persistent session for QoS 1 message queueing)
* Keep-alive: `60` seconds

## MQTT Topics

All topics use the prefix `lua/devices/{agentId}/{deviceName}/`.

### Device Subscribes To (Server -> Device)

| Topic Suffix     | QoS | Description                       | Payload                                 |
| ---------------- | --- | --------------------------------- | --------------------------------------- |
| `command`        | 1   | Incoming command from agent       | [CommandMessage](#commandmessage)       |
| `connected`      | 1   | Server confirms device connection | `{"message": "..."}`                    |
| `trigger_ack`    | 1   | Server acknowledges a trigger     | [TriggerAckMessage](#triggerackmessage) |
| `trigger_result` | 1   | Result from trigger execution     | `{"triggerName": "...", "result": ...}` |
| `error`          | 1   | Error from server                 | `{"code": "...", "message": "..."}`     |

### Device Publishes To (Device -> Server)

| Topic Suffix | QoS | Retain  | Description                        | Payload                                                                    |
| ------------ | --- | ------- | ---------------------------------- | -------------------------------------------------------------------------- |
| `status`     | 1   | **Yes** | Online/offline status (no secrets) | [StatusMessage](#statusmessage-retained)                                   |
| `status`     | 1   | **No**  | Command manifest                   | [CommandManifestStatusMessage](#commandmanifeststatusmessage-non-retained) |
| `response`   | 1   | No      | Command execution result           | [ResponseMessage](#responsemessage)                                        |
| `trigger`    | 1   | No      | Fire a trigger to the agent        | [TriggerMessage](#triggermessage)                                          |
| `heartbeat`  | 0   | No      | Keep-alive signal                  | Empty payload (`""`)                                                       |

## Socket.IO Events

If you prefer WebSocket transport, connect to `{serverUrl}/devices` with Socket.IO.

| Event            | Direction        | Description              | Payload                                          |
| ---------------- | ---------------- | ------------------------ | ------------------------------------------------ |
| `connected`      | Server -> Device | Connection confirmed     | `{}`                                             |
| `command`        | Server -> Device | Incoming command         | [CommandMessage](#commandmessage) + ack callback |
| `trigger_ack`    | Server -> Device | Trigger acknowledged     | [TriggerAckMessage](#triggerackmessage)          |
| `trigger_result` | Server -> Device | Trigger execution result | `{triggerName, result}`                          |
| `error`          | Server -> Device | Error                    | `{code, message}`                                |
| `response`       | Device -> Server | Command result           | [ResponseMessage](#responsemessage)              |
| `trigger`        | Device -> Server | Fire trigger             | [TriggerMessage](#triggermessage)                |
| `heartbeat`      | Device -> Server | Keep-alive               | `{}`                                             |

**Socket.IO auth** is passed in the `auth` option at connection time:

The historical wire field is named `apiKey` even when it carries a device credential.

```json theme={null}
{
  "apiKey": "<device-credential>",
  "agentId": "baseAgent_agent_abc123",
  "deviceName": "warehouse-scanner",
  "group": "warehouse-a",
  "commands": [...]
}
```

`auth.apiKey` is the stable Socket.IO wire field for both device credentials and existing legacy keys. Do not rename this protocol field.

## Message Schemas

### CommandMessage

Received on the `command` topic when the agent invokes a device command.

```json theme={null}
{
  "commandId": "cmd_abc123",
  "command": "scan_barcode",
  "payload": { "format": "qr" },
  "timeout": 30000
}
```

| Field       | Type   | Required | Description                                |
| ----------- | ------ | -------- | ------------------------------------------ |
| `commandId` | string | Yes      | Unique ID for idempotency                  |
| `command`   | string | Yes      | Command name matching a registered handler |
| `payload`   | any    | No       | Input parameters for the command           |
| `timeout`   | number | No       | Timeout in milliseconds (default: 30000)   |

### ResponseMessage

Published to the `response` topic after executing a command.

```json theme={null}
{
  "commandId": "cmd_abc123",
  "success": true,
  "data": { "barcode": "ABC-12345", "format": "CODE128" }
}
```

```json theme={null}
{
  "commandId": "cmd_abc123",
  "success": false,
  "error": "Scanner hardware not responding"
}
```

| Field       | Type    | Required | Description                          |
| ----------- | ------- | -------- | ------------------------------------ |
| `commandId` | string  | Yes      | Must match the incoming command's ID |
| `success`   | boolean | Yes      | Whether the command succeeded        |
| `data`      | any     | No       | Result data (on success)             |
| `error`     | string  | No       | Error message (on failure)           |

### TriggerMessage

Published to the `trigger` topic to fire an event to the agent.

```json theme={null}
{
  "triggerName": "barcode_scanned",
  "payload": { "value": "ABC-12345", "location": "aisle-3" }
}
```

| Field         | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `triggerName` | string | Yes      | Name of the trigger            |
| `payload`     | any    | No       | Trigger data sent to the agent |

### TriggerAckMessage

Received on the `trigger_ack` topic after the server processes a trigger.

```json theme={null}
{
  "triggerId": "trg_abc123",
  "received": true
}
```

| Field       | Type    | Required | Description                      |
| ----------- | ------- | -------- | -------------------------------- |
| `triggerId` | string  | Yes      | Server-assigned trigger ID       |
| `received`  | boolean | Yes      | Whether the trigger was accepted |
| `error`     | string  | No       | Error message if rejected        |

### StatusMessage (retained)

Published to the `status` topic with `retain: true`. This message must not contain a credential because the broker stores retained messages and delivers them to future subscribers.

```json theme={null}
{
  "status": "online",
  "timestamp": "2026-04-17T10:30:00.000Z",
  "group": "warehouse-a"
}
```

### CommandManifestStatusMessage (non-retained)

Published to the `status` topic with `retain: false` immediately after the retained status. A client that uses a device credential sends its command manifest without repeating the credential. The gateway uses the identity established during MQTT CONNECT.

```json theme={null}
{
  "status": "online",
  "group": "warehouse-a",
  "commands": [
    {
      "name": "scan_barcode",
      "description": "Scan a barcode and return its value",
      "inputSchema": {
        "type": "object",
        "properties": {
          "format": { "type": "string", "enum": ["qr", "code128", "ean13"] }
        }
      },
      "timeoutMs": 30000
    }
  ]
}
```

An existing client that uses a non-dotted legacy key keeps the `apiKey` property in this non-retained message. Do not add `apiKey` when the CONNECT password is a typed device credential.

### Heartbeat

Published to the `heartbeat` topic every 30 seconds with an empty payload. QoS 0 (fire-and-forget).

### Last Will and Testament (LWT)

Set the MQTT LWT to publish an offline status if the device disconnects unexpectedly:

* **Topic:** `lua/devices/{agentId}/{deviceName}/status`
* **Payload:** `{"status": "offline", "timestamp": "..."}`
* **QoS:** 1
* **Retain:** true

## Self-Describing Commands

Commands are sent at connect time in the [CommandManifestStatusMessage](#commandmanifeststatusmessage-non-retained). The server registers permitted commands as agent tools automatically.

```json theme={null}
{
  "name": "read_temperature",
  "description": "Read current temperature in celsius from the DHT22 sensor",
  "inputSchema": {
    "type": "object",
    "properties": {
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    }
  },
  "timeoutMs": 5000,
  "retry": { "maxAttempts": 3, "backoffMs": 1000 }
}
```

| Field         | Type   | Required | Description                               |
| ------------- | ------ | -------- | ----------------------------------------- |
| `name`        | string | Yes      | Command name (used by agent to invoke)    |
| `description` | string | Yes      | Shown to the AI agent as tool description |
| `inputSchema` | object | No       | JSON Schema for command parameters        |
| `timeoutMs`   | number | No       | Timeout in ms (default: 30000)            |
| `retry`       | object | No       | `{maxAttempts, backoffMs}`                |

## Command Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Idle
    Idle --> Received: command message arrives
    Received --> DedupCheck: parse commandId
    DedupCheck --> CachedResponse: commandId seen before
    DedupCheck --> HandlerLookup: new commandId
    CachedResponse --> PublishResponse: re-send cached response
    HandlerLookup --> ExecuteHandler: handler found
    HandlerLookup --> ErrorResponse: unknown command
    ExecuteHandler --> SuccessResponse: handler returns result
    ExecuteHandler --> ErrorResponse: handler throws exception
    SuccessResponse --> CacheAndPublish: cache + publish
    ErrorResponse --> CacheAndPublish: cache + publish
    CacheAndPublish --> PublishResponse
    PublishResponse --> Idle
```

## Idempotency

Commands include a `commandId` that must be used for idempotency. Your client should:

1. Maintain an LRU cache of recently seen `commandId` values (recommended: 1000 entries, 5-minute TTL)
2. On receiving a command, check if the `commandId` has been seen before
3. If seen, re-publish the cached response without re-executing the handler
4. If new, execute the handler, cache the response, then publish it

This ensures that retried messages (common with QoS 1) do not cause duplicate side effects.

<Warning>
  Without idempotency handling, MQTT QoS 1 redelivery can cause commands to execute multiple times.
  Always implement the dedup cache.
</Warning>

## Rate Limits and Constraints

| Constraint              | Value        |
| ----------------------- | ------------ |
| Max payload size (MQTT) | 256 KB       |
| Max commands per device | 50           |
| Heartbeat interval      | 30 seconds   |
| Trigger ACK timeout     | 10 seconds   |
| Command default timeout | 30 seconds   |
| Dedup cache TTL         | 5 minutes    |
| Dedup cache size        | 1000 entries |
| Reconnect base delay    | 1 second     |
| Reconnect max delay     | 30 seconds   |
| MQTT keep-alive         | 60 seconds   |

## Example Implementations

<Tabs>
  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "encoding/json"
        "fmt"
        mqtt "github.com/eclipse/paho.mqtt.golang"
        "os"
        "os/signal"
        "time"
    )

    func main() {
        agentID := "baseAgent_agent_abc123"
        deviceName := "go-sensor"
        deviceCredential := "your-device-credential"
        prefix := fmt.Sprintf("lua/devices/%s/%s/", agentID, deviceName)

        opts := mqtt.NewClientOptions().
            AddBroker("wss://mqtt.heylua.ai/mqtt").
            SetClientID(fmt.Sprintf("lua-%s-%s", agentID, deviceName)).
            SetUsername(fmt.Sprintf("%s:%s", agentID, deviceName)).
            SetPassword(deviceCredential).
            SetKeepAlive(60 * time.Second).
            SetCleanSession(false).
            SetWill(prefix+"status",
                `{"status":"offline","timestamp":"`+time.Now().UTC().Format(time.RFC3339)+`"}`,
                1, true)

        client := mqtt.NewClient(opts)
        if token := client.Connect(); token.Wait() && token.Error() != nil {
            panic(token.Error())
        }

        // Subscribe to commands
        client.Subscribe(prefix+"command", 1, func(c mqtt.Client, msg mqtt.Message) {
            var cmd map[string]interface{}
            json.Unmarshal(msg.Payload(), &cmd)

            response := map[string]interface{}{
                "commandId": cmd["commandId"],
                "success":   true,
                "data":      map[string]interface{}{"temp": 22.5},
            }
            payload, _ := json.Marshal(response)
            c.Publish(prefix+"response", 1, false, payload)
        })

        // Publish online status
        online, _ := json.Marshal(map[string]string{"status": "online", "timestamp": time.Now().UTC().Format(time.RFC3339)})
        client.Publish(prefix+"status", 1, true, online)
        manifest, _ := json.Marshal(map[string]interface{}{"status": "online", "commands": []interface{}{}})
        client.Publish(prefix+"status", 1, false, manifest)

        fmt.Println("Device connected. Press Ctrl+C to exit.")
        sig := make(chan os.Signal, 1)
        signal.Notify(sig, os.Interrupt)
        <-sig
        client.Disconnect(250)
    }
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use rumqttc::{MqttOptions, AsyncClient, QoS, Event, Packet, LastWill};
    use serde_json::{json, Value};
    use tokio;

    #[tokio::main]
    async fn main() {
        let agent_id = "baseAgent_agent_abc123";
        let device_name = "rust-sensor";
        let device_credential = "your-device-credential";
        let prefix = format!("lua/devices/{agent_id}/{device_name}/");

        let mut opts = MqttOptions::new(
            format!("lua-{agent_id}-{device_name}"),
            "wss://mqtt.heylua.ai/mqtt", 443,
        );
        opts.set_credentials(format!("{agent_id}:{device_name}"), device_credential);
        opts.set_keep_alive(std::time::Duration::from_secs(60));
        opts.set_clean_session(false);
        opts.set_last_will(LastWill::new(
            format!("{prefix}status"),
            json!({"status": "offline"}).to_string(),
            QoS::AtLeastOnce, true,
        ));
        opts.set_transport(rumqttc::Transport::tls_with_default_config());

        let (client, mut eventloop) = AsyncClient::new(opts, 10);
        client.subscribe(format!("{prefix}command"), QoS::AtLeastOnce).await.unwrap();

        // Publish online status
        let online = json!({"status": "online"}).to_string();
        client.publish(format!("{prefix}status"), QoS::AtLeastOnce, true, online).await.unwrap();
        let manifest = json!({"status": "online", "commands": []}).to_string();
        client.publish(format!("{prefix}status"), QoS::AtLeastOnce, false, manifest).await.unwrap();

        println!("Device connected. Listening for commands...");
        while let Ok(event) = eventloop.poll().await {
            if let Event::Incoming(Packet::Publish(msg)) = event {
                if msg.topic.ends_with("/command") {
                    let cmd: Value = serde_json::from_slice(&msg.payload).unwrap();
                    let response = json!({
                        "commandId": cmd["commandId"],
                        "success": true,
                        "data": {"temp": 22.5}
                    });
                    client.publish(
                        format!("{prefix}response"), QoS::AtLeastOnce, false,
                        response.to_string(),
                    ).await.unwrap();
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using MQTTnet;
    using MQTTnet.Client;
    using System.Text;
    using System.Text.Json;

    var agentId = "baseAgent_agent_abc123";
    var deviceName = "csharp-sensor";
    var deviceCredential = "your-device-credential";
    var prefix = $"lua/devices/{agentId}/{deviceName}/";

    var factory = new MqttFactory();
    var client = factory.CreateMqttClient();

    var options = new MqttClientOptionsBuilder()
        .WithTcpServer("wss://mqtt.heylua.ai/mqtt", 443)
        .WithTlsOptions(o => o.UseTls())
        .WithClientId($"lua-{agentId}-{deviceName}")
        .WithCredentials($"{agentId}:{deviceName}", deviceCredential)
        .WithKeepAlivePeriod(TimeSpan.FromSeconds(60))
        .WithCleanSession(false)
        .WithWillTopic($"{prefix}status")
        .WithWillPayload(JsonSerializer.Serialize(new { status = "offline" }))
        .WithWillQualityOfServiceLevel(MQTTnet.Protocol.MqttQualityOfServiceLevel.AtLeastOnce)
        .WithWillRetain(true)
        .Build();

    client.ApplicationMessageReceivedAsync += async e =>
    {
        if (e.ApplicationMessage.Topic.EndsWith("/command"))
        {
            var cmd = JsonSerializer.Deserialize<JsonElement>(e.ApplicationMessage.PayloadSegment);
            var response = JsonSerializer.Serialize(new
            {
                commandId = cmd.GetProperty("commandId").GetString(),
                success = true,
                data = new { temp = 22.5 }
            });
            await client.PublishStringAsync($"{prefix}response", response,
                MQTTnet.Protocol.MqttQualityOfServiceLevel.AtLeastOnce);
        }
    };

    await client.ConnectAsync(options);
    await client.SubscribeAsync($"{prefix}command",
        MQTTnet.Protocol.MqttQualityOfServiceLevel.AtLeastOnce);

    // Publish online status
    await client.PublishStringAsync($"{prefix}status",
        JsonSerializer.Serialize(new { status = "online" }),
        MQTTnet.Protocol.MqttQualityOfServiceLevel.AtLeastOnce, true);
    await client.PublishStringAsync($"{prefix}status",
        JsonSerializer.Serialize(new { status = "online", commands = Array.Empty<object>() }),
        MQTTnet.Protocol.MqttQualityOfServiceLevel.AtLeastOnce, false);

    Console.WriteLine("Device connected. Press Ctrl+C to exit.");
    await Task.Delay(Timeout.Infinite);
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import MQTTNIO
    import NIO
    import Foundation

    let agentId = "baseAgent_agent_abc123"
    let deviceName = "swift-sensor"
    let deviceCredential = "your-device-credential"
    let prefix = "lua/devices/\(agentId)/\(deviceName)/"

    let client = MQTTClient(
        configuration: .init(
            target: .webSocket("wss://mqtt.heylua.ai/mqtt"),
            tls: .forClient(certificateVerification: .fullVerification),
            clientId: "lua-\(agentId)-\(deviceName)",
            clean: false,
            credentials: .init(
                username: "\(agentId):\(deviceName)",
                password: deviceCredential
            ),
            willMessage: .init(
                topic: "\(prefix)status",
                payload: ByteBuffer(string: #"{"status":"offline"}"#),
                qos: .atLeastOnce,
                retain: true
            ),
            keepAliveInterval: .seconds(60)
        ),
        eventLoopGroupProvider: .createNew
    )

    try client.connect().wait()
    try client.subscribe(to: [.init(topicFilter: "\(prefix)command", qos: .atLeastOnce)]).wait()

    // Publish online status
    let online = #"{"status":"online"}"#
    try client.publish(.init(topic: "\(prefix)status",
        payload: ByteBuffer(string: online), qos: .atLeastOnce, retain: true)).wait()
    let manifest = #"{"status":"online","commands":[]}"#
    try client.publish(.init(topic: "\(prefix)status",
        payload: ByteBuffer(string: manifest), qos: .atLeastOnce, retain: false)).wait()

    client.addPublishListener(named: "commands") { result in
        if case .success(let msg) = result, msg.topic.hasSuffix("/command") {
            guard let data = msg.payload.getData(at: 0, length: msg.payload.readableBytes),
                  let cmd = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
                  let commandId = cmd["commandId"] as? String else { return }

            let response: [String: Any] = [
                "commandId": commandId, "success": true,
                "data": ["temp": 22.5]
            ]
            let payload = try! JSONSerialization.data(withJSONObject: response)
            _ = try? client.publish(.init(topic: "\(prefix)response",
                payload: ByteBuffer(data: payload), qos: .atLeastOnce, retain: false)).wait()
        }
    }

    print("Device connected. Listening for commands...")
    dispatchMain()
    ```
  </Tab>
</Tabs>

<Note>
  These examples show the minimal connect-and-handle pattern. Production clients should add:
  idempotency dedup, heartbeat loop, LWT, graceful shutdown, error handling, and auto-reconnect
  with exponential backoff.
</Note>


# CDN Uploads
Source: https://docs.heylua.ai/devices/cdn-uploads

Upload and download files between your device and the Lua CDN

## Overview

Every `DeviceClient` instance includes a `cdn` property for uploading files such as screenshots, logs, and sensor data exports. The CDN uses the same credential as the device connection. A new device credential must include the `assets.upload` operation before this client can upload files.

## Methods

### upload

Upload a file to the CDN. Returns a `CdnUploadResult` with the file ID and public URL.

```typescript theme={null}
const result = await device.cdn.upload(data, filename, contentType);
```

<ParamField type="Buffer | Blob">
  File content as a Node.js Buffer or Blob.
</ParamField>

<ParamField type="string">
  Filename including extension (e.g., `screenshot.png`, `sensor-log.csv`).
</ParamField>

<ParamField type="string">
  MIME type (e.g., `image/png`, `text/csv`). Defaults to `application/octet-stream`.
</ParamField>

**Returns:** `CdnUploadResult`

```typescript theme={null}
interface CdnUploadResult {
  fileId: string;      // Unique file identifier
  mediaType: string;   // Detected MIME type
  extension: string;   // File extension
  url: string;         // Public URL (https://cdn.heylua.ai/{fileId})
}
```

### download

Download a file from the CDN by its file ID.

```typescript theme={null}
const buffer = await device.cdn.download(fileId);
```

<ParamField type="string">
  The file ID returned from a previous upload.
</ParamField>

**Returns:** `Buffer` containing the file content.

### getUrl

Get the public URL for a file without downloading it.

```typescript theme={null}
const url = device.cdn.getUrl(fileId);
// https://cdn.heylua.ai/{fileId}
```

<ParamField type="string">
  The file ID returned from a previous upload.
</ParamField>

**Returns:** `string` -- the full CDN URL.

## Use Cases

<CardGroup>
  <Card title="Screenshots" icon="camera">
    Kiosk devices capturing screen state for debugging or audit.
  </Card>

  <Card title="Sensor Logs" icon="file-csv">
    Periodic CSV or JSON exports of accumulated sensor readings.
  </Card>

  <Card title="Photos" icon="image">
    Camera-equipped devices uploading inspection photos.
  </Card>

  <Card title="Firmware Reports" icon="file-lines">
    Diagnostic reports uploaded for agent analysis.
  </Card>
</CardGroup>

## Example: Screenshot Upload

A kiosk device that takes a screenshot when the agent requests it and uploads it to the CDN:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';
  import { execSync } from 'child_process';
  import fs from 'fs';

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'lobby-kiosk',
    commands: [
      {
        name: 'take_screenshot',
        description: 'Capture a screenshot of the kiosk display and upload it',
      },
      {
        name: 'upload_logs',
        description: 'Upload the last hour of application logs',
      },
    ],
  });

  device.onCommand('take_screenshot', async () => {
    // Capture screenshot (Linux with scrot, macOS with screencapture)
    const tmpPath = '/tmp/kiosk-screenshot.png';
    execSync(`screencapture -x ${tmpPath}`);

    const screenshot = fs.readFileSync(tmpPath);
    const result = await device.cdn.upload(screenshot, 'kiosk-screenshot.png', 'image/png');

    return {
      message: 'Screenshot captured and uploaded',
      url: result.url,
      fileId: result.fileId,
      size: screenshot.length,
    };
  });

  device.onCommand('upload_logs', async () => {
    const logPath = '/var/log/kiosk/app.log';
    const logContent = fs.readFileSync(logPath);

    const result = await device.cdn.upload(
      logContent,
      `kiosk-logs-${new Date().toISOString().slice(0, 10)}.log`,
      'text/plain',
    );

    return {
      message: 'Logs uploaded',
      url: result.url,
      fileId: result.fileId,
      lines: logContent.toString().split('\n').length,
    };
  });

  async function main() {
    await device.connect();
    console.log('Kiosk device online');
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  import subprocess
  from datetime import date
  from lua_device import DeviceClient, DeviceCommandDefinition

  client = DeviceClient(
      agent_id=os.environ["LUA_AGENT_ID"],
      api_key=os.environ["LUA_API_KEY"],
      device_name="lobby-kiosk",
      commands=[
          DeviceCommandDefinition(
              name="take_screenshot",
              description="Capture a screenshot of the kiosk display and upload it",
          ),
          DeviceCommandDefinition(
              name="upload_logs",
              description="Upload the last hour of application logs",
          ),
      ],
  )

  @client.on_command("take_screenshot")
  async def handle_take_screenshot(payload):
      # Capture screenshot (Linux with scrot, macOS with screencapture)
      tmp_path = "/tmp/kiosk-screenshot.png"
      subprocess.run(["screencapture", "-x", tmp_path], check=True)

      with open(tmp_path, "rb") as f:
          screenshot = f.read()

      result = await client.cdn.upload(screenshot, "kiosk-screenshot.png", "image/png")

      return {
          "message": "Screenshot captured and uploaded",
          "url": result.url,
          "fileId": result.file_id,
          "size": len(screenshot),
      }

  @client.on_command("upload_logs")
  async def handle_upload_logs(payload):
      log_path = "/var/log/kiosk/app.log"
      with open(log_path, "rb") as f:
          log_content = f.read()

      result = await client.cdn.upload(
          log_content,
          f"kiosk-logs-{date.today().isoformat()}.log",
          "text/plain",
      )

      return {
          "message": "Logs uploaded",
          "url": result.url,
          "fileId": result.file_id,
          "lines": log_content.decode().count("\n"),
      }

  async def main():
      await client.connect()
      print("Kiosk device online")

  asyncio.run(main())
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Full client reference including CDN property
  </Card>

  <Card title="Retail Kiosk Example" icon="store" href="/devices/examples/retail-kiosk">
    Complete kiosk example with CDN uploads
  </Card>

  <Card title="API Reference" icon="book" href="/api/luadeviceclient">
    CDN class method signatures
  </Card>
</CardGroup>


# CLI Commands
Source: https://docs.heylua.ai/devices/cli-commands

Reference for all device-related CLI commands

## lua devices

Manage connected devices from the command line.

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

### Actions

| Action         | Description                                 |
| -------------- | ------------------------------------------- |
| *(none)*       | Interactive device management               |
| `list`         | List all connected devices                  |
| `status`       | Check the status of a specific device       |
| `enable`       | Enable a device                             |
| `disable`      | Disable a device (stops receiving commands) |
| `remove`       | Remove a device from the agent              |
| `test`         | Interactively test a device command         |
| `test-trigger` | Test a device trigger                       |

### Options

| Flag                   | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `--device-name <name>` | Target device name                             |
| `--group <group>`      | Filter by device group                         |
| `--payload <json>`     | JSON payload for test commands (default: `{}`) |
| `--force`              | Skip confirmation prompts                      |

### Examples

```bash theme={null}
# Interactive management
lua devices

# List all connected devices
lua devices list

# List devices in a specific group
lua devices list --group warehouse-floor

# Check device status
lua devices status --device-name label-printer

# Enable a device
lua devices enable --device-name label-printer

# Disable a device
lua devices disable --device-name label-printer

# Remove a device (with confirmation)
lua devices remove --device-name label-printer

# Remove without confirmation
lua devices remove --device-name label-printer --force

# Test a command interactively
lua devices test --device-name label-printer

# Test a trigger
lua devices test-trigger --device-name label-printer
```

## lua push device-trigger

Push a compiled device trigger to the server.

```bash theme={null}
lua push device-trigger [name]
```

Device triggers are agent-side primitives that handle events fired by devices. They are compiled, versioned, and pushed like other Lua primitives (skills, webhooks, jobs).

<Steps>
  <Step title="Compile">
    ```bash theme={null}
    lua compile
    ```

    The compiler detects `defineDeviceTrigger()` calls and bundles them.
  </Step>

  <Step title="Push">
    ```bash theme={null}
    # Push a specific device trigger
    lua push device-trigger temperature-alert

    # Push all primitives (including device triggers)
    lua push
    ```
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    lua deploy
    ```

    Activates the pushed version.
  </Step>
</Steps>

## lua compile

The compiler automatically detects device-related primitives in your source code:

* **`defineDeviceTrigger()`** calls are compiled as device trigger primitives
* **`defineDevice()`** calls define device metadata (commands and inline triggers)

No special flags are needed -- `lua compile` handles everything.

```bash theme={null}
lua compile
```

Output includes device triggers alongside other primitives:

```
Compiled:
  Skills: 2
  Webhooks: 1
  Device Triggers: 3
  Jobs: 0
```

## lua chat

Test device interactions through the chat interface:

```bash theme={null}
lua chat
```

When devices are connected, the agent has access to their commands as tools. You can test device interactions by chatting naturally:

```
> What devices are connected?
> Read the temperature from pico-sensor
> Turn on the LED on my device
```

<Note>
  The device must be running and connected for its tools to appear. If you do not see device tools, check that your device is online with `lua devices list`.
</Note>

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/devices/quickstart">
    Connect your first device
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Device trigger development guide
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Full device client reference
  </Card>

  <Card title="Overview" icon="satellite-dish" href="/devices/overview">
    Device Gateway architecture
  </Card>
</CardGroup>


# Device credentials
Source: https://docs.heylua.ai/devices/credentials

Provision and manage a credential for one exact device

New Node.js installations and custom protocol clients use a device credential. The server binds each credential to one agent, one device name, and the device operations that you select.

<Note>
  `@lua-ai-global/device-client` 1.1.0 and later support the `deviceCredential` option. The published Python 1.3.0 client and the current MicroPython distribution use `api_key` with existing non-dotted legacy keys. Those legacy configurations remain supported indefinitely.
</Note>

## Choose the permitted operations

Grant only the operations that the device uses.

| Operation       | Allows the device to                                                     |
| --------------- | ------------------------------------------------------------------------ |
| `commands`      | Advertise command handlers, receive commands, and return command results |
| `triggers`      | Send device triggers to the agent                                        |
| `assets.upload` | Upload files through the device client's CDN helper                      |

A device credential is different from a scoped personal API key. Lua accepts it only on supported device connections and device file uploads. A typed personal API key cannot replace a device credential on these device-only paths. Existing non-dotted legacy keys keep their permanent compatibility behavior.

## Provision a device credential

The provisioning request requires a renewable first-party user session. Do not send an API key to this endpoint, and never store the user session on the device.

The following example creates a credential for one device that receives commands and sends triggers:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST "https://api.heylua.ai/admin/users/me/credentials/device" \
  --header "Authorization: Bearer $FIRST_PARTY_SESSION_TOKEN" \
  --header "Content-Type: application/json" \
  --output response.json \
  --data '{
    "agentId": "baseAgent_agent_abc123",
    "deviceName": "warehouse-scanner",
    "operations": ["commands", "triggers"],
    "name": "Warehouse scanner"
  }'
```

`FIRST_PARTY_SESSION_TOKEN` is a placeholder for the current signed-in user's session token. It is not a Lua API key.

The signed-in user must be allowed to issue credentials and perform every requested operation on the target agent. The endpoint returns `403` without creating a credential when either check fails.

The request body accepts these fields:

| Field        | Required | Description                                                          |
| ------------ | -------- | -------------------------------------------------------------------- |
| `agentId`    | Yes      | The exact agent that the device may connect to                       |
| `deviceName` | Yes      | The exact device identity used by the client and MQTT topics         |
| `operations` | Yes      | One or more values from `commands`, `triggers`, and `assets.upload`  |
| `name`       | No       | A label for credential management, up to 120 characters              |
| `expiresAt`  | No       | An absolute expiry time in epoch milliseconds. Omit it for no expiry |

The `deviceName` must contain 1 to 200 characters. Do not use whitespace or the MQTT topic characters `/`, `+`, or `#`.

The response identifies the credential class, exact binding, operations, and lifecycle state:

| Response field              | Value                                                                  |
| --------------------------- | ---------------------------------------------------------------------- |
| `secret`                    | The full opaque credential. Lua returns it only after create or rotate |
| `credential.id`             | The stable identifier used by lifecycle endpoints                      |
| `credential.credentialType` | `deviceCredential`                                                     |
| `credential.status`         | `active` after creation                                                |
| `credential.secretVersion`  | The current secret version                                             |
| `credential.deviceBinding`  | The exact `agentId`, `deviceName`, and `operations` from the request   |

Treat the secret as opaque. Do not parse its prefix or dotted format.

```bash theme={null}
export LUA_DEVICE_CREDENTIAL="$(jq -r '.secret' response.json)"
export LUA_DEVICE_CREDENTIAL_ID="$(jq -r '.credential.id' response.json)"
```

Store the secret in the device's secret store. Keep the credential identifier in your provisioning system so that you can rotate, suspend, or revoke the device later.

<Warning>
  The `agentId` and `deviceName` in the client configuration must exactly match the values used at provisioning. The gateway rejects a different agent or device name even when the secret is valid.
</Warning>

## Configure the device client

Use `deviceCredential` with the Node.js client 1.1.0 or later:

```typescript theme={null}
import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: process.env.LUA_AGENT_ID!,
  deviceName: 'warehouse-scanner',
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
});
```

The published Python 1.3.0 client and the current MicroPython distribution do not expose a typed credential option. Keep their existing `api_key` configuration unchanged.

For raw MQTT clients, use `{agentId}:{deviceName}` as the username and the device credential as the MQTT CONNECT password. Do not include a typed device credential in a status payload. See [Build your own client](/devices/build-your-own).

## Manage the lifecycle

All lifecycle requests require a renewable first-party user session. Replace `credential-id` with the stable `credential.id` returned at provisioning.

<AccordionGroup>
  <Accordion title="List credentials">
    List the signed-in user's personal and device credentials:

    ```bash theme={null}
    curl "https://api.heylua.ai/admin/users/me/credentials" \
      --header "Authorization: Bearer $FIRST_PARTY_SESSION_TOKEN"
    ```

    Device entries have `credentialType: "deviceCredential"` and include their `deviceBinding`. List responses never contain the secret.
  </Accordion>

  <Accordion title="Rotate">
    Replace the secret without changing the credential identifier, device binding, or permitted operations:

    ```bash theme={null}
    curl --request POST \
      "https://api.heylua.ai/admin/users/me/credentials/credential-id/rotate" \
      --header "Authorization: Bearer $FIRST_PARTY_SESSION_TOKEN"
    ```

    Save the new `secret`, then replace the old secret on the device. Lua returns the new secret only in this response.
  </Accordion>

  <Accordion title="Suspend and reactivate">
    Suspend the credential without deleting its binding:

    ```bash theme={null}
    curl --request POST \
      "https://api.heylua.ai/admin/users/me/credentials/credential-id/suspend" \
      --header "Authorization: Bearer $FIRST_PARTY_SESSION_TOKEN"
    ```

    Reactivate an unexpired suspended credential:

    ```bash theme={null}
    curl --request POST \
      "https://api.heylua.ai/admin/users/me/credentials/credential-id/reactivate" \
      --header "Authorization: Bearer $FIRST_PARTY_SESSION_TOKEN"
    ```
  </Accordion>

  <Accordion title="Revoke">
    Permanently revoke the credential:

    ```bash theme={null}
    curl --request DELETE \
      "https://api.heylua.ai/admin/users/me/credentials/credential-id" \
      --header "Authorization: Bearer $FIRST_PARTY_SESSION_TOKEN"
    ```

    You cannot reactivate a revoked credential. Provision a new one if the device needs access again.
  </Accordion>
</AccordionGroup>

Lifecycle changes disconnect affected Socket.IO and MQTT sessions as the change propagates. The authorization backstop applies within about one minute.

## Preserve existing installations

Existing device settings remain compatible:

* Node.js continues to accept `apiKey` indefinitely.
* Python and MicroPython continue to accept `api_key` indefinitely.
* Existing non-dotted legacy keys remain valid indefinitely. Lua does not rotate, rewrite, revoke, or expire them automatically.
* Socket.IO continues to send the credential in the `auth.apiKey` wire field.
* MQTT continues to send the credential as the CONNECT password.

For Node.js and custom clients, that password can be the typed device credential. Published Python 1.3.0 and current MicroPython clients send their existing non-dotted legacy `api_key`.

For new Node.js installations, use `deviceCredential`. This tells the MQTT client not to repeat the typed secret in the non-retained status message. If you provide both `deviceCredential` and `apiKey`, their values must match.

## Next steps

<CardGroup>
  <Card title="Device quickstart" icon="rocket" href="/devices/quickstart">
    Connect a Node.js or Python device
  </Card>

  <Card title="MQTT transport" icon="tower-broadcast" href="/devices/mqtt-client">
    Configure MQTT clients and topics
  </Card>
</CardGroup>


# Factory Monitor
Source: https://docs.heylua.ai/devices/examples/industrial-sensor

Monitor industrial equipment with MicroPython on a Raspberry Pi Pico W

## Overview

**Industry:** Manufacturing

A factory floor monitoring system running on a Raspberry Pi Pico W. The device reads vibration and temperature sensors, provides an emergency stop command, and fires triggers when anomalies are detected.

**Commands:**

* `read_vibration` -- Read vibration amplitude from an accelerometer
* `read_temperature` -- Read bearing temperature
* `emergency_stop` -- Trigger the emergency stop relay

**Triggers:**

* `vibration_anomaly` -- Fires when vibration exceeds safe threshold

The current MicroPython distribution uses `api_key` with an existing non-dotted legacy key. This configuration remains supported indefinitely.

## Device Client (MicroPython)

```python theme={null}
import network
import machine
import time

# -- WiFi --
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("FACTORY_WIFI", "secure_password_here")

while not wlan.isconnected():
    time.sleep(0.5)

print("WiFi connected:", wlan.ifconfig()[0])

# -- Hardware setup --
# Onboard LED for status indication
status_led = machine.Pin("LED", machine.Pin.OUT)

# ADC for vibration sensor (analog accelerometer on GP26)
vibration_adc = machine.ADC(machine.Pin(26))

# DS18B20 or analog temp sensor on GP27
temp_adc = machine.ADC(machine.Pin(27))

# Emergency stop relay on GP16
estop_relay = machine.Pin(16, machine.Pin.OUT, value=0)

# -- Device --
from lua_device import LuaDevice

device = LuaDevice(
    agent_id="your-agent-id",
    api_key="your-api-key",
    device_name="cnc-monitor-01",
    server="mqtt.heylua.ai",
    group="factory-floor",
)

@device.command("read_vibration")
def read_vibration(payload):
    # Read ADC value and convert to g-force (simplified)
    raw = vibration_adc.read_u16()
    amplitude_g = (raw / 65535.0) * 4.0  # 0-4g range
    return {
        "amplitude_g": round(amplitude_g, 3),
        "raw_adc": raw,
        "status": "warning" if amplitude_g > 2.5 else "normal",
    }

@device.command("read_temperature")
def read_temperature(payload):
    raw = temp_adc.read_u16()
    # Convert to celsius (simplified linear conversion)
    temp_c = (raw / 65535.0) * 150.0  # 0-150C range for bearing temp
    return {
        "temperature": round(temp_c, 1),
        "unit": "celsius",
        "status": "critical" if temp_c > 80 else "warning" if temp_c > 60 else "normal",
    }

@device.command("emergency_stop")
def emergency_stop(payload):
    estop_relay.on()  # Activate relay (normally open -> closed)
    status_led.on()   # Visual indicator

    reason = payload.get("reason", "manual trigger")
    print("[ESTOP] Emergency stop activated:", reason)

    return {
        "activated": True,
        "reason": reason,
        "timestamp": str(time.time()),
    }

# -- Connect and run --
device.connect()
status_led.on()  # LED on = connected
print("Factory monitor online")

# -- Main loop with anomaly detection --
VIBRATION_THRESHOLD = 3.0  # g-force
last_check = time.time()
check_interval = 10  # seconds

while True:
    try:
        device._client.check_msg()

        now = time.time()

        # Heartbeat
        if now - device._last_heartbeat >= device._heartbeat_interval:
            device._client.publish(device._topic_prefix + "heartbeat", b"", qos=0)
            device._last_heartbeat = now

        # Periodic vibration check
        if now - last_check >= check_interval:
            raw = vibration_adc.read_u16()
            amplitude = (raw / 65535.0) * 4.0

            if amplitude > VIBRATION_THRESHOLD:
                device.trigger("vibration_anomaly", {
                    "amplitude_g": round(amplitude, 3),
                    "threshold_g": VIBRATION_THRESHOLD,
                    "machine": "CNC-Mill-04",
                    "location": "bay-3",
                })
                # Blink LED rapidly to indicate alert
                for _ in range(5):
                    status_led.toggle()
                    time.sleep_ms(100)
                status_led.on()

            last_check = now

        # Clean dedup cache
        if len(device._seen_ids) > 100:
            device._clean_dedup()

        time.sleep_ms(100)

    except OSError as e:
        print("Connection lost:", e)
        status_led.off()
        device._reconnect()
        status_led.on()
    except Exception as e:
        print("Error:", e)
        time.sleep(1)
```

## Agent-Side Trigger Handler

```typescript theme={null}
// src/triggers/vibration-anomaly.ts
import { defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';

export const vibrationAnomaly = defineDeviceTrigger({
  name: 'vibration-anomaly',
  description: 'Fired when a factory machine vibration reading exceeds the safe threshold',
  payloadSchema: z.object({
    amplitude_g: z.number(),
    threshold_g: z.number(),
    machine: z.string(),
    location: z.string(),
  }),
  execute: async (payload, { agent, device }) => {
    const severity = payload.amplitude_g > payload.threshold_g * 1.5 ? 'CRITICAL' : 'WARNING';

    await agent.chat(
      `${severity} VIBRATION ALERT from ${device.name}: ` +
      `Machine "${payload.machine}" in ${payload.location} ` +
      `reading ${payload.amplitude_g}g (threshold: ${payload.threshold_g}g). ` +
      (severity === 'CRITICAL'
        ? 'This is significantly above threshold. Consider activating emergency stop.'
        : 'Monitor closely and schedule maintenance if readings persist.')
    );
  },
});
```

## Agent Configuration

```typescript theme={null}
// src/index.ts
import { LuaAgent, LuaSkill } from 'lua-cli';
import { vibrationAnomaly } from './triggers/vibration-anomaly';

const factorySkill = new LuaSkill({
  name: 'factory-monitoring',
  description: 'Industrial equipment monitoring and control',
  context: `
    You monitor factory equipment through connected sensors.

    Device tools:
    - read_vibration: Check machine vibration levels. Normal < 2.5g, warning < 3.0g, critical > 3.0g.
    - read_temperature: Check bearing temperature. Normal < 60C, warning < 80C, critical > 80C.
    - emergency_stop: CRITICAL COMMAND. Only use when explicitly requested or when readings indicate
      imminent equipment failure. Always confirm with the operator first unless automated shutdown
      is triggered.

    When receiving vibration anomaly triggers:
    1. Read the current vibration and temperature
    2. Assess combined risk
    3. Recommend maintenance or emergency stop based on severity
  `,
  tools: [],
});

export const agent = new LuaAgent({
  name: 'factory-monitor',
  persona: `You are a factory floor monitoring assistant. You help operators keep equipment
    running safely. Be precise with readings. Escalate critical situations immediately.
    Never hesitate to recommend an emergency stop if readings indicate danger.`,
  skills: [factorySkill],
  deviceTriggers: [vibrationAnomaly],
});
```

## Next Steps

<CardGroup>
  <Card title="Pico W Setup" icon="screwdriver-wrench" href="/devices/examples/raspberry-pi-pico">
    Step-by-step hardware setup guide
  </Card>

  <Card title="MicroPython Client" icon="microchip" href="/devices/micropython-client">
    Full MicroPython client reference
  </Card>

  <Card title="Warehouse Scanner" icon="warehouse" href="/devices/examples/warehouse-inventory">
    Node.js logistics example
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    How triggers flow from device to agent
  </Card>
</CardGroup>


# Mac Controller
Source: https://docs.heylua.ai/devices/examples/mac-controller

Control your MacBook remotely through your AI agent

## Overview

**Use case:** Personal computer automation via WhatsApp or web chat

Turn your Mac into an AI-controllable device. Ask your agent to take screenshots, open apps, search files, control music, manage your clipboard, and more -- all from a chat message.

**Commands:**

* `take_screenshot` -- Capture the screen and return the image
* `send_notification` -- Show a desktop notification
* `open_url` -- Open a URL in the default browser
* `open_app` -- Launch an application by name
* `search_files` -- Find files using Spotlight
* `get_active_app` -- Get the currently focused application
* `system_info` -- Hostname, CPU, memory, uptime, battery
* `get_clipboard` -- Read clipboard contents
* `set_clipboard` -- Write text to the clipboard
* `lock_screen` -- Lock the Mac
* `play_music` -- Play, pause, or skip tracks in Apple Music or Spotify
* `set_volume` -- Set the system volume (0--100)
* `run_shortcut` -- Run a Shortcuts.app shortcut by name

<Note>
  **Prerequisites:**

  * [Node.js](https://nodejs.org/) 18+ (for the Node.js client) or Python 3.10+ (for the Python client)
  * `terminal-notifier` for desktop notifications -- install with `brew install terminal-notifier`
  * Screen recording permission granted to your terminal app (for screenshots)
</Note>

For Node.js, [provision a device credential](/devices/credentials#provision-a-device-credential) with `commands` for the exact agent and device name in this example. The Python example uses `api_key` with an existing non-dotted legacy key. This key remains supported indefinitely.

## Device Client

<CodeGroup>
  ```typescript Node.js theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';
  import { execSync } from 'child_process';
  import { readFileSync, unlinkSync } from 'fs';
  import { tmpdir } from 'os';
  import { join } from 'path';

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'my-macbook',
    group: 'personal-devices',
    commands: [
      {
        name: 'take_screenshot',
        description: 'Capture a screenshot of the entire screen and return the image URL.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'send_notification',
        description: 'Show a macOS desktop notification.',
        inputSchema: {
          type: 'object',
          properties: {
            title: { type: 'string', description: 'Notification title' },
            message: { type: 'string', description: 'Notification body text' },
          },
          required: ['title', 'message'],
        },
      },
      {
        name: 'open_url',
        description: 'Open a URL in the default browser.',
        inputSchema: {
          type: 'object',
          properties: {
            url: { type: 'string', description: 'The URL to open' },
          },
          required: ['url'],
        },
      },
      {
        name: 'open_app',
        description: 'Launch an application by name (e.g., "Slack", "Safari", "Terminal").',
        inputSchema: {
          type: 'object',
          properties: {
            name: { type: 'string', description: 'Application name' },
          },
          required: ['name'],
        },
      },
      {
        name: 'search_files',
        description: 'Search for files by name using Spotlight (mdfind).',
        inputSchema: {
          type: 'object',
          properties: {
            query: { type: 'string', description: 'Filename or search term' },
            limit: { type: 'number', description: 'Max results (default 10)' },
          },
          required: ['query'],
        },
      },
      {
        name: 'get_active_app',
        description: 'Get the name of the currently focused application.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'system_info',
        description: 'Get system information: hostname, CPU, memory, uptime, and battery level.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'get_clipboard',
        description: 'Read the current clipboard text contents.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'set_clipboard',
        description: 'Set the clipboard text contents.',
        inputSchema: {
          type: 'object',
          properties: {
            text: { type: 'string', description: 'Text to copy to clipboard' },
          },
          required: ['text'],
        },
      },
      {
        name: 'lock_screen',
        description: 'Lock the Mac screen immediately.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'play_music',
        description: 'Control music playback: play, pause, or skip to next/previous track.',
        inputSchema: {
          type: 'object',
          properties: {
            action: {
              type: 'string',
              enum: ['play', 'pause', 'next', 'previous'],
              description: 'Playback action',
            },
            app: {
              type: 'string',
              enum: ['Music', 'Spotify'],
              description: 'Music app to control (default: Music)',
            },
          },
          required: ['action'],
        },
      },
      {
        name: 'set_volume',
        description: 'Set the system output volume.',
        inputSchema: {
          type: 'object',
          properties: {
            level: { type: 'number', minimum: 0, maximum: 100, description: 'Volume level 0-100' },
          },
          required: ['level'],
        },
      },
      {
        name: 'run_shortcut',
        description: 'Run a macOS Shortcuts.app shortcut by name.',
        inputSchema: {
          type: 'object',
          properties: {
            name: { type: 'string', description: 'Shortcut name' },
          },
          required: ['name'],
        },
      },
    ],
  });

  device.onCommand('take_screenshot', async () => {
    const filepath = join(tmpdir(), `screenshot-${Date.now()}.png`);
    execSync(`screencapture -x ${filepath}`);
    const buffer = readFileSync(filepath);
    const url = await device.uploadFile(buffer, `screenshot-${Date.now()}.png`, 'image/png');
    unlinkSync(filepath);
    return { imageUrl: url, timestamp: new Date().toISOString() };
  });

  device.onCommand('send_notification', async (payload) => {
    const title = payload.title.replace(/"/g, '\\"');
    const message = payload.message.replace(/"/g, '\\"');
    execSync(`terminal-notifier -title "${title}" -message "${message}"`);
    return { sent: true, title: payload.title, message: payload.message };
  });

  device.onCommand('open_url', async (payload) => {
    execSync(`open "${payload.url}"`);
    return { opened: true, url: payload.url };
  });

  device.onCommand('open_app', async (payload) => {
    execSync(`open -a "${payload.name}"`);
    return { opened: true, app: payload.name };
  });

  device.onCommand('search_files', async (payload) => {
    const limit = payload.limit || 10;
    const raw = execSync(`mdfind -name "${payload.query}" | head -${limit}`).toString().trim();
    const files = raw ? raw.split('\n') : [];
    return { query: payload.query, results: files, count: files.length };
  });

  device.onCommand('get_active_app', async () => {
    const script = 'tell application "System Events" to get name of first application process whose frontmost is true';
    const name = execSync(`osascript -e '${script}'`).toString().trim();
    return { activeApp: name };
  });

  device.onCommand('system_info', async () => {
    const hostname = execSync('hostname').toString().trim();
    const cpu = execSync('sysctl -n machdep.cpu.brand_string').toString().trim();
    const memBytes = parseInt(execSync('sysctl -n hw.memsize').toString().trim());
    const memGB = Math.round(memBytes / 1073741824);
    const uptime = execSync('uptime').toString().trim();
    let battery = 'N/A';
    try {
      battery = execSync('pmset -g batt | grep -o "[0-9]*%"').toString().trim();
    } catch {}
    return { hostname, cpu, memoryGB: memGB, uptime, battery };
  });

  device.onCommand('get_clipboard', async () => {
    const text = execSync('osascript -e "the clipboard"').toString().trim();
    return { clipboard: text };
  });

  device.onCommand('set_clipboard', async (payload) => {
    const escaped = payload.text.replace(/"/g, '\\"');
    execSync(`osascript -e 'set the clipboard to "${escaped}"'`);
    return { set: true, text: payload.text };
  });

  device.onCommand('lock_screen', async () => {
    execSync('pmset displaysleepnow');
    return { locked: true, timestamp: new Date().toISOString() };
  });

  device.onCommand('play_music', async (payload) => {
    const app = payload.app || 'Music';
    const actionMap: Record<string, string> = {
      play: 'play', pause: 'pause', next: 'next track', previous: 'previous track',
    };
    const command = actionMap[payload.action];
    execSync(`osascript -e 'tell application "${app}" to ${command}'`);
    return { action: payload.action, app };
  });

  device.onCommand('set_volume', async (payload) => {
    const vol = Math.round((payload.level / 100) * 7);
    execSync(`osascript -e 'set volume output volume ${payload.level}'`);
    return { volume: payload.level };
  });

  device.onCommand('run_shortcut', async (payload) => {
    execSync(`shortcuts run "${payload.name}"`);
    return { ran: true, shortcut: payload.name };
  });

  async function main() {
    await device.connect();
    console.log('Mac controller online');
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  import subprocess
  import tempfile
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition

  client = DeviceClient(
      agent_id=os.environ["LUA_AGENT_ID"],
      api_key=os.environ["LUA_API_KEY"],
      device_name="my-macbook",
      group="personal-devices",
      commands=[
          DeviceCommandDefinition(
              name="take_screenshot",
              description="Capture a screenshot of the entire screen and return the image URL.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="send_notification",
              description="Show a macOS desktop notification.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "title": {"type": "string", "description": "Notification title"},
                      "message": {"type": "string", "description": "Notification body text"},
                  },
                  "required": ["title", "message"],
              },
          ),
          DeviceCommandDefinition(
              name="open_url",
              description="Open a URL in the default browser.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "url": {"type": "string", "description": "The URL to open"},
                  },
                  "required": ["url"],
              },
          ),
          DeviceCommandDefinition(
              name="open_app",
              description="Launch an application by name (e.g., 'Slack', 'Safari', 'Terminal').",
              input_schema={
                  "type": "object",
                  "properties": {
                      "name": {"type": "string", "description": "Application name"},
                  },
                  "required": ["name"],
              },
          ),
          DeviceCommandDefinition(
              name="search_files",
              description="Search for files by name using Spotlight (mdfind).",
              input_schema={
                  "type": "object",
                  "properties": {
                      "query": {"type": "string", "description": "Filename or search term"},
                      "limit": {"type": "number", "description": "Max results (default 10)"},
                  },
                  "required": ["query"],
              },
          ),
          DeviceCommandDefinition(
              name="get_active_app",
              description="Get the name of the currently focused application.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="system_info",
              description="Get system information: hostname, CPU, memory, uptime, and battery level.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="get_clipboard",
              description="Read the current clipboard text contents.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="set_clipboard",
              description="Set the clipboard text contents.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "text": {"type": "string", "description": "Text to copy to clipboard"},
                  },
                  "required": ["text"],
              },
          ),
          DeviceCommandDefinition(
              name="lock_screen",
              description="Lock the Mac screen immediately.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="play_music",
              description="Control music playback: play, pause, or skip to next/previous track.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "action": {
                          "type": "string",
                          "enum": ["play", "pause", "next", "previous"],
                          "description": "Playback action",
                      },
                      "app": {
                          "type": "string",
                          "enum": ["Music", "Spotify"],
                          "description": "Music app to control (default: Music)",
                      },
                  },
                  "required": ["action"],
              },
          ),
          DeviceCommandDefinition(
              name="set_volume",
              description="Set the system output volume.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "level": {"type": "number", "minimum": 0, "maximum": 100, "description": "Volume level 0-100"},
                  },
                  "required": ["level"],
              },
          ),
          DeviceCommandDefinition(
              name="run_shortcut",
              description="Run a macOS Shortcuts.app shortcut by name.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "name": {"type": "string", "description": "Shortcut name"},
                  },
                  "required": ["name"],
              },
          ),
      ],
  )


  @client.on_command("take_screenshot")
  async def handle_take_screenshot(payload):
      filepath = os.path.join(tempfile.gettempdir(), f"screenshot-{int(datetime.now().timestamp())}.png")
      subprocess.run(["screencapture", "-x", filepath], check=True)
      with open(filepath, "rb") as f:
          buffer = f.read()
      url = await client.upload_file(buffer, f"screenshot-{int(datetime.now().timestamp())}.png", "image/png")
      os.unlink(filepath)
      return {"imageUrl": url, "timestamp": datetime.now(timezone.utc).isoformat()}


  @client.on_command("send_notification")
  async def handle_send_notification(payload):
      subprocess.run(
          ["terminal-notifier", "-title", payload["title"], "-message", payload["message"]],
          check=True,
      )
      return {"sent": True, "title": payload["title"], "message": payload["message"]}


  @client.on_command("open_url")
  async def handle_open_url(payload):
      subprocess.run(["open", payload["url"]], check=True)
      return {"opened": True, "url": payload["url"]}


  @client.on_command("open_app")
  async def handle_open_app(payload):
      subprocess.run(["open", "-a", payload["name"]], check=True)
      return {"opened": True, "app": payload["name"]}


  @client.on_command("search_files")
  async def handle_search_files(payload):
      limit = payload.get("limit", 10)
      result = subprocess.run(
          ["mdfind", "-name", payload["query"]],
          capture_output=True, text=True,
      )
      files = [f for f in result.stdout.strip().split("\n") if f][:limit]
      return {"query": payload["query"], "results": files, "count": len(files)}


  @client.on_command("get_active_app")
  async def handle_get_active_app(payload):
      script = 'tell application "System Events" to get name of first application process whose frontmost is true'
      result = subprocess.run(["osascript", "-e", script], capture_output=True, text=True)
      return {"activeApp": result.stdout.strip()}


  @client.on_command("system_info")
  async def handle_system_info(payload):
      hostname = subprocess.run(["hostname"], capture_output=True, text=True).stdout.strip()
      cpu = subprocess.run(["sysctl", "-n", "machdep.cpu.brand_string"], capture_output=True, text=True).stdout.strip()
      mem_bytes = int(subprocess.run(["sysctl", "-n", "hw.memsize"], capture_output=True, text=True).stdout.strip())
      mem_gb = round(mem_bytes / 1073741824)
      uptime = subprocess.run(["uptime"], capture_output=True, text=True).stdout.strip()
      try:
          batt = subprocess.run("pmset -g batt | grep -o '[0-9]*%'", shell=True, capture_output=True, text=True).stdout.strip()
      except Exception:
          batt = "N/A"
      return {"hostname": hostname, "cpu": cpu, "memoryGB": mem_gb, "uptime": uptime, "battery": batt or "N/A"}


  @client.on_command("get_clipboard")
  async def handle_get_clipboard(payload):
      result = subprocess.run(["osascript", "-e", "the clipboard"], capture_output=True, text=True)
      return {"clipboard": result.stdout.strip()}


  @client.on_command("set_clipboard")
  async def handle_set_clipboard(payload):
      escaped = payload["text"].replace('"', '\\"')
      subprocess.run(["osascript", "-e", f'set the clipboard to "{escaped}"'], check=True)
      return {"set": True, "text": payload["text"]}


  @client.on_command("lock_screen")
  async def handle_lock_screen(payload):
      subprocess.run(["pmset", "displaysleepnow"], check=True)
      return {"locked": True, "timestamp": datetime.now(timezone.utc).isoformat()}


  @client.on_command("play_music")
  async def handle_play_music(payload):
      app = payload.get("app", "Music")
      action_map = {"play": "play", "pause": "pause", "next": "next track", "previous": "previous track"}
      command = action_map[payload["action"]]
      subprocess.run(["osascript", "-e", f'tell application "{app}" to {command}'], check=True)
      return {"action": payload["action"], "app": app}


  @client.on_command("set_volume")
  async def handle_set_volume(payload):
      subprocess.run(["osascript", "-e", f'set volume output volume {payload["level"]}'], check=True)
      return {"volume": payload["level"]}


  @client.on_command("run_shortcut")
  async def handle_run_shortcut(payload):
      subprocess.run(["shortcuts", "run", payload["name"]], check=True)
      return {"ran": True, "shortcut": payload["name"]}


  async def main():
      await client.connect()
      print("Mac controller online")

  asyncio.run(main())
  ```
</CodeGroup>

## Agent Configuration

```typescript theme={null}
// src/index.ts
import { LuaAgent, LuaSkill } from 'lua-cli';

const macControlSkill = new LuaSkill({
  name: 'mac-controller',
  description: 'Control a MacBook remotely',
  context: `
    You are a personal assistant that controls a MacBook.
    You can take screenshots, open apps, search files, control music,
    manage clipboard, and more.

    Device tools:
    - take_screenshot: Captures the screen and returns an image URL.
    - send_notification: Shows a desktop notification with a title and message.
    - open_url: Opens a URL in the default browser.
    - open_app: Launches a Mac application by name.
    - search_files: Searches for files using Spotlight. Great for finding documents.
    - get_active_app: Reports which application is currently in the foreground.
    - system_info: Returns hostname, CPU, memory, uptime, and battery status.
    - get_clipboard: Reads the current clipboard text.
    - set_clipboard: Sets the clipboard to the provided text.
    - lock_screen: Locks the Mac immediately.
    - play_music: Controls Apple Music or Spotify (play, pause, next, previous).
    - set_volume: Sets the system volume from 0 to 100.
    - run_shortcut: Runs a Shortcuts.app shortcut by name.

    Guidelines:
    - When asked for a screenshot, take it and share the image URL
    - For file searches, show the full paths in the results
    - Confirm destructive actions (like locking the screen) before executing
    - Be conversational and helpful
  `,
  tools: [],
});

export const agent = new LuaAgent({
  name: 'mac-assistant',
  persona: `You are a personal assistant that controls a MacBook. You can take
    screenshots, open apps, search files, control music, manage the clipboard,
    and automate tasks. Be helpful, concise, and confirm before taking
    potentially disruptive actions like locking the screen.`,
  skills: [macControlSkill],
});
```

## What You Can Ask

Here are real conversational examples you can send from WhatsApp or web chat:

<CardGroup>
  <Card title="Screenshots" icon="camera">
    "Take a screenshot and send it to me"
  </Card>

  <Card title="Open Apps" icon="window-maximize">
    "Open Slack" / "Launch Safari"
  </Card>

  <Card title="File Search" icon="magnifying-glass">
    "Search for files called invoice.pdf"
  </Card>

  <Card title="Active App" icon="desktop">
    "What app am I currently using?"
  </Card>

  <Card title="Lock Screen" icon="lock">
    "Lock my Mac"
  </Card>

  <Card title="Volume" icon="volume-high">
    "Set the volume to 30%"
  </Card>

  <Card title="Music" icon="music">
    "Play the next song" / "Pause the music"
  </Card>

  <Card title="Clipboard" icon="clipboard">
    "Copy this text to my clipboard: Meeting at 3pm"
  </Card>

  <Card title="System Info" icon="microchip">
    "How much battery do I have left?"
  </Card>

  <Card title="Notifications" icon="bell">
    "Send me a notification that says Stand up and stretch"
  </Card>

  <Card title="Browser" icon="globe">
    "Open github.com in my browser"
  </Card>

  <Card title="Shortcuts" icon="bolt">
    "Run my Focus Mode shortcut"
  </Card>
</CardGroup>

<Warning>
  **Security note:** This device client gives your AI agent direct control over your computer. Only run it on machines you trust, and consider limiting which commands are registered based on your comfort level.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Windows Controller" icon="windows" href="/devices/examples/windows-controller">
    Control a Windows PC the same way
  </Card>

  <Card title="Smart Office" icon="building" href="/devices/examples/smart-office">
    Office automation with sensors and displays
  </Card>

  <Card title="CDN Uploads" icon="cloud-arrow-up" href="/devices/cdn-uploads">
    How screenshot uploads work
  </Card>

  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    How to write effective command definitions
  </Card>
</CardGroup>


# Raspberry Pi Pico W Setup
Source: https://docs.heylua.ai/devices/examples/raspberry-pi-pico

Step-by-step guide to running a Lua device on a Raspberry Pi Pico W

## Hardware List

| Item                    | Purpose                  | Notes                                 |
| ----------------------- | ------------------------ | ------------------------------------- |
| Raspberry Pi Pico W     | Main board               | Must be the **W** variant (with WiFi) |
| Micro-USB cable         | Power and programming    | Data-capable, not charge-only         |
| DHT22 sensor (optional) | Temperature and humidity | Connect to GP15 with 10k pull-up      |
| LED (optional)          | Status indicator         | Onboard LED works for basic use       |
| Breadboard + jumpers    | Wiring                   | For connecting sensors                |

## Setup with Thonny

<Steps>
  <Step title="Install Thonny IDE">
    Download [Thonny](https://thonny.org/) for your operating system. Thonny has built-in MicroPython support for the Pico W.
  </Step>

  <Step title="Flash MicroPython firmware">
    1. Hold the **BOOTSEL** button on the Pico W
    2. While holding, connect the USB cable to your computer
    3. Release BOOTSEL -- the Pico appears as a USB drive
    4. Download the latest `.uf2` firmware from [micropython.org/download/RPI\_PICO\_W](https://micropython.org/download/RPI_PICO_W/)
    5. Drag the `.uf2` file onto the Pico USB drive
    6. The Pico reboots automatically with MicroPython
  </Step>

  <Step title="Configure Thonny for Pico W">
    1. Open Thonny
    2. Go to **Tools > Options > Interpreter**
    3. Select **MicroPython (Raspberry Pi Pico)**
    4. Select the correct port (usually auto-detected)
    5. Click **OK**
    6. You should see the MicroPython REPL in the bottom panel
  </Step>

  <Step title="Upload the Lua device library">
    1. Open `lua_device.py` in Thonny
    2. Go to **File > Save as...**
    3. Select **Raspberry Pi Pico** as the target
    4. Save as `lua_device.py` on the Pico
  </Step>

  <Step title="Configure WiFi credentials">
    Create a `config.py` file on the Pico with your WiFi and Lua credentials:

    ```python theme={null}
    # config.py -- save this to the Pico
    WIFI_SSID = "YOUR_WIFI_NETWORK"
    WIFI_PASSWORD = "YOUR_WIFI_PASSWORD"
    LUA_AGENT_ID = "your-agent-id"
    LUA_API_KEY = "your-api-key"
    LUA_DEVICE_NAME = "pico-sensor"
    ```

    <Warning>
      Keep `config.py` on the Pico only. Do not commit WiFi passwords or API keys to version control. The current MicroPython client uses an existing non-dotted legacy key, which remains supported indefinitely.
    </Warning>
  </Step>

  <Step title="Create main.py">
    Create the main application file. This runs automatically when the Pico boots:

    ```python theme={null}
    # main.py -- save this to the Pico
    import network
    import machine
    import time
    import config

    # -- WiFi connection --
    led = machine.Pin("LED", machine.Pin.OUT)
    led.off()

    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    wlan.connect(config.WIFI_SSID, config.WIFI_PASSWORD)

    print("Connecting to WiFi...")
    timeout = 30
    while not wlan.isconnected() and timeout > 0:
        led.toggle()
        time.sleep(0.5)
        timeout -= 1

    if not wlan.isconnected():
        print("WiFi connection failed!")
        # Blink rapidly to indicate error
        for _ in range(20):
            led.toggle()
            time.sleep_ms(100)
        machine.reset()

    led.on()
    print("WiFi connected:", wlan.ifconfig()[0])

    # -- Optional: DHT22 sensor --
    try:
        import dht
        dht_sensor = dht.DHT22(machine.Pin(15))
        has_dht = True
        print("DHT22 sensor detected on GP15")
    except Exception:
        has_dht = False
        print("No DHT22 sensor -- using simulated values")

    # -- Device setup --
    from lua_device import LuaDevice

    device = LuaDevice(
        agent_id=config.LUA_AGENT_ID,
        api_key=config.LUA_API_KEY,
        device_name=config.LUA_DEVICE_NAME,
        server="mqtt.heylua.ai",
    )

    @device.command("led_on")
    def led_on(payload):
        led.on()
        return {"status": "on"}

    @device.command("led_off")
    def led_off(payload):
        led.off()
        return {"status": "off"}

    @device.command("blink")
    def blink(payload):
        count = payload.get("count", 3)
        for _ in range(count):
            led.on()
            time.sleep_ms(200)
            led.off()
            time.sleep_ms(200)
        led.on()  # leave on (connected state)
        return {"blinked": count}

    @device.command("read_environment")
    def read_environment(payload):
        if has_dht:
            dht_sensor.measure()
            return {
                "temperature": dht_sensor.temperature(),
                "humidity": dht_sensor.humidity(),
                "source": "DHT22",
            }
        else:
            return {
                "temperature": 22.0 + (time.ticks_ms() % 50) / 10,
                "humidity": 55 + (time.ticks_ms() % 200) / 10,
                "source": "simulated",
            }

    @device.command("system_info")
    def system_info(payload):
        import gc
        gc.collect()
        return {
            "free_memory": gc.mem_free(),
            "ip_address": wlan.ifconfig()[0],
            "rssi": wlan.status("rssi"),
            "uptime_ms": time.ticks_ms(),
        }

    # -- Connect and run --
    device.connect()
    print("Lua device connected -- listening for commands")

    device.run()
    ```
  </Step>

  <Step title="Run and test">
    1. Click the green **Run** button in Thonny (or press F5)
    2. You should see:
       ```
       Connecting to WiFi...
       WiFi connected: 192.168.1.42
       DHT22 sensor detected on GP15
       [lua-device] Connected as pico-sensor
       Lua device connected -- listening for commands
       [lua-device] Listening for commands...
       ```
    3. Open `lua chat` in your terminal and try:
       ```
       > Turn on the LED on pico-sensor
       > Read the environment from pico-sensor
       > Blink the LED 5 times
       > What's the system info on pico-sensor?
       ```
  </Step>
</Steps>

## File Structure on Pico

After setup, the Pico should have these files:

```
/
├── lua_device.py      # Lua device client library
├── config.py          # WiFi and API credentials
└── main.py            # Your application (runs on boot)
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pico does not appear as USB drive">
    * Make sure you are holding **BOOTSEL** before plugging in the USB cable
    * Try a different USB cable (some are charge-only, not data)
    * Try a different USB port on your computer
  </Accordion>

  <Accordion title="WiFi connection fails">
    * Pico W only supports 2.4 GHz WiFi (not 5 GHz)
    * Check SSID and password in `config.py` (case-sensitive)
    * Move the Pico closer to the router
    * Check `wlan.status()` for error codes: -1 = connection failed, -2 = no matching SSID, -3 = auth failed
  </Accordion>

  <Accordion title="MQTT connection fails">
    * Verify `agent_id`, `api_key`, and `device_name` in `config.py`
    * Check WiFi is connected first (`wlan.isconnected()`)
    * Ensure port 443 (WebSocket) is not blocked by your network
    * Try `device = LuaDevice(..., use_ssl=False)` temporarily for debugging
  </Accordion>

  <Accordion title="MemoryError during operation">
    * Add `import gc; gc.collect()` periodically in your code
    * Compile `lua_device.py` to bytecode: `mpy-cross lua_device.py`, then copy `lua_device.mpy`
    * Reduce payload sizes in command responses
    * Keep the dedup cache small (it auto-cleans at 100 entries)
  </Accordion>

  <Accordion title="Device connects but commands do not work">
    * Check the REPL output for error messages
    * Verify command names match between the handler and what the agent expects
    * Ensure `device.run()` is being called (it is the message processing loop)
    * Check that `device.connect()` completed without errors
  </Accordion>

  <Accordion title="DHT22 sensor not reading">
    * Check wiring: data pin to GP15, 10k pull-up resistor between data and 3.3V
    * DHT22 requires at least 2 seconds between readings
    * Try `dht_sensor.measure()` in the REPL first to verify
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="MicroPython Client" icon="microchip" href="/devices/micropython-client">
    Full LuaDevice class reference
  </Card>

  <Card title="Factory Monitor" icon="industry" href="/devices/examples/industrial-sensor">
    Industrial monitoring example on Pico W
  </Card>

  <Card title="MQTT Transport" icon="tower-broadcast" href="/devices/mqtt-client">
    MQTT topic structure and QoS details
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Send events from the Pico W to your agent
  </Card>
</CardGroup>


# Retail Kiosk
Source: https://docs.heylua.ai/devices/examples/retail-kiosk

Build an AI-powered retail kiosk with receipt printing, NFC, and customer help requests

## Overview

**Industry:** Retail

A customer-facing kiosk that prints receipts, reads NFC loyalty cards, displays messages on screen, and lets customers request help from the AI agent.

**Commands:**

* `print_receipt` -- Print a formatted receipt
* `read_nfc_card` -- Read an NFC loyalty card
* `display_message` -- Show a message on the kiosk screen

**Triggers:**

* `customer_help_requested` -- Fires when a customer presses the help button

For Node.js, [provision a device credential](/devices/credentials#provision-a-device-credential) with `commands` and `triggers` for the exact agent and device name in this example. The Python example uses `api_key` with an existing non-dotted legacy key. This key remains supported indefinitely.

## Device Client

<CodeGroup>
  ```typescript Node.js theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';

  // Simulated hardware interfaces
  const printer = {
    print: async (lines: string[]) => {
      console.log('--- RECEIPT ---');
      lines.forEach(l => console.log(l));
      console.log('--- END ---');
      return { printed: true, lineCount: lines.length };
    },
  };

  const nfc = {
    read: async () => ({
      cardId: 'NFC-8847-2024',
      memberName: 'Jane Smith',
      tier: 'Gold',
      points: 2450,
    }),
  };

  const display = {
    show: async (message: string, style: string) => {
      console.log(`[DISPLAY ${style}] ${message}`);
      return { displayed: true };
    },
  };

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'store-kiosk-01',
    group: 'retail-kiosks',
    commands: [
      {
        name: 'print_receipt',
        description: 'Print a receipt on the kiosk thermal printer. Provide an array of text lines to print.',
        inputSchema: {
          type: 'object',
          properties: {
            lines: {
              type: 'array',
              items: { type: 'string' },
              description: 'Array of text lines to print on the receipt',
            },
            header: { type: 'string', description: 'Store name or header text' },
            footer: { type: 'string', description: 'Footer text (e.g., return policy)' },
          },
          required: ['lines'],
        },
        timeoutMs: 15000,
      },
      {
        name: 'read_nfc_card',
        description: 'Activate the NFC reader and scan a loyalty card. Returns member name, tier, and points balance. Prompts the customer to tap their card.',
        timeoutMs: 30000,
      },
      {
        name: 'display_message',
        description: 'Show a message on the kiosk display screen',
        inputSchema: {
          type: 'object',
          properties: {
            message: { type: 'string', description: 'Message text to display' },
            style: { type: 'string', enum: ['welcome', 'info', 'success', 'error'], default: 'info' },
          },
          required: ['message'],
        },
      },
    ],
  });

  device.onCommand('print_receipt', async (payload) => {
    const lines: string[] = [];

    if (payload.header) {
      lines.push('================================');
      lines.push(`  ${payload.header}`);
      lines.push('================================');
    }

    lines.push('');
    lines.push(...(payload.lines || []));
    lines.push('');

    if (payload.footer) {
      lines.push('--------------------------------');
      lines.push(payload.footer);
    }

    lines.push(`  ${new Date().toLocaleString()}`);

    const result = await printer.print(lines);
    return { ...result, totalLines: lines.length };
  });

  device.onCommand('read_nfc_card', async () => {
    await display.show('Please tap your loyalty card...', 'info');
    const card = await nfc.read();
    await display.show(`Welcome back, ${card.memberName}!`, 'success');
    return card;
  });

  device.onCommand('display_message', async (payload) => {
    const result = await display.show(payload.message, payload.style || 'info');
    return { ...result, message: payload.message };
  });

  async function main() {
    await device.connect();
    console.log('Retail kiosk online');

    await display.show('Welcome! How can I help you today?', 'welcome');

    // Simulate a customer pressing the help button every few minutes
    setInterval(async () => {
      if (Math.random() < 0.1) {
        await device.trigger('customer_help_requested', {
          kiosk: 'store-kiosk-01',
          location: 'entrance',
          timestamp: new Date().toISOString(),
        });
      }
    }, 30000);
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  import random
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition

  # Simulated hardware interfaces
  async def printer_print(lines):
      print("--- RECEIPT ---")
      for line in lines:
          print(line)
      print("--- END ---")
      return {"printed": True, "lineCount": len(lines)}

  async def nfc_read():
      return {
          "cardId": "NFC-8847-2024",
          "memberName": "Jane Smith",
          "tier": "Gold",
          "points": 2450,
      }

  async def display_show(message, style):
      print(f"[DISPLAY {style}] {message}")
      return {"displayed": True}

  client = DeviceClient(
      agent_id=os.environ["LUA_AGENT_ID"],
      api_key=os.environ["LUA_API_KEY"],
      device_name="store-kiosk-01",
      group="retail-kiosks",
      commands=[
          DeviceCommandDefinition(
              name="print_receipt",
              description="Print a receipt on the kiosk thermal printer. Provide an array of text lines to print.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "lines": {
                          "type": "array",
                          "items": {"type": "string"},
                          "description": "Array of text lines to print on the receipt",
                      },
                      "header": {"type": "string", "description": "Store name or header text"},
                      "footer": {"type": "string", "description": "Footer text (e.g., return policy)"},
                  },
                  "required": ["lines"],
              },
              timeout_ms=15000,
          ),
          DeviceCommandDefinition(
              name="read_nfc_card",
              description="Activate the NFC reader and scan a loyalty card. Returns member name, tier, and points balance. Prompts the customer to tap their card.",
              timeout_ms=30000,
          ),
          DeviceCommandDefinition(
              name="display_message",
              description="Show a message on the kiosk display screen",
              input_schema={
                  "type": "object",
                  "properties": {
                      "message": {"type": "string", "description": "Message text to display"},
                      "style": {"type": "string", "enum": ["welcome", "info", "success", "error"], "default": "info"},
                  },
                  "required": ["message"],
              },
          ),
      ],
  )

  @client.on_command("print_receipt")
  async def handle_print_receipt(payload):
      lines = []

      if payload.get("header"):
          lines.append("================================")
          lines.append(f"  {payload['header']}")
          lines.append("================================")

      lines.append("")
      lines.extend(payload.get("lines", []))
      lines.append("")

      if payload.get("footer"):
          lines.append("--------------------------------")
          lines.append(payload["footer"])

      lines.append(f"  {datetime.now().strftime('%c')}")

      result = await printer_print(lines)
      return {**result, "totalLines": len(lines)}

  @client.on_command("read_nfc_card")
  async def handle_read_nfc_card(payload):
      await display_show("Please tap your loyalty card...", "info")
      card = await nfc_read()
      await display_show(f"Welcome back, {card['memberName']}!", "success")
      return card

  @client.on_command("display_message")
  async def handle_display_message(payload):
      result = await display_show(payload["message"], payload.get("style", "info"))
      return {**result, "message": payload["message"]}

  async def main():
      await client.connect()
      print("Retail kiosk online")

      await display_show("Welcome! How can I help you today?", "welcome")

      # Simulate a customer pressing the help button every few minutes
      while True:
          if random.random() < 0.1:
              await client.trigger("customer_help_requested", {
                  "kiosk": "store-kiosk-01",
                  "location": "entrance",
                  "timestamp": datetime.now(timezone.utc).isoformat(),
              })
          await asyncio.sleep(30)

  asyncio.run(main())
  ```
</CodeGroup>

## Agent-Side Trigger Handler

```typescript theme={null}
// src/triggers/customer-help.ts
import { defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';

export const customerHelp = defineDeviceTrigger({
  name: 'customer-help-requested',
  description: 'Fired when a customer presses the help button on a retail kiosk',
  payloadSchema: z.object({
    kiosk: z.string(),
    location: z.string(),
    timestamp: z.string(),
  }),
  execute: async (payload, { agent, device }) => {
    await agent.chat(
      `A customer at kiosk "${payload.kiosk}" (${payload.location}) ` +
      `is requesting help. Please display a helpful greeting and ` +
      `ask what they need assistance with.`
    );
  },
});
```

## Agent Configuration

```typescript theme={null}
// src/index.ts
import { LuaAgent, LuaSkill } from 'lua-cli';
import { customerHelp } from './triggers/customer-help';

const retailSkill = new LuaSkill({
  name: 'retail-kiosk',
  description: 'Retail kiosk customer service',
  context: `
    You operate customer-facing retail kiosks.

    Device tools:
    - print_receipt: Print receipts. Format nicely with header, items, and footer.
    - read_nfc_card: Scan loyalty cards. Use when customer wants to check points or redeem rewards.
    - display_message: Show messages on screen. Use 'welcome' for greetings, 'success' for confirmations.

    Guidelines:
    - Always greet customers warmly
    - After reading a loyalty card, mention their tier and points
    - Include store name in receipt headers
    - Add return policy in receipt footers
  `,
  tools: [],
});

export const agent = new LuaAgent({
  name: 'retail-assistant',
  persona: `You are a friendly retail assistant at a kiosk. Help customers check loyalty points,
    print receipts, and find information. Be warm, concise, and helpful.`,
  skills: [retailSkill],
  deviceTriggers: [customerHelp],
});
```

## Next Steps

<CardGroup>
  <Card title="CDN Uploads" icon="cloud-arrow-up" href="/devices/cdn-uploads">
    Upload screenshots and logs from kiosk devices
  </Card>

  <Card title="Smart Office" icon="building" href="/devices/examples/smart-office">
    Facilities management example
  </Card>

  <Card title="Warehouse Scanner" icon="warehouse" href="/devices/examples/warehouse-inventory">
    Logistics and inventory management
  </Card>

  <Card title="Agent Tools" icon="wrench" href="/devices/agent-tools">
    How device commands become agent tools
  </Card>
</CardGroup>


# Smart Office
Source: https://docs.heylua.ai/devices/examples/smart-office

Build an AI facilities concierge with meeting room sensors, thermostats, and desk occupancy

## Overview

**Industry:** Facilities Management

A smart office system where the AI agent acts as a facilities concierge. It checks meeting room availability, adjusts climate controls, monitors desk occupancy, and sends notifications to office displays.

**Commands:**

* `check_meeting_rooms` -- Query occupancy sensors in all meeting rooms
* `adjust_thermostat` -- Set target temperature for a zone
* `desk_occupancy` -- Get desk utilization for a floor
* `send_notification` -- Display a message on an office screen

For Node.js, [provision a device credential](/devices/credentials#provision-a-device-credential) with `commands` for the exact agent and device name in this example. The Python example uses `api_key` with an existing non-dotted legacy key. This key remains supported indefinitely.

## Device Client

<CodeGroup>
  ```typescript Node.js theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';

  // Simulated office hardware
  const meetingRooms = [
    { name: 'Atlas', floor: 3, capacity: 8, occupied: true, bookedUntil: '14:30' },
    { name: 'Everest', floor: 3, capacity: 12, occupied: false, bookedUntil: null },
    { name: 'Summit', floor: 4, capacity: 6, occupied: true, bookedUntil: '15:00' },
    { name: 'Pinnacle', floor: 4, capacity: 20, occupied: false, bookedUntil: null },
  ];

  const zones: Record<string, { currentTemp: number; targetTemp: number; mode: string }> = {
    'floor-3': { currentTemp: 23.2, targetTemp: 22, mode: 'cooling' },
    'floor-4': { currentTemp: 21.8, targetTemp: 22, mode: 'idle' },
  };

  const desks: Record<string, { total: number; occupied: number }> = {
    'floor-3': { total: 48, occupied: 31 },
    'floor-4': { total: 52, occupied: 18 },
  };

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'office-controller',
    group: 'building-systems',
    commands: [
      {
        name: 'check_meeting_rooms',
        description: 'Check availability and occupancy of all meeting rooms. Returns room name, floor, capacity, and whether currently occupied.',
        inputSchema: {
          type: 'object',
          properties: {
            floor: { type: 'number', description: 'Filter by floor number (optional)' },
            minCapacity: { type: 'number', description: 'Minimum room capacity (optional)' },
          },
        },
      },
      {
        name: 'adjust_thermostat',
        description: 'Adjust the target temperature for a building zone. Zones are identified by floor (e.g., floor-3, floor-4).',
        inputSchema: {
          type: 'object',
          properties: {
            zone: { type: 'string', description: 'Zone identifier (e.g., floor-3)' },
            targetTemperature: { type: 'number', minimum: 18, maximum: 28, description: 'Target temperature in celsius' },
          },
          required: ['zone', 'targetTemperature'],
        },
      },
      {
        name: 'desk_occupancy',
        description: 'Get desk occupancy statistics for a given floor. Returns total desks, occupied desks, and utilization percentage.',
        inputSchema: {
          type: 'object',
          properties: {
            floor: { type: 'number', description: 'Floor number to check' },
          },
          required: ['floor'],
        },
      },
      {
        name: 'send_notification',
        description: 'Display a notification message on the office lobby or floor display screens',
        inputSchema: {
          type: 'object',
          properties: {
            message: { type: 'string', description: 'Message text to display' },
            screen: { type: 'string', enum: ['lobby', 'floor-3', 'floor-4', 'all'], description: 'Target screen' },
            priority: { type: 'string', enum: ['info', 'warning', 'urgent'], default: 'info' },
          },
          required: ['message', 'screen'],
        },
      },
    ],
  });

  device.onCommand('check_meeting_rooms', async (payload) => {
    let rooms = meetingRooms;
    if (payload?.floor) {
      rooms = rooms.filter(r => r.floor === payload.floor);
    }
    if (payload?.minCapacity) {
      rooms = rooms.filter(r => r.capacity >= payload.minCapacity);
    }
    return {
      rooms: rooms.map(r => ({
        ...r,
        available: !r.occupied,
      })),
      timestamp: new Date().toISOString(),
    };
  });

  device.onCommand('adjust_thermostat', async (payload) => {
    const zone = zones[payload.zone];
    if (!zone) {
      throw new Error(`Unknown zone: ${payload.zone}`);
    }
    zone.targetTemp = payload.targetTemperature;
    zone.mode = zone.currentTemp > payload.targetTemperature ? 'cooling' : 'heating';
    return {
      zone: payload.zone,
      currentTemperature: zone.currentTemp,
      targetTemperature: zone.targetTemp,
      mode: zone.mode,
    };
  });

  device.onCommand('desk_occupancy', async (payload) => {
    const floorKey = `floor-${payload.floor}`;
    const floor = desks[floorKey];
    if (!floor) {
      throw new Error(`No data for floor ${payload.floor}`);
    }
    return {
      floor: payload.floor,
      totalDesks: floor.total,
      occupiedDesks: floor.occupied,
      availableDesks: floor.total - floor.occupied,
      utilization: Math.round((floor.occupied / floor.total) * 100),
    };
  });

  device.onCommand('send_notification', async (payload) => {
    console.log(`[DISPLAY ${payload.screen}] ${payload.priority?.toUpperCase() || 'INFO'}: ${payload.message}`);
    return {
      sent: true,
      screen: payload.screen,
      message: payload.message,
      timestamp: new Date().toISOString(),
    };
  });

  async function main() {
    await device.connect();
    console.log('Office controller online');
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition

  # Simulated office hardware
  meeting_rooms = [
      {"name": "Atlas", "floor": 3, "capacity": 8, "occupied": True, "bookedUntil": "14:30"},
      {"name": "Everest", "floor": 3, "capacity": 12, "occupied": False, "bookedUntil": None},
      {"name": "Summit", "floor": 4, "capacity": 6, "occupied": True, "bookedUntil": "15:00"},
      {"name": "Pinnacle", "floor": 4, "capacity": 20, "occupied": False, "bookedUntil": None},
  ]

  zones = {
      "floor-3": {"currentTemp": 23.2, "targetTemp": 22, "mode": "cooling"},
      "floor-4": {"currentTemp": 21.8, "targetTemp": 22, "mode": "idle"},
  }

  desks = {
      "floor-3": {"total": 48, "occupied": 31},
      "floor-4": {"total": 52, "occupied": 18},
  }

  client = DeviceClient(
      agent_id=os.environ["LUA_AGENT_ID"],
      api_key=os.environ["LUA_API_KEY"],
      device_name="office-controller",
      group="building-systems",
      commands=[
          DeviceCommandDefinition(
              name="check_meeting_rooms",
              description="Check availability and occupancy of all meeting rooms. Returns room name, floor, capacity, and whether currently occupied.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "floor": {"type": "number", "description": "Filter by floor number (optional)"},
                      "minCapacity": {"type": "number", "description": "Minimum room capacity (optional)"},
                  },
              },
          ),
          DeviceCommandDefinition(
              name="adjust_thermostat",
              description="Adjust the target temperature for a building zone. Zones are identified by floor (e.g., floor-3, floor-4).",
              input_schema={
                  "type": "object",
                  "properties": {
                      "zone": {"type": "string", "description": "Zone identifier (e.g., floor-3)"},
                      "targetTemperature": {"type": "number", "minimum": 18, "maximum": 28, "description": "Target temperature in celsius"},
                  },
                  "required": ["zone", "targetTemperature"],
              },
          ),
          DeviceCommandDefinition(
              name="desk_occupancy",
              description="Get desk occupancy statistics for a given floor. Returns total desks, occupied desks, and utilization percentage.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "floor": {"type": "number", "description": "Floor number to check"},
                  },
                  "required": ["floor"],
              },
          ),
          DeviceCommandDefinition(
              name="send_notification",
              description="Display a notification message on the office lobby or floor display screens",
              input_schema={
                  "type": "object",
                  "properties": {
                      "message": {"type": "string", "description": "Message text to display"},
                      "screen": {"type": "string", "enum": ["lobby", "floor-3", "floor-4", "all"], "description": "Target screen"},
                      "priority": {"type": "string", "enum": ["info", "warning", "urgent"], "default": "info"},
                  },
                  "required": ["message", "screen"],
              },
          ),
      ],
  )

  @client.on_command("check_meeting_rooms")
  async def handle_check_meeting_rooms(payload):
      rooms = meeting_rooms
      if payload and payload.get("floor"):
          rooms = [r for r in rooms if r["floor"] == payload["floor"]]
      if payload and payload.get("minCapacity"):
          rooms = [r for r in rooms if r["capacity"] >= payload["minCapacity"]]
      return {
          "rooms": [{**r, "available": not r["occupied"]} for r in rooms],
          "timestamp": datetime.now(timezone.utc).isoformat(),
      }

  @client.on_command("adjust_thermostat")
  async def handle_adjust_thermostat(payload):
      zone = zones.get(payload["zone"])
      if not zone:
          raise Exception(f"Unknown zone: {payload['zone']}")
      zone["targetTemp"] = payload["targetTemperature"]
      zone["mode"] = "cooling" if zone["currentTemp"] > payload["targetTemperature"] else "heating"
      return {
          "zone": payload["zone"],
          "currentTemperature": zone["currentTemp"],
          "targetTemperature": zone["targetTemp"],
          "mode": zone["mode"],
      }

  @client.on_command("desk_occupancy")
  async def handle_desk_occupancy(payload):
      floor_key = f"floor-{payload['floor']}"
      floor = desks.get(floor_key)
      if not floor:
          raise Exception(f"No data for floor {payload['floor']}")
      return {
          "floor": payload["floor"],
          "totalDesks": floor["total"],
          "occupiedDesks": floor["occupied"],
          "availableDesks": floor["total"] - floor["occupied"],
          "utilization": round((floor["occupied"] / floor["total"]) * 100),
      }

  @client.on_command("send_notification")
  async def handle_send_notification(payload):
      priority = (payload.get("priority") or "info").upper()
      print(f"[DISPLAY {payload['screen']}] {priority}: {payload['message']}")
      return {
          "sent": True,
          "screen": payload["screen"],
          "message": payload["message"],
          "timestamp": datetime.now(timezone.utc).isoformat(),
      }

  async def main():
      await client.connect()
      print("Office controller online")

  asyncio.run(main())
  ```
</CodeGroup>

## Agent Configuration

```typescript theme={null}
// src/index.ts
import { LuaAgent, LuaSkill } from 'lua-cli';

const facilitiesSkill = new LuaSkill({
  name: 'facilities-concierge',
  description: 'Smart office management',
  context: `
    You manage office facilities through connected devices.

    Device tools:
    - check_meeting_rooms: Use when someone needs a meeting room. Filter by floor or capacity.
    - adjust_thermostat: Use when someone reports temperature issues. Range: 18-28C.
    - desk_occupancy: Use to report floor utilization.
    - send_notification: Use to broadcast messages to office screens.

    Guidelines:
    - When someone needs a room, check availability and suggest the best match
    - For temperature complaints, check current temp first, then adjust
    - Only send urgent notifications for actual emergencies
    - Be friendly and helpful -- you are the office concierge
  `,
  tools: [],
});

export const agent = new LuaAgent({
  name: 'office-concierge',
  persona: `You are a friendly office concierge. You help employees find meeting rooms,
    manage comfort settings, and stay informed about office status. Be warm and helpful.`,
  skills: [facilitiesSkill],
});
```

## Next Steps

<CardGroup>
  <Card title="Warehouse Scanner" icon="warehouse" href="/devices/examples/warehouse-inventory">
    Logistics and inventory management
  </Card>

  <Card title="Industrial Sensor" icon="industry" href="/devices/examples/industrial-sensor">
    Factory monitoring on Pico W
  </Card>

  <Card title="Retail Kiosk" icon="store" href="/devices/examples/retail-kiosk">
    Customer-facing kiosk with NFC and receipts
  </Card>

  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    How to write effective command definitions
  </Card>
</CardGroup>


# Warehouse Scanner
Source: https://docs.heylua.ai/devices/examples/warehouse-inventory

Build an AI-powered warehouse inventory system with barcode scanners and weight sensors

## Overview

**Industry:** Logistics / Warehousing

A warehouse device that connects barcode scanners, weight scales, stock-level sensors, and gate controllers to an AI agent. The agent manages inventory, verifies shipments, and controls dock access through natural language.

**Commands:**

* `scan_barcode` -- Activate scanner, return barcode value
* `read_weight` -- Read current weight on the scale
* `check_stock_level` -- Query stock for a given SKU
* `open_gate` -- Open a dock gate

**Triggers:**

* `low_stock_alert` -- Fires when stock drops below reorder threshold

For Node.js, [provision a device credential](/devices/credentials#provision-a-device-credential) with `commands` and `triggers` for the exact agent and device name in this example. The Python example uses `api_key` with an existing non-dotted legacy key. This key remains supported indefinitely.

## Device Client

<CodeGroup>
  ```typescript Node.js theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';

  // Simulated hardware interfaces
  const scanner = { scan: async () => ({ value: 'SKU-2024-0847', format: 'CODE128' }) };
  const scale = { read: async () => ({ weight: 12.4, unit: 'kg' }) };
  const inventory: Record<string, { quantity: number; threshold: number; name: string }> = {
    'SKU-2024-0847': { quantity: 8, threshold: 10, name: 'Widget A' },
    'SKU-2024-0312': { quantity: 142, threshold: 20, name: 'Bracket B' },
    'SKU-2024-1100': { quantity: 3, threshold: 15, name: 'Sensor C' },
  };
  const gate = { open: async () => ({ opened: true }) };

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'warehouse-station-01',
    group: 'warehouse-floor',
    commands: [
      {
        name: 'scan_barcode',
        description: 'Activate the barcode scanner and return the scanned code. Takes 1-2 seconds. Returns barcode value and format.',
        timeoutMs: 10000,
      },
      {
        name: 'read_weight',
        description: 'Read the current weight on the shipping scale in kilograms',
      },
      {
        name: 'check_stock_level',
        description: 'Check current stock level for a given SKU',
        inputSchema: {
          type: 'object',
          properties: {
            sku: { type: 'string', description: 'Product SKU to check' },
          },
          required: ['sku'],
        },
      },
      {
        name: 'open_gate',
        description: 'Open the dock gate for incoming/outgoing shipments. Confirm with the user before opening.',
        inputSchema: {
          type: 'object',
          properties: {
            gate: { type: 'string', enum: ['dock-a', 'dock-b', 'dock-c'] },
          },
          required: ['gate'],
        },
        timeoutMs: 15000,
      },
    ],
  });

  device.onCommand('scan_barcode', async () => {
    const result = await scanner.scan();
    return { barcode: result.value, format: result.format, timestamp: new Date().toISOString() };
  });

  device.onCommand('read_weight', async () => {
    const result = await scale.read();
    return { weight: result.weight, unit: result.unit };
  });

  device.onCommand('check_stock_level', async (payload) => {
    const item = inventory[payload.sku];
    if (!item) {
      return { error: `Unknown SKU: ${payload.sku}`, found: false };
    }
    return {
      sku: payload.sku,
      name: item.name,
      quantity: item.quantity,
      threshold: item.threshold,
      status: item.quantity <= item.threshold ? 'low' : 'ok',
      found: true,
    };
  });

  device.onCommand('open_gate', async (payload) => {
    const result = await gate.open();
    return { gate: payload.gate, opened: result.opened, timestamp: new Date().toISOString() };
  });

  async function main() {
    await device.connect();
    console.log('Warehouse station online');

    // Monitor stock levels every 60 seconds
    setInterval(async () => {
      for (const [sku, item] of Object.entries(inventory)) {
        if (item.quantity <= item.threshold) {
          await device.trigger('low_stock_alert', {
            sku,
            name: item.name,
            currentQuantity: item.quantity,
            threshold: item.threshold,
          });
        }
      }
    }, 60000);
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition

  # Simulated hardware interfaces
  async def scan_barcode():
      return {"value": "SKU-2024-0847", "format": "CODE128"}

  async def read_scale():
      return {"weight": 12.4, "unit": "kg"}

  inventory = {
      "SKU-2024-0847": {"quantity": 8, "threshold": 10, "name": "Widget A"},
      "SKU-2024-0312": {"quantity": 142, "threshold": 20, "name": "Bracket B"},
      "SKU-2024-1100": {"quantity": 3, "threshold": 15, "name": "Sensor C"},
  }

  async def open_gate_hw():
      return {"opened": True}

  client = DeviceClient(
      agent_id=os.environ["LUA_AGENT_ID"],
      api_key=os.environ["LUA_API_KEY"],
      device_name="warehouse-station-01",
      group="warehouse-floor",
      commands=[
          DeviceCommandDefinition(
              name="scan_barcode",
              description="Activate the barcode scanner and return the scanned code. Takes 1-2 seconds. Returns barcode value and format.",
              timeout_ms=10000,
          ),
          DeviceCommandDefinition(
              name="read_weight",
              description="Read the current weight on the shipping scale in kilograms",
          ),
          DeviceCommandDefinition(
              name="check_stock_level",
              description="Check current stock level for a given SKU",
              input_schema={
                  "type": "object",
                  "properties": {
                      "sku": {"type": "string", "description": "Product SKU to check"},
                  },
                  "required": ["sku"],
              },
          ),
          DeviceCommandDefinition(
              name="open_gate",
              description="Open the dock gate for incoming/outgoing shipments. Confirm with the user before opening.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "gate": {"type": "string", "enum": ["dock-a", "dock-b", "dock-c"]},
                  },
                  "required": ["gate"],
              },
              timeout_ms=15000,
          ),
      ],
  )

  @client.on_command("scan_barcode")
  async def handle_scan_barcode(payload):
      result = await scan_barcode()
      return {"barcode": result["value"], "format": result["format"], "timestamp": datetime.now(timezone.utc).isoformat()}

  @client.on_command("read_weight")
  async def handle_read_weight(payload):
      result = await read_scale()
      return {"weight": result["weight"], "unit": result["unit"]}

  @client.on_command("check_stock_level")
  async def handle_check_stock_level(payload):
      item = inventory.get(payload["sku"])
      if not item:
          return {"error": f"Unknown SKU: {payload['sku']}", "found": False}
      return {
          "sku": payload["sku"],
          "name": item["name"],
          "quantity": item["quantity"],
          "threshold": item["threshold"],
          "status": "low" if item["quantity"] <= item["threshold"] else "ok",
          "found": True,
      }

  @client.on_command("open_gate")
  async def handle_open_gate(payload):
      result = await open_gate_hw()
      return {"gate": payload["gate"], "opened": result["opened"], "timestamp": datetime.now(timezone.utc).isoformat()}

  async def main():
      await client.connect()
      print("Warehouse station online")

      # Monitor stock levels every 60 seconds
      while True:
          for sku, item in inventory.items():
              if item["quantity"] <= item["threshold"]:
                  await client.trigger("low_stock_alert", {
                      "sku": sku,
                      "name": item["name"],
                      "currentQuantity": item["quantity"],
                      "threshold": item["threshold"],
                  })
          await asyncio.sleep(60)

  asyncio.run(main())
  ```
</CodeGroup>

## Agent-Side Trigger Handler

```typescript theme={null}
// src/triggers/low-stock-alert.ts
import { defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';

export const lowStockAlert = defineDeviceTrigger({
  name: 'low-stock-alert',
  description: 'Fired when warehouse stock for an item drops below its reorder threshold',
  payloadSchema: z.object({
    sku: z.string(),
    name: z.string(),
    currentQuantity: z.number(),
    threshold: z.number(),
  }),
  execute: async (payload, { agent, device }) => {
    await agent.chat(
      `LOW STOCK ALERT from ${device.name}: ` +
      `"${payload.name}" (${payload.sku}) is at ${payload.currentQuantity} units, ` +
      `below the reorder threshold of ${payload.threshold}. ` +
      `Please create a purchase order to restock.`
    );
  },
});
```

## Agent Configuration

```typescript theme={null}
// src/index.ts
import { LuaAgent, LuaSkill } from 'lua-cli';
import { lowStockAlert } from './triggers/low-stock-alert';

const warehouseSkill = new LuaSkill({
  name: 'warehouse-operations',
  description: 'Warehouse inventory and shipping tools',
  context: `
    This skill works with warehouse floor devices.

    Device tools (available when devices are connected):
    - scan_barcode: Use when a worker asks to scan or identify an item
    - read_weight: Use when verifying shipment weights
    - check_stock_level: Use when checking inventory for a SKU
    - open_gate: Use when a shipment needs dock access. ALWAYS confirm with the user first.

    Guidelines:
    - After scanning a barcode, automatically check its stock level
    - Compare shipment weights against expected values when available
    - Never open a gate without explicit user confirmation
  `,
  tools: [],
});

export const agent = new LuaAgent({
  name: 'warehouse-agent',
  persona: `You are a warehouse operations assistant. You help workers manage inventory,
    verify shipments, and control dock access. Be concise and action-oriented.
    If a device is offline, tell the worker and suggest they check the connection.`,
  skills: [warehouseSkill],
  deviceTriggers: [lowStockAlert],
});
```

## Next Steps

<CardGroup>
  <Card title="Smart Office" icon="building" href="/devices/examples/smart-office">
    Facilities management example
  </Card>

  <Card title="Industrial Sensor" icon="industry" href="/devices/examples/industrial-sensor">
    Factory monitoring on Pico W
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Deep dive into trigger architecture
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Full client reference
  </Card>
</CardGroup>


# Windows Controller
Source: https://docs.heylua.ai/devices/examples/windows-controller

Control your Windows PC remotely through your AI agent

## Overview

**Use case:** Personal computer automation via WhatsApp or web chat

Turn your Windows PC into an AI-controllable device. Ask your agent to take screenshots, open apps, search files, manage processes, control volume, and more -- all from a chat message.

**Commands:**

* `take_screenshot` -- Capture the screen and return the image
* `send_notification` -- Show a toast notification
* `open_url` -- Open a URL in the default browser
* `open_app` -- Launch an application
* `search_files` -- Find files by name
* `get_active_window` -- Get the current foreground window title
* `system_info` -- Hostname, OS, CPU, RAM, uptime, battery
* `get_clipboard` -- Read clipboard contents
* `set_clipboard` -- Write text to the clipboard
* `lock_screen` -- Lock the PC
* `set_volume` -- Set the system volume (0--100)
* `list_processes` -- List running processes with CPU usage
* `kill_process` -- Kill a process by name

<Note>
  **Prerequisites:**

  * [Node.js](https://nodejs.org/) 18+ (for the Node.js client) or Python 3.10+ (for the Python client)
  * PowerShell 5.1+ (included with Windows 10/11)
  * Optional: [BurntToast](https://github.com/Windos/BurntToast) PowerShell module for richer toast notifications (`Install-Module -Name BurntToast`)
  * Optional: [nircmd](https://www.nirsoft.net/utils/nircmd.html) for volume control (alternative to PowerShell)
</Note>

For Node.js, [provision a device credential](/devices/credentials#provision-a-device-credential) with `commands` for the exact agent and device name in this example. The Python example uses `api_key` with an existing non-dotted legacy key. This key remains supported indefinitely.

## Device Client

<CodeGroup>
  ```typescript Node.js theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';
  import { execSync } from 'child_process';
  import { readFileSync, unlinkSync } from 'fs';
  import { tmpdir } from 'os';
  import { join } from 'path';

  // Helper to run PowerShell commands
  function ps(command: string): string {
    return execSync(`powershell -NoProfile -Command "${command.replace(/"/g, '\\"')}"`)
      .toString()
      .trim();
  }

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'my-windows-pc',
    group: 'personal-devices',
    commands: [
      {
        name: 'take_screenshot',
        description: 'Capture a screenshot of the entire screen and return the image URL.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'send_notification',
        description: 'Show a Windows toast notification.',
        inputSchema: {
          type: 'object',
          properties: {
            title: { type: 'string', description: 'Notification title' },
            message: { type: 'string', description: 'Notification body text' },
          },
          required: ['title', 'message'],
        },
      },
      {
        name: 'open_url',
        description: 'Open a URL in the default browser.',
        inputSchema: {
          type: 'object',
          properties: {
            url: { type: 'string', description: 'The URL to open' },
          },
          required: ['url'],
        },
      },
      {
        name: 'open_app',
        description: 'Launch an application by name or path (e.g., "notepad", "calc", "C:\\Program Files\\App\\app.exe").',
        inputSchema: {
          type: 'object',
          properties: {
            name: { type: 'string', description: 'Application name or path' },
          },
          required: ['name'],
        },
      },
      {
        name: 'search_files',
        description: 'Search for files by name. Searches common locations (Desktop, Documents, Downloads).',
        inputSchema: {
          type: 'object',
          properties: {
            query: { type: 'string', description: 'Filename or wildcard pattern (e.g., "invoice.pdf", "*.xlsx")' },
            path: { type: 'string', description: 'Directory to search (default: user home)' },
            limit: { type: 'number', description: 'Max results (default 10)' },
          },
          required: ['query'],
        },
      },
      {
        name: 'get_active_window',
        description: 'Get the title of the currently focused window.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'system_info',
        description: 'Get system information: hostname, OS version, CPU, RAM, uptime, and battery level.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'get_clipboard',
        description: 'Read the current clipboard text contents.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'set_clipboard',
        description: 'Set the clipboard text contents.',
        inputSchema: {
          type: 'object',
          properties: {
            text: { type: 'string', description: 'Text to copy to clipboard' },
          },
          required: ['text'],
        },
      },
      {
        name: 'lock_screen',
        description: 'Lock the Windows PC immediately.',
        inputSchema: { type: 'object', properties: {} },
      },
      {
        name: 'set_volume',
        description: 'Set the system output volume.',
        inputSchema: {
          type: 'object',
          properties: {
            level: { type: 'number', minimum: 0, maximum: 100, description: 'Volume level 0-100' },
          },
          required: ['level'],
        },
      },
      {
        name: 'list_processes',
        description: 'List running processes sorted by CPU usage.',
        inputSchema: {
          type: 'object',
          properties: {
            limit: { type: 'number', description: 'Max number of processes to return (default 10)' },
          },
        },
      },
      {
        name: 'kill_process',
        description: 'Kill a running process by name.',
        inputSchema: {
          type: 'object',
          properties: {
            name: { type: 'string', description: 'Process name (e.g., "notepad", "chrome")' },
          },
          required: ['name'],
        },
      },
    ],
  });

  device.onCommand('take_screenshot', async () => {
    const filepath = join(tmpdir(), `screenshot-${Date.now()}.png`);
    ps(`
      Add-Type -AssemblyName System.Windows.Forms;
      Add-Type -AssemblyName System.Drawing;
      $screen = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds;
      $bitmap = New-Object System.Drawing.Bitmap($screen.Width, $screen.Height);
      $graphics = [System.Drawing.Graphics]::FromImage($bitmap);
      $graphics.CopyFromScreen($screen.Location, [System.Drawing.Point]::Empty, $screen.Size);
      $bitmap.Save('${filepath.replace(/\\/g, '\\\\')}');
      $graphics.Dispose();
      $bitmap.Dispose()
    `);
    const buffer = readFileSync(filepath);
    const url = await device.uploadFile(buffer, `screenshot-${Date.now()}.png`, 'image/png');
    unlinkSync(filepath);
    return { imageUrl: url, timestamp: new Date().toISOString() };
  });

  device.onCommand('send_notification', async (payload) => {
    const title = payload.title.replace(/'/g, "''");
    const message = payload.message.replace(/'/g, "''");
    try {
      ps(`New-BurntToastNotification -Text '${title}', '${message}'`);
    } catch {
      // Fallback if BurntToast is not installed
      ps(`
        [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null;
        $xml = '<toast><visual><binding template="ToastText02"><text id="1">${title}</text><text id="2">${message}</text></binding></visual></toast>';
        $toast = [Windows.UI.Notifications.ToastNotification]::new([Windows.Data.Xml.Dom.XmlDocument]::new());
        $toast.Content.LoadXml($xml);
        [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Lua Agent').Show($toast)
      `);
    }
    return { sent: true, title: payload.title, message: payload.message };
  });

  device.onCommand('open_url', async (payload) => {
    execSync(`start "" "${payload.url}"`);
    return { opened: true, url: payload.url };
  });

  device.onCommand('open_app', async (payload) => {
    ps(`Start-Process '${payload.name}'`);
    return { opened: true, app: payload.name };
  });

  device.onCommand('search_files', async (payload) => {
    const limit = payload.limit || 10;
    const searchPath = payload.path || '$env:USERPROFILE';
    const raw = ps(`
      Get-ChildItem -Path ${searchPath} -Recurse -Filter '${payload.query}' -ErrorAction SilentlyContinue |
      Select-Object -First ${limit} -ExpandProperty FullName
    `);
    const files = raw ? raw.split('\r\n').filter(Boolean) : [];
    return { query: payload.query, results: files, count: files.length };
  });

  device.onCommand('get_active_window', async () => {
    const title = ps(`
      Add-Type -Name Win32 -Namespace Native -MemberDefinition '[DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow(); [DllImport("user32.dll", CharSet = CharSet.Auto)] public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder lpString, int nMaxCount);';
      $sb = New-Object System.Text.StringBuilder(256);
      [Native.Win32]::GetWindowText([Native.Win32]::GetForegroundWindow(), $sb, 256) | Out-Null;
      $sb.ToString()
    `);
    return { activeWindow: title };
  });

  device.onCommand('system_info', async () => {
    const info = ps(`
      $os = Get-CimInstance Win32_OperatingSystem;
      $cpu = (Get-CimInstance Win32_Processor).Name;
      $ramGB = [math]::Round($os.TotalVisibleMemorySize / 1MB, 1);
      $uptime = (Get-Date) - $os.LastBootUpTime;
      $battery = (Get-CimInstance Win32_Battery -ErrorAction SilentlyContinue).EstimatedChargeRemaining;
      @{
        hostname = $env:COMPUTERNAME;
        os = $os.Caption;
        cpu = $cpu;
        memoryGB = $ramGB;
        uptime = '{0}d {1}h {2}m' -f $uptime.Days, $uptime.Hours, $uptime.Minutes;
        battery = if ($battery) { "$battery%" } else { 'N/A (desktop)' }
      } | ConvertTo-Json
    `);
    return JSON.parse(info);
  });

  device.onCommand('get_clipboard', async () => {
    const text = ps('Get-Clipboard');
    return { clipboard: text };
  });

  device.onCommand('set_clipboard', async (payload) => {
    const escaped = payload.text.replace(/'/g, "''");
    ps(`Set-Clipboard -Value '${escaped}'`);
    return { set: true, text: payload.text };
  });

  device.onCommand('lock_screen', async () => {
    execSync('rundll32.exe user32.dll,LockWorkStation');
    return { locked: true, timestamp: new Date().toISOString() };
  });

  device.onCommand('set_volume', async (payload) => {
    ps(`
      $wsh = New-Object -ComObject WScript.Shell;
      1..50 | ForEach-Object { $wsh.SendKeys([char]174) };
      $steps = [math]::Round(${payload.level} / 2);
      1..$steps | ForEach-Object { $wsh.SendKeys([char]175) }
    `);
    return { volume: payload.level };
  });

  device.onCommand('list_processes', async (payload) => {
    const limit = payload?.limit || 10;
    const raw = ps(`
      Get-Process | Sort-Object CPU -Descending |
      Select-Object -First ${limit} Name, Id, @{N='CPU_Seconds';E={[math]::Round($_.CPU,1)}}, @{N='Memory_MB';E={[math]::Round($_.WorkingSet64/1MB,1)}} |
      ConvertTo-Json
    `);
    return { processes: JSON.parse(raw) };
  });

  device.onCommand('kill_process', async (payload) => {
    const name = payload.name.replace(/'/g, "''");
    ps(`Stop-Process -Name '${name}' -Force -ErrorAction SilentlyContinue`);
    return { killed: true, process: payload.name };
  });

  async function main() {
    await device.connect();
    console.log('Windows controller online');
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import json
  import os
  import subprocess
  import tempfile
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition


  def ps(command: str) -> str:
      """Run a PowerShell command and return its output."""
      result = subprocess.run(
          ["powershell", "-NoProfile", "-Command", command],
          capture_output=True, text=True,
      )
      return result.stdout.strip()


  client = DeviceClient(
      agent_id=os.environ["LUA_AGENT_ID"],
      api_key=os.environ["LUA_API_KEY"],
      device_name="my-windows-pc",
      group="personal-devices",
      commands=[
          DeviceCommandDefinition(
              name="take_screenshot",
              description="Capture a screenshot of the entire screen and return the image URL.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="send_notification",
              description="Show a Windows toast notification.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "title": {"type": "string", "description": "Notification title"},
                      "message": {"type": "string", "description": "Notification body text"},
                  },
                  "required": ["title", "message"],
              },
          ),
          DeviceCommandDefinition(
              name="open_url",
              description="Open a URL in the default browser.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "url": {"type": "string", "description": "The URL to open"},
                  },
                  "required": ["url"],
              },
          ),
          DeviceCommandDefinition(
              name="open_app",
              description="Launch an application by name or path (e.g., 'notepad', 'calc').",
              input_schema={
                  "type": "object",
                  "properties": {
                      "name": {"type": "string", "description": "Application name or path"},
                  },
                  "required": ["name"],
              },
          ),
          DeviceCommandDefinition(
              name="search_files",
              description="Search for files by name. Searches common locations (Desktop, Documents, Downloads).",
              input_schema={
                  "type": "object",
                  "properties": {
                      "query": {"type": "string", "description": "Filename or wildcard pattern (e.g., 'invoice.pdf', '*.xlsx')"},
                      "path": {"type": "string", "description": "Directory to search (default: user home)"},
                      "limit": {"type": "number", "description": "Max results (default 10)"},
                  },
                  "required": ["query"],
              },
          ),
          DeviceCommandDefinition(
              name="get_active_window",
              description="Get the title of the currently focused window.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="system_info",
              description="Get system information: hostname, OS version, CPU, RAM, uptime, and battery level.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="get_clipboard",
              description="Read the current clipboard text contents.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="set_clipboard",
              description="Set the clipboard text contents.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "text": {"type": "string", "description": "Text to copy to clipboard"},
                  },
                  "required": ["text"],
              },
          ),
          DeviceCommandDefinition(
              name="lock_screen",
              description="Lock the Windows PC immediately.",
              input_schema={"type": "object", "properties": {}},
          ),
          DeviceCommandDefinition(
              name="set_volume",
              description="Set the system output volume.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "level": {"type": "number", "minimum": 0, "maximum": 100, "description": "Volume level 0-100"},
                  },
                  "required": ["level"],
              },
          ),
          DeviceCommandDefinition(
              name="list_processes",
              description="List running processes sorted by CPU usage.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "limit": {"type": "number", "description": "Max number of processes to return (default 10)"},
                  },
              },
          ),
          DeviceCommandDefinition(
              name="kill_process",
              description="Kill a running process by name.",
              input_schema={
                  "type": "object",
                  "properties": {
                      "name": {"type": "string", "description": "Process name (e.g., 'notepad', 'chrome')"},
                  },
                  "required": ["name"],
              },
          ),
      ],
  )


  @client.on_command("take_screenshot")
  async def handle_take_screenshot(payload):
      filepath = os.path.join(tempfile.gettempdir(), f"screenshot-{int(datetime.now().timestamp())}.png")
      ps(f"""
          Add-Type -AssemblyName System.Windows.Forms;
          Add-Type -AssemblyName System.Drawing;
          $screen = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds;
          $bitmap = New-Object System.Drawing.Bitmap($screen.Width, $screen.Height);
          $graphics = [System.Drawing.Graphics]::FromImage($bitmap);
          $graphics.CopyFromScreen($screen.Location, [System.Drawing.Point]::Empty, $screen.Size);
          $bitmap.Save('{filepath}');
          $graphics.Dispose();
          $bitmap.Dispose()
      """)
      with open(filepath, "rb") as f:
          buffer = f.read()
      url = await client.upload_file(buffer, f"screenshot-{int(datetime.now().timestamp())}.png", "image/png")
      os.unlink(filepath)
      return {"imageUrl": url, "timestamp": datetime.now(timezone.utc).isoformat()}


  @client.on_command("send_notification")
  async def handle_send_notification(payload):
      title = payload["title"].replace("'", "''")
      message = payload["message"].replace("'", "''")
      try:
          ps(f"New-BurntToastNotification -Text '{title}', '{message}'")
      except Exception:
          ps(f"""
              [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null;
              $xml = '<toast><visual><binding template="ToastText02"><text id="1">{title}</text><text id="2">{message}</text></binding></visual></toast>';
              $toast = [Windows.UI.Notifications.ToastNotification]::new([Windows.Data.Xml.Dom.XmlDocument]::new());
              $toast.Content.LoadXml($xml);
              [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Lua Agent').Show($toast)
          """)
      return {"sent": True, "title": payload["title"], "message": payload["message"]}


  @client.on_command("open_url")
  async def handle_open_url(payload):
      subprocess.run(["start", "", payload["url"]], shell=True, check=True)
      return {"opened": True, "url": payload["url"]}


  @client.on_command("open_app")
  async def handle_open_app(payload):
      ps(f"Start-Process '{payload['name']}'")
      return {"opened": True, "app": payload["name"]}


  @client.on_command("search_files")
  async def handle_search_files(payload):
      limit = payload.get("limit", 10)
      search_path = payload.get("path", "$env:USERPROFILE")
      query = payload["query"].replace("'", "''")
      raw = ps(f"""
          Get-ChildItem -Path {search_path} -Recurse -Filter '{query}' -ErrorAction SilentlyContinue |
          Select-Object -First {limit} -ExpandProperty FullName
      """)
      files = [f for f in raw.split("\r\n") if f] if raw else []
      return {"query": payload["query"], "results": files, "count": len(files)}


  @client.on_command("get_active_window")
  async def handle_get_active_window(payload):
      title = ps("""
          Add-Type -Name Win32 -Namespace Native -MemberDefinition '[DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow(); [DllImport("user32.dll", CharSet = CharSet.Auto)] public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder lpString, int nMaxCount);';
          $sb = New-Object System.Text.StringBuilder(256);
          [Native.Win32]::GetWindowText([Native.Win32]::GetForegroundWindow(), $sb, 256) | Out-Null;
          $sb.ToString()
      """)
      return {"activeWindow": title}


  @client.on_command("system_info")
  async def handle_system_info(payload):
      raw = ps("""
          $os = Get-CimInstance Win32_OperatingSystem;
          $cpu = (Get-CimInstance Win32_Processor).Name;
          $ramGB = [math]::Round($os.TotalVisibleMemorySize / 1MB, 1);
          $uptime = (Get-Date) - $os.LastBootUpTime;
          $battery = (Get-CimInstance Win32_Battery -ErrorAction SilentlyContinue).EstimatedChargeRemaining;
          @{
              hostname = $env:COMPUTERNAME;
              os = $os.Caption;
              cpu = $cpu;
              memoryGB = $ramGB;
              uptime = '{0}d {1}h {2}m' -f $uptime.Days, $uptime.Hours, $uptime.Minutes;
              battery = if ($battery) { "$battery%" } else { 'N/A (desktop)' }
          } | ConvertTo-Json
      """)
      return json.loads(raw)


  @client.on_command("get_clipboard")
  async def handle_get_clipboard(payload):
      text = ps("Get-Clipboard")
      return {"clipboard": text}


  @client.on_command("set_clipboard")
  async def handle_set_clipboard(payload):
      escaped = payload["text"].replace("'", "''")
      ps(f"Set-Clipboard -Value '{escaped}'")
      return {"set": True, "text": payload["text"]}


  @client.on_command("lock_screen")
  async def handle_lock_screen(payload):
      subprocess.run(["rundll32.exe", "user32.dll,LockWorkStation"], check=True)
      return {"locked": True, "timestamp": datetime.now(timezone.utc).isoformat()}


  @client.on_command("set_volume")
  async def handle_set_volume(payload):
      ps(f"""
          $wsh = New-Object -ComObject WScript.Shell;
          1..50 | ForEach-Object {{ $wsh.SendKeys([char]174) }};
          $steps = [math]::Round({payload['level']} / 2);
          1..$steps | ForEach-Object {{ $wsh.SendKeys([char]175) }}
      """)
      return {"volume": payload["level"]}


  @client.on_command("list_processes")
  async def handle_list_processes(payload):
      limit = payload.get("limit", 10) if payload else 10
      raw = ps(f"""
          Get-Process | Sort-Object CPU -Descending |
          Select-Object -First {limit} Name, Id, @{{N='CPU_Seconds';E={{[math]::Round($_.CPU,1)}}}}, @{{N='Memory_MB';E={{[math]::Round($_.WorkingSet64/1MB,1)}}}} |
          ConvertTo-Json
      """)
      return {"processes": json.loads(raw)}


  @client.on_command("kill_process")
  async def handle_kill_process(payload):
      name = payload["name"].replace("'", "''")
      ps(f"Stop-Process -Name '{name}' -Force -ErrorAction SilentlyContinue")
      return {"killed": True, "process": payload["name"]}


  async def main():
      await client.connect()
      print("Windows controller online")

  asyncio.run(main())
  ```
</CodeGroup>

## Agent Configuration

```typescript theme={null}
// src/index.ts
import { LuaAgent, LuaSkill } from 'lua-cli';

const windowsControlSkill = new LuaSkill({
  name: 'windows-controller',
  description: 'Control a Windows PC remotely',
  context: `
    You are a personal assistant that controls a Windows PC.
    You can take screenshots, open apps, search files, manage processes,
    control volume, and more.

    Device tools:
    - take_screenshot: Captures the screen and returns an image URL.
    - send_notification: Shows a Windows toast notification with a title and message.
    - open_url: Opens a URL in the default browser.
    - open_app: Launches an application by name or path.
    - search_files: Searches for files by name across user directories.
    - get_active_window: Reports the title of the currently focused window.
    - system_info: Returns hostname, OS, CPU, RAM, uptime, and battery status.
    - get_clipboard: Reads the current clipboard text.
    - set_clipboard: Sets the clipboard to the provided text.
    - lock_screen: Locks the PC immediately.
    - set_volume: Sets the system volume from 0 to 100.
    - list_processes: Lists running processes sorted by CPU usage.
    - kill_process: Kills a process by name. Use with caution.

    Guidelines:
    - When asked for a screenshot, take it and share the image URL
    - For file searches, show the full paths in the results
    - Confirm destructive actions (locking the screen, killing processes) before executing
    - Be conversational and helpful
  `,
  tools: [],
});

export const agent = new LuaAgent({
  name: 'windows-assistant',
  persona: `You are a personal assistant that controls a Windows PC. You can take
    screenshots, open apps, search files, manage processes, control volume,
    and automate tasks. Be helpful, concise, and confirm before taking
    potentially disruptive actions like locking the screen or killing processes.`,
  skills: [windowsControlSkill],
});
```

## What You Can Ask

Here are real conversational examples you can send from WhatsApp or web chat:

<CardGroup>
  <Card title="Screenshots" icon="camera">
    "Take a screenshot and send it to me"
  </Card>

  <Card title="Open Apps" icon="window-maximize">
    "Open Notepad" / "Launch Excel"
  </Card>

  <Card title="File Search" icon="magnifying-glass">
    "Search for files called invoice.pdf"
  </Card>

  <Card title="Active Window" icon="desktop">
    "What window do I have open right now?"
  </Card>

  <Card title="Lock Screen" icon="lock">
    "Lock my PC"
  </Card>

  <Card title="Volume" icon="volume-high">
    "Set the volume to 30%"
  </Card>

  <Card title="Processes" icon="microchip">
    "What processes are using the most CPU?"
  </Card>

  <Card title="Kill Process" icon="xmark">
    "Kill the Notepad process"
  </Card>

  <Card title="Clipboard" icon="clipboard">
    "Copy this text to my clipboard: Meeting at 3pm"
  </Card>

  <Card title="Notifications" icon="bell">
    "Send me a notification that says Stand up and stretch"
  </Card>

  <Card title="Browser" icon="globe">
    "Open github.com in my browser"
  </Card>

  <Card title="System Info" icon="computer">
    "How much RAM do I have? What's my uptime?"
  </Card>
</CardGroup>

<Warning>
  **Security note:** This device client gives your AI agent direct control over your computer. Only run it on machines you trust, and consider limiting which commands are registered based on your comfort level.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Mac Controller" icon="apple" href="/devices/examples/mac-controller">
    Control a Mac the same way
  </Card>

  <Card title="Smart Office" icon="building" href="/devices/examples/smart-office">
    Office automation with sensors and displays
  </Card>

  <Card title="CDN Uploads" icon="cloud-arrow-up" href="/devices/cdn-uploads">
    How screenshot uploads work
  </Card>

  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    How to write effective command definitions
  </Card>
</CardGroup>


# How It Works
Source: https://docs.heylua.ai/devices/how-it-works

Architecture of the Lua Device Gateway

## Architecture Overview

The Device Gateway sits between your physical devices and the Lua agent runtime. It handles authentication, connection management, command routing, and trigger delivery.

```mermaid theme={null}
graph LR
    subgraph Devices
        D1["🖥️ Node.js Device<br/>(Socket.IO)"]
        D2["📡 Pico W / IoT<br/>(MQTT)"]
    end

    subgraph Lua Platform
        GW["🔌 Device Gateway<br/>Auth · Routing · Heartbeat"]
        AG["🤖 AI Agent<br/>Skills · Tools · Triggers"]
    end

    subgraph Users
        U1["💬 WhatsApp"]
        U2["🌐 Web Chat"]
    end

    D1 <-->|WebSocket| GW
    D2 <-->|MQTT| GW
    GW <-->|Commands & Responses| AG
    AG <-->|Conversation| U1
    AG <-->|Conversation| U2
```

## Self-Describing Flow

When a device connects, it does not need any server-side configuration. The device tells the gateway what it can do, and the gateway tells the agent.

<Steps>
  <Step title="Device connects with command manifest">
    The device client sends its `commands` array during the Socket.IO auth handshake or MQTT online status message. Each command includes a name, description, and optional JSON Schema for input parameters.
  </Step>

  <Step title="Gateway registers device">
    The gateway validates the device credential, its exact agent and device binding, and the permitted operations. It then registers the device and stores the permitted command manifest.
  </Step>

  <Step title="Agent discovers tools">
    When the agent processes a user message, it queries connected devices and merges their commands into the tool list. Each device command appears as a tool named `device__{deviceName}__{commandName}`.
  </Step>

  <Step title="Device disconnects, tools disappear">
    When a device goes offline (intentional disconnect, network loss, or missed heartbeats), its tools are removed from the agent. No stale tools remain.
  </Step>
</Steps>

## Command Delivery Path

When the agent decides to use a device tool, the command flows through the gateway:

```mermaid theme={null}
sequenceDiagram
    participant User as 💬 User
    participant Agent as 🤖 Agent
    participant GW as 🔌 Gateway
    participant Device as 📡 Device

    User->>Agent: "Read the temperature"
    Agent->>Agent: Selects tool: device__pico_sensor__read_temperature
    Agent->>GW: Send command (commandId, payload)
    GW->>Device: Deliver command via WebSocket/MQTT
    Device->>Device: Execute handler
    Device->>GW: Return response
    GW->>Agent: Deliver response
    Agent->>User: "The temperature is 23.5°C"
```

Each command carries a unique `commandId` for idempotency. If the device receives the same command twice (due to retry or redelivery), it returns the cached response.

## Trigger Flow

Triggers go in the opposite direction — from device to agent:

```mermaid theme={null}
sequenceDiagram
    participant Device as 📡 Device
    participant GW as 🔌 Gateway
    participant Agent as 🤖 Agent
    participant User as 💬 User

    Device->>Device: Detects temperature > 40°C
    Device->>GW: trigger('high_temp', { temperature: 42.1 })
    GW->>Device: ACK (triggerId, received: true)
    GW->>Agent: Deliver trigger to handler
    Agent->>Agent: Runs defineDeviceTrigger execute()
    Agent->>User: "⚠️ Temperature alert: 42.1°C!"
```

<Note>
  Triggers are **fire-and-forget** from the device's perspective. The device gets an acknowledgment that the gateway received the trigger, but does not wait for the agent to finish processing it.
</Note>

## Transport Comparison

| Feature          | Socket.IO                  | MQTT                                              |
| ---------------- | -------------------------- | ------------------------------------------------- |
| Protocol         | WebSocket over HTTPS       | MQTT 3.1.1 over TLS                               |
| Default URL      | `https://api.heylua.ai`    | `wss://mqtt.heylua.ai/mqtt`                       |
| Reconnection     | Built-in with jitter       | Built-in with backoff                             |
| Message ordering | Guaranteed (single socket) | Guaranteed per topic (QoS 1)                      |
| Offline queueing | No                         | Yes (persistent session)                          |
| Last Will (LWT)  | Not applicable             | Automatic offline status on disconnect            |
| Best for         | Node.js, desktops, servers | Microcontrollers, battery devices, flaky networks |
| RAM footprint    | \~10 MB (Node.js)          | \~30 KB (MicroPython on Pico W)                   |

## Security Model

<CardGroup>
  <Card title="Bound device credentials" icon="key">
    New installations use a credential bound to one agent, one device name, and selected device operations. Existing non-dotted legacy keys remain supported indefinitely.
  </Card>

  <Card title="Agent Scoping" icon="shield-halved">
    A device can only interact with the agent it authenticates against. Cross-agent communication is not possible.
  </Card>

  <Card title="TLS Encryption" icon="lock">
    All transports use TLS. Socket.IO connects over HTTPS. MQTT connects over port 443 (WebSocket) with TLS.
  </Card>

  <Card title="Heartbeat Monitoring" icon="heart-pulse">
    The gateway expects a heartbeat every 30 seconds. Missed heartbeats trigger disconnect detection. MQTT additionally uses Last Will and Testament (LWT) for instant offline notification.
  </Card>
</CardGroup>

## Connection Lifecycle

<Tabs>
  <Tab title="Socket.IO">
    ```
    1. Client opens WebSocket to https://api.heylua.ai/devices
    2. Auth handshake: { apiKey: deviceCredential, agentId, deviceName, commands[] }
    3. Server validates the credential binding and permitted operations, then emits 'connected'
    4. Client starts heartbeat (every 30s)
    5. Bidirectional command/trigger exchange
    6. On disconnect: auto-reconnect with jittered exponential backoff
    7. On reconnect: re-sends auth (commands may have changed)
    8. On SIGTERM/SIGINT: graceful disconnect, no reconnect
    ```
  </Tab>

  <Tab title="MQTT">
    ```
    1. Client connects to wss://mqtt.heylua.ai/mqtt
       - username: {agentId}:{deviceName}
       - password: {deviceCredential}
       - LWT: offline status (retained)
    2. Client subscribes to: command, connected, trigger_ack, error
    3. Client publishes online status (retained, no secrets)
    4. Client publishes commands without the typed credential (non-retained)
    5. Client starts heartbeat (every 30s)
    6. Bidirectional command/trigger exchange via topics
    7. On disconnect: broker publishes LWT, server detects offline
    8. On reconnect: re-subscribe, re-publish online status
    ```
  </Tab>
</Tabs>

The Socket.IO `auth.apiKey` property and MQTT password remain the protocol fields for both device credentials and existing legacy keys. The Node.js client uses `deviceCredential` for new provisioning. Published Python and MicroPython clients continue to use `api_key` with existing legacy keys. See [Device credentials](/devices/credentials).

## Next Steps

<CardGroup>
  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    Deep dive into how devices declare their capabilities
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Understand device-to-agent event flow
  </Card>

  <Card title="MQTT Transport" icon="tower-broadcast" href="/devices/mqtt-client">
    Configure MQTT for constrained devices
  </Card>

  <Card title="Agent Tools" icon="wrench" href="/devices/agent-tools">
    How device commands become agent tools
  </Card>
</CardGroup>


# MicroPython Client
Source: https://docs.heylua.ai/devices/micropython-client

Connect a Raspberry Pi Pico W or any MicroPython board to your Lua agent

## Overview

The MicroPython client (`lua_device.py`) runs on microcontrollers with as little as 264KB of RAM. It uses MQTT natively and supports the full device protocol: commands, triggers, heartbeats, reconnection, and idempotency dedup.

## Hardware Requirements

| Component   | Minimum             | Recommended                     |
| ----------- | ------------------- | ------------------------------- |
| Board       | Raspberry Pi Pico W | Any MicroPython board with WiFi |
| RAM         | 264 KB              | 512 KB+                         |
| Flash       | 2 MB                | 2 MB                            |
| MicroPython | v1.20+              | Latest stable                   |
| Network     | WiFi (2.4 GHz)      | WiFi with stable connection     |

<Note>
  The client depends on `umqtt.robust` (preferred) or `umqtt.simple`, both included in standard MicroPython firmware for the Pico W.
</Note>

## Setup

<Note>
  The current MicroPython distribution uses `api_key` with an existing non-dotted legacy key. This configuration remains supported indefinitely. The client does not expose the typed `device_credential` option.
</Note>

<Steps>
  <Step title="Flash MicroPython firmware">
    Download the latest MicroPython UF2 from [micropython.org](https://micropython.org/download/RPI_PICO_W/) and flash it to your Pico W.
  </Step>

  <Step title="Copy the client library">
    Copy `lua_device.py` to your Pico W. You can use Thonny, `mpremote`, or `rshell`:

    ```bash theme={null}
    mpremote cp lua_device.py :lua_device.py
    ```
  </Step>

  <Step title="Connect to WiFi">
    Create a `main.py` that connects to WiFi before creating the device:

    ```python theme={null}
    import network
    import time

    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    wlan.connect("YOUR_SSID", "YOUR_PASSWORD")

    while not wlan.isconnected():
        time.sleep(0.5)

    print("WiFi connected:", wlan.ifconfig()[0])
    ```
  </Step>

  <Step title="Create your device">
    Add the device setup after WiFi connection:

    ```python theme={null}
    from lua_device import LuaDevice

    device = LuaDevice(
        agent_id="your-agent-id",
        api_key="your-api-key",
        device_name="pico-sensor",
        server="mqtt.heylua.ai",
    )
    ```
  </Step>

  <Step title="Register commands and run">
    Register command handlers and start the main loop:

    ```python theme={null}
    @device.command("read_sensor")
    def read_sensor(payload):
        return {"temperature": 22.5, "humidity": 60}

    device.connect()
    device.run()  # blocks forever, handles commands
    ```
  </Step>
</Steps>

## LuaDevice Class Reference

### Constructor

Create the client with keyword arguments. Replace each placeholder value:

```python theme={null}
LuaDevice(
    agent_id="your-agent-id",
    api_key="your-api-key",
    device_name="your-device-name",
    server="mqtt.heylua.ai",
    port=443,
    group=None,
    use_ssl=True,
)
```

| Parameter     | Type | Default  | Description                                            |
| ------------- | ---- | -------- | ------------------------------------------------------ |
| `agent_id`    | str  | required | Agent ID to connect to                                 |
| `api_key`     | str  | required | Existing non-dotted legacy key, supported indefinitely |
| `device_name` | str  | required | Unique name for this device                            |
| `server`      | str  | required | MQTT broker hostname (e.g., `mqtt.heylua.ai`)          |
| `port`        | int  | `443`    | MQTT broker port                                       |
| `group`       | str  | `None`   | Optional device group name                             |
| `use_ssl`     | bool | `True`   | Enable TLS encryption                                  |

### Methods

| Method                        | Description                                                          |
| ----------------------------- | -------------------------------------------------------------------- |
| `connect()`                   | Connect to the MQTT broker. Sets up LWT and subscriptions.           |
| `disconnect()`                | Gracefully disconnect. Publishes offline status first.               |
| `run(check_interval_ms=100)`  | Main loop. Blocks forever, checks for messages and sends heartbeats. |
| `trigger(name, payload=None)` | Fire a trigger event to the agent.                                   |
| `on_command(name, handler)`   | Register a command handler (non-decorator style).                    |

### The `@device.command` Decorator

The preferred way to register command handlers:

```python theme={null}
@device.command("led_on")
def led_on(payload):
    # payload is a dict with whatever the agent sent
    pin = machine.Pin("LED", machine.Pin.OUT)
    pin.on()
    return {"status": "on"}
```

The handler receives a `payload` dict and must return a dict (or `None`). If the handler raises an exception, the error message is sent back to the agent.

## Complete Example: LED + DHT22

A Pico W that controls an onboard LED and reads a DHT22 temperature/humidity sensor:

```python theme={null}
import network
import machine
import time
import dht

# -- WiFi --
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("YOUR_SSID", "YOUR_PASSWORD")

while not wlan.isconnected():
    time.sleep(0.5)

print("WiFi connected:", wlan.ifconfig()[0])

# -- Sensor setup --
led = machine.Pin("LED", machine.Pin.OUT)
dht_sensor = dht.DHT22(machine.Pin(15))

# -- Device --
from lua_device import LuaDevice

device = LuaDevice(
    agent_id="your-agent-id",
    api_key="your-api-key",
    device_name="pico-env-sensor",
    server="mqtt.heylua.ai",
    group="office-sensors",
)

@device.command("led_on")
def led_on(payload):
    led.on()
    return {"status": "on"}

@device.command("led_off")
def led_off(payload):
    led.off()
    return {"status": "off"}

@device.command("read_environment")
def read_environment(payload):
    dht_sensor.measure()
    return {
        "temperature": dht_sensor.temperature(),
        "humidity": dht_sensor.humidity(),
        "led": "on" if led.value() else "off",
    }

@device.command("blink")
def blink(payload):
    count = payload.get("count", 3)
    delay = payload.get("delay_ms", 200)
    for _ in range(count):
        led.on()
        time.sleep_ms(delay)
        led.off()
        time.sleep_ms(delay)
    return {"blinked": count}

# -- Connect and run --
device.connect()

# Optional: fire a trigger every 60s if temperature is high
last_check = time.time()

while True:
    try:
        device._client.check_msg()

        now = time.time()
        if now - device._last_heartbeat >= device._heartbeat_interval:
            device._client.publish(device._topic_prefix + "heartbeat", b"", qos=0)
            device._last_heartbeat = now

        # Periodic temperature check
        if now - last_check >= 60:
            dht_sensor.measure()
            temp = dht_sensor.temperature()
            if temp > 30:
                device.trigger("high_temperature", {
                    "temperature": temp,
                    "threshold": 30,
                })
            last_check = now

        time.sleep_ms(100)

    except OSError as e:
        print("Connection lost:", e)
        device._reconnect()
    except Exception as e:
        print("Error:", e)
        time.sleep(1)
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="OSError: [Errno 110] ETIMEDOUT">
    The Pico W cannot reach the MQTT broker. Check:

    * WiFi is connected (`wlan.isconnected()` returns `True`)
    * DNS resolution works (try `socket.getaddrinfo("mqtt.heylua.ai", 443)`)
    * No firewall blocking port 443 (WebSocket)
  </Accordion>

  <Accordion title="MQTTException: 5 (Not authorized)">
    Authentication failed. Verify:

    * `agent_id` matches your agent exactly
    * `api_key` is valid and not expired
    * `device_name` is 1–200 characters and contains no whitespace, `/`, `+`, or `#`
  </Accordion>

  <Accordion title="MemoryError or device freezes">
    The Pico W has limited RAM. Try:

    * Reduce `_dedup_ttl` (default 300 seconds) if you are processing many commands
    * Avoid large payloads in command responses
    * Use `gc.collect()` periodically in your main loop
    * Compile `lua_device.py` to `.mpy` bytecode with `mpy-cross` to save RAM
  </Accordion>

  <Accordion title="Commands not received">
    Ensure:

    * `device.connect()` completed without error
    * You are calling `device.run()` or manually calling `device._client.check_msg()` in a loop
    * The command name in your handler matches the name the agent is using
  </Accordion>

  <Accordion title="SSL handshake fails">
    Some MicroPython builds have limited TLS support. Try:

    * Update to the latest MicroPython firmware
    * Set `use_ssl=False` temporarily for debugging (not recommended in production)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Pico W Setup Guide" icon="screwdriver-wrench" href="/devices/examples/raspberry-pi-pico">
    Step-by-step hardware setup with photos and wiring
  </Card>

  <Card title="Industrial Sensor Example" icon="industry" href="/devices/examples/industrial-sensor">
    Complete factory monitoring example on Pico W
  </Card>

  <Card title="MQTT Transport" icon="tower-broadcast" href="/devices/mqtt-client">
    MQTT topic structure and QoS details
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Send events from your device to the agent
  </Card>
</CardGroup>


# MQTT Transport
Source: https://docs.heylua.ai/devices/mqtt-client

Configure MQTT for constrained devices and unreliable networks

## When to Use MQTT

Use MQTT instead of the default Socket.IO transport when:

* Your device has limited RAM (microcontrollers, Pico W)
* The network connection is unreliable or intermittent
* You need offline message queueing (commands delivered when the device reconnects)
* You are already running an MQTT infrastructure
* The device is battery-powered and needs a lightweight protocol

<Note>
  The Lua Device Gateway runs an MQTT broker at `wss://mqtt.heylua.ai/mqtt`. You do not need to run your own broker.
</Note>

## Configuration

For a new Node.js installation, [provision a device credential](/devices/credentials#provision-a-device-credential) for the exact agent, device name, and operations that the device uses. The published Python 1.3.0 client and the current MicroPython distribution continue to use `api_key` with existing legacy keys.

### Node.js

```typescript theme={null}
import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: 'your-agent-id',
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  deviceName: 'pico-sensor-01',
  transport: 'mqtt',
  mqttUrl: 'wss://mqtt.heylua.ai/mqtt', // default, can be omitted
  commands: [
    { name: 'read_sensor', description: 'Read temperature and humidity' },
  ],
});

device.onCommand('read_sensor', async () => {
  return { temperature: 22.5, humidity: 60 };
});

await device.connect();
```

### Python

```python theme={null}
import asyncio
import os
from lua_device import DeviceClient, DeviceCommandDefinition

client = DeviceClient(
    agent_id="your-agent-id",
    api_key=os.environ["LUA_API_KEY"],
    device_name="pico-sensor-01",
    transport="mqtt",
    mqtt_url="wss://mqtt.heylua.ai/mqtt",  # default, can be omitted
    commands=[
        DeviceCommandDefinition(name="read_sensor", description="Read temperature and humidity"),
    ],
)

@client.on_command("read_sensor")
async def handle_read_sensor(payload):
    return {"temperature": 22.5, "humidity": 60}

asyncio.run(client.connect())
```

### MicroPython

```python theme={null}
from lua_device import LuaDevice

device = LuaDevice(
    agent_id="your-agent-id",
    api_key="your-api-key",
    device_name="pico-sensor-01",
    server="mqtt.heylua.ai",
    port=443,
)

@device.command("read_sensor")
def read_sensor(payload):
    return {"temperature": 22.5, "humidity": 60}

device.connect()
device.run()  # blocks, listens for commands
```

## Topic Structure

All MQTT topics follow a consistent prefix pattern:

```
lua/devices/{agentId}/{deviceName}/{suffix}
```

| Topic Suffix     | Direction        | QoS | Retained | Purpose                                                 |
| ---------------- | ---------------- | --- | -------- | ------------------------------------------------------- |
| `status`         | Device publish   | 1   | Yes      | Online/offline status (retained for broker persistence) |
| `heartbeat`      | Device publish   | 0   | No       | Keepalive signal every 30 seconds                       |
| `response`       | Device publish   | 1   | No       | Command execution results                               |
| `trigger`        | Device publish   | 1   | No       | Device-to-agent event triggers                          |
| `command`        | Device subscribe | 1   | No       | Incoming commands from the agent                        |
| `connected`      | Device subscribe | 1   | No       | Server connection confirmation                          |
| `trigger_ack`    | Device subscribe | 1   | No       | Trigger receipt acknowledgment                          |
| `trigger_result` | Device subscribe | 1   | No       | Trigger execution results (optional)                    |
| `error`          | Device subscribe | 1   | No       | Server-side error messages                              |
| `pong`           | Device subscribe | 0   | No       | Heartbeat response                                      |

## Last Will and Testament (LWT)

The MQTT client automatically sets a Last Will and Testament message on the `status` topic. If the device disconnects unexpectedly (network failure, power loss), the broker publishes the LWT message, which the gateway uses to immediately mark the device as offline.

```json theme={null}
{
  "status": "offline",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```

This is more reliable than heartbeat-based detection alone, since the broker publishes the LWT within seconds of losing the TCP connection.

## QoS Levels

| QoS | Meaning                             | Used For                                                  |
| --- | ----------------------------------- | --------------------------------------------------------- |
| 0   | At most once (fire-and-forget)      | Heartbeats -- acceptable to miss one                      |
| 1   | At least once (with acknowledgment) | Commands, responses, triggers, status -- must not be lost |

The device client uses QoS 1 for all messages except heartbeats. Combined with persistent sessions (`clean: false`), this means commands are queued by the broker when the device is temporarily offline and delivered when it reconnects.

<Warning>
  The idempotency dedup layer on the device (LRU cache of recent `commandId` values) ensures that redelivered QoS 1 messages do not cause duplicate command execution.
</Warning>

## Authentication

MQTT authentication uses the `username` and `password` fields of the MQTT CONNECT packet:

| Field      | Value                                                                                                       |
| ---------- | ----------------------------------------------------------------------------------------------------------- |
| `clientId` | `lua-{agentId}-{deviceName}`                                                                                |
| `username` | `{agentId}:{deviceName}`                                                                                    |
| `password` | Node.js/custom clients: device credential. Published Python/MicroPython clients: existing legacy `api_key`. |

For a typed device credential, the CONNECT password is the only MQTT message that contains the secret. The client sends its command manifest in a separate non-retained status message without the credential. Retained status messages never contain a secret.

Existing clients that use a non-dotted legacy key keep their current behavior. They send the key as the CONNECT password and in the existing non-retained `apiKey` status field. See [Device credentials](/devices/credentials#preserve-existing-installations).

## Complete Example

A humidity and temperature monitor that fires an alert trigger when conditions are out of range:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'greenhouse-sensor',
    transport: 'mqtt',
    group: 'greenhouse-sensors',
    commands: [
      {
        name: 'read_environment',
        description: 'Read temperature, humidity, and soil moisture',
      },
      {
        name: 'toggle_irrigation',
        description: 'Turn irrigation on or off',
        inputSchema: {
          type: 'object',
          properties: {
            enabled: { type: 'boolean' },
          },
          required: ['enabled'],
        },
      },
    ],
  });

  let irrigationOn = false;

  device.onCommand('read_environment', async () => {
    return {
      temperature: 28.3,
      humidity: 65,
      soilMoisture: 42,
      irrigationOn,
      timestamp: new Date().toISOString(),
    };
  });

  device.onCommand('toggle_irrigation', async (payload) => {
    irrigationOn = payload.enabled;
    return { irrigationOn };
  });

  async function main() {
    device.on('connected', () => console.log('Sensor online (MQTT)'));
    device.on('reconnected', () => console.log('Sensor reconnected'));
    device.on('error', (err) => console.error('MQTT error:', err));

    await device.connect();

    // Periodically check conditions and fire triggers
    setInterval(async () => {
      const humidity = 65 + Math.random() * 20;
      if (humidity > 80) {
        await device.trigger('humidity_alert', {
          humidity: Math.round(humidity),
          threshold: 80,
          sensor: 'greenhouse-sensor',
        });
      }
    }, 10000);
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  import random
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition

  irrigation_on = False

  client = DeviceClient(
      agent_id=os.environ["LUA_AGENT_ID"],
      api_key=os.environ["LUA_API_KEY"],
      device_name="greenhouse-sensor",
      transport="mqtt",
      group="greenhouse-sensors",
      commands=[
          DeviceCommandDefinition(
              name="read_environment",
              description="Read temperature, humidity, and soil moisture",
          ),
          DeviceCommandDefinition(
              name="toggle_irrigation",
              description="Turn irrigation on or off",
              input_schema={
                  "type": "object",
                  "properties": {
                      "enabled": {"type": "boolean"},
                  },
                  "required": ["enabled"],
              },
          ),
      ],
  )

  @client.on_command("read_environment")
  async def handle_read_environment(payload):
      return {
          "temperature": 28.3,
          "humidity": 65,
          "soilMoisture": 42,
          "irrigationOn": irrigation_on,
          "timestamp": datetime.now(timezone.utc).isoformat(),
      }

  @client.on_command("toggle_irrigation")
  async def handle_toggle_irrigation(payload):
      global irrigation_on
      irrigation_on = payload["enabled"]
      return {"irrigationOn": irrigation_on}

  async def main():
      await client.connect()
      print("Sensor online (MQTT)")

      # Periodically check conditions and fire triggers
      while True:
          humidity = 65 + random.random() * 20
          if humidity > 80:
              await client.trigger("humidity_alert", {
                  "humidity": round(humidity),
                  "threshold": 80,
                  "sensor": "greenhouse-sensor",
              })
          await asyncio.sleep(10)

  asyncio.run(main())
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="MicroPython Client" icon="microchip" href="/devices/micropython-client">
    Run on a Raspberry Pi Pico W with native MQTT
  </Card>

  <Card title="Pico W Setup Guide" icon="screwdriver-wrench" href="/devices/examples/raspberry-pi-pico">
    Step-by-step hardware setup with Thonny
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Socket.IO transport for full-featured Node.js devices
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/devices/how-it-works">
    Understand the full transport comparison
  </Card>
</CardGroup>


# Node.js Client
Source: https://docs.heylua.ai/devices/node-client

Complete reference for the @lua-ai-global/device-client Node.js package

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @lua-ai-global/device-client
  ```

  ```bash yarn theme={null}
  yarn add @lua-ai-global/device-client
  ```

  ```bash pnpm theme={null}
  pnpm add @lua-ai-global/device-client
  ```
</CodeGroup>

## DeviceClientConfig

The configuration object passed to `new DeviceClient()`. At least one credential field, `deviceCredential` or `apiKey`, is required.

For a new installation, first [provision a device credential](/devices/credentials#provision-a-device-credential) for the exact `agentId`, `deviceName`, and operations that the device uses.

<ParamField type="string">
  Agent ID to connect to. Found in `.lua/lua.config.yaml` or the Lua dashboard.
</ParamField>

<ParamField type="string">
  Device credential for new provisioning. The credential binding must match `agentId` and `deviceName`.
</ParamField>

<ParamField type="string">
  Existing compatibility field. It remains supported indefinitely, including for devices that already use a non-dotted legacy key.
</ParamField>

<ParamField type="string">
  Unique name for this device. Lowercase with hyphens (e.g., `label-printer`, `pico-sensor-01`).
</ParamField>

<ParamField type="DeviceCommandDefinition[]">
  Array of commands this device supports. Sent to the server at connect time so the agent can use them as tools. See [Self-Describing Commands](/devices/self-describing-commands).
</ParamField>

<ParamField type="'socketio' | 'mqtt'">
  Transport protocol. Use `'mqtt'` for constrained devices or environments where MQTT is preferred.
</ParamField>

<ParamField type="string">
  Server URL for Socket.IO transport.
</ParamField>

<ParamField type="string">
  MQTT broker URL. Required when `transport` is `'mqtt'`.
</ParamField>

<ParamField type="string">
  CDN URL for file uploads and downloads.
</ParamField>

<ParamField type="string">
  Optional device group name for fan-out commands (e.g., `'printers'`, `'sensors-floor-2'`).
</ParamField>

Provide either credential field. If you provide both, their values must match.

<Note>
  The `deviceCredential` option requires `@lua-ai-global/device-client` 1.1.0 or later. Existing `apiKey` configurations remain supported indefinitely.
</Note>

## DeviceCommandDefinition

Each entry in the `commands` array describes one command the device supports.

<ParamField type="string">
  Command name. Used by the agent to invoke the command (e.g., `read_temperature`).
</ParamField>

<ParamField type="string">
  Human-readable description. Shown to the AI agent as the tool description. Write it as if explaining to a person what the command does.
</ParamField>

<ParamField type="Record<string, any>">
  JSON Schema for command input parameters. The agent uses this to know what arguments to pass.
</ParamField>

<ParamField type="number">
  Command timeout in milliseconds. If the device does not respond within this time, the command fails.
</ParamField>

<ParamField type="{ maxAttempts: number; backoffMs: number }">
  Retry configuration for failed commands. The gateway retries with exponential backoff.
</ParamField>

## Connection Lifecycle

```typescript theme={null}
import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({ /* config */ });

// Connect -- resolves when authenticated
await device.connect();

// Check connection status
console.log(device.isConnected()); // true

// Listen for lifecycle events
device.on('connected', () => console.log('Connected'));
device.on('reconnected', () => console.log('Reconnected'));
device.on('disconnected', (reason) => console.log('Disconnected:', reason));
device.on('error', (err) => console.error('Error:', err));

// Graceful shutdown (stops auto-reconnect)
await device.disconnect();
```

<Note>
  The client automatically reconnects on network failures with jittered exponential backoff (1s to 30s). Call `disconnect()` to stop reconnection. The client also registers `SIGTERM` and `SIGINT` handlers for graceful shutdown.
</Note>

## Handling Commands

Register handlers for commands the agent can send to this device:

```typescript theme={null}
device.onCommand('read_temperature', async (payload) => {
  // payload contains whatever the agent sent (validated against inputSchema)
  const reading = await sensor.read();
  return {
    temperature: reading.celsius,
    humidity: reading.humidity,
    timestamp: new Date().toISOString(),
  };
});

device.onCommand('set_led', async (payload) => {
  const { color, brightness } = payload;
  await led.setColor(color);
  await led.setBrightness(brightness);
  return { success: true, color, brightness };
});
```

If a handler throws an error, the error message is returned to the agent as a failed command result. The agent sees the error and can decide how to respond to the user.

## Firing Triggers

Send events from the device to the agent:

```typescript theme={null}
// Fire a trigger -- resolves when the server acknowledges receipt
await device.trigger('temperature_alert', {
  temperature: 42.1,
  threshold: 40,
  sensor: 'main-floor',
});

// Optionally listen for trigger execution results
device.onTriggerResult('temperature_alert', (result) => {
  console.log('Agent handled the alert:', result);
});
```

See [Triggers](/devices/triggers) for the full guide on how to handle triggers on the agent side.

## CDN Uploads

Every `DeviceClient` instance includes a `cdn` property for uploading and downloading files:

```typescript theme={null}
import fs from 'fs';

// Upload a screenshot
const screenshot = fs.readFileSync('/tmp/screenshot.png');
const result = await device.cdn.upload(screenshot, 'screenshot.png', 'image/png');
console.log(result.url); // https://cdn.heylua.ai/{fileId}

// Get the URL for a previously uploaded file
const url = device.cdn.getUrl(result.fileId);

// Download a file
const buffer = await device.cdn.download(result.fileId);
fs.writeFileSync('/tmp/downloaded.png', buffer);
```

See [CDN Uploads](/devices/cdn-uploads) for more details.

## Transport Configuration

<Tabs>
  <Tab title="Socket.IO (default)">
    ```typescript theme={null}
    const device = new DeviceClient({
      agentId: 'your-agent-id',
      deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
      deviceName: 'my-device',
      // transport defaults to 'socketio'
      // serverUrl defaults to 'https://api.heylua.ai'
      commands: [
        { name: 'ping', description: 'Health check' },
      ],
    });
    ```

    Socket.IO is best for Node.js applications running on desktops, servers, or single-board computers with plenty of memory.
  </Tab>

  <Tab title="MQTT">
    ```typescript theme={null}
    const device = new DeviceClient({
      agentId: 'your-agent-id',
      deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
      deviceName: 'my-device',
      transport: 'mqtt',
      // mqttUrl defaults to 'wss://mqtt.heylua.ai/mqtt'
      commands: [
        { name: 'ping', description: 'Health check' },
      ],
    });
    ```

    MQTT is best for constrained devices, battery-powered sensors, or environments with flaky network connectivity. MQTT supports offline message queueing with persistent sessions.
  </Tab>
</Tabs>

## Complete Example

A device that simulates a smart thermostat with temperature reading, target temperature setting, and a high-temperature alert trigger:

```typescript theme={null}
import { DeviceClient } from '@lua-ai-global/device-client';

let currentTemp = 21.0;
let targetTemp = 22.0;
let heatingOn = false;

const device = new DeviceClient({
  agentId: process.env.LUA_AGENT_ID!,
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  deviceName: 'smart-thermostat',
  commands: [
    {
      name: 'read_temperature',
      description: 'Read the current room temperature in celsius',
    },
    {
      name: 'set_target',
      description: 'Set the target temperature for the thermostat',
      inputSchema: {
        type: 'object',
        properties: {
          temperature: { type: 'number', minimum: 10, maximum: 35 },
        },
        required: ['temperature'],
      },
    },
    {
      name: 'get_status',
      description: 'Get full thermostat status including heating state',
    },
  ],
});

device.onCommand('read_temperature', async () => {
  return { temperature: currentTemp, unit: 'celsius' };
});

device.onCommand('set_target', async (payload) => {
  targetTemp = payload.temperature;
  heatingOn = currentTemp < targetTemp;
  return { targetTemperature: targetTemp, heatingOn };
});

device.onCommand('get_status', async () => {
  return {
    currentTemperature: currentTemp,
    targetTemperature: targetTemp,
    heatingOn,
    timestamp: new Date().toISOString(),
  };
});

async function main() {
  device.on('connected', () => console.log('Thermostat online'));
  device.on('disconnected', (reason) => console.log('Offline:', reason));

  await device.connect();

  // Simulate temperature changes and fire trigger on high temp
  setInterval(async () => {
    currentTemp += (Math.random() - 0.4) * 0.5;
    currentTemp = Math.round(currentTemp * 10) / 10;

    if (currentTemp > 35) {
      await device.trigger('high_temperature', {
        temperature: currentTemp,
        threshold: 35,
      });
    }
  }, 5000);
}

main().catch(console.error);
```

## Next Steps

<CardGroup>
  <Card title="MQTT Transport" icon="tower-broadcast" href="/devices/mqtt-client">
    Deep dive into MQTT configuration and topic structure
  </Card>

  <Card title="CDN Uploads" icon="cloud-arrow-up" href="/devices/cdn-uploads">
    Upload and download files from your device
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Send events from your device to the agent
  </Card>

  <Card title="API Reference" icon="book" href="/api/luadeviceclient">
    Complete class and method documentation
  </Card>
</CardGroup>


# What are Devices?
Source: https://docs.heylua.ai/devices/overview

Give your AI agent a remote control for the physical world

## What are Devices?

**Devices** let your AI agent reach beyond the cloud and into the physical world. A device is any hardware -- a barcode scanner, a temperature sensor, a kiosk display -- that connects to your agent over the internet and exchanges commands and triggers in real time.

<Card title="Think of it as:" icon="satellite-dish">
  A remote control for your agent to reach into the physical world -- send commands to hardware, receive sensor data back, no middleware required
</Card>

<Note>
  **No compile or push needed.** Devices are self-describing. When a device connects, it tells the agent what commands it supports. Those commands instantly become tools the agent can use. Disconnect the device and the tools disappear.
</Note>

## Why Devices?

<CardGroup>
  <Card title="Real-Time Bidirectional" icon="arrows-left-right">
    Agent sends commands to devices. Devices fire triggers back to the agent. Both directions are instant over persistent connections.
  </Card>

  <Card title="No Middleware" icon="diagram-project">
    Devices connect directly to the agent gateway. No cron jobs, no polling APIs, no message queues to maintain.
  </Card>

  <Card title="Self-Describing Commands" icon="list-check">
    Devices declare their capabilities at connect time. The agent automatically gets tools for every command the device supports.
  </Card>

  <Card title="Runs on a Pico W" icon="microchip">
    The MicroPython client fits on a Raspberry Pi Pico W with 264KB of RAM. Full MQTT support, command handling, and triggers.
  </Card>
</CardGroup>

## Before and After

<Tabs>
  <Tab title="Before: Traditional IoT">
    ```
    Device  -->  MQTT Broker  -->  Middleware API  -->  Cron Job  -->  Agent
                                        |
                                   Database (polling)
                                        |
                                   Dashboard (manual)
    ```

    * Multiple systems to maintain
    * Polling delays (seconds to minutes)
    * Custom glue code for every device type
    * Agent has no direct control
  </Tab>

  <Tab title="After: Lua Device Gateway">
    ```
    Device  <-->  Agent
    ```

    * One persistent connection
    * Sub-second latency
    * Device describes itself -- no glue code
    * Agent sends commands and receives triggers directly
  </Tab>
</Tabs>

## Supported Transports

| Transport     | Best For                                                       | Protocol             | Library                                                                                               |
| ------------- | -------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| **Socket.IO** | Node.js devices, desktops, servers                             | WebSocket over HTTPS | `@lua-ai-global/device-client` (npm) or `lua-device-client` (pip)                                     |
| **MQTT**      | Microcontrollers, constrained devices, battery-powered sensors | MQTT 3.1.1 over TLS  | `@lua-ai-global/device-client` (Node), `lua-device-client` (Python), or `lua_device.py` (MicroPython) |

Both transports support the full feature set: commands, triggers, heartbeats, reconnection, and CDN uploads.

New Node.js installations and custom protocol clients [provision a device credential](/devices/credentials) for one exact agent, device name, and set of operations. Published Python and MicroPython clients continue to use existing non-dotted legacy keys. These keys remain supported indefinitely.

## What Can You Build?

<CardGroup>
  <Card title="Warehouse Monitoring" icon="warehouse" href="/devices/examples/warehouse-inventory">
    Barcode scanners, weight sensors, gate controllers. Agent manages inventory in real time.
  </Card>

  <Card title="Smart Office" icon="building" href="/devices/examples/smart-office">
    Meeting room sensors, thermostats, desk occupancy. Agent acts as a facilities concierge.
  </Card>

  <Card title="Industrial IoT" icon="industry" href="/devices/examples/industrial-sensor">
    Vibration sensors, temperature probes, emergency stop buttons. Agent monitors factory health on a Pico W.
  </Card>

  <Card title="Retail Kiosks" icon="store" href="/devices/examples/retail-kiosk">
    Receipt printers, NFC readers, display screens. Agent powers customer-facing interactions.
  </Card>

  <Card title="Agriculture" icon="seedling">
    Soil moisture sensors, irrigation valves, weather stations. Agent optimizes crop management.
  </Card>

  <Card title="Your Hardware" icon="microchip">
    Any device that runs Node.js or MicroPython. If it can open a socket, it can talk to your agent.
  </Card>
</CardGroup>

## How It Works (30 Seconds)

<Steps>
  <Step title="Device connects">
    Your device opens a Socket.IO or MQTT connection to the Lua gateway and sends a list of commands it supports.
  </Step>

  <Step title="Agent gets tools">
    Each command becomes a tool the agent can call. The agent sees them just like any other skill tool.
  </Step>

  <Step title="Users talk to the agent">
    A user says "scan the next barcode". The agent picks the right device tool and sends the command.
  </Step>

  <Step title="Device responds">
    The device executes the command and returns the result. The agent uses the result in its response to the user.
  </Step>

  <Step title="Device fires triggers">
    The device can also push events to the agent -- "temperature exceeded 40C" -- which run server-side logic.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Device credentials" icon="key" href="/devices/credentials">
    Provision and manage access for one exact device
  </Card>

  <Card title="5-Minute Quickstart" icon="rocket" href="/devices/quickstart">
    Connect your first device in under 5 minutes
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/devices/how-it-works">
    Understand the full command and trigger flow
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Complete reference for the Node.js device client
  </Card>

  <Card title="MicroPython Client" icon="microchip" href="/devices/micropython-client">
    Run on a Raspberry Pi Pico W
  </Card>
</CardGroup>


# 5-Minute Quickstart
Source: https://docs.heylua.ai/devices/quickstart

Connect your first device to a Lua agent in under 5 minutes

## Connect Your First Device

Get a device connected and responding to agent commands.

<Steps>
  <Step title="Install the device client">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @lua-ai-global/device-client
      ```

      ```bash yarn theme={null}
      yarn add @lua-ai-global/device-client
      ```

      ```bash pnpm theme={null}
      pnpm add @lua-ai-global/device-client
      ```

      ```bash pip theme={null}
      pip install lua-device-client
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure the credential">
    For Node.js, create a credential bound to your exact agent, the device name `my-first-device`, and the `commands` operation. Follow [Provision a device credential](/devices/credentials#provision-a-device-credential), then save the returned secret in an environment variable:

    ```bash theme={null}
    export LUA_DEVICE_CREDENTIAL="your-device-credential"
    ```

    <Note>
      The published Python 1.3.0 client uses `api_key`. Set `LUA_API_KEY` to an existing non-dotted legacy key. Existing legacy configurations remain supported indefinitely.
    </Note>

    For the Python example, set the variable that its `api_key` field reads:

    ```bash theme={null}
    export LUA_API_KEY="your-existing-legacy-key"
    ```
  </Step>

  <Step title="Create a device client">
    Create a file called `device.ts` or `device.py`. Use the same agent ID and device name that you used at provisioning:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { DeviceClient } from '@lua-ai-global/device-client';

      const device = new DeviceClient({
        agentId: 'your-agent-id',
        deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
        deviceName: 'my-first-device',
        commands: [
          {
            name: 'ping',
            description: 'Check if the device is alive',
          },
          {
            name: 'read_sensor',
            description: 'Read the current temperature in celsius',
            inputSchema: {
              type: 'object',
              properties: {
                unit: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' },
              },
            },
          },
        ],
      });
      ```

      ```python Python theme={null}
      import os
      from lua_device import DeviceClient, DeviceCommandDefinition

      client = DeviceClient(
          agent_id="your-agent-id",
          api_key=os.environ["LUA_API_KEY"],
          device_name="my-first-device",
          commands=[
              DeviceCommandDefinition(
                  name="ping",
                  description="Check if the device is alive",
              ),
              DeviceCommandDefinition(
                  name="read_sensor",
                  description="Read the current temperature in celsius",
                  input_schema={
                      "type": "object",
                      "properties": {
                          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
                      },
                  },
              ),
          ],
      )
      ```
    </CodeGroup>

    Find your `agentId` in `.lua/lua.config.yaml` after running `lua init`, or in the [Lua dashboard](https://admin.heylua.ai).
  </Step>

  <Step title="Register command handlers">
    Tell the device what to do when the agent sends each command:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      device.onCommand('ping', async () => {
        return { status: 'ok', timestamp: new Date().toISOString() };
      });

      device.onCommand('read_sensor', async (payload) => {
        // In a real device, read from hardware here
        const tempCelsius = 22.5;
        const temp = payload?.unit === 'fahrenheit'
          ? (tempCelsius * 9/5) + 32
          : tempCelsius;

        return { temperature: temp, unit: payload?.unit || 'celsius' };
      });
      ```

      ```python Python theme={null}
      from datetime import datetime, timezone

      @client.on_command("ping")
      async def handle_ping(payload):
          return {"status": "ok", "timestamp": datetime.now(timezone.utc).isoformat()}

      @client.on_command("read_sensor")
      async def handle_read_sensor(payload):
          # In a real device, read from hardware here
          temp_celsius = 22.5
          unit = (payload or {}).get("unit", "celsius")
          temp = (temp_celsius * 9 / 5) + 32 if unit == "fahrenheit" else temp_celsius
          return {"temperature": temp, "unit": unit}
      ```
    </CodeGroup>
  </Step>

  <Step title="Connect">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      async function main() {
        await device.connect();
        console.log('Device connected and ready for commands');
      }

      main().catch(console.error);
      ```

      ```python Python theme={null}
      import asyncio

      async def main():
          await client.connect()
          print("Device connected and ready for commands")

      asyncio.run(main())
      ```
    </CodeGroup>

    Run your device:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx device.ts
      ```

      ```bash Python theme={null}
      python device.py
      ```
    </CodeGroup>

    You should see:

    ```
    Device connected and ready for commands
    ```
  </Step>

  <Step title="Test with lua chat">
    In another terminal, start a chat session with your agent:

    ```bash theme={null}
    lua chat
    ```

    Try saying:

    ```
    > Ping my-first-device
    > What's the temperature reading from my-first-device?
    > Read the sensor in fahrenheit
    ```

    The agent will use the device tools to send commands and return the results.
  </Step>
</Steps>

<Note>
  **No compile or push needed.** Your device declared its commands at connect time. The agent already has tools for them. Change the commands array, restart the device, and the agent sees the new tools instantly.
</Note>

## Complete Working Example

Here is the full file in one piece:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';

  const device = new DeviceClient({
    agentId: 'your-agent-id',
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'my-first-device',
    commands: [
      {
        name: 'ping',
        description: 'Check if the device is alive',
      },
      {
        name: 'read_sensor',
        description: 'Read the current temperature in celsius',
        inputSchema: {
          type: 'object',
          properties: {
            unit: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' },
          },
        },
      },
    ],
  });

  device.onCommand('ping', async () => {
    return { status: 'ok', timestamp: new Date().toISOString() };
  });

  device.onCommand('read_sensor', async (payload) => {
    const tempCelsius = 22.5;
    const temp = payload?.unit === 'fahrenheit'
      ? (tempCelsius * 9/5) + 32
      : tempCelsius;
    return { temperature: temp, unit: payload?.unit || 'celsius' };
  });

  async function main() {
    await device.connect();
    console.log('Device connected and ready for commands');
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition

  client = DeviceClient(
      agent_id="your-agent-id",
      api_key=os.environ["LUA_API_KEY"],
      device_name="my-first-device",
      commands=[
          DeviceCommandDefinition(
              name="ping",
              description="Check if the device is alive",
          ),
          DeviceCommandDefinition(
              name="read_sensor",
              description="Read the current temperature in celsius",
              input_schema={
                  "type": "object",
                  "properties": {
                      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
                  },
              },
          ),
      ],
  )

  @client.on_command("ping")
  async def handle_ping(payload):
      return {"status": "ok", "timestamp": datetime.now(timezone.utc).isoformat()}

  @client.on_command("read_sensor")
  async def handle_read_sensor(payload):
      temp_celsius = 22.5
      unit = (payload or {}).get("unit", "celsius")
      temp = (temp_celsius * 9 / 5) + 32 if unit == "fahrenheit" else temp_celsius
      return {"temperature": temp, "unit": unit}

  async def main():
      await client.connect()
      print("Device connected and ready for commands")

  asyncio.run(main())
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Architecture" icon="diagram-project" href="/devices/how-it-works">
    Understand how commands and triggers flow through the system
  </Card>

  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    Learn how devices declare their capabilities
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Let your device push events to the agent
  </Card>

  <Card title="Node.js Client Reference" icon="node-js" href="/devices/node-client">
    Full API reference for the device client
  </Card>
</CardGroup>


# Self-Describing Commands
Source: https://docs.heylua.ai/devices/self-describing-commands

How devices declare their capabilities without any server-side configuration

## The Key Innovation

Traditional IoT platforms require you to define device capabilities on the server, then write matching firmware, then keep both in sync. With Lua devices, the device itself declares what it can do. There is no server-side schema to maintain.

<Card title="Think of it as:" icon="id-card">
  Each device carries its own resume. When it connects, the agent reads the resume and knows exactly what the device can do.
</Card>

When a device connects, it sends an array of `DeviceCommandDefinition` objects. The gateway stores these alongside the connection. The agent runtime reads them and creates tools automatically. When the device disconnects, the tools disappear.

## DeviceCommandDefinition Fields

Each command definition has the following fields:

```typescript theme={null}
interface DeviceCommandDefinition {
  /** Command name (used by agent to invoke) */
  name: string;

  /** Human-readable description (shown to the AI agent as tool description) */
  description: string;

  /** JSON Schema for command input parameters */
  inputSchema?: Record<string, any>;

  /** Command timeout in milliseconds (default: 30000) */
  timeoutMs?: number;

  /** Retry configuration for failed commands */
  retry?: { maxAttempts: number; backoffMs: number };
}
```

<ParamField type="string">
  The command name. This becomes part of the tool name the agent sees (`device:{deviceName}:{name}`). Use lowercase with underscores (e.g., `read_temperature`, `set_brightness`).
</ParamField>

<ParamField type="string">
  A natural-language description of what the command does. The AI agent reads this to decide when to use the tool. Write it as if explaining to a person: "Read the current room temperature in celsius" is better than "temp read".
</ParamField>

<ParamField type="Record<string, any>">
  A JSON Schema object describing the parameters the command accepts. The agent uses this to construct the correct payload.
</ParamField>

<ParamField type="number">
  How long to wait for the device to respond before the command fails. Increase for slow operations like printing or scanning.
</ParamField>

<ParamField type="{ maxAttempts: number; backoffMs: number }">
  Automatic retry on failure. The gateway retries with exponential backoff starting at `backoffMs`.
</ParamField>

## JSON Schema Examples

### No Parameters

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    name: 'get_status',
    description: 'Get the current status of the printer including paper level and ink',
  }
  ```

  ```python Python theme={null}
  DeviceCommandDefinition(
      name="get_status",
      description="Get the current status of the printer including paper level and ink",
  )
  ```
</CodeGroup>

### Simple Parameters

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    name: 'set_brightness',
    description: 'Set the display brightness level',
    inputSchema: {
      type: 'object',
      properties: {
        level: {
          type: 'number',
          minimum: 0,
          maximum: 100,
          description: 'Brightness percentage (0-100)',
        },
      },
      required: ['level'],
    },
  }
  ```

  ```python Python theme={null}
  DeviceCommandDefinition(
      name="set_brightness",
      description="Set the display brightness level",
      input_schema={
          "type": "object",
          "properties": {
              "level": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "Brightness percentage (0-100)",
              },
          },
          "required": ["level"],
      },
  )
  ```
</CodeGroup>

### Enum Parameters

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    name: 'set_mode',
    description: 'Switch the device operating mode',
    inputSchema: {
      type: 'object',
      properties: {
        mode: {
          type: 'string',
          enum: ['idle', 'active', 'maintenance', 'sleep'],
          description: 'Target operating mode',
        },
      },
      required: ['mode'],
    },
  }
  ```

  ```python Python theme={null}
  DeviceCommandDefinition(
      name="set_mode",
      description="Switch the device operating mode",
      input_schema={
          "type": "object",
          "properties": {
              "mode": {
                  "type": "string",
                  "enum": ["idle", "active", "maintenance", "sleep"],
                  "description": "Target operating mode",
              },
          },
          "required": ["mode"],
      },
  )
  ```
</CodeGroup>

### Complex Parameters

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    name: 'print_label',
    description: 'Print a shipping label with the given details',
    inputSchema: {
      type: 'object',
      properties: {
        recipient: {
          type: 'object',
          properties: {
            name: { type: 'string' },
            address: { type: 'string' },
            city: { type: 'string' },
            postalCode: { type: 'string' },
          },
          required: ['name', 'address', 'city', 'postalCode'],
        },
        copies: {
          type: 'number',
          minimum: 1,
          maximum: 10,
          default: 1,
        },
      },
      required: ['recipient'],
    },
    timeoutMs: 60000,
    retry: { maxAttempts: 2, backoffMs: 1000 },
  }
  ```

  ```python Python theme={null}
  DeviceCommandDefinition(
      name="print_label",
      description="Print a shipping label with the given details",
      input_schema={
          "type": "object",
          "properties": {
              "recipient": {
                  "type": "object",
                  "properties": {
                      "name": {"type": "string"},
                      "address": {"type": "string"},
                      "city": {"type": "string"},
                      "postalCode": {"type": "string"},
                  },
                  "required": ["name", "address", "city", "postalCode"],
              },
              "copies": {
                  "type": "number",
                  "minimum": 1,
                  "maximum": 10,
                  "default": 1,
              },
          },
          "required": ["recipient"],
      },
      timeout_ms=60000,
      retry={"maxAttempts": 2, "backoffMs": 1000},
  )
  ```
</CodeGroup>

## Validation Rules

* **`name`** must be unique within a single device. Two devices can have commands with the same name.
* **`description`** should be a complete sentence. The agent treats it as a tool description.
* **`inputSchema`** must be valid JSON Schema draft-07. The `type` at the top level should be `'object'`.
* **`timeoutMs`** minimum is 1000 (1 second). The default of 30000 (30 seconds) works for most commands.

## Dynamic Updates

Commands are sent at connect time. To change the command list, update the `commands` array in your `DeviceClientConfig` and restart the device (or disconnect and reconnect).

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Version 1: basic sensor
  const device = new DeviceClient({
    deviceName: 'env-sensor',
    commands: [
      { name: 'read_temperature', description: 'Read temperature' },
    ],
    // ...
  });

  // Version 2: added humidity and calibration
  const device = new DeviceClient({
    deviceName: 'env-sensor',
    commands: [
      { name: 'read_temperature', description: 'Read temperature in celsius' },
      { name: 'read_humidity', description: 'Read relative humidity percentage' },
      { name: 'calibrate', description: 'Run sensor calibration routine', timeoutMs: 60000 },
    ],
    // ...
  });
  ```

  ```python Python theme={null}
  # Version 1: basic sensor
  client = DeviceClient(
      device_name="env-sensor",
      commands=[
          DeviceCommandDefinition(name="read_temperature", description="Read temperature"),
      ],
      # ...
  )

  # Version 2: added humidity and calibration
  client = DeviceClient(
      device_name="env-sensor",
      commands=[
          DeviceCommandDefinition(name="read_temperature", description="Read temperature in celsius"),
          DeviceCommandDefinition(name="read_humidity", description="Read relative humidity percentage"),
          DeviceCommandDefinition(name="calibrate", description="Run sensor calibration routine", timeout_ms=60000),
      ],
      # ...
  )
  ```
</CodeGroup>

No `lua push` or `lua deploy` needed. Just restart the device.

<Warning>
  **When a device goes offline, its tools disappear from the agent.** If a user asks the agent to use a device tool and the device is not connected, the agent will not have that tool available. Design your agent persona to handle this gracefully (e.g., "The sensor is currently offline").
</Warning>

## Next Steps

<CardGroup>
  <Card title="Agent Tools" icon="wrench" href="/devices/agent-tools">
    How device commands become tools the agent can use
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Complete DeviceClientConfig reference
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    The other direction -- device events sent to the agent
  </Card>

  <Card title="Quickstart" icon="rocket" href="/devices/quickstart">
    See self-describing commands in action
  </Card>
</CardGroup>


# Triggers
Source: https://docs.heylua.ai/devices/triggers

Send events from devices to your agent and handle them with server-side logic

## Two Sides of a Trigger

A device trigger has two sides:

1. **Device side** -- the device fires the trigger using `client.trigger()` or `device.trigger()`
2. **Agent side** -- you define what happens when the trigger arrives using `defineDeviceTrigger()`

The device sends the event. The agent handles it.

<Card title="Think of it as:" icon="bell">
  A doorbell. The device presses it (fires the trigger). Your agent-side code decides what to do when it rings (the execute function).
</Card>

## Device Side: Firing Triggers

### Node.js

```typescript theme={null}
// Fire a trigger with a payload
await device.trigger('low_stock', {
  sku: 'WIDGET-001',
  currentQuantity: 3,
  threshold: 10,
  location: 'warehouse-A',
});
```

The `trigger()` method resolves when the server acknowledges receipt. It does not wait for the agent to finish processing.

### Python

```python theme={null}
# Fire a trigger with a payload
await client.trigger("low_stock", {
    "sku": "WIDGET-001",
    "currentQuantity": 3,
    "threshold": 10,
    "location": "warehouse-A",
})
```

### MicroPython

```python theme={null}
device.trigger("low_stock", {
    "sku": "WIDGET-001",
    "currentQuantity": 3,
    "threshold": 10,
    "location": "warehouse-A",
})
```

## Agent Side: Handling Triggers

On the agent side, create a device trigger primitive using `defineDeviceTrigger()`. This is a standalone file that gets compiled, pushed, and deployed like any other Lua primitive.

```typescript theme={null}
// src/triggers/low-stock.ts
import { defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';

export const lowStock = defineDeviceTrigger({
  name: 'low-stock',
  description: 'Fired when inventory for an item drops below its reorder threshold',
  payloadSchema: z.object({
    sku: z.string(),
    currentQuantity: z.number(),
    threshold: z.number(),
    location: z.string(),
  }),
  execute: async (payload, { agent, device }) => {
    await agent.chat(
      `Device ${device.name} reports low stock for SKU ${payload.sku}. ` +
      `Current quantity: ${payload.currentQuantity}, threshold: ${payload.threshold}. ` +
      `Location: ${payload.location}. Please create a reorder request.`
    );
  },
});
```

<Note>
  The trigger `name` on the agent side uses hyphens (e.g., `low-stock`). The trigger name on the device side uses underscores (e.g., `low_stock`). The gateway maps between the two conventions automatically.
</Note>

## Both Sides Together

<CodeGroup>
  ```typescript Device Side (Node.js) theme={null}
  import { DeviceClient } from '@lua-ai-global/device-client';

  const device = new DeviceClient({
    agentId: process.env.LUA_AGENT_ID!,
    deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
    deviceName: 'temp-monitor',
    commands: [
      { name: 'read_temperature', description: 'Read current temperature' },
    ],
  });

  device.onCommand('read_temperature', async () => {
    const temp = readSensor();
    return { temperature: temp, unit: 'celsius' };
  });

  async function main() {
    await device.connect();

    // Check temperature every 30 seconds, trigger alert if too high
    setInterval(async () => {
      const temp = readSensor();
      if (temp > 40) {
        await device.trigger('temperature_alert', {
          temperature: temp,
          threshold: 40,
          sensor: 'main-hall',
        });
      }
    }, 30000);
  }

  function readSensor(): number {
    return 20 + Math.random() * 25; // simulated
  }

  main().catch(console.error);
  ```

  ```python Device Side (Python) theme={null}
  import asyncio
  import random
  from lua_device import DeviceClient, DeviceCommandDefinition

  client = DeviceClient(
      agent_id="your-agent-id",
      api_key="your-api-key",
      device_name="temp-monitor",
      commands=[
          DeviceCommandDefinition(name="read_temperature", description="Read current temperature"),
      ],
  )

  def read_sensor() -> float:
      return 20 + random.random() * 25  # simulated

  @client.on_command("read_temperature")
  async def handle_read_temperature(payload):
      temp = read_sensor()
      return {"temperature": temp, "unit": "celsius"}

  async def main():
      await client.connect()

      # Check temperature every 30 seconds, trigger alert if too high
      while True:
          temp = read_sensor()
          if temp > 40:
              await client.trigger("temperature_alert", {
                  "temperature": temp,
                  "threshold": 40,
                  "sensor": "main-hall",
              })
          await asyncio.sleep(30)

  asyncio.run(main())
  ```

  ```typescript Agent Side (src/triggers/temperature-alert.ts) theme={null}
  import { defineDeviceTrigger } from 'lua-cli';
  import { z } from 'zod';

  export const temperatureAlert = defineDeviceTrigger({
    name: 'temperature-alert',
    description: 'Fired when a temperature sensor exceeds its threshold',
    payloadSchema: z.object({
      temperature: z.number(),
      threshold: z.number(),
      sensor: z.string(),
    }),
    execute: async (payload, { agent, device }) => {
      const message =
        `ALERT: Device "${device.name}" sensor "${payload.sensor}" ` +
        `reads ${payload.temperature}C (threshold: ${payload.threshold}C). ` +
        `Please investigate and take appropriate action.`;

      await agent.chat(message);
    },
  });
  ```
</CodeGroup>

## Deploying Device Triggers

Device triggers are compiled and pushed like other Lua primitives:

```bash theme={null}
lua push device-trigger
```

Or push everything at once:

```bash theme={null}
lua push
```

Then deploy:

```bash theme={null}
lua deploy
```

## LuaDeviceTriggerConfig Reference

<ParamField type="string">
  Trigger name. Lowercase with hyphens (e.g., `paper-low`, `temperature-alert`).
</ParamField>

<ParamField type="string">
  Description of when this trigger fires. Helps with debugging and documentation.
</ParamField>

<ParamField type="ZodType">
  Zod schema for validating the trigger payload. The payload is validated before `execute` runs.
</ParamField>

<ParamField type="(payload, context) => Promise<any>">
  The function that runs when the trigger fires. Receives the validated payload and a context object.
</ParamField>

### Execute Context

The `execute` function receives a context object:

| Property | Type               | Description                                                          |
| -------- | ------------------ | -------------------------------------------------------------------- |
| `agent`  | object             | Agent context. Call `agent.chat()` to send messages or invoke tools. |
| `device` | `{ name: string }` | Information about the device that fired the trigger.                 |

## Trigger Result Listening (Optional)

On the device side, you can optionally listen for the result of trigger execution:

<CodeGroup>
  ```typescript TypeScript theme={null}
  device.onTriggerResult('temperature_alert', (result) => {
    console.log('Agent handled the alert:', result);
    // e.g., result might contain actions taken
  });
  ```

  ```python Python theme={null}
  @client.on_trigger_result("temperature_alert")
  async def handle_alert_result(result):
      print("Agent handled the alert:", result)
      # e.g., result might contain actions taken
  ```
</CodeGroup>

This is optional. Most triggers are fire-and-forget.

## Next Steps

<CardGroup>
  <Card title="Agent Tools" icon="wrench" href="/devices/agent-tools">
    How the other direction works -- agent sending commands to devices
  </Card>

  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    How devices declare their command capabilities
  </Card>

  <Card title="Warehouse Example" icon="warehouse" href="/devices/examples/warehouse-inventory">
    Full example with triggers for low stock alerts
  </Card>

  <Card title="Industrial Sensor" icon="industry" href="/devices/examples/industrial-sensor">
    MicroPython trigger example for vibration anomalies
  </Card>
</CardGroup>


# Baskets Tools Example
Source: https://docs.heylua.ai/examples/baskets

Complete shopping cart workflow with 9 tools

## Overview

**File**: `src/tools/BasketTool.ts`

Nine tools demonstrating the complete shopping cart workflow from creation to checkout.

## The Complete Shopping Flow

```mermaid theme={null}
graph TD
    A[Create Basket] --> B[Add Items]
    B --> C[Update Metadata]
    C --> D[Checkout]
    D --> E[Order Created!]
```

<Steps>
  <Step title="Create Basket">
    Start a new shopping session
  </Step>

  <Step title="Add Items">
    Add products to cart (can add multiple)
  </Step>

  <Step title="Manage Cart">
    Remove items, update quantities, add notes
  </Step>

  <Step title="Checkout">
    Convert basket to order
  </Step>
</Steps>

## Key Tools

### CreateBasketTool

```typescript theme={null}
import { LuaTool, Baskets } from 'lua-cli';
import { z } from 'zod';

export class CreateBasketTool implements LuaTool {
  name = "create_basket";
  description = "Create a new shopping basket";
  
  inputSchema = z.object({
    currency: z.string().default('USD')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const basket = await Baskets.create({
      currency: input.currency,
      metadata: { createdBy: 'chat' }
    });
    
    return {
      basketId: basket.id,
      message: "New basket created! Start adding items."
    };
  }
}
```

### AddItemToBasketTool

```typescript theme={null}
export class AddItemToBasketTool implements LuaTool {
  name = "add_to_basket";
  description = "Add a product to the shopping basket";
  
  inputSchema = z.object({
    basketId: z.string(),
    productId: z.string(),
    quantity: z.number().min(1).default(1)
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get product to get current price
    const product = await Products.getById(input.productId);
    
    // Check stock
    if (!product.inStock) {
      return {
        success: false,
        message: `${product.name} is currently out of stock`
      };
    }
    
    // Add to basket
    const updated = await Baskets.addItem(input.basketId, {
      id: input.productId,
      price: product.price,
      quantity: input.quantity,
      SKU: product.sku
    });
    
    return {
      basketId: updated.id,
      itemCount: updated.common.itemCount,
      total: `$${updated.common.totalAmount.toFixed(2)}`,
      message: `Added ${input.quantity}x ${product.name} to basket`
    };
  }
}
```

### CheckoutBasketTool

```typescript theme={null}
export class CheckoutBasketTool implements LuaTool {
  name = "checkout_basket";
  description = "Complete purchase and create order";
  
  inputSchema = z.object({
    basketId: z.string(),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      zip: z.string()
    }),
    paymentMethod: z.string().default('stripe')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const order = await Baskets.placeOrder({
      shippingAddress: input.shippingAddress,
      paymentMethod: input.paymentMethod
    }, input.basketId);
    
    return {
      orderId: order.id,
      status: order.common.status,
      total: `$${order.common.totalAmount.toFixed(2)}`,
      message: "Order created successfully!"
    };
  }
}
```

## All 9 Tools

1. **CreateBasketTool** - Start shopping
2. **GetBasketsTool** - List all baskets
3. **AddItemToBasketTool** - Add products
4. **RemoveItemFromBasketTool** - Remove products
5. **ClearBasketTool** - Empty cart
6. **UpdateBasketStatusTool** - Change status
7. **UpdateBasketMetadataTool** - Add notes/data
8. **CheckoutBasketTool** - Convert to order
9. **GetBasketByIdTool** - View specific basket

## Testing the Flow

```bash theme={null}
lua chat
```

Select sandbox mode, then try this conversation:

1. "Create a shopping basket"
2. "Search for laptop"
3. "Add that laptop to my basket"
4. "Show me my cart"
5. "Checkout with shipping to 123 Main St, New York"

## What You'll Learn

<CardGroup>
  <Card title="Multi-Step Workflows" icon="diagram-project">
    Handle complex processes
  </Card>

  <Card title="State Management" icon="database">
    Track cart state over time
  </Card>

  <Card title="API Chaining" icon="link">
    Combine multiple API calls
  </Card>

  <Card title="Business Logic" icon="brain">
    Implement e-commerce rules
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Baskets API" icon="book" href="/api/baskets">
    Complete API reference
  </Card>

  <Card title="Orders API" icon="receipt" href="/api/orders">
    Manage orders after checkout
  </Card>
</CardGroup>


# Custom Data Tools Example
Source: https://docs.heylua.ai/examples/custom-data

Vector search and custom data collections

## Overview

**File**: `src/tools/CustomDataTool.ts`

Demonstrates the powerful Custom Data API with semantic vector search. The example uses a movie database, but the patterns work for any searchable content.

## What Makes This Special

**Vector Search** = Semantic Understanding

Traditional search:

* Query: "Inception" → Finds "Inception" ✅
* Query: "dream movie" → Finds nothing ❌

Vector search:

* Query: "Inception" → Finds "Inception" ✅
* Query: "dream movie" → Finds "Inception"! ✅
* Query: "mind-bending thriller" → Finds similar movies! ✅

## Complete Tools

### Create Movie Tool

```typescript theme={null}
import { LuaTool, Data } from 'lua-cli';
import { z } from 'zod';

export class CreateMovieTool implements LuaTool {
  name = "create_movie";
  description = "Add a new movie to the database";
  
  inputSchema = z.object({
    title: z.string(),
    director: z.string(),
    year: z.number(),
    genre: z.string(),
    description: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // ⭐ KEY: Create searchable text with all relevant info
    const searchText = [
      input.title,
      input.director,
      input.genre,
      input.description
    ].filter(Boolean).join(' ');
    
    const movie = await Data.create('movies', input, searchText);
    
    return {
      id: movie.id,
      message: `Added "${input.title}" to database`
    };
  }
}
```

### Search Movies Tool

```typescript theme={null}
export class SearchMoviesTool implements LuaTool {
  name = "search_movies";
  description = "Search movies by title, director, genre, or theme";
  
  inputSchema = z.object({
    query: z.string().describe("Search query (can be descriptive)")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // ⭐ Vector search with similarity threshold
    const results = await Data.search(
      'movies',
      input.query,
      10,           // Max 10 results
      0.7           // Min similarity score
    );
    
    return {
      movies: results.map(entry => ({
        id: entry.id,
        title: entry.title,
        year: entry.year,
        director: entry.director,
        relevance: Math.round(entry.score * 100) + '%'
      })),
      count: results.length
    };
  }
}
```

### Get Movie Tool

```typescript theme={null}
export class GetMovieByIdTool implements LuaTool {
  name = "get_movie";
  description = "Get detailed information about a specific movie";
  
  inputSchema = z.object({
    id: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const movie = await Data.getEntry('movies', input.id);
    return movie.data;
  }
}
```

## Key Concepts

### 1. Search Text is Critical

The `searchText` parameter determines what the AI can find:

```typescript theme={null}
// ✅ Good - Rich search text
const searchText = `${input.title} ${input.director} ${input.genre} ${input.description} ${input.tags.join(' ')}`;

// ❌ Bad - Only title
const searchText = input.title;
```

### 2. Similarity Scores

Understanding score thresholds:

* `1.0` = Perfect match
* `0.8-0.9` = Very similar
* `0.7-0.8` = Somewhat similar
* `0.6-0.7` = Loosely related
* `<0.6` = May be irrelevant

```typescript theme={null}
// Strict (high precision)
await Data.search('movies', query, 10, 0.8);

// Balanced (recommended)
await Data.search('movies', query, 10, 0.7);

// Loose (high recall)
await Data.search('movies', query, 10, 0.6);
```

### 3. Natural Language Queries

Users can search naturally:

```typescript theme={null}
// All of these work:
"sci-fi movies about space"
"Christopher Nolan films"
"thriller with plot twists"
"movies like Inception"
"romantic comedies from 2020"
```

### 4. Index Your Filter Fields

Vector search scales automatically — **filtered queries do not**. If your
tools call `Data.get(collection, { field: value })` and the collection grows
(imports, CDC syncs, event logs), declare the filtered fields when storing:

```typescript theme={null}
await Data.create('movies', movie, {
  searchText: buildSearchText(movie),
  index: ['year'],                    // you filter by year
  // index: [['genre', 'year']],      // compound: filtered together
});
```

The platform builds an agent-scoped index within minutes and retires it
automatically \~14 days after your agent stops using it — no cleanup code.
Skip this on a large collection and filtered queries eventually fail with an
error telling you exactly which field to declare. Check build status any time
with `Data.collections()`.

## Testing

```bash theme={null}
lua test
```

Try semantic searches:

* "mind-bending thriller" → Should find Inception
* "Christopher Nolan movies" → Should find his films
* "space exploration" → Should find relevant sci-fi
* "romantic comedy" → Should find rom-coms

## Use Cases

### Knowledge Base

```typescript theme={null}
await Data.create('articles', {
  title: 'How to Reset Password',
  content: 'Step by step guide...',
  category: 'Account'
}, 'password reset account help guide');

// Users can find with:
// - "forgot password"
// - "can't log in"
// - "reset account"
```

### Product Recommendations

```typescript theme={null}
await Data.create('products', {
  name: 'Wireless Headphones',
  description: 'Noise cancelling...'
}, 'wireless headphones bluetooth noise cancelling audio');

// Users can find with:
// - "best headphones for travel"
// - "noise canceling earphones"
// - "bluetooth audio"
```

### Customer Notes

```typescript theme={null}
await Data.create('customers', {
  name: 'John Doe',
  company: 'Acme Corp',
  notes: 'Interested in enterprise plan'
}, 'John Doe Acme Corp enterprise interested sales');

// Find with:
// - "enterprise customers"
// - "Acme contacts"
// - "sales leads"
```

## Customization Ideas

### Add Ratings

```typescript theme={null}
inputSchema = z.object({
  ...existing,
  rating: z.number().min(0).max(10)
});

// Sort by rating
results.sort((a, b) => b.rating - a.rating);
```

### Add Filters

```typescript theme={null}
// Search with filters
const results = await Data.search('movies', query, 50, 0.7);

// Filter by year
const recentMovies = results.filter(m => 
  m.year >= 2020
);
```

### Update Movies

```typescript theme={null}
export class UpdateMovieTool implements LuaTool {
  name = "update_movie";
  description = "Update movie information";
  
  inputSchema = z.object({
    id: z.string(),
    data: z.object({
      rating: z.number().optional(),
      awards: z.array(z.string()).optional(),
      description: z.string().optional()
    }),
    updateSearchText: z.boolean().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const movie = await Data.getEntry('movies', input.id);
    
    // Optionally update search text if description changed
    const searchText = input.updateSearchText 
      ? `${movie.title} ${movie.director} ${input.data.description || ''}`
      : undefined;
    
    await Data.update('movies', input.id, input.data, searchText);
    
    return { success: true, message: `Updated movie ${movie.title}` };
  }
}
```

### Using save() Method

```typescript theme={null}
export class UpdateMovieRatingTool implements LuaTool {
  name = "update_movie_rating";
  description = "Update movie rating and review";
  
  inputSchema = z.object({
    id: z.string(),
    rating: z.number().min(0).max(10),
    review: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Get the entry
    const movie = await Data.getEntry('movies', input.id);
    
    // Modify properties directly
    movie.rating = input.rating;
    if (input.review) {
      movie.review = input.review;
    }
    movie.updatedAt = new Date().toISOString();
    
    // Save all changes at once
    // Optionally update search text if review added
    const searchText = input.review 
      ? `${movie.title} ${movie.director} rating ${input.rating} ${input.review}`
      : undefined;
    
    await movie.save(searchText);
    
    return { 
      success: true,
      message: `Updated "${movie.title}" rating to ${input.rating}` 
    };
  }
}
```

## What You'll Learn

<CardGroup>
  <Card title="Vector Search" icon="magnifying-glass">
    Semantic similarity search with AI
  </Card>

  <Card title="Custom Collections" icon="database">
    Store any data structure
  </Card>

  <Card title="Search Indexing" icon="book">
    Optimize for findability
  </Card>

  <Card title="Score Thresholds" icon="sliders">
    Tune precision vs recall
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Data API Reference" icon="book" href="/api/data">
    Complete Data API documentation
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Uses Data API with vector search
  </Card>
</CardGroup>


# Tool Examples Overview
Source: https://docs.heylua.ai/examples/overview

Learn from 30+ working tool examples

## Available Examples

The template project includes 30+ working tools demonstrating all major patterns and use cases.

<CardGroup>
  <Card title="Weather Tool" icon="cloud" href="/examples/weather">
    External API integration
  </Card>

  <Card title="User Data Tools" icon="user" href="/examples/user-data">
    User profile management (2 tools)
  </Card>

  <Card title="Products Tools" icon="box" href="/examples/products">
    E-commerce catalog (6 tools)
  </Card>

  <Card title="Baskets Tools" icon="cart-shopping" href="/examples/baskets">
    Shopping cart workflow (9 tools)
  </Card>

  <Card title="Custom Data Tools" icon="database" href="/examples/custom-data">
    Vector search database (6 tools)
  </Card>

  <Card title="Payment Tool" icon="credit-card" href="/examples/payment">
    Stripe integration
  </Card>
</CardGroup>

## Learning Path

<Steps>
  <Step title="Start Simple">
    **Weather Tool** - External API integration

    Shows how to call external APIs and handle responses
  </Step>

  <Step title="Platform APIs">
    **User Data Tools** - Simple platform API usage

    Learn how to use Lua's built-in APIs
  </Step>

  <Step title="CRUD Operations">
    **Products Tools** - Complete CRUD pattern

    Create, read, update, delete with pagination
  </Step>

  <Step title="Vector Search">
    **Custom Data Tools** - Semantic search

    Most powerful feature! Build searchable knowledge bases
  </Step>

  <Step title="Complex Workflows">
    **Baskets Tools** - Multi-step processes

    Handle complex business logic and state
  </Step>
</Steps>

## Tool Categories

### External APIs (1 tool)

Tools that integrate with external services:

<Card title="GetWeatherTool" icon="cloud">
  **File**: `GetWeatherTool.ts`

  **What it does**: Fetches real-time weather using Open-Meteo API

  **Learn**:

  * Making HTTP requests
  * Handling API responses
  * Error handling
  * No API key required
</Card>

### Platform APIs (27 tools)

Tools using Lua's built-in platform APIs:

<Tabs>
  <Tab title="User (2 tools)">
    * `get_user_data` - Retrieve user info
    * `update_user_data` - Update profile

    **Learn**: Basic platform API usage
  </Tab>

  <Tab title="Products (6 tools)">
    * `search_products` - Search catalog
    * `get_all_products` - List with pagination
    * `create_product` - Add new items
    * `update_product` - Modify existing
    * `get_product_by_id` - Get specific
    * `delete_product` - Remove items

    **Learn**: Complete CRUD operations
  </Tab>

  <Tab title="Baskets (9 tools)">
    * `create_basket` - Start shopping
    * `get_baskets` - List carts
    * `add_to_basket` - Add items
    * `remove_from_basket` - Remove items
    * `clear_basket` - Empty cart
    * `update_basket_status` - Change status
    * `update_basket_metadata` - Add notes
    * `checkout_basket` - Convert to order
    * `get_basket_by_id` - View specific

    **Learn**: Multi-step workflows
  </Tab>

  <Tab title="Orders (4 tools)">
    * `create_order` - From basket
    * `update_order_status` - Track fulfillment
    * `get_order_by_id` - Order details
    * `get_user_orders` - List user orders

    **Learn**: Order management
  </Tab>

  <Tab title="Custom Data (6 tools)">
    * `create_movie` - Add with indexing
    * `get_movies` - List all
    * `get_movie_by_id` - Get specific
    * `update_movie` - Modify
    * `search_movies` - **Semantic search**
    * `delete_movie` - Remove

    **Learn**: **Vector search** (most powerful!)
  </Tab>
</Tabs>

### Integrations (2 tools)

<CardGroup>
  <Card title="Payment Tool" icon="credit-card">
    Stripe payment link creation

    **Learn**: Environment variables, external services
  </Card>

  <Card title="Create Post Tool" icon="pen">
    Simple example

    **Learn**: Basic tool structure
  </Card>
</CardGroup>

## Quick Reference

| Tool            | Complexity   | Best For Learning |
| --------------- | ------------ | ----------------- |
| CreatePostTool  | ⭐ Easy       | Tool basics       |
| GetWeatherTool  | ⭐⭐ Medium    | External APIs     |
| UserDataTools   | ⭐ Easy       | Platform APIs     |
| ProductsTools   | ⭐⭐ Medium    | CRUD operations   |
| CustomDataTools | ⭐⭐⭐ Advanced | Vector search     |
| BasketsTools    | ⭐⭐⭐ Complex  | Workflows         |
| OrderTools      | ⭐⭐ Medium    | Order management  |
| PaymentTool     | ⭐⭐⭐ Advanced | Integrations      |

## How to Use These Examples

### Approach 1: Copy and Modify

1. Find similar tool (e.g., `CustomDataTool.ts` for searchable data)
2. Copy the file
3. Rename (e.g., `ArticleTool.ts`)
4. Update names, descriptions
5. Modify logic for your domain

**Time**: 15-30 minutes per tool

### Approach 2: Learn Pattern, Build New

1. Read an example tool
2. Understand the pattern
3. Close the file
4. Build your own from memory
5. Refer back if stuck

**Time**: 30-60 minutes per tool
**Learning**: Deeper understanding

### Approach 3: Mix and Match

1. Keep useful examples as-is
2. Delete irrelevant ones
3. Add your custom tools alongside
4. Deploy mix of examples + custom

**Time**: Variable
**Best for**: Quick prototyping

## Testing Examples

```bash theme={null}
# Test conversationally (primary method)
lua chat

# Try in sandbox mode:
# - "What's the weather in Tokyo?"
# - "Show me your products"
# - "Find movies about space"

# Test individual tools (optional)
lua test

# Select a tool:
# - get_weather: Enter "London"
# - search_products: Enter "laptop"
# - search_movies: Enter "thriller"
```

## Common Patterns Demonstrated

<AccordionGroup>
  <Accordion title="External API Calls">
    **Example**: `GetWeatherTool.ts`

    ```typescript theme={null}
    const response = await fetch(apiUrl);
    const data = await response.json();
    return transformedData;
    ```
  </Accordion>

  <Accordion title="Platform API Usage">
    **Example**: `ProductsTool.ts`

    ```typescript theme={null}
    import { Products } from 'lua-cli';
    const products = await Products.search(query);
    ```
  </Accordion>

  <Accordion title="Vector Search">
    **Example**: `CustomDataTool.ts`

    ```typescript theme={null}
    // Create with search text
    await Data.create('items', data, searchableText);

    // Search semantically
    const results = await Data.search('items', query, 10, 0.7);
    ```
  </Accordion>

  <Accordion title="Multi-Step Workflows">
    **Example**: `BasketTool.ts`

    ```typescript theme={null}
    // Step 1: Create
    const basket = await Baskets.create({...});

    // Step 2: Add items
    await Baskets.addItem(basket.id, {...});

    // Step 3: Checkout
    const order = await Baskets.placeOrder({...}, basket.id);
    ```
  </Accordion>

  <Accordion title="Environment Variables">
    **Example**: `PaymentTool.ts`

    ```typescript theme={null}
    import { env } from 'lua-cli';
    const apiKey = env('STRIPE_API_KEY');
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Weather Tool" icon="cloud" href="/examples/weather">
    Start with external API integration
  </Card>

  <Card title="Custom Data Tools" icon="database" href="/examples/custom-data">
    Learn powerful vector search
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Follow step-by-step tutorial
  </Card>

  <Card title="Template Guide" icon="layer-group" href="/template/overview">
    Understand the project structure
  </Card>
</CardGroup>


# Payment Tool Example
Source: https://docs.heylua.ai/examples/payment

Stripe payment integration with environment variables

## Overview

**File**: `src/tools/PaymentTool.ts`

Demonstrates payment integration using Stripe API with secure environment variable management.

## Complete Code

```typescript theme={null}
import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

export default class CreatePaymentLinkTool implements LuaTool {
  name = "create_payment_link";
  description = "Create a payment checkout link via Stripe";
  
  inputSchema = z.object({
    amount: z.number().positive().describe("Amount in dollars"),
    currency: z.string().default('USD'),
    description: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // ⭐ Get API key from environment
    const stripeKey = env('STRIPE_API_KEY');
    
    // ⭐ Validate it exists
    if (!stripeKey) {
      throw new Error(
        'STRIPE_API_KEY not configured. ' +
        'Please add it to your .env file or use `lua env` for production'
      );
    }
    
    // Create Stripe checkout session
    const response = await fetch('https://api.stripe.com/v1/checkout/sessions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${stripeKey}`,
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        'line_items[0][price_data][currency]': input.currency.toLowerCase(),
        'line_items[0][price_data][unit_amount]': (input.amount * 100).toString(),
        'line_items[0][price_data][product_data][name]': input.description,
        'line_items[0][quantity]': '1',
        'mode': 'payment',
        'success_url': 'https://example.com/success',
        'cancel_url': 'https://example.com/cancel'
      })
    });
    
    if (!response.ok) {
      const error = await response.text();
      throw new Error(`Stripe API error: ${error}`);
    }
    
    const session = await response.json();
    
    return {
      paymentUrl: session.url,
      sessionId: session.id,
      amount: `$${input.amount.toFixed(2)}`,
      message: "Payment link created successfully"
    };
  }
}
```

## Key Concepts

### 1. Environment Variables

**Never hardcode API keys!**

```typescript theme={null}
// ❌ Bad
const apiKey = 'sk_test_abc123';

// ✅ Good
import { env } from 'lua-cli';
const apiKey = env('STRIPE_API_KEY');
```

### 2. Validation

Always check environment variables exist:

```typescript theme={null}
const apiKey = env('STRIPE_API_KEY');

if (!apiKey) {
  throw new Error(
    'STRIPE_API_KEY not configured. ' +
    'Add it to .env file or use `lua env` for production'
  );
}
```

### 3. Error Handling

Handle external API failures gracefully:

```typescript theme={null}
if (!response.ok) {
  const error = await response.text();
  throw new Error(`Stripe API error: ${error}`);
}
```

### 4. Amount Conversion

Stripe uses cents, not dollars:

```typescript theme={null}
// Convert dollars to cents
const amountInCents = input.amount * 100;

'unit_amount': amountInCents.toString()
```

## Setup Required

### 1. Get Stripe API Key

1. Create account at [https://stripe.com](https://stripe.com)
2. Go to Dashboard → Developers → API Keys
3. Copy "Secret key" (starts with `sk_test_`)

### 2. Add to .env File

Create `.env` in project root:

```bash theme={null}
STRIPE_API_KEY=sk_test_your_key_here
```

### 3. Test

```bash theme={null}
lua test
```

Select `create_payment_link`:

* Amount: `29.99`
* Currency: `USD`
* Description: `Product Purchase`

## Customization Ideas

### Add Customer Info

```typescript theme={null}
inputSchema = z.object({
  amount: z.number(),
  customerEmail: z.string().email()
});

// In Stripe API call
body: {
  customer_email: input.customerEmail,
  // ... other fields
}
```

### Add Success/Cancel URLs

```typescript theme={null}
inputSchema = z.object({
  amount: z.number(),
  successUrl: z.string().url(),
  cancelUrl: z.string().url()
});

// Use in API call
'success_url': input.successUrl,
'cancel_url': input.cancelUrl
```

### Add Metadata

```typescript theme={null}
// Track custom data
const orderId = generateOrderId();

body: {
  metadata: {
    orderId,
    source: 'ai_chat',
    timestamp: Date.now()
  }
}
```

## Other Payment Providers

Same pattern works for other providers:

<Tabs>
  <Tab title="PayPal">
    ```typescript theme={null}
    const apiKey = env('PAYPAL_CLIENT_ID');

    // PayPal API integration
    ```
  </Tab>

  <Tab title="Square">
    ```typescript theme={null}
    const apiKey = env('SQUARE_ACCESS_TOKEN');

    // Square API integration
    ```
  </Tab>

  <Tab title="Custom Gateway">
    ```typescript theme={null}
    const apiKey = env('PAYMENT_API_KEY');
    const apiUrl = env('PAYMENT_API_URL');

    // Custom payment integration
    ```
  </Tab>
</Tabs>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Test Keys in Development">
    ```bash theme={null}
    # .env (development)
    STRIPE_API_KEY=sk_test_abc123
    ```

    ```yaml theme={null}
    # lua.skill.yaml (production)
    skill:
      env:
        STRIPE_API_KEY: sk_live_xyz789
    ```
  </Accordion>

  <Accordion title="Never Log API Keys">
    ```typescript theme={null}
    // ❌ Bad
    console.log('API Key:', apiKey);

    // ✅ Good
    console.log('API Key configured:', !!apiKey);
    ```
  </Accordion>

  <Accordion title="Validate Amounts">
    ```typescript theme={null}
    if (input.amount < 0.50) {
      throw new Error('Minimum amount is $0.50');
    }

    if (input.amount > 999999) {
      throw new Error('Amount exceeds maximum limit');
    }
    ```
  </Accordion>

  <Accordion title="Add .env to .gitignore">
    ```
    # .gitignore
    .env
    .env.local
    .env.*.local
    ```
  </Accordion>
</AccordionGroup>

## What You'll Learn

<CardGroup>
  <Card title="Environment Variables" icon="key">
    Secure secret management
  </Card>

  <Card title="External Integration" icon="plug">
    Third-party API integration
  </Card>

  <Card title="Payment Processing" icon="credit-card">
    Real payment workflows
  </Card>

  <Card title="Error Handling" icon="shield">
    Graceful failure handling
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Environment Variables" icon="key" href="/concepts/environment-variables">
    Complete guide to configuration
  </Card>

  <Card title="Environment API" icon="book" href="/api/environment">
    API reference for env()
  </Card>
</CardGroup>


# Proactive Inbox
Source: https://docs.heylua.ai/examples/proactive-inbox

A monitoring skill that pushes notices, approvals, and connection fixes to the user's desk

## What we're building

A refund-monitoring job that watches for anomalies and uses [`User.Inbox.push()`](/api/inbox) to reach the user proactively — the three card kinds working together:

1. A **notice** when a refund spike appears (revised in place as numbers change),
2. An **approval** when the agent has drafted a response and wants a go-ahead,
3. A **connection fix** when the data source it depends on disconnects.

Along the way it handles every receipt outcome — including being `capped` — so the skill degrades gracefully instead of erroring.

## The monitor

```typescript theme={null}
import { User } from 'lua-cli';

async function checkRefunds() {
  const spike = await detectRefundSpike(); // your own logic

  if (!spike) return { status: 'all clear' };

  // ── 1. The notice — keyed, so re-runs REVISE instead of re-knocking ──
  const receipt = await User.Inbox.push({
    title: `${spike.count} refunds on ${spike.sku} within the hour`,
    body: 'All from the same checkout flow — want a summary before it spreads?',
    deeplink: `https://yourdashboard.example.com/refunds?sku=${spike.sku}`,
    priority: spike.count > 5 ? 'urgent' : 'high',
    key: `refund-spike-${spike.sku}`, // stable per incident
  });

  // ── 2. Handle the receipt — capped is a NORMAL outcome ──
  if (receipt.outcome === 'capped') {
    // Budget spent or the org has disabled pushes. Don't retry, don't
    // throw — carry the finding in your run summary instead.
    return {
      status: 'anomaly found',
      note: `Refund spike on ${spike.sku} (${spike.count} in the last hour). ` +
            `Inbox push unavailable: ${receipt.reason}`,
    };
  }

  return { status: 'user notified', outcome: receipt.outcome };
}
```

Run it again while the incident is live and the same card updates silently:

```typescript theme={null}
// Ten minutes later, the spike grew — same key, so the card revises:
await User.Inbox.push({
  title: `9 refunds on ${spike.sku} within the hour`,
  body: 'Still climbing. Draft response ready when you are.',
  key: `refund-spike-${spike.sku}`,
});
// → { outcome: 'updated' } — the card changed, the user was NOT re-notified
```

## Asking for a go-ahead

When the agent has done the work and needs one human click, push an approval — `approve` without options becomes an Approve / Decline pair, and the user's pick resolves the card:

```typescript theme={null}
await User.Inbox.push({
  title: 'Pause the checkout flow for SKU-2481?',
  body: 'The refund spike traces to a broken discount code. I can disable it now.',
  actions: ['approve'],
  priority: 'urgent',
  threadId: currentThreadId, // acting hands off into this conversation
});
```

Or offer real choices:

```typescript theme={null}
await User.Inbox.push({
  title: 'How should I handle the affected orders?',
  body: '12 orders hit the broken discount before I caught it.',
  options: [
    { label: 'Refund all 12', description: 'Full refunds, apology email' },
    { label: 'Honor the discount', description: 'Keep the orders, eat the margin' },
    { label: 'Ask me per order' },
  ],
});
```

## When the data source breaks

If the integration your monitor depends on disconnects, don't fail silently — push the fix. The card deep-links the user straight into reconnecting:

```typescript theme={null}
try {
  await fetchRefundData();
} catch (err) {
  if (isAuthError(err)) {
    await User.Inbox.push({
      title: 'Stripe disconnected',
      body: "Refund monitoring is blind until it's reconnected.",
      actions: ['fix'],
      connection: { type: 'stripe', name: 'Stripe' },
    });
    return { status: 'blocked on connection' };
  }
  throw err;
}
```

## Design notes

* **Key everything that recurs.** A monitor without a `key` mints a new card per run and burns its daily budget by lunch. With a stable key, the whole incident is ONE card that stays current.
* **Let `capped` be boring.** Five pushes per day per user per card class is the contract; your skill should have a summary-shaped fallback ready, not a retry loop.
* **Don't lean on `urgent`.** It's capped at 2/day (the excess lands as `high`), and inside the user's quiet hours even urgent sends **no notification at all** — the card still lands, and that's what you should count on.
* **Test in `lua dev`.** Pushes from dev runs land in your own Inbox, so you can watch the full loop — card, notification, revision, resolution — before your users ever do.


# Proactive Send Example
Source: https://docs.heylua.ai/examples/proactive-send

Schedule agent-initiated outreach with LuaJob + Channels.send

## Overview

This recipe shows how to make your agent **reach out on a schedule** — a daily reminder, a follow-up, a status nudge — by combining a [scheduled job](/api/luajob) with the [Channels API](/api/channels). The same pattern works from [webhooks](/api/luawebhook) and tools.

## What It Does

* Runs every morning on a cron schedule
* Looks up who needs a reminder
* Sends each a WhatsApp message with `Channels.send`
* Falls back to an approved template when the recipient's 24-hour window is closed
* Every send is recorded to the recipient's conversation thread, so replies continue naturally

## Complete Code

```typescript theme={null}
import { LuaJob, Channels } from 'lua-cli';

const appointmentReminders = new LuaJob({
  name: 'appointment-reminders',
  description: 'Send next-day appointment reminders every morning',
  schedule: {
    type: 'cron',
    expression: '0 9 * * *' // every day at 9:00 AM
  },
  execute: async () => {
    const appointments = await getTomorrowsAppointments();

    for (const appt of appointments) {
      try {
        const result = await Channels.send({
          channel: 'whatsapp',
          to: { userId: appt.userId },
          text: `Hi ${appt.name}! Reminder: your appointment is tomorrow at ${appt.time}. Reply here if you need to reschedule.`,
          options: { whatsapp: { onClosedWindow: 'fail' } }
        });

        console.log(`Reminded ${appt.userId} (delivered: ${result.delivered})`);
      } catch {
        // Window closed — start the conversation with an approved template
        await Channels.whatsapp.sendTemplate({
          to: { userId: appt.userId },
          templateName: 'appointment_reminder',
          languageCode: 'en_US',
          components: [
            { type: 'BODY', parameters: [{ type: 'text', text: appt.time }] }
          ],
          messageContext: `Reminded ${appt.name} about their appointment tomorrow at ${appt.time}`
        });
      }
    }
  }
});

export default appointmentReminders;
```

## Key Concepts

<AccordionGroup>
  <Accordion title="Window-aware sending">
    Free-form WhatsApp is only allowed within 24 hours of the user's last message. Setting `onClosedWindow: 'fail'` makes `Channels.send` throw when the window is closed, so the `catch` block can send an approved template instead. (Omit the option to let it **queue** automatically — see [Proactive Messaging](/channels/proactive-messaging#the-whatsapp-24-hour-window).)
  </Accordion>

  <Accordion title="No conversational context in jobs">
    A scheduled job runs outside any conversation, so you address recipients explicitly — here by `to.userId`. You can also target a raw `phoneNumber` or `email` for cold outreach.
  </Accordion>

  <Accordion title="messageContext keeps the agent coherent">
    When you send a template, `messageContext` is the plain-text summary recorded to the thread. When the user replies, your agent sees "Reminded … about their appointment" and continues naturally — not a blank slate.
  </Accordion>
</AccordionGroup>

## Variation: confirm on a webhook event

The same `Channels.send` call works from a [webhook](/api/luawebhook) — for example, confirming a payment the moment your payment provider fires its event:

```typescript theme={null}
import { LuaWebhook, Channels } from 'lua-cli';

const paymentConfirmation = new LuaWebhook({
  name: 'payment-confirmation',
  description: 'Notify the customer when their payment succeeds',
  execute: async (event) => {
    const { customerId, amount } = event.body;

    await Channels.send({
      channel: 'whatsapp',
      to: { userId: customerId },
      text: `Payment of $${amount} received — thank you! 🎉`
    });

    return { notified: true };
  }
});

export default paymentConfirmation;
```

## Next steps

<CardGroup>
  <Card title="Channels API" icon="paper-plane" href="/api/channels">
    Full reference for send, sendTemplate, and email.send
  </Card>

  <Card title="Proactive Messaging" icon="bell" href="/channels/proactive-messaging">
    The model behind agent-initiated messages
  </Card>

  <Card title="LuaJob" icon="calendar" href="/api/luajob">
    Define scheduled tasks
  </Card>

  <Card title="Webhooks" icon="bolt" href="/api/luawebhook">
    React to external events
  </Card>
</CardGroup>


# Products Tools Example
Source: https://docs.heylua.ai/examples/products

Complete CRUD operations for product catalog

## Overview

**File**: `src/tools/ProductsTool.ts`

Six tools demonstrating complete product management with the Products API.

## Tools Included

<CardGroup>
  <Card title="Search" icon="magnifying-glass">
    Find products by query
  </Card>

  <Card title="Get All" icon="list">
    List with pagination
  </Card>

  <Card title="Filter" icon="filter">
    Query by attributes
  </Card>

  <Card title="Create" icon="plus">
    Add new products
  </Card>

  <Card title="Update" icon="pen">
    Modify existing
  </Card>

  <Card title="Delete" icon="trash">
    Remove products
  </Card>
</CardGroup>

## Example Tools

### SearchProductsTool

```typescript theme={null}
import { LuaTool, Products } from 'lua-cli';
import { z } from 'zod';

export class SearchProductsTool implements LuaTool {
  name = "search_products";
  description = "Search products by name or description";
  
  inputSchema = z.object({
    query: z.string().describe("Search query")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Products.search(input.query);
    
    return {
      products: results.map(p => ({
        id: p.id,
        name: p.name,
        price: `$${p.price.toFixed(2)}`,
        inStock: p.inStock
      })),
      count: results.length
    };
  }
}
```

### CreateProductTool

```typescript theme={null}
export class CreateProductTool implements LuaTool {
  name = "create_product";
  description = "Add a new product to the catalog";
  
  inputSchema = z.object({
    name: z.string(),
    price: z.number().positive(),
    category: z.string().optional(),
    sku: z.string().optional(),
    description: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Products.create({
      ...input,
      id: generateId(),  // Generate unique ID
      inStock: true
    });
    
    return {
      success: true,
      productId: result.product.id,
      message: `Product "${input.name}" created`
    };
  }
}
```

### UpdateProductTool

```typescript theme={null}
export class UpdateProductTool implements LuaTool {
  name = "update_product";
  description = "Update product information";
  
  inputSchema = z.object({
    id: z.string(),
    name: z.string().optional(),
    price: z.number().positive().optional(),
    inStock: z.boolean().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const { id, ...updates } = input;
    
    await Products.update(updates, id);
    
    return {
      success: true,
      message: "Product updated successfully"
    };
  }
}
```

### BrowseProductsTool (with Filters)

```typescript theme={null}
export class BrowseProductsTool implements LuaTool {
  name = "browse_products";
  description = "Browse and filter products by category, price, or availability";
  
  inputSchema = z.object({
    category: z.string().optional().describe("Product category"),
    minPrice: z.number().optional().describe("Minimum price"),
    maxPrice: z.number().optional().describe("Maximum price"),
    inStockOnly: z.boolean().optional().describe("Only show in-stock items"),
    page: z.number().optional().default(1)
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Build filter from input
    const filter: Record<string, any> = {};
    
    if (input.category) {
      filter.category = input.category;
    }
    
    if (input.minPrice !== undefined || input.maxPrice !== undefined) {
      filter.price = {};
      if (input.minPrice !== undefined) filter.price.$gte = input.minPrice;
      if (input.maxPrice !== undefined) filter.price.$lte = input.maxPrice;
    }
    
    if (input.inStockOnly) {
      filter.inStock = true;
    }
    
    const results = await Products.get({
      page: input.page,
      limit: 10,
      filter
    });
    
    return {
      products: results.map(p => ({
        id: p.id,
        name: p.name,
        price: `$${p.price.toFixed(2)}`,
        category: p.category,
        inStock: p.inStock
      })),
      pagination: {
        page: results.pagination.currentPage,
        totalPages: results.pagination.totalPages,
        totalProducts: results.pagination.totalCount
      }
    };
  }
}
```

## Use Cases

### E-commerce Catalog

```typescript theme={null}
// Browse products with pagination
const products = await Products.get({ page: 1, limit: 20 });

// Search for specific items (semantic search)
const laptops = await Products.search('laptop');

// Filter by category
const electronics = await Products.get({
  filter: { category: 'Electronics' }
});

// Get product details — laptops is ProductSearchInstance, use .products[0] or index directly
const product = await Products.getById(laptops.products[0].id);
```

### Filtering Products

```typescript theme={null}
// Filter by price range
const affordable = await Products.get({
  filter: {
    price: { $gte: 50, $lte: 200 }
  }
});

// Filter by category and stock status
const availablePhones = await Products.get({
  filter: {
    category: 'Phones',
    inStock: true
  }
});

// Filter by nested fields
const appleProducts = await Products.get({
  filter: {
    'metadata.brand': 'Apple'
  }
});

// Multiple categories
const gadgets = await Products.get({
  filter: {
    category: { $in: ['Phones', 'Tablets', 'Watches'] }
  }
});
```

### Inventory Management

```typescript theme={null}
// Update stock status
await Products.update({ inStock: false }, productId);

// Update price
await Products.update({ price: 899.99 }, productId);

// Get out-of-stock products
const outOfStock = await Products.get({
  filter: { inStock: false }
});

// Bulk update by category
const electronics = await Products.get({
  limit: 100,
  filter: { category: 'Electronics' }
});

for (const product of electronics) {
  await Products.update({ onSale: true }, product.id);
}
```

### Admin Dashboard

```typescript theme={null}
// Get all products
const all = await Products.get({ page: 1, limit: 1000 });

// Statistics
const totalValue = all.reduce((sum, p) => sum + p.price, 0);
const inStock = all.filter(p => p.inStock).length;
const categories = [...new Set(all.map(p => p.category))];

// Get low-stock items (custom field)
const lowStock = await Products.get({
  filter: {
    stockCount: { $lte: 10 },
    inStock: true
  }
});
```

### Using save() Method (New!)

```typescript theme={null}
// Get product and modify multiple fields
const product = await Products.getById('product_123');

// Modify properties directly
product.price = 899.99;
product.inStock = true;
product.category = 'Electronics - Sale';
product.description = 'Updated description';

// Save all changes at once
await product.save();

// Much cleaner than calling update()!
```

### Practical Example: Bulk Price Update

```typescript theme={null}
export class BulkDiscountTool implements LuaTool {
  name = "apply_discount";
  description = "Apply discount to products in a category";
  
  inputSchema = z.object({
    category: z.string(),
    discountPercent: z.number()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Use filter to get only products in the target category
    const products = await Products.get({
      limit: 1000,
      filter: { category: input.category }
    });
    
    let updatedCount = 0;
    for (const product of products.data) {
      // Modify and save
      product.price = product.price * (1 - input.discountPercent / 100);
      await product.save();
      updatedCount++;
    }
    
    return { 
      message: `Discount applied to ${updatedCount} ${input.category} products` 
    };
  }
}
```

## What You'll Learn

<CardGroup>
  <Card title="CRUD Operations" icon="database">
    Create, Read, Update, Delete
  </Card>

  <Card title="Pagination" icon="table">
    Handle large datasets
  </Card>

  <Card title="Search" icon="magnifying-glass">
    Semantic search with vector embeddings
  </Card>

  <Card title="Filtering" icon="filter">
    MongoDB-style queries for structured data
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Products API" icon="book" href="/api/products">
    Complete API reference
  </Card>

  <Card title="Baskets Example" icon="cart-shopping" href="/examples/baskets">
    Add products to carts
  </Card>
</CardGroup>


# User Data Tools Example
Source: https://docs.heylua.ai/examples/user-data

Persistent user storage: state machines, onboarding flows, and preferences

## Overview

**File**: `src/tools/UserDataTool.ts`

Tools demonstrating the User API as a **persistent per-user storage layer** — from simple profile reads to multi-step onboarding state machines.

## Tools Included

### GetUserDataTool

Retrieve current user's information.

```typescript theme={null}
import { LuaTool, User } from 'lua-cli';
import { z } from 'zod';

export class GetUserDataTool implements LuaTool {
  name = "get_user_data";
  description = "Retrieve current user's profile information";
  
  inputSchema = z.object({});

  async execute(input: any) {
    const user = await User.get();
    
    return {
      name: user.name,
      email: user.email,
      id: user.id
    };
  }
}
```

### UpdateUserDataTool

Update user profile information.

```typescript theme={null}
export class UpdateUserDataTool implements LuaTool {
  name = "update_user_data";
  description = "Update user's profile information";
  
  inputSchema = z.object({
    data: z.object({
      name: z.string().optional(),
      phone: z.string().optional(),
      preferences: z.record(z.any()).optional()
    })
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const user = await User.get();
    const updated = await user.update(input.data);
    
    return {
      success: true,
      message: "Profile updated successfully",
      user: updated
    };
  }
}
```

## Use Cases

### Onboarding State Machine (Persistent Across Sessions)

The most powerful use of the User API — track multi-step workflows that persist across conversations. If a user leaves mid-onboarding and comes back days later, your agent picks up exactly where they left off.

```typescript theme={null}
export class OnboardingStepTool {
  name = 'onboarding_step';
  description = 'Advance the user through onboarding, resuming where they left off';

  inputSchema = z.object({
    data: z.record(z.any()).optional().describe('Data collected in this step')
  });

  async execute(input: any) {
    const user = await User.get();

    // This persists across conversations — the user can leave and come back
    const step = user.onboardingStep || 'not_started';

    switch (step) {
      case 'not_started':
        user.onboardingStep = 'collecting_info';
        user.onboardingStartedAt = new Date().toISOString();
        user.completedSteps = [];
        await user.save();
        return { nextAction: 'Ask for company name and role' };

      case 'collecting_info':
        // Accumulate data across multiple tool calls
        user.companyName = input.data?.companyName;
        user.role = input.data?.role;
        user.onboardingStep = 'selecting_plan';
        user.completedSteps = [...(user.completedSteps || []), 'info_collected'];
        await user.save();
        return { nextAction: 'Present plan options' };

      case 'selecting_plan':
        user.plan = input.data?.plan;
        user.onboardingStep = 'complete';
        user.onboardingCompletedAt = new Date().toISOString();
        user.completedSteps = [...(user.completedSteps || []), 'plan_selected'];
        await user.save();
        return { message: `Welcome to the ${user.plan} plan, ${user.companyName}!` };

      case 'complete':
        return {
          message: 'Onboarding already complete!',
          completedAt: user.onboardingCompletedAt,
          plan: user.plan
        };
    }
  }
}
```

### Personalized Greeting

```typescript theme={null}
export class GreetUserTool {
  async execute(input: any) {
    const user = await User.get();
    
    const hour = new Date().getHours();
    const greeting = hour < 12 ? 'Good morning'
      : hour < 18 ? 'Good afternoon'
      : 'Good evening';
    
    return {
      message: `${greeting}, ${user.name}! How can I help you today?`
    };
  }
}
```

### User Preferences

```typescript theme={null}
export class SavePreferencesTool {
  async execute(input: { theme: string, language: string }) {
    const user = await User.get();
    
    await user.update({
      preferences: {
        theme: input.theme,
        language: input.language,
        updatedAt: new Date().toISOString()
      }
    });
    
    return { message: "Preferences saved!" };
  }
}
```

### Using save() Method (New!)

```typescript theme={null}
export class UpdateProfileTool {
  async execute(input: { name: string, email: string, phone: string }) {
    const user = await User.get();
    
    // Modify properties directly
    user.name = input.name;
    user.email = input.email;
    user.phone = input.phone;
    
    // Save all changes at once
    await user.save();
    
    return { 
      message: "Profile updated successfully!",
      user: {
        name: user.name,
        email: user.email,
        phone: user.phone
      }
    };
  }
}
```

### Sending Messages to Users (New!)

```typescript theme={null}
export class SendOrderUpdateTool {
  async execute(input: { orderId: string, status: string }) {
    const user = await User.get();
    
    // Send notification to user
    await user.send([
      {
        type: "text",
        text: `Hi ${user.name}! Your order #${input.orderId} is now ${input.status}.`
      },
      {
        type: "text",
        text: "Thank you for your purchase!"
      }
    ]);
    
    return { message: "Notification sent to user" };
  }
}
```

### Sending Images and Files (New!)

```typescript theme={null}
export class SendReceiptTool {
  async execute(input: { orderId: string, receiptData: string, qrCode: string }) {
    const user = await User.get();
    
    // Send receipt with QR code
    await user.send([
      {
        type: "text",
        text: `Receipt for order #${input.orderId}`
      },
      {
        type: "image",
        image: input.qrCode,
        mediaType: "image/png"
      },
      {
        type: "file",
        data: input.receiptData,
        mediaType: "application/pdf"
      }
    ]);
    
    return { message: "Receipt sent to user" };
  }
}
```

## What You'll Learn

<CardGroup>
  <Card title="Persistent State" icon="database">
    Store onboarding progress, workflow state, and custom data across sessions
  </Card>

  <Card title="State Machines" icon="arrows-spin">
    Build multi-step flows that resume where the user left off
  </Card>

  <Card title="Platform APIs" icon="server">
    Using Lua's built-in User API
  </Card>

  <Card title="save() Method" icon="floppy-disk">
    Simpler workflow for multiple changes
  </Card>

  <Card title="Messaging Users" icon="message">
    Send proactive notifications
  </Card>

  <Card title="Media Support" icon="image">
    Send images and files to users
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="User API Reference" icon="book" href="/api/user">
    Complete API documentation
  </Card>

  <Card title="Products Example" icon="box" href="/examples/products">
    See CRUD operations
  </Card>
</CardGroup>


# Weather Tool Example
Source: https://docs.heylua.ai/examples/weather

External API integration without requiring an API key

## Overview

**File**: `src/tools/GetWeatherTool.ts`

The Weather Tool demonstrates external API integration using the free Open-Meteo API (no API key required).

## What It Does

* Fetches real-time weather for any city worldwide
* Two-step process: geocoding + weather data
* Error handling for invalid cities
* No API key or authentication required

## Complete Code

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class GetWeatherTool implements LuaTool {
  name = "get_weather";
  description = "Get current weather conditions for any city";
  
  inputSchema = z.object({
    city: z.string().describe("City name (e.g., 'London', 'Tokyo')")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // Step 1: Convert city name to coordinates
    const geoUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(input.city)}&count=1`;
    const geoRes = await fetch(geoUrl);
    const geoData = await geoRes.json();
    
    if (!geoData.results?.[0]) {
      throw new Error(`City not found: ${input.city}`);
    }
    
    const { latitude, longitude, name } = geoData.results[0];
    
    // Step 2: Get weather for coordinates
    const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current_weather=true`;
    const weatherRes = await fetch(weatherUrl);
    const weatherData = await weatherRes.json();
    
    return {
      city: name,
      temperature: weatherData.current_weather.temperature,
      windSpeed: weatherData.current_weather.windspeed,
      weatherCode: weatherData.current_weather.weathercode
    };
  }
}
```

## Key Concepts

### 1. Two-Step API Call

**Why?** Weather APIs need coordinates, but users provide city names.

```typescript theme={null}
// Step 1: City name → Coordinates
const geoData = await fetch(geocodingUrl);
const { latitude, longitude } = geoData.results[0];

// Step 2: Coordinates → Weather
const weatherData = await fetch(weatherUrl);
```

### 2. URL Encoding

Always encode user input in URLs:

```typescript theme={null}
const geoUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(input.city)}&count=1`;
```

### 3. Error Handling

Check if city exists before proceeding:

```typescript theme={null}
if (!geoData.results?.[0]) {
  throw new Error(`City not found: ${input.city}`);
}
```

### 4. Structured Return

Return organized data, not raw API response:

```typescript theme={null}
return {
  city: name,              // Clean city name
  temperature: data.temp,  // Extract what's needed
  windSpeed: data.wind     // No extra data
};
```

## Testing

```bash theme={null}
lua test
```

Try different cities:

* `London` - Should work
* `Tokyo` - Should work
* `New York` - Should work
* `XYZ123` - Should fail gracefully

## Customization Ideas

### Add Temperature Units

```typescript theme={null}
inputSchema = z.object({
  city: z.string(),
  units: z.enum(['metric', 'imperial']).default('metric')
});

// In URL
const weatherUrl = `...&temperature_unit=${units === 'imperial' ? 'fahrenheit' : 'celsius'}`;
```

### Add Weather Recommendations

```typescript theme={null}
return {
  ...weatherData,
  recommendation: temperature < 10 
    ? "🧥 Bring a warm jacket"
    : temperature < 20
    ? "👕 Light jacket recommended"
    : "☀️ T-shirt weather!"
};
```

### Add Forecast

```typescript theme={null}
const forecastUrl = `...&forecast_days=7`;
const forecast = await fetch(forecastUrl);

return {
  current: {...},
  forecast: forecast.daily
};
```

## What You'll Learn

<CardGroup>
  <Card title="External APIs" icon="plug">
    How to call external REST APIs
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    Graceful error messages
  </Card>

  <Card title="Data Transformation" icon="shuffle">
    Converting API responses to clean output
  </Card>

  <Card title="URL Encoding" icon="link">
    Safely encoding user input in URLs
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="User Data Example" icon="user" href="/examples/user-data">
    Learn platform API usage
  </Card>

  <Card title="Payment Example" icon="credit-card" href="/examples/payment">
    See authenticated external API
  </Card>
</CardGroup>


# Actions Component
Source: https://docs.heylua.ai/formatting/actions

Interactive buttons and quick replies

## Overview

The **Actions** component presents clickable action buttons that users can tap to take next steps.

<Card title="Perfect for:" icon="hand-pointer">
  Call-to-action buttons, quick replies, navigation options after showing information
</Card>

## Format

```
::: actions
- Action Label 1
- Action Label 2
- Action Label 3
:::
```

## Requirements

* ✅ Maximum **10 actions**
* ✅ Clear, action-oriented language
* ✅ Only actions your agent can handle
* ✅ Most relevant first

## Examples

### After Product Listing

```
::: actions
- Add to Cart
- View Details
- Compare Products
- Check Store Availability
- Save for Later
:::
```

<Frame>
  <img alt="Action buttons rendered in the Lua Pop web widget" />
</Frame>

*Action buttons rendered in the Lua Pop web widget.*

### After Hotel Rooms

```
::: actions
- Book This Room
- See More Photos
- Check Other Dates
- View Amenities
- Get Directions
:::
```

### After Support Article

```
::: actions
- Mark as Solved
- Still Need Help
- Read Related Articles
- Contact Human Agent
:::
```

## How to Configure

```typescript theme={null}
persona: `
  After showing options to users, ALWAYS provide relevant actions:
  
  ::: actions
  - [Primary action]
  - [Secondary action]
  - [Alternative action]
  :::
  
  Examples:
  - After products: "Add to Cart", "View Details"
  - After rooms: "Book Now", "See Photos"
  - After articles: "Read More", "Share"
`
```

## Best Practices

* Use verbs: "Book", "View", "Check"
* Be specific: "Add to Cart" not "Continue"
* Limit to 5-7 for best UX
* Order by importance

## Next Steps

<Card title="Links Component" icon="link" href="/formatting/links">
  Learn about displaying URLs
</Card>


# Documents Component
Source: https://docs.heylua.ai/formatting/documents

Send downloadable files and attachments to users

## Overview

The **Documents** component sends downloadable files to users — PDFs, contracts, invoices, images, and any other file type. Each document displays as a clickable card with a filename and opens in a new tab.

## Format

```
::: documents
[Display Name](https://url-to-file.pdf) filename:filename.pdf mime:application/pdf
:::
```

You can include multiple files in a single block:

```
::: documents
[Display Name 1](https://url-to-file1.pdf) filename:file1.pdf mime:application/pdf
[Display Name 2](https://url-to-file2.docx) filename:file2.docx mime:application/vnd.openxmlformats-officedocument.wordprocessingml.document
:::
```

### Fields

| Field            | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `[Display Name]` | The label shown to the user on the file card             |
| `(url)`          | Direct URL to the file (use the Lua CDN for uploads)     |
| `filename:`      | The actual filename with extension (e.g. `contract.pdf`) |
| `mime:`          | The MIME type of the file (e.g. `application/pdf`)       |

## Example

```
::: documents
[Loan Agreement](https://cdn.heylua.ai/2a46d577-77d1-490a-9148-b11243000da8.pdf) filename:loan_agreement.pdf mime:application/pdf
[Terms & Conditions](https://cdn.heylua.ai/5f32c891-aa2d-41bc-9e12-c33410000ec9.pdf) filename:terms_and_conditions.pdf mime:application/pdf
:::
```

<Frame>
  <img alt="Document cards rendered in the Lua Pop web widget" />
</Frame>

*Document cards rendered in the Lua Pop web widget.*

## Common MIME Types

| File Type     | MIME Type                                                                 |
| ------------- | ------------------------------------------------------------------------- |
| PDF           | `application/pdf`                                                         |
| Word (.docx)  | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| Excel (.xlsx) | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       |
| PNG image     | `image/png`                                                               |
| JPEG image    | `image/jpeg`                                                              |
| CSV           | `text/csv`                                                                |

## Configure in Persona

```typescript theme={null}
persona: `
  After completing a loan application, send the agreement documents using:
  
  ::: documents
  [Loan Agreement](url) filename:loan_agreement.pdf mime:application/pdf
  :::
  
  Always confirm the user has received the documents.
`
```

## Upload Files with the CDN

Use the Lua CDN API to upload files before referencing them in the documents component. The CDN returns a permanent URL you can include in the block.

<Card title="CDN API" icon="cloud-arrow-up" href="/api/cdn">
  Upload files and get permanent URLs
</Card>

## Best For

* Loan agreements and contracts
* Invoices and receipts
* Policy documents
* Onboarding packets
* Reports and summaries
* Any user-facing file download

<Card title="Payment Component" icon="credit-card" href="/formatting/payment">
  Next: Payment links
</Card>


# Flow Component
Source: https://docs.heylua.ai/formatting/flow

Send WhatsApp Flows as interactive forms inside the chat

## Overview

The **Flow** component sends a [WhatsApp Flow](https://developers.facebook.com/docs/whatsapp/flows) as an interactive message with a CTA button. When the user taps the button, a multi-screen form opens inside WhatsApp — they fill it in and submit it, all without leaving the chat.

Flows are built in **WhatsApp Manager** (not in Lua). The agent just needs to know the Flow ID to send it.

<Warning>
  **WhatsApp only** — This component only works on WhatsApp. On other channels, the raw `:::` block will be sent as plain text.
</Warning>

<Frame>
  <img alt="A WhatsApp Flow: the message with a CTA button, the multi-screen form, and the confirmation" />
</Frame>

*A WhatsApp Flow in action — the message with its CTA button, the multi-screen form the user fills in, and the confirmation. Example from [Meta's WhatsApp Flows documentation](https://developers.facebook.com/docs/whatsapp/flows).*

## Format

```
::: flow
flow_id=<FLOW_ID>
flow_cta=<Button text>
body=<Message body shown above the button>
:::
```

### Required Fields

| Field      | Description                                           |
| ---------- | ----------------------------------------------------- |
| `flow_id`  | The Flow ID from WhatsApp Manager (e.g. `1234567890`) |
| `flow_cta` | Text on the CTA button (max 30 characters, no emoji)  |

### Optional Fields

| Field    | Description                                                                                              |
| -------- | -------------------------------------------------------------------------------------------------------- |
| `body`   | Message body text shown above the CTA button. Falls back to the text outside the `:::` block if omitted. |
| `header` | Header text shown above the body                                                                         |
| `footer` | Footer text shown below the body                                                                         |
| `screen` | The screen ID to open first (defaults to the flow's entry screen)                                        |

<Note>
  The parser is flexible on separators — it accepts `=` or `:`, with or without spaces or quotes around values. All of these work:

  ```
  flow_id=123
  flow_id = 123
  flow_id: 123
  body="Hello world"
  body='Hello world'
  body = Hello world
  ```
</Note>

<Warning>
  **Each field must be on its own line.** The parser splits the block on newlines, then runs a `key[:=]value` regex per line. A single-line variant like `::: flow flow_id=1 flow_cta=Go body=Hi :::` will be silently dropped — the greedy regex captures the rest of the line into `flow_id`, leaving `flow_cta` unset and failing the required-fields check. If the Flow isn't rendering, this is usually why.
</Warning>

## Examples

### Simple — OTP / Password Entry

```
Please tap below to securely enter your verification code.

::: flow
flow_id=9876543210
flow_cta=Enter Code
body=Tap to enter your verification code securely
:::
```

The user sees a message with a "Enter Code" button. Tapping it opens the flow form where they can type their code in a password field — hidden from the chat history.

### With Header and Footer

```
::: flow
flow_id=1122334455
flow_cta=Book Appointment
body=Select your preferred date and time
header=Schedule a Visit
footer=Available Mon-Fri, 9am-5pm
:::
```

### With Specific Start Screen

```
::: flow
flow_id=5566778899
flow_cta=Start Survey
body=We'd love your feedback! It only takes 2 minutes.
screen=FEEDBACK_SCREEN
:::
```

## How the Response Works

When the user completes the flow and submits, the agent receives a message like:

```
User completed a WhatsApp Flow. Submitted data:
- name: John Smith
- email: john@example.com
- appointment_date: 2025-03-15
(flow_token: abc123)
```

The agent can then process the submitted data as normal conversation context.

<Note>
  **Password/passcode fields** are automatically excluded from the WhatsApp chat summary UI (since Flows v5.1). However, the submitted values **are still included in the webhook payload** and will appear in the agent's conversation history.
</Note>

## Handling Sensitive Data

WhatsApp hides password/passcode fields from the chat summary UI, but the raw values still arrive in the webhook and get stored in conversation history. There are two approaches depending on your security needs:

### Option A: Preprocessor masking (basic)

Use a [preprocessor](/overview/preprocessors) to mask sensitive fields before the agent sees the current message. Note that the original values may still appear in stored conversation history.

```typescript theme={null}
// Detect flow response messages and mask fields matching sensitive patterns
const SENSITIVE_PATTERNS = [/password/i, /passcode/i, /secret/i, /pin/i, /otp/i, /code/i];

// Replace values with [REDACTED] before the agent processes the message
```

### Option B: Flow with endpoint (recommended for sensitive data)

For truly secure handling (OTP validation, password checks), use a **flow with a data exchange endpoint**. The sensitive data is validated server-side *inside* the flow before it closes. The `complete` payload only sends the validation result (e.g., `"otp_verified": true`), so the raw value never reaches the agent or conversation history.

This requires setting up an encrypted endpoint — see [WhatsApp Flows endpoint documentation](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint) for details.

## Configure

Tell your agent in **Persona** or **Skill Context** which flow to use and when:

```
context: `
  When the user needs to enter their verification code,
  send them the secure input flow:

  ::: flow
  flow_id=9876543210
  flow_cta=Enter Code
  body=Tap to securely enter your verification code
  :::

  After they submit, you'll receive their input as
  "User completed a WhatsApp Flow. Submitted data:"
  followed by the form fields.
`
```

## Finding Your Flow ID

1. Go to **WhatsApp Manager** > **Account tools** > **Flows**
2. Click on your flow
3. The Flow ID is shown in the URL or flow details

Only **Published** flows can be sent to users. Draft flows can be sent for testing using the API with `mode=draft`.

## Best For

* Appointment booking forms
* Lead generation & sign-up forms
* Customer feedback surveys
* Order details collection
* Any structured data collection that benefits from a form UI
* OTP / password / PIN entry (hidden from WhatsApp chat UI; for full security, use a flow with endpoint)


# Horizontal-List-Item Component (Carousel)
Source: https://docs.heylua.ai/formatting/horizontal-list-item

Display items in a horizontally scrollable carousel format

## Overview

The **Horizontal-List-Item** component displays items as a horizontally scrollable **Media Card Carousel**. This is ideal for showcasing multiple options in a compact, swipeable format.

<Card title="Perfect for:" icon="images">
  Product categories, menu sections, room options, service packages - any list where visual browsing is key
</Card>

<Warning>
  **WhatsApp Only**: This component currently only works on WhatsApp Business. On other channels, it falls back to the standard list-item format.
</Warning>

## Format

```
::: horizontal-list-item
![image](Image-URL)
#Item Title
##Item Subheading
Brief description of the item.
:::
```

## Requirements & Limitations

<CardGroup>
  <Card title="Minimum 2 Items" icon="hashtag">
    At least 2 items required for carousel
  </Card>

  <Card title="Maximum 10 Items" icon="hashtag">
    Up to 10 items per carousel. More items split into multiple carousels.
  </Card>

  <Card title="Image Required" icon="image">
    Each item MUST have an image. A placeholder is used if missing.
  </Card>

  <Card title="Unique Titles" icon="fingerprint">
    Each item must have a unique heading
  </Card>
</CardGroup>

### Meta/WhatsApp Restrictions

<Warning>
  These are restrictions imposed by Meta's WhatsApp Business API:
</Warning>

| Restriction        | Limit                                |
| ------------------ | ------------------------------------ |
| Cards per carousel | 2-10                                 |
| Card body text     | 160 characters max                   |
| Header text        | 60 characters max                    |
| Image format       | JPEG, PNG                            |
| Buttons per card   | Up to 2 (quick reply, URL, or phone) |

<Note>
  **Template Approval**: Carousel templates require Meta approval. The system creates templates automatically when you first use this component. The first request falls back to list-item format while templates are pending approval (\~30 seconds to a few minutes).
</Note>

### Current Implementation Defaults

<Info>
  These are current implementation choices that may become configurable in the future:
</Info>

| Setting            | Current Value                                          |
| ------------------ | ------------------------------------------------------ |
| Button per card    | 1 quick reply with text "Select"                       |
| Button payload     | `#Header` (sent to agent when user taps)               |
| Template body text | `Results: {remainderText}. Browse below.`              |
| Card body format   | `Details: {header + subHeading + body}. Select below.` |
| Default image      | Lua placeholder when no image provided                 |

**Parameter mapping from component:**

```
::: horizontal-list-item
![image](image-url)        → Card header image
#Item Title                → Button payload + part of card body
##Subheading               → Part of card body
Description text here.     → Part of card body
:::
```

The card body combines all text (`#Title - ##Subheading - Description`) into a single parameter, truncated to 135 characters to fit WhatsApp's 160 char limit with the static text.

When user taps "Select", the agent receives: `Select: *Item Title*`

## Complete Examples

### Product Categories

```
::: horizontal-list-item
![image](https://cdn.example.com/hot-drinks.jpg)
#Hot Drinks
##12 Options Available
Explore our selection of coffees, teas, and specialty hot beverages.
:::

::: horizontal-list-item
![image](https://cdn.example.com/cold-drinks.jpg)
#Cold Drinks
##8 Options Available
Refreshing iced coffees, smoothies, and cold brew options.
:::

::: horizontal-list-item
![image](https://cdn.example.com/desserts.jpg)
#Desserts
##6 Options Available
Sweet treats including cakes, pastries, and seasonal specials.
:::
```

### Menu Items

```
::: horizontal-list-item
![image](https://cdn.example.com/latte.jpg)
#Caramel Latte
##$4.50 - Popular
Rich espresso with steamed milk and caramel syrup. Available hot or iced.
:::

::: horizontal-list-item
![image](https://cdn.example.com/cappuccino.jpg)
#Classic Cappuccino
##$3.75 - Best Seller
Double shot espresso with velvety foam. Perfect morning pick-me-up.
:::

::: horizontal-list-item
![image](https://cdn.example.com/mocha.jpg)
#Chocolate Mocha
##$4.25 - Customer Favorite
Espresso meets rich chocolate. Topped with whipped cream.
:::
```

### Hotel Rooms

```
::: horizontal-list-item
![image](https://hotel.example.com/standard.jpg)
#Standard Room
##$120/night - 5 Available
Comfortable room with queen bed, city view, and modern amenities.
:::

::: horizontal-list-item
![image](https://hotel.example.com/deluxe.jpg)
#Deluxe Suite
##$200/night - 2 Available
Spacious suite with king bed, ocean view, and private balcony.
:::

::: horizontal-list-item
![image](https://hotel.example.com/penthouse.jpg)
#Penthouse
##$450/night - 1 Available
Luxury penthouse with panoramic views, jacuzzi, and butler service.
:::
```

## How It Works

### First-Time Use

1. Agent responds with `horizontal-list-item` components
2. System checks if carousel templates exist
3. If templates don't exist:
   * Creates templates in background (async)
   * Falls back to list-item format for this request
4. Templates submitted to Meta for approval (\~30 sec to minutes)
5. Next request uses the approved carousel templates

### User Interaction

When a user taps "Select" on a carousel card:

* The agent receives: `Select: *Item Title*`
* Example: `Select: *Caramel Latte*`

This allows the agent to know exactly which item the user selected.

## How to Configure

### In Persona

```yaml theme={null}
persona: |
  When showing product categories or menu sections, use horizontal-list-item for a carousel view:
  
  ::: horizontal-list-item
  ![image](category-image-url)
  #Category Name
  ##Item Count or Key Info
  Brief description of the category.
  :::
  
  Requirements:
  - Minimum 2 items, maximum 10 items per carousel
  - Always include an image for each item
  - Keep descriptions under 160 characters
```

### In Skill Context

```typescript theme={null}
const menuSkill = new LuaSkill({
  context: `
    When showing menu categories, format as horizontal carousel:
    
    ::: horizontal-list-item
    ![image](category.imageUrl)
    #category.name
    ##category.itemCount items
    category.description
    :::
    
    This creates a swipeable carousel on WhatsApp.
    Minimum 2 categories required for carousel format.
  `
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Use for Visual Browsing">
    ```
    ✅ Good use cases:
    - Product categories
    - Menu sections  
    - Room types
    - Service tiers

    ❌ Not ideal for:
    - Single items
    - Text-heavy content
    - Sequential steps
    ```
  </Accordion>

  <Accordion title="✅ Keep Text Concise">
    ```
    ✅ Good:
    Rich espresso with steamed milk. Available hot or iced.

    ❌ Bad:
    Our signature caramel latte is made with premium espresso beans 
    sourced from Colombia, combined with locally sourced organic milk 
    that is perfectly steamed to 160°F... (too long - will be truncated)
    ```
  </Accordion>

  <Accordion title="✅ Use High-Quality Images">
    * Square or landscape orientation works best
    * Images are automatically cropped to wide ratio
    * Use HTTPS URLs
    * Ensure images load quickly
  </Accordion>

  <Accordion title="✅ Provide Meaningful Subheadings">
    ```
    ✅ Good:
    ##$4.50 - Popular
    ##12 Options Available
    ##$200/night - 2 Available

    ❌ Bad:
    ##Info
    ##Details
    ##Click here
    ```
  </Accordion>
</AccordionGroup>

## Comparison: List-Item vs Horizontal-List-Item

| Feature     | List-Item          | Horizontal-List-Item  |
| ----------- | ------------------ | --------------------- |
| Layout      | Vertical (stacked) | Horizontal (carousel) |
| Channels    | All channels       | WhatsApp only         |
| Min items   | 1                  | 2                     |
| Max items   | 10                 | 10 (per carousel)     |
| Image       | Optional           | Required              |
| Interaction | View only          | "Select" button       |
| Best for    | Detailed listings  | Visual browsing       |

## Fallback Behavior

When horizontal-list-item can't render as a carousel:

| Situation                  | Behavior                       |
| -------------------------- | ------------------------------ |
| Non-WhatsApp channel       | Falls back to list-item        |
| Less than 2 items          | Falls back to list-item        |
| Templates pending approval | Falls back to list-item        |
| More than 10 items         | Splits into multiple carousels |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Carousel not showing on first use">
    This is expected! The first request creates templates which need Meta approval.
    The response falls back to list-item format. Try again in 30 seconds to a few minutes.
  </Accordion>

  <Accordion title="Getting list-item format instead of carousel">
    Check:

    1. Are you on WhatsApp? (carousel is WhatsApp-only)
    2. Do you have at least 2 items?
    3. Have templates been approved? (check agent logs)
  </Accordion>

  <Accordion title="Images not displaying">
    Ensure images are:

    * Using HTTPS URLs
    * Publicly accessible
    * In JPEG or PNG format
    * Loading within reasonable time
  </Accordion>

  <Accordion title="Text being truncated">
    WhatsApp limits card body to 160 characters. Keep descriptions concise.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="List-Item Component" icon="list" href="/formatting/list-item">
    Standard vertical list format
  </Card>

  <Card title="Actions Component" icon="hand-pointer" href="/formatting/actions">
    Add interactive buttons
  </Card>

  <Card title="WhatsApp Channel" icon="whatsapp" href="/channels/whatsapp">
    Set up WhatsApp integration
  </Card>

  <Card title="Configure Persona" icon="user" href="/cli/persona-command">
    Add formatting instructions
  </Card>
</CardGroup>


# Images Component
Source: https://docs.heylua.ai/formatting/images

Display image galleries and multiple photos

## Overview

The **Images** component displays multiple images in gallery format.

## Format

```
::: images
![image](Image-URL-1)
![image](Image-URL-2)
![image](Image-URL-3)
:::
```

## Example

```
::: images
![image](https://example.com/product-front.jpg)
![image](https://example.com/product-side.jpg)
![image](https://example.com/product-back.jpg)
:::
```

<Frame>
  <img alt="Image gallery rendered in the Lua Pop web widget" />
</Frame>

*An image gallery rendered in the Lua Pop web widget.*

## Configure

```typescript theme={null}
persona: `
  When showing product photos, use images component:
  
  ::: images
  ![image](photo-1)
  ![image](photo-2)
  :::
  
  Always show multiple angles.
`
```

## Best For

* Product photos
* Property images
* Menu item photos
* Before/after
* Gallery views

<Card title="Payment Component" icon="credit-card" href="/formatting/payment">
  Next: Payment links
</Card>


# Response Formatting
Source: https://docs.heylua.ai/formatting/introduction

Create rich, visual responses across all channels

## Overview

Make your agent's responses visually appealing with **formatting components** that work across WhatsApp, Facebook, Instagram, Email, Slack, and your website.

<Warning>
  **Important**: You must explicitly instruct your agent in the **Persona** or **Skill Context** to use these components. They won't be used automatically!
</Warning>

<Note>
  These components work in **proactive messages** too — the `text` you pass to [`Channels.send`](/api/channels) (and `user.send()`) supports the same `:::` blocks, rendered on channels that support them. See [Proactive Messaging](/channels/proactive-messaging#components-in-proactive-messages).
</Note>

## 10 Visual Components

<CardGroup>
  <Card title="List-Item" icon="list" href="/formatting/list-item">
    **Products, rooms, menus**

    Structured lists with images, titles, and descriptions
  </Card>

  <Card title="Horizontal-List-Item" icon="images" href="/formatting/horizontal-list-item">
    **Carousel display**

    Swipeable cards for visual browsing (WhatsApp only)
  </Card>

  <Card title="Actions" icon="hand-pointer" href="/formatting/actions">
    **Interactive buttons**

    Clickable action buttons for next steps
  </Card>

  <Card title="Links" icon="link" href="/formatting/links">
    **Web URLs**

    Links with rich previews
  </Card>

  <Card title="Images" icon="image" href="/formatting/images">
    **Photo galleries**

    Multiple images in gallery format
  </Card>

  <Card title="Documents" icon="file" href="/formatting/documents">
    **File downloads**

    Send PDFs, contracts, invoices, and other files
  </Card>

  <Card title="Payment" icon="credit-card" href="/formatting/payment">
    **Checkout links**

    Secure payment and booking links
  </Card>

  <Card title="Flow" icon="rectangle-list" href="/formatting/flow">
    **Interactive forms**

    WhatsApp Flows for secure data collection (WhatsApp only)
  </Card>

  <Card title="Navigate" icon="arrow-up-right-from-square" href="/formatting/navigate">
    **Website navigation**

    Direct users to pages (WebChat only)
  </Card>

  <Card title="Reaction" icon="face-smile" href="/formatting/reaction">
    **Emoji reactions**

    React to the user's message instead of replying
  </Card>
</CardGroup>

## Quick Example

### E-commerce Product Response

**Without formatting:**

```
We have the UltraBook Pro for $1,299 and Student Laptop for $599.
```

**With formatting:**

```
::: list-item
![image](https://cdn.example.com/laptop-pro.jpg)
# UltraBook Pro
$1,299 · In Stock — 16GB RAM, 512GB SSD. Free 2-day shipping.
:::

::: list-item
![image](https://cdn.example.com/laptop-student.jpg)
# Student Laptop
$599 · Available — 8GB RAM, 256GB SSD. One-year warranty.
:::

::: actions
- Add to Cart
- Compare Laptops
- View Full Specs
:::
```

**Result**: Beautiful visual cards with images, structured info, and clickable actions!

<Frame>
  <img alt="Formatted response rendered in the Lua Pop chat widget" />
</Frame>

*The formatted markup above, rendered as visual cards in the Lua Pop chat widget.*

## How to Configure

Tell your agent in **Persona** or **Skill Context**:

```typescript theme={null}
persona: `
  When showing products, use list-item format:
  
  ::: list-item
  ![image](url)
  # Product Name
  $Price · Stock. Description here.
  :::
  
  Then provide actions:
  
  ::: actions
  - Add to Cart
  - View Details
  :::
`
```

<Card title="Complete Configuration Guide" icon="book" href="/cli/persona-command">
  Learn how to configure your agent's persona
</Card>

## Platform Support

Most components work across all channels:

* ✅ WhatsApp Business
* ✅ Facebook Messenger
* ✅ Instagram Messenger
* ✅ Email
* ✅ Slack
* ✅ Website (LuaPop)

<Note>
  **Channel-specific components:**

  * **Navigate** - WebChat/LuaPop only (requires onNavigate handler)
  * **Horizontal-List-Item** - WhatsApp only (falls back to list-item on other channels)
  * **Flow** - WhatsApp only (sends interactive WhatsApp Flows for secure data collection)
  * **Reaction** - WhatsApp, Instagram, Facebook Messenger, Slack, iMessage, and web chat (ignored elsewhere)
</Note>

## Explore Components

Click on any component in the left sidebar to see:

* Complete format specification
* Multiple examples across channels
* How to configure in persona/context
* Best practices
* Troubleshooting

<CardGroup>
  <Card title="Start with List-Item" icon="list" href="/formatting/list-item">
    Most commonly used component
  </Card>

  <Card title="Add Actions" icon="hand-pointer" href="/formatting/actions">
    Make responses interactive
  </Card>

  <Card title="Configure Persona" icon="user" href="/cli/persona-command">
    Add formatting instructions
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Verify formatting works
  </Card>
</CardGroup>


# Links Component
Source: https://docs.heylua.ai/formatting/links

Display web URLs and search results

## Overview

The **Links** component displays URLs with rich previews - perfect for web search results or documentation links.

## Format

```
::: links
![link](URL-1)
![link](URL-2)
![link](URL-3)
:::
```

## Example

```
::: links
![link](https://docs.example.com/getting-started)
![link](https://docs.example.com/api-reference)
![link](https://support.example.com/troubleshooting)
:::
```

<Frame>
  <img alt="Link preview cards rendered in the Lua Pop web widget" />
</Frame>

*Link preview cards rendered in the Lua Pop web widget.*

## Configure in Persona

```yaml theme={null}
persona: |
  When user asks for documentation or web resources:
  
  ::: links
  ![link](relevant-url-1)
  ![link](relevant-url-2)
  :::
```

## Best For

* Web search results
* Documentation links
* Support articles
* External resources

<Card title="Images Component" icon="image" href="/formatting/images">
  Next: Display image galleries
</Card>


# List-Item Component
Source: https://docs.heylua.ai/formatting/list-item

Display structured lists of products, rooms, menu items, or articles

## Overview

The **List-Item** component displays structured information in a visually appealing format across all channels.

<Card title="Perfect for:" icon="list">
  Products, hotel rooms, menu items, articles, search results - any list of options
</Card>

## Format

```
::: list-item
![image](Image-URL)
# Item Title
Brief summary of the item (price, availability, key details — max ~40 words).
:::
```

<Note>
  The title must be a `# ` line (hash **followed by a space**). There is no separate subheading — put the price, stock, or other key details at the start of the description.
</Note>

## Requirements

<CardGroup>
  <Card title="Unique Titles" icon="fingerprint">
    Each item must have a unique title
  </Card>

  <Card title="10 Item Max" icon="hashtag">
    Maximum 10 items per response
  </Card>

  <Card title="Images Optional" icon="image">
    Include when available
  </Card>

  <Card title="Concise" icon="text">
    \~40 words max per summary
  </Card>
</CardGroup>

## Complete Examples

### E-commerce Product

```
::: list-item
![image](https://cdn.example.com/laptop-pro.jpg)
# UltraBook Pro Laptop
$1,299.00 · In Stock. Professional-grade laptop with 16GB RAM, 512GB SSD, and a stunning 14" Retina display. Perfect for developers and content creators. Free 2-day shipping.
:::
```

<Frame>
  <img alt="List-items rendered in the Lua Pop web widget" />
</Frame>

*List-items rendered in the Lua Pop web widget.*

### Hotel Room

```
::: list-item
![image](https://hotel.example.com/deluxe-ocean.jpg)
# Deluxe Ocean View Suite
$250/night · 3 rooms available. Spacious suite with king bed, private ocean-facing balcony, and modern amenities. Includes complimentary breakfast, WiFi, and parking. Maximum 2 guests.
:::
```

### Restaurant Menu Item

```
::: list-item
![image](https://restaurant.example.com/pasta-special.jpg)
# Chef's Seafood Linguine
$24.99 · Available tonight. Handmade linguine with fresh seafood, cherry tomatoes, and basil in a white wine sauce. Served with garlic bread. Gluten-free option on request.
:::
```

## How to Configure

### In Persona

```yaml theme={null}
persona: |
  When showing products, ALWAYS use list-item format:
  
  ::: list-item
  ![image](product-image-url)
  # Product Name
  $Price · Stock status. Product description here.
  :::
  
  Format each product individually. Maximum 10 products per response.
```

### In Skill Context

```typescript theme={null}
const ecommerceSkill = new LuaSkill({
  context: `
    When search_products returns results, format each as:
    
    ::: list-item
    ![image](product.imageUrl)
    # product.name
    $product.price · product.stockStatus. product.description
    :::
    
    Always include image if available.
  `
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Make Titles Unique">
    ```
    ✅ Good:
    # Deluxe Ocean View
    # Standard Garden View

    ❌ Bad:
    # Room Option
    # Room Option
    ```
  </Accordion>

  <Accordion title="✅ Lead the Description with Key Info">
    There's no subheading — open the description with price, availability, or other key details.

    ```
    ✅ Good:
    # Deluxe Ocean View
    $250/night · Available. King bed, private balcony.

    ❌ Bad:
    # Deluxe Ocean View
    A room.
    ```
  </Accordion>

  <Accordion title="✅ Keep Descriptions Concise">
    ```
    ✅ Good: ~40 words with key features
    ❌ Bad: 200 word essay
    ```
  </Accordion>

  <Accordion title="✅ Use Quality Images">
    * High resolution
    * Direct image URLs
    * Web-accessible (HTTPS)
    * Representative of item
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Actions Component" icon="hand-pointer" href="/formatting/actions">
    Add interactive buttons after lists
  </Card>

  <Card title="Configure Persona" icon="user" href="/cli/persona-command">
    Add formatting instructions
  </Card>
</CardGroup>


# Navigate Component
Source: https://docs.heylua.ai/formatting/navigate

Direct users to specific pages on your website

## Overview

The **Navigate** component lets your agent send users to a specific page on your website — pricing, a product, checkout, docs, or any path.

<Card title="WebChat / Lua Pop only" icon="globe">
  This component only works in the website chat widget (Lua Pop) and requires an `onNavigate` handler in your widget config.
</Card>

## Format

```
::: navigate
![navigate](/pathname?param1=value1&param2=value2)
:::
```

* `pathname` — a relative page path (e.g. `/pricing`, `/products/laptop`, `/checkout`)
* `?param=value` — optional query parameters

<Warning>
  Navigate **renders nothing in the chat** — no button or link. When the message arrives, the widget strips the block and immediately calls your `onNavigate` handler, so navigation happens automatically. Always include a line of context before the block so the jump isn't a surprise.
</Warning>

## How it works

<Steps>
  <Step title="Agent includes a navigate block">
    ```
    Our pricing starts at $300/month. Here's the full breakdown:

    ::: navigate
    ![navigate](/pricing?channel=web)
    :::
    ```
  </Step>

  <Step title="Widget calls your onNavigate handler">
    ```javascript theme={null}
    onNavigate("/pricing", { query: { channel: "web" } });
    ```
  </Step>

  <Step title="Your code performs the navigation">
    Route the user using your framework (see below).
  </Step>
</Steps>

## Configure the onNavigate handler

Navigation only works if you pass an `onNavigate` handler to the widget. It receives the `pathname` and an options object with the parsed `query` params.

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  onNavigate: (pathname, options) => {
    // pathname: "/pricing"
    // options.query: { channel: "web" }
    const params = new URLSearchParams(options.query).toString();
    window.location.href = params ? `${pathname}?${params}` : pathname;
  }
});
```

Using a router? Swap the last line for your framework:

```javascript theme={null}
// React Router
navigate({ pathname, search: new URLSearchParams(options.query).toString() });

// Next.js
router.push({ pathname, query: options.query });

// Vue Router
router.push({ path: pathname, query: options.query });
```

## Query parameters

Pass data to the destination page through the URL:

```
::: navigate
![navigate](/products/laptop?source=chat&campaign=spring)
:::
```

```javascript theme={null}
onNavigate("/products/laptop", {
  query: { source: "chat", campaign: "spring" }
});
```

Common uses: attribution (`?source=chat`), pre-filling forms (`?product=123`), campaigns (`?promo=SAVE10`), or opening a specific tab/filter (`?tab=specs`).

## Tell your agent to use it

Components are never used automatically — instruct the agent in its **persona** or a **skill context**:

```yaml theme={null}
persona: |
  You are a shopping assistant for TechStore.

  After describing a product, send the user to its page:

  ::: navigate
  ![navigate](/products/PRODUCT_SLUG?source=chat)
  :::

  For pricing questions, send them to pricing:

  ::: navigate
  ![navigate](/pricing?channel=chat)
  :::

  Always add source=chat for tracking.
```

## Best practices

<AccordionGroup>
  <Accordion title="Add context before the block">
    Because navigation is automatic, precede the block with a sentence about where the user is going (e.g. "Here's the full pricing breakdown:") so the jump feels intentional.
  </Accordion>

  <Accordion title="Use relative paths">
    Prefer `/pricing` or `/products/123` over absolute URLs like `https://yoursite.com/pricing` — relative paths route correctly through `onNavigate`.
  </Accordion>

  <Accordion title="Include tracking parameters">
    Add `?source=chat` (or similar) so you can measure how much traffic and conversion comes from the agent.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nothing happens">
    Make sure an `onNavigate` handler is passed to `window.LuaPop.init()`. Without it the block is stripped but no navigation occurs. Check the console for errors and confirm the pathname is relative.
  </Accordion>

  <Accordion title="Query parameters missing">
    Use a single `?` and join params with `&`: `/page?a=1&b=2` (not `/page?a=1?b=2`).
  </Accordion>

  <Accordion title="Agent never navigates">
    The agent only uses the component if you instruct it in the persona or skill context with the exact format shown above.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Widget Configuration" icon="cog" href="/chat-widget/configuration">
    Set up the onNavigate handler
  </Card>

  <Card title="Widget Events" icon="bolt" href="/chat-widget/events">
    All widget callbacks and events
  </Card>

  <Card title="Response Formatting" icon="list" href="/formatting/introduction">
    Explore the other components
  </Card>
</CardGroup>


# Payment Component
Source: https://docs.heylua.ai/formatting/payment

Secure payment and checkout links

## Overview

The **Payment** component displays secure payment links for checkout, bookings, or invoices.

## Format

```
::: payment
[Link text describing payment](Payment-URL)
:::
```

## Example

```
::: payment
[Complete your $1,299 order payment](https://checkout.stripe.com/session_abc123)
:::
```

<Frame>
  <img alt="Payment button rendered in the Lua Pop web widget" />
</Frame>

*A payment link rendered as a button in the Lua Pop web widget.*

## Configure

```typescript theme={null}
context: `
  After creating order, provide payment:
  
  ::: payment
  [Complete payment for Order #ID](payment-url)
  :::
  
  Include order number and amount.
`
```

## Best For

* Checkout flows
* Booking payments
* Invoice links
* Subscription payments

<Card title="All Components" icon="list" href="/formatting/introduction">
  Explore all response formatting components
</Card>


# Reaction Component
Source: https://docs.heylua.ai/formatting/reaction

React with an emoji to the user's message instead of sending a new one

## Overview

The **Reaction** component lets your agent react with a single emoji to the user message it's replying to — the same tap-and-hold reaction a person would leave, instead of (or as well as) a text reply.

<Warning>
  **Renders no message content.** Reaction doesn't produce a bubble in the chat — it attaches an emoji to the message it's reacting to. A reply that's *only* a reaction block sends no text at all.
</Warning>

## Format

```
::: reaction
emoji=👍
:::
```

* `emoji` — a single emoji to react with. One emoji only, and at most one reaction per reply.

<Note>
  The parser is flexible on the separator — it accepts `=` or `:`:

  ```
  emoji=👍
  emoji: 👍
  ```
</Note>

## Why use it

Reaction can be the agent's **entire response** — that's the point. It's ideal for acknowledging or concluding a conversation without sending another message that invites a reply. If the user says "thanks, that's all I needed," reacting 👍 closes the loop; sending "You're welcome!" as text just prompts another reply.

```
::: reaction
emoji=👍
:::
```

## Platform support

Reaction only works on channels that support native message reactions. Elsewhere the block is ignored — nothing is sent or rendered.

| Platform                                | Support                                                                                                                   |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| WhatsApp                                | Full support                                                                                                              |
| Instagram                               | Full support                                                                                                              |
| Facebook Messenger                      | Fixed reaction set only: like, love, haha, wow, sad, angry, dislike, smile. Only emoji that map to one of these are sent. |
| Slack                                   | Common emoji only, mapped to Slack reaction names. Requires the Slack app to have the `reactions:write` bot scope.        |
| iMessage                                | Mapped to the closest tapback: love, like, dislike, laugh, emphasize, or question.                                        |
| Web chat (WebChat, LuaPop, Lua Desktop) | Rendered as an emoji badge on the user's message. On older clients the block is stripped and nothing is rendered.         |
| Email, SMS, Teams, and other channels   | Ignored — the block is stripped and nothing is sent or rendered.                                                          |

<Warning>
  **Slack requires `reactions:write`.** Without this bot scope, Slack reactions silently fail to send. See [Required bot scopes](/channels/slack#required-bot-scopes).
</Warning>

## Tell your agent to use it

Components are never used automatically — instruct the agent in its **persona** or a **skill context**:

```yaml theme={null}
persona: |
  You are a support assistant for Acme.

  When the user says goodbye or indicates they're done, don't send
  another message — just react to their message instead:

  ::: reaction
  emoji=👍
  :::
```

## Best practices

<AccordionGroup>
  <Accordion title="Use it to end a conversation cleanly">
    A closing "You're welcome!" or "Glad I could help!" invites another reply. Reacting 👍 to a goodbye acknowledges it without extending the exchange.
  </Accordion>

  <Accordion title="Stick to common emoji">
    Slack maps emoji to a fixed set of reaction names and Messenger maps to a fixed reaction set (like/love/haha/wow/sad/angry/dislike/smile). Uncommon or highly specific emoji may not have a mapping on those channels and won't be sent.
  </Accordion>

  <Accordion title="Don't rely on it as your only channel-specific logic">
    On unsupported channels the block is silently dropped — no error, no fallback text. If the reaction is meaningful to the interaction (not just a nicety), pair it with persona instructions that also work as plain text on channels without reaction support.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nothing happens">
    Confirm the channel supports reactions (WhatsApp, Instagram, Facebook Messenger, Slack, or iMessage). On any other channel the block is stripped silently — this is expected, not a bug.
  </Accordion>

  <Accordion title="Reaction not appearing on Slack">
    Check that the Slack app has the `reactions:write` bot scope under **OAuth & Permissions**. See [Required bot scopes](/channels/slack#required-bot-scopes).
  </Accordion>

  <Accordion title="Wrong tapback on iMessage / wrong reaction on Messenger">
    Both channels map your emoji to a fixed set rather than sending it as-is. iMessage maps to the closest tapback (love, like, dislike, laugh, emphasize, question); Messenger maps to like, love, haha, wow, sad, angry, dislike, or smile. If your emoji doesn't map cleanly, pick one closer to those sets.
  </Accordion>

  <Accordion title="Agent never reacts">
    The agent only uses the component if you instruct it in the persona or skill context with the exact format shown above.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Response Formatting" icon="list" href="/formatting/introduction">
    Explore the other components
  </Card>

  <Card title="Slack Channel" icon="slack" href="/channels/slack">
    Connect Slack and configure bot scopes
  </Card>
</CardGroup>


# Your First Skill
Source: https://docs.heylua.ai/getting-started/first-skill

Build a complete task management skill from scratch

## Build a Task Management Skill

Let's build a complete skill that manages tasks (create, list, complete, delete).

## Step 1: Initialize Project

```bash theme={null}
mkdir task-management-skill
cd task-management-skill
lua init
```

Follow the prompts to create a new agent.

## Step 2: Clean Up Template

Remove unnecessary example files:

```bash theme={null}
rm src/tools/ProductsTool.ts
rm src/tools/BasketTool.ts
rm src/tools/OrderTool.ts
rm src/tools/PaymentTool.ts
rm src/tools/GetWeatherTool.ts
```

## Step 3: Create Task Tool

Create `src/tools/TaskTool.ts`:

```typescript theme={null}
import { LuaTool, Data } from "lua-cli";
import { z } from "zod";

export class CreateTaskTool implements LuaTool {
  name = "create_task";
  description = "Create a new task";
  
  inputSchema = z.object({
    title: z.string().describe("Task title"),
    description: z.string().optional(),
    priority: z.enum(['low', 'medium', 'high']).default('medium'),
    dueDate: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const task = await Data.create('tasks', {
      ...input,
      status: 'pending',
      createdAt: new Date().toISOString()
    }, input.title + ' ' + (input.description || ''));
    
    return {
      taskId: task.id,
      message: `Task "${input.title}" created`
    };
  }
}

export class ListTasksTool implements LuaTool {
  name = "list_tasks";
  description = "List all tasks, optionally filtered by status";
  
  inputSchema = z.object({
    status: z.enum(['pending', 'in_progress', 'completed']).optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const filter = input.status ? { status: input.status } : {};
    const result = await Data.get('tasks', filter, 1, 50);
    
    return {
      tasks: result.data.map(entry => ({
        id: entry.id,
        ...entry.data
      })),
      count: result.pagination.totalCount
    };
  }
}

export class CompleteTaskTool implements LuaTool {
  name = "complete_task";
  description = "Mark a task as completed";
  
  inputSchema = z.object({
    taskId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const task = await Data.getEntry('tasks', input.taskId);
    
    await Data.update('tasks', input.taskId, {
      ...task.data,
      status: 'completed',
      completedAt: new Date().toISOString()
    });
    
    return {
      success: true,
      message: `Task "${task.data.title}" marked as completed`
    };
  }
}

export class SearchTasksTool implements LuaTool {
  name = "search_tasks";
  description = "Search tasks by content";
  
  inputSchema = z.object({
    query: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const results = await Data.search('tasks', input.query, 20, 0.6);
    
    return {
      tasks: results.map(entry => ({
        id: entry.id,
        ...entry.data,
        relevance: entry.score
      }))
    };
  }
}
```

## Step 4: Create Agent with Skill

Update `src/index.ts` to use the **LuaAgent pattern**:

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  CreateTaskTool,
  ListTasksTool,
  CompleteTaskTool,
  SearchTasksTool
} from "./tools/TaskTool";

// Create the task management skill
const taskSkill = new LuaSkill({
  name: "task-management-skill",
  description: "Manage tasks and to-do lists with creation, listing, completion, and search",
  context: `
    This skill helps users manage their tasks.
    
    - Use create_task when users want to add a new task
    - Use list_tasks to show all tasks or filter by status
    - Use complete_task when users finish a task
    - Use search_tasks to find tasks by content
    
    Always confirm task details before creating.
    When listing tasks, organize by priority and due date.
  `,
  tools: [
    new CreateTaskTool(),
    new ListTasksTool(),
    new CompleteTaskTool(),
    new SearchTasksTool()
  ]
});

// Create agent
export const agent = new LuaAgent({
  name: "task-assistant",
  
  persona: `You are a helpful task management assistant.
  
Your role:
- Help users create and organize their tasks
- Keep track of todos and deadlines
- Search for tasks when needed
- Mark tasks as complete

Communication style:
- Friendly and encouraging
- Clear and concise
- Confirm actions before executing
- Provide helpful summaries

Capabilities:
- Create new tasks with title, description, priority, and due date
- List all tasks or filter by status
- Search tasks semantically
- Mark tasks as completed

Always confirm task details with users before creating them.`,

  
  skills: [taskSkill]
});
```

<Note>
  Use `LuaAgent` to configure your agent with persona, welcome message, and skills in one place.
</Note>

## Step 5: Test Your Tools

### Test Individual Tools

```bash theme={null}
lua test
```

Select tools and test:

* **create\_task**: Create a task to buy milk
* **list\_tasks**: View all pending tasks
* **complete\_task**: Mark a task as done
* **search\_tasks**: Find tasks about "meeting"

### Test Conversationally

```bash theme={null}
lua chat
```

Try these in the chat:

* "Create a task to buy milk"
* "Show me my pending tasks"
* "Mark the milk task as done"
* "Find all tasks about meetings"

<Check>
  Your task management skill is now working!
</Check>

## Step 6: Deploy

When you're satisfied with your skill:

```bash theme={null}
# Upload to server
lua push

# Deploy to production
lua deploy
```

## Step 7: Test on Real Channels (Optional)

Want to test your agent on WhatsApp, Facebook, Instagram, or other platforms?

<Card title="Quick Testing Channels" icon="mobile" href="/channels/quick-testing">
  Link your agent to existing Lua channels for instant testing without channel setup
</Card>

**Example for WhatsApp:**

```
https://wa.me/13023778932?text=link-me-to:YOUR_AGENT_ID
```

Replace `YOUR_AGENT_ID` with your agent ID from `lua.skill.yaml`

## What You Built

<CardGroup>
  <Card title="4 Tools" icon="wrench">
    Create, list, complete, and search tasks
  </Card>

  <Card title="Custom Data" icon="database">
    Uses Lua's Data API for storage
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    Semantic search for finding tasks
  </Card>

  <Card title="Type Safe" icon="shield">
    Full TypeScript with Zod validation
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Add More Features">
    * Delete tasks
    * Update task details
    * Set reminders
    * Add tags
  </Step>

  <Step title="Improve User Experience">
    * Better error messages
    * Confirmation prompts
    * Progress indicators
  </Step>

  <Step title="Explore Other Examples">
    <Card title="Tool Examples" icon="layer-group" href="/examples/overview">
      See 30+ working examples
    </Card>
  </Step>
</Steps>

## Common Patterns Used

### Pattern: Data Storage

```typescript theme={null}
await Data.create('collection', data, searchableText);
```

Creates entries with optional vector search indexing.

### Pattern: Semantic Search

```typescript theme={null}
await Data.search('collection', query, limit, threshold);
```

Finds similar items based on meaning, not just exact matches.

### Pattern: CRUD Operations

```typescript theme={null}
await Data.get('collection', filter);
await Data.getEntry('collection', id);
await Data.update('collection', id, data);
await Data.delete('collection', id);
```

### Pattern: Input Validation

```typescript theme={null}
inputSchema = z.object({
  title: z.string(),
  status: z.enum(['pending', 'completed']).optional()
});
```

Zod schemas provide runtime validation and TypeScript types.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot find module 'lua-cli'">
    Install dependencies:

    ```bash theme={null}
    npm install
    ```
  </Accordion>

  <Accordion title="Task not found error">
    Make sure you're using the correct task ID from the list\_tasks response.
  </Accordion>

  <Accordion title="Search returns no results">
    * Lower the score threshold: `0.6` instead of `0.7`
    * Check that tasks have searchable text
    * Try broader search terms
  </Accordion>
</AccordionGroup>


# Installation
Source: https://docs.heylua.ai/getting-started/installation

Install Lua CLI and set up your development environment

## Prerequisites

<CardGroup>
  <Card title="Node.js" icon="node-js">
    Version 16.0.0 or higher
  </Card>

  <Card title="npm" icon="npm">
    Version 7.0.0 or higher
  </Card>
</CardGroup>

## Installation Methods

### Global Installation (Recommended)

Install Lua CLI globally to use it from anywhere:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g lua-cli
  ```

  ```bash yarn theme={null}
  yarn global add lua-cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g lua-cli
  ```
</CodeGroup>

Verify installation:

```bash theme={null}
lua --version
```

### Using Package Runners (No Installation)

Run Lua CLI without installing:

<CodeGroup>
  ```bash npx theme={null}
  npx lua-cli [command]
  ```

  ```bash yarn theme={null}
  yarn dlx lua-cli [command]
  ```

  ```bash pnpm theme={null}
  pnpm dlx lua-cli [command]
  ```
</CodeGroup>

<Note>
  Package runners are great for trying out Lua CLI, but global installation is recommended for regular use.
</Note>

## Authentication

After installation, set up your credentials:

```bash theme={null}
lua auth configure
```

### Authentication Methods

<Tabs>
  <Tab title="Email (Recommended)">
    **Sign in with a renewable session**

    1. Choose **Email**.
    2. Enter your email address and the six-digit code sent to you.
    3. The CLI saves a renewable first-party session.

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: Email
    ? Enter your email address: you@example.com
    ? Enter the OTP code: 123456
    ✅ Signed in as you@example.com.
    ```
  </Tab>

  <Tab title="API Key">
    **Existing API Key**

    If you already have a scoped or non-dotted legacy API key:

    1. Choose **API Key**.
    2. Enter your API key.
    3. The CLI validates and saves it unchanged.

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: API Key
    ? Enter your API key: api_abc123def456...
    🔐 Validating API key...
    ✅ API key validated and saved securely.
    ```
  </Tab>
</Tabs>

### Credential precedence

The CLI reads credentials in this order:

1. `LUA_API_KEY`; if it is not exported, the CLI loads it from the current project's `.env`
2. The renewable session for the active Lua environment
3. `~/.lua-cli/credentials`

Email login writes an owner-only session file under `~/.lua-cli/sessions/`. Direct API-key setup writes `~/.lua-cli/credentials`. Existing API keys remain supported alongside Email login.

<Warning>
  Never commit your API key to version control or share it publicly.
</Warning>

## Verify Installation

Check that everything is working:

```bash theme={null}
# Check CLI version
lua --version

# View stored API key
lua auth key

# Get help
lua --help
```

## Development Tools

While not required, these tools enhance the development experience:

<CardGroup>
  <Card title="VS Code" icon="code">
    Recommended editor with TypeScript support
  </Card>

  <Card title="Git" icon="git">
    Version control for your skills
  </Card>
</CardGroup>

## TypeScript Setup

The template project includes TypeScript configuration. No additional setup needed!

When you run `lua init`, you get:

* `tsconfig.json` - TypeScript configuration
* `package.json` - Dependencies
* Full type definitions for all Lua APIs

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found: lua">
    **Problem**: The CLI isn't in your PATH

    **Solutions**:

    * Reinstall globally: `npm install -g lua-cli`
    * Use npx instead: `npx lua-cli [command]`
    * Check npm global path: `npm config get prefix`
  </Accordion>

  <Accordion title="Permission denied">
    **Problem**: Need sudo for global installation

    **Solution on Unix**:

    ```bash theme={null}
    sudo npm install -g lua-cli
    ```

    **Better solution**: Configure npm to install globally without sudo:

    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    export PATH=~/.npm-global/bin:$PATH
    ```
  </Accordion>

  <Accordion title="API key not found">
    **Problem**: Authentication not configured

    **Solution**:

    ```bash theme={null}
    lua auth configure
    ```
  </Accordion>

  <Accordion title="Node.js version too old">
    **Problem**: Node.js version is below 16.0.0

    **Solution**: Update Node.js

    * Visit [https://nodejs.org](https://nodejs.org)
    * Download and install LTS version
    * Or use nvm: `nvm install --lts`
  </Accordion>
</AccordionGroup>

## Next Steps

<Steps>
  <Step title="Create Your First Project">
    ```bash theme={null}
    mkdir my-skill && cd my-skill
    lua init
    ```
  </Step>

  <Step title="Explore the Template">
    Learn about the example tools and skills included

    <Card title="Template Guide" icon="layer-group" href="/template/overview" />
  </Step>

  <Step title="Start Building">
    Begin customizing tools for your use case

    <Card title="Building Skills" icon="hammer" href="/template/building-skills" />
  </Step>
</Steps>


# Quick Start
Source: https://docs.heylua.ai/getting-started/quick-start

Get your first AI skill running in 5 minutes

## 🚀 Quick Start (5 Minutes)

Get from zero to your first deployed AI skill in minutes.

<Steps>
  <Step title="Install the CLI">
    <CodeGroup>
      ```bash npm theme={null}
      npm install -g lua-cli
      ```

      ```bash yarn theme={null}
      yarn global add lua-cli
      ```

      ```bash pnpm theme={null}
      pnpm add -g lua-cli
      ```
    </CodeGroup>
  </Step>

  <Step title="Set up authentication">
    ```bash theme={null}
    lua auth configure
    ```

    Choose **Email** and follow the prompts:

    1. Enter your email address and the six-digit code sent to you.
    2. The CLI signs you in with a renewable user session.

    Each project's `lua.skill.yaml` selects its agent. If you already have a working scoped or legacy key, choose **API Key** to keep using it unchanged.
  </Step>

  <Step title="Create your first skill">
    ```bash theme={null}
    mkdir my-first-skill && cd my-first-skill
    lua init
    ```

    Choose "Create new agent" and follow prompts to set up your agent

    After init, the CLI typically surfaces a suggested loop: compile → test → sandbox chat → push & deploy — use it as your default checklist before customizing code.
  </Step>

  <Step title="Test it locally">
    ```bash theme={null}
    lua test
    ```

    Select a tool and try it out with different inputs!
  </Step>

  <Step title="Test and verify">
    ```bash theme={null}
    # Production path: push, deploy (or push with --auto-deploy), then traffic, then logs
    lua push && lua deploy
    lua chat -m "your first test"

    # Then check the logs (nothing appears until deployed AND you have generated traffic)
    lua logs --type skill --limit 5
    ```

    Every successful build has a verify step. The CLI suggests the next command after each action — follow the `✨ Tip:` and `💡 Diagnose:` hints printed at the end of `lua push`, `lua chat`, and `lua test`. After `lua push` without `--auto-deploy`, your code is staged but not live until you `lua deploy`. After every chat turn the CLI also runs a quiet `agent_error` probe and warns you if any pipeline errors fired during your test.

    For the full canonical loop, see [Debugging your agent — the post-deploy loop](/cli/debugging).
  </Step>
</Steps>

<Check>
  **Congratulations!** You now have a working AI skill! 🎉
</Check>

## What You Just Created

When you ran `lua init`, you got:

* ✅ Multiple skill examples
* ✅ 30+ tool examples
* ✅ Integration with all Lua platform APIs
* ✅ TypeScript configuration
* ✅ Ready to customize and deploy

## Try These Commands

### Test Individual Tools

```bash theme={null}
lua test
```

Select tools to test:

* `get_weather` - Enter city: "London"
* `search_products` - Enter query: "laptop"
* `create_basket` - Create a shopping cart

### Test Your Tools

```bash theme={null}
lua test
```

Try testing these tools:

* `get_weather` - Enter "Tokyo"
* `search_products` - Enter "laptop"
* `create_basket` - Create a shopping cart
* `add_to_basket` - Add items to cart

## Test on Real Channels

Want to test your agent on WhatsApp, Facebook, Instagram, Email, or Slack **without setting up your own channels?**

<Card title="Quick Testing Channels" icon="bolt" href="/channels/quick-testing">
  Link your agent to existing Lua channels for instant testing on any platform
</Card>

## Next Steps

<CardGroup>
  <Card title="AI Agent Building Guide" icon="robot" href="/ai-guide">
    Using Cursor, Windsurf, or Copilot? Complete guide for AI IDEs
  </Card>

  <Card title="Test on Real Channels" icon="mobile" href="/channels/quick-testing">
    Test your agent on WhatsApp, Facebook, Instagram, and more
  </Card>

  <Card title="Understand the Template" icon="layer-group" href="/template/overview">
    Learn about the 30+ example tools included
  </Card>

  <Card title="Learn Core Concepts" icon="book" href="/concepts/skills-and-tools">
    Understand skills, tools, and how they work
  </Card>

  <Card title="Explore CLI Commands" icon="terminal" href="/cli/overview">
    Master all available CLI commands
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Dive into the complete API documentation
  </Card>

  <Card title="Set Up Your Own Channels" icon="plug" href="/channels/introduction">
    Connect your own channels for production
  </Card>
</CardGroup>

## Common First Tasks

<AccordionGroup>
  <Accordion title="Customize an Example Tool">
    1. Open `src/tools/GetWeatherTool.ts`
    2. Modify the `execute` function
    3. Save the file (auto-reloads in dev mode)
    4. Test in the chat interface
  </Accordion>

  <Accordion title="Create a New Tool">
    1. Create `src/tools/MyTool.ts`
    2. Implement the `LuaTool` interface
    3. Add to skill in `src/index.ts`
    4. Run `lua test` to try it
  </Accordion>

  <Accordion title="Deploy to Production">
    ```bash theme={null}
    lua push      # Upload version
    lua deploy    # Deploy to production
    ```
  </Accordion>

  <Accordion title="Remove Unused Examples">
    1. Delete tool files you don't need from `src/tools/`
    2. Update `src/index.ts` to remove references
    3. Test with `lua test`
  </Accordion>
</AccordionGroup>

## Need Help?

<CardGroup>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Chat with other builders, get help, and share your projects
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.heylua.ai">
    Complete guides and references
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@lua.ai">
    Contact our support team
  </Card>
</CardGroup>


# Shopify
Source: https://docs.heylua.ai/integrations/shopify

Add AI shopping assistant to your Shopify store

## Overview

### About Shopify

**Shopify** is the world's leading e-commerce platform, powering over 4 million online stores globally. From small businesses to enterprise brands, Shopify provides everything you need to sell products online - inventory management, payment processing, shipping, and a beautiful storefront.

### Transform Your Shopify Store with AI

The **Lua AI Shopping Assistant** turns your Shopify store into an AI-powered sales machine. Instead of customers browsing alone, they get a personal shopping assistant available 24/7 across WhatsApp, Instagram, Facebook Messenger, and your website.

**The Impact:**

* 🚀 **Boost Conversions** - AI guides customers from browsing to checkout
* 💬 **Multi-Channel Sales** - Sell on social media with the same AI assistant
* ⏰ **24/7 Availability** - Never miss a sale, even at 3 AM
* 🎯 **Personalized Shopping** - AI recommends products based on preferences
* 📱 **Meet Customers Anywhere** - Website, WhatsApp, Instagram, Facebook
* ⚡ **Instant Responses** - No waiting for human agents
* 💰 **Higher Cart Values** - AI upsells and cross-sells intelligently

<CardGroup>
  <Card title="Shopify App Store" icon="shopify">
    Official verified Shopify app
  </Card>

  <Card title="10-Minute Setup" icon="clock">
    Install and configure in minutes
  </Card>

  <Card title="Multi-Channel Sales" icon="broadcast-tower">
    WhatsApp, Instagram, Facebook, Website
  </Card>

  <Card title="AI-Powered" icon="robot">
    Smart product search and recommendations
  </Card>
</CardGroup>

## App Store Link

<Card title="Lua AI Shopping Assistant on Shopify" icon="shopify" href="https://apps.shopify.com/lua-shopping-assistant">
  Visit the Shopify App Store to install
</Card>

## Features

According to the [Shopify App Store](https://apps.shopify.com/lua-shopping-assistant):

* 🔍 **AI-powered product search** - Help customers find exactly what they need
* 💡 **Personalized recommendations** - Smart product suggestions
* 🛒 **Cart creation in chat** - Build carts directly in conversations
* 💳 **Checkout links** - One-click checkout from chat
* 📱 **Multi-channel** - Messenger, Instagram, WhatsApp, Website
* 🌍 **Multi-language** - Supports 100+ languages
* 📊 **Analytics** - Track conversions and engagement
* ⚡ **Fast setup** - Less than 10 minutes to launch

**Rating**: ⭐⭐⭐⭐⭐ 5.0

***

## Installation from Shopify App Store

<Steps>
  <Step title="Visit Shopify App Store">
    Go to the [Lua AI Shopping Assistant](https://apps.shopify.com/lua-shopping-assistant) page

    Or search for "Lua AI Shopping Assistant" in Shopify App Store
  </Step>

  <Step title="Click Install">
    Click the "Install" button on the app page

    <Frame>
      <img alt="Shopify install button" />
    </Frame>

    *Screenshot: Shopify App Store page with "Install" button highlighted*
  </Step>

  <Step title="Accept Access Request">
    Shopify will ask for permissions. Review and click "Install"

    <Frame>
      <img alt="Accept permissions" />
    </Frame>

    *Screenshot: Permission request dialog showing:*

    * Read/write products
    * Read/write orders
    * Read customer data
    * "Install" button
  </Step>

  <Step title="Installation Complete">
    App installs and admin dashboard loads

    <Frame>
      <img alt="Admin dashboard loaded" />
    </Frame>

    *Screenshot: Lua admin dashboard loaded within Shopify admin*
  </Step>
</Steps>

***

## Activate Chat Widget on Website

After installation, enable the chat widget on your storefront:

<Steps>
  <Step title="Navigate to Online Store">
    In Shopify admin: **Sales Channels** → **Online Store**

    <Frame>
      <img alt="Online Store menu" />
    </Frame>

    *Screenshot: Shopify sidebar showing Sales Channels → Online Store*
  </Step>

  <Step title="Go to Themes">
    Click **Themes** → **Customize**

    <Frame>
      <img alt="Themes customize button" />
    </Frame>

    *Screenshot: Themes page with "Customize" button*
  </Step>

  <Step title="Open App Embeds">
    In the theme customizer, click **App embeds** in the left sidebar

    <Frame>
      <img alt="App embeds menu" />
    </Frame>

    *Screenshot: Theme customizer showing "App embeds" in left navigation*
  </Step>

  <Step title="Find LuaPop Chat">
    Locate "LuaPop Chat" in the app embeds list

    <Frame>
      <img alt="LuaPop in app embeds" />
    </Frame>

    *Screenshot: App embeds list showing "LuaPop Chat" with toggle*
  </Step>

  <Step title="Toggle Active & Customize">
    1. Toggle the switch to **Active**
    2. Customize appearance:
       * Position (Bottom Right, Bottom Left, etc.)
       * Theme (Light or Dark)
       * Button text
       * Colors and styling

    <Frame>
      <img alt="Customize LuaPop" />
    </Frame>

    *Screenshot: LuaPop settings panel showing:*

    * Active toggle (ON)
    * Position dropdown
    * Theme selector
    * Button text field
    * Color pickers
    * Styling options
  </Step>

  <Step title="Save Changes">
    Click **Save** in the top right corner

    <Frame>
      <img alt="Save button" />
    </Frame>

    *Screenshot: Theme customizer with "Save" button highlighted in top right*
  </Step>
</Steps>

***

## Styling & Customization

For complete styling options and customization:

<Card title="Chat Widget Styling Guide" icon="palette" href="/chat-widget/styling">
  Complete guide to colors, positioning, themes, and custom styles →
</Card>

All LuaPop customization options are available in the Shopify app embed settings!

***

## What Your Agent Can Do

With Shopify integration, your agent can:

* 🔍 **Product Search** - Find items in your catalog
* 📦 **Product Details** - Specs, pricing, availability, reviews
* 🛒 **Cart Creation** - Build carts in chat conversations
* 💳 **Checkout Links** - Generate one-click checkout URLs
* 📍 **Order Tracking** - Check order status and shipping
* 💡 **Smart Recommendations** - Personalized product suggestions
* ❓ **Answer Questions** - Product info, shipping, returns, policies
* 🌐 **Multi-Channel** - Same assistant on web, WhatsApp, Instagram, Facebook

***

## Multi-Channel Setup

The Shopify app supports multiple channels beyond website chat:

<CardGroup>
  <Card title="WhatsApp" icon="whatsapp">
    Connect WhatsApp Business
  </Card>

  <Card title="Instagram" icon="instagram">
    Link Instagram Business account
  </Card>

  <Card title="Facebook" icon="facebook">
    Connect Facebook Page
  </Card>

  <Card title="Website" icon="globe">
    Chat widget (auto-enabled)
  </Card>
</CardGroup>

<Card title="Setup Additional Channels" icon="link" href="/channels/introduction">
  See Channels documentation to connect WhatsApp, Instagram, and Facebook →
</Card>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget not appearing on store">
    **Check:**

    1. App embed is toggled to **Active**
    2. Theme customizer changes were **Saved**
    3. Clear browser cache and refresh
    4. Check theme compatibility
    5. View published theme (not preview)
  </Accordion>

  <Accordion title="Chat not responding">
    **Check:**

    1. Agent is deployed (`lua production`)
    2. Skills are pushed (`lua push`)
    3. Check browser console for errors
    4. Verify agent ID is correct
    5. Test in admin dashboard
  </Accordion>

  <Accordion title="Can't find app embeds">
    **Location:**

    * Theme Customizer → Left sidebar → App embeds

    **If missing:**

    * Ensure app is installed
    * Try different theme
    * Contact Shopify support
  </Accordion>

  <Accordion title="Products not showing in chat">
    **Check:**

    1. Products are published in Shopify
    2. Products have inventory
    3. Agent has product search tools
    4. Test with simple product names
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Position for Best Engagement">
    **Bottom Right** (default)

    * Standard placement
    * Familiar to users
    * Doesn't interfere with product images

    Mobile-optimized automatically
  </Accordion>

  <Accordion title="Match Your Brand">
    Customize colors to match your store:

    * Use your brand colors
    * Match header/footer styling
    * Ensure good contrast
    * Test on mobile and desktop
  </Accordion>

  <Accordion title="Test Before Going Live">
    ```bash theme={null}
    # Test your agent first
    lua chat

    # Test product searches
    # Test cart creation
    # Test checkout links

    # Then enable on store
    ```
  </Accordion>

  <Accordion title="Monitor Performance">
    * Check analytics in Shopify admin
    * View conversations in `lua admin`
    * Track conversions from chat
    * Optimize based on usage
  </Accordion>
</AccordionGroup>

***

## App Updates

The Shopify app updates automatically:

* ✅ Latest features added automatically
* ✅ Security patches applied
* ✅ No manual update needed
* ✅ Changes announced in app dashboard

***

## Support & Resources

<CardGroup>
  <Card title="Shopify App Store" icon="shopify" href="https://apps.shopify.com/lua-shopping-assistant">
    View app listing and reviews
  </Card>

  <Card title="Configure Agent" icon="robot" href="/cli/persona-command">
    Set up shopping assistant personality
  </Card>

  <Card title="Widget Styling" icon="palette" href="/chat-widget/styling">
    Customize chat appearance
  </Card>

  <Card title="Get Support" icon="life-ring" href="mailto:support@heylua.ai">
    Email: [support@heylua.ai](mailto:support@heylua.ai)
  </Card>
</CardGroup>

***

## What Customers Are Saying

From the [Shopify App Store](https://apps.shopify.com/lua-shopping-assistant) reviews:

> "Great product- helped us automate customer queries & turn chats into sales."\
> — Ma boutique, France

> "I installed Lua to help me sell on Instagram & WhatsApp- loving it so far!"\
> — Rocco & Rose, United Kingdom

**Rating**: ⭐⭐⭐⭐⭐ 5.0 out of 5

***

## Next Steps

<CardGroup>
  <Card title="Install Shopify App" icon="shopify" href="https://apps.shopify.com/lua-shopping-assistant">
    Get started on Shopify App Store
  </Card>

  <Card title="Configure Channels" icon="broadcast-tower" href="/channels/introduction">
    Add WhatsApp, Instagram, Facebook
  </Card>

  <Card title="E-commerce Demo" icon="cart-shopping" href="/demos/ecommerce-assistant">
    See complete shopping assistant
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Test shopping conversations
  </Card>
</CardGroup>


# SimplyBook.me
Source: https://docs.heylua.ai/integrations/simplybook

Connect your booking system with Lua AI agent

## Overview

### About SimplyBook.me

**SimplyBook.me** is a powerful online booking and appointment scheduling system trusted by over 10,000 service-based businesses worldwide. From beauty salons and fitness studios to medical clinics and professional consultants, SimplyBook.me handles the complexity of appointment scheduling, payments, reminders, and customer management.

### Automate Bookings with AI

Integrate **Lua AI** with SimplyBook.me to give your customers an intelligent booking assistant that works 24/7. Instead of customers navigating your booking page alone, they chat with an AI agent that understands their needs, checks availability, and completes bookings instantly.

**Why This Transforms Your Business:**

* 📅 **More Bookings** - AI converts casual inquiries into confirmed appointments
* ⏰ **24/7 Availability** - Book appointments even when you're closed
* 💬 **Natural Conversations** - "I need a haircut tomorrow afternoon" → Done
* 📱 **Multi-Channel Booking** - WhatsApp, Facebook, Instagram, Email, Website
* ⚡ **Instant Confirmation** - No back-and-forth, immediate scheduling
* 🔄 **Reduce No-Shows** - AI sends personalized reminders
* 💰 **Upsell Services** - AI suggests additional services intelligently
* 📊 **Fill Empty Slots** - AI proactively offers last-minute openings

<CardGroup>
  <Card title="Appointment Scheduling" icon="calendar-check">
    Complete booking management
  </Card>

  <Card title="API Integration" icon="plug">
    Connect via official API
  </Card>

  <Card title="Multi-Industry" icon="briefcase">
    Beauty, fitness, medical, professional
  </Card>

  <Card title="AI Booking Agent" icon="robot">
    Conversational appointment scheduling
  </Card>
</CardGroup>

## What SimplyBook.me Offers

According to [SimplyBook.me](https://simplybook.me/en/):

**Features:**

* 📅 Online booking system
* 📱 Client & Admin mobile apps
* 💳 Payment processing (Stripe, PayPal, etc.)
* 🔔 WhatsApp, SMS & Email notifications
* 🌍 Multi-location support
* 📊 Business analytics
* 🔄 Calendar sync (Google, Outlook)
* 🎨 Customizable booking websites

**Perfect for:**

* Beauty & Wellness
* Sports & Fitness
* Healthcare
* Educational services
* Events & Entertainment
* Professional services
* And more

***

## Prerequisites

Before connecting to Lua, you need:

1. **SimplyBook.me Account** - Active account at [simplybook.me](https://simplybook.me/en/)
2. **Company Login** - Your unique SimplyBook.me identifier
3. **API Access** - API custom feature enabled
4. **API Key** - Generated from your account

***

## Setup Steps

<Steps>
  <Step title="Login to SimplyBook.me">
    Go to [https://simplybook.me/en/](https://simplybook.me/en/) and log in to your account

    <Frame>
      <img alt="SimplyBook.me login" />
    </Frame>

    *Screenshot: SimplyBook.me login page*
  </Step>

  <Step title="Access Account Info">
    Hover over your account name (left menu) and select **Account Info**

    <Frame>
      <img alt="Account menu" />
    </Frame>

    *Screenshot: Dropdown menu showing:*

    * Account name
    * Account Info (highlighted)
    * Settings
    * Logout
  </Step>

  <Step title="Find Your Company Login">
    On the Account Info page, locate your **Company Login**

    <Frame>
      <img alt="Company login" />
    </Frame>

    *Screenshot: Account Info page showing:*

    * Company Login field (e.g., "yourcompany")
    * This is your unique identifier
    * Used in booking URL: yourcompany.simplybook.me

    <Note>
      **Save your Company Login** - You'll need this for API integration with Lua
    </Note>
  </Step>

  <Step title="Enable API Custom Feature">
    Navigate to: **Custom Features** tab

    Scroll down to find **API**

    Toggle it **ON** (if currently disabled)

    <Frame>
      <img alt="Enable API" />
    </Frame>

    *Screenshot: Custom Features page showing:*

    * List of custom features
    * API toggle switch
    * Toggle in OFF state (before)
    * Toggle in ON state (after)
  </Step>

  <Step title="Generate API Key">
    If you don't have an API key yet:

    1. Find the API key section
    2. Click **Generate New API Key**
    3. Copy the generated key

    <Frame>
      <img alt="Generate API key" />
    </Frame>

    *Screenshot: API key generation interface showing:*

    * "Generate New API Key" button
    * Generated key display (partially masked)
    * Copy button

    <Warning>
      **Save your API key securely!** You'll need this to integrate with Lua. This key provides access to your booking system.
    </Warning>
  </Step>
</Steps>

***

## SimplyBook.me API Capabilities

Your Lua agent can use the SimplyBook.me API to:

<CardGroup>
  <Card title="Check Availability" icon="calendar-check">
    View available appointment slots
  </Card>

  <Card title="Create Bookings" icon="plus">
    Schedule appointments
  </Card>

  <Card title="Manage Bookings" icon="pen">
    Update or cancel appointments
  </Card>

  <Card title="Customer Info" icon="user">
    Access client data
  </Card>

  <Card title="Service Details" icon="info">
    Get service information
  </Card>

  <Card title="Provider Schedule" icon="clock">
    Check staff availability
  </Card>
</CardGroup>

## Common Use Cases

### Appointment Booking Agent

```typescript theme={null}
// Tools your agent can use:
- search_services: Find available services
- check_availability: Show open time slots
- create_booking: Schedule appointment
- get_booking: Check booking details
- cancel_booking: Cancel appointment
- reschedule_booking: Change appointment time
```

**Example conversation:**

```
User: "I need a haircut appointment"

Agent: "I can help you book a haircut! 
        What day works best for you?"

User: "Tomorrow afternoon"

Agent: [Calls check_availability]
       "Here are available times tomorrow afternoon:
       - 2:00 PM
       - 3:30 PM
       - 4:00 PM
       
       Which time would you prefer?"

User: "2:00 PM"

Agent: [Calls create_booking]
       "Perfect! Your haircut is booked for tomorrow at 2:00 PM.
       You'll receive a confirmation via email."
```

***

## Industries Supported

SimplyBook.me works across [many industries](https://simplybook.me/en/):

<Tabs>
  <Tab title="Beauty & Wellness">
    * Hair salons
    * Spa & massage
    * Nail salons
    * Barber shops
    * Beauty services
  </Tab>

  <Tab title="Health & Medical">
    * Medical clinics
    * Dental offices
    * Physiotherapy
    * Mental health
    * Wellness centers
  </Tab>

  <Tab title="Sports & Fitness">
    * Personal training
    * Yoga studios
    * Gyms
    * Sports coaching
    * Fitness classes
  </Tab>

  <Tab title="Professional">
    * Consulting
    * Legal services
    * Financial advisors
    * Coaching
    * Photography
  </Tab>

  <Tab title="Other">
    * Education & tutoring
    * Events & entertainment
    * Pet services
    * Home services
    * And more
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="SimplyBook.me Account" icon="external-link" href="https://simplybook.me/en/">
    Create account if you don't have one
  </Card>
</CardGroup>


# Square
Source: https://docs.heylua.ai/integrations/square-appointments

Connect Square Appointments with your AI booking assistant

## Overview

### About Square Appointments

**Square Appointments** is the leading booking and scheduling system trusted by thousands of service-based businesses worldwide. From beauty salons and fitness studios to medical clinics and professional consultants, Square Appointments handles appointment scheduling, staff management, customer communications, and payments - all in one platform.

### Automate Bookings with AI

Integrate **Lua AI** with Square Appointments to give your customers an intelligent booking assistant that works 24/7. Instead of customers navigating your booking page alone, they chat with an AI agent that understands their needs, checks availability, and completes bookings instantly across any channel.

**Why This Transforms Your Business:**

* 📅 **More Bookings** - AI converts casual inquiries into confirmed appointments
* ⏰ **24/7 Availability** - Book appointments even when you're closed
* 💬 **Natural Conversations** - "I need a haircut tomorrow afternoon" → Done
* 📱 **Multi-Channel Booking** - WhatsApp, Facebook, Instagram, Email, Website
* ⚡ **Instant Confirmation** - No back-and-forth, immediate scheduling
* 🔄 **Reduce No-Shows** - AI sends personalized reminders
* 💰 **Upsell Services** - AI suggests additional services intelligently
* 📊 **Fill Empty Slots** - AI proactively offers last-minute openings

<CardGroup>
  <Card title="Complete Booking System" icon="calendar-check">
    Full appointment management
  </Card>

  <Card title="5-Minute Setup" icon="bolt">
    OAuth integration, zero configuration
  </Card>

  <Card title="Multi-Industry" icon="briefcase">
    Beauty, fitness, medical, professional
  </Card>

  <Card title="AI Booking Agent" icon="robot">
    Conversational appointment scheduling
  </Card>
</CardGroup>

## What Square Appointments Offers

According to [Square](https://squareup.com/us/en):

**Appointment Features:**

* 📅 **Online Booking** - 24/7 self-service scheduling
* 📱 **Mobile Apps** - Client and staff apps
* 💳 **Payment Processing** - Take deposits or full payment
* 🔔 **SMS & Email Reminders** - Automated notifications
* 👥 **Staff Management** - Schedule multiple team members
* 🌍 **Multi-Location** - Handle multiple business locations
* 📊 **Analytics** - Booking insights and reports
* 🔄 **Calendar Sync** - Google, Outlook integration

**Perfect for:**

* 💅 Beauty & Wellness (salons, spas, barbershops)
* 🏋️ Sports & Fitness (gyms, trainers, studios)
* 🏥 Healthcare (clinics, therapy, wellness)
* 💼 Professional Services (consulting, coaching, legal)
* 🐕 Pet Services (grooming, training, veterinary)
* 🏠 Home Services (cleaning, repairs, landscaping)

***

## Prerequisites

Before connecting Square to Lua:

1. **Active Square Account** - Sign up at [squareup.com](https://squareup.com)

<Note>
  Square Appointments is included with Square Plus (\$29/month) or higher plans.
  The free plan has limited appointment features.
</Note>

<Warning>
  **Important: Email Linking**

  When you connect Square to Lua, your admin account will be automatically linked to an email address from your Square business. The system searches for an email in this priority order:

  1. **Owner Email** - The merchant owner's email address
  2. **Business Email** - Your main location's business email
  3. **Team Member Email** - The first team member with owner role

  Make sure at least one of these emails is valid and accessible, as you'll use it to access your Lua admin dashboard.
</Warning>

***

## Integration Setup

<Card title="📺 Video Tutorial" icon="video" href="https://www.loom.com/share/96947659531d4856a75bf301913d7e12?sid=cc5e40f7-6f66-487d-8d83-6a7557d3df04">
  Prefer watching a video? Follow along with our step-by-step video guide
</Card>

<Steps>
  <Step title="Navigate to Lua Square Auth">
    Open your browser and go to:
    **[https://auth.heylua.ai/square/auth](https://auth.heylua.ai/square/auth)**

    <Note>
      This secure OAuth flow connects your Square account to Lua without sharing
      your password.
    </Note>
  </Step>

  <Step title="Sign In to Square">
    Click **"Sign in with Square"** or **"Continue with Square"** Enter your
    Square account credentials: - Email address - Password - (Two-factor
    authentication if enabled)

    <Frame>
      <img alt="Square login form" />
    </Frame>

    *Screenshot: Square login form showing email and password fields*

    <Tip>
      Using Square with multiple businesses? Don't worry - you'll select which one
      to connect in the next step.
    </Tip>
  </Step>

  <Step title="Select Your Business (If Applicable)">
    If your Square account manages multiple businesses, you'll see a selection
    screen. Choose the business you want to connect to your Lua agent.

    <Frame>
      <img alt="Select Square business" />
    </Frame>

    *Screenshot: Business selection screen showing multiple Square
    locations/businesses*

    <Note>
      **Managing multiple businesses?** You can connect different Lua agents to
      different Square locations. Just repeat this process for each agent/business
      combination.
    </Note>
  </Step>

  <Step title="Grant Permissions">
    Square will display the permissions that Lua needs to function.

    **Lua requires access to:**

    * 📅 Appointments (for booking management)
    * 👥 Staff (for team member availability)
    * 👤 Customer Info (for personalized service)
    * 💳 Payments (for booking deposits)

    Review the permissions and click **"Allow"** or **"Authorize"**

    <Frame>
      <img alt="Square permissions screen" />
    </Frame>

    *Screenshot: Square OAuth permission screen listing required access scopes
    with "Allow" button*

    <Warning>
      **About Permissions**: Lua only requests the minimum permissions needed to
      help your customers. Your payment details and sensitive business data remain
      secure with Square.
    </Warning>
  </Step>

  <Step title="Integration Complete!">
    You'll be redirected to your **Lua Admin Dashboard** Your Square integration
    is now active and ready to use!

    <Frame>
      <img alt="Lua admin dashboard" />
    </Frame>

    *Screenshot: Lua admin dashboard showing successful Square integration*

    <Check>
      **Success!** Your Lua agent can now access your Square Appointments,
      availability, and booking data in real-time.
    </Check>
  </Step>
</Steps>

***

## What Your Agent Can Do

With Square Appointments integration, your AI agent becomes a powerful booking assistant:

<CardGroup>
  <Card title="Check Availability" icon="calendar-check">
    View open appointment slots
  </Card>

  <Card title="Book Appointments" icon="calendar-plus">
    Schedule services instantly
  </Card>

  <Card title="Service Details" icon="clipboard-list">
    Pricing, duration, staff info
  </Card>

  <Card title="Staff Selection" icon="user-tie">
    Choose specific providers
  </Card>

  <Card title="View Bookings" icon="list">
    Check customer appointment history
  </Card>

  <Card title="Multi-Service" icon="layer-group">
    Book multiple services at once
  </Card>

  <Card title="Location Support" icon="map-location-dot">
    Handle multiple business locations
  </Card>

  <Card title="Booking Policies" icon="file-contract">
    Communicate cancellation rules
  </Card>
</CardGroup>

<Note>
  **Current Limitation**: The AI agent can check availability and search for
  rescheduling options, but cannot finalize rescheduling or cancel existing
  bookings. Customers will need to manage changes through Square or contact you
  directly.
</Note>

***

## Use Cases by Industry

<Tabs>
  <Tab title="💅 Beauty & Wellness">
    **Perfect for: Hair Salons, Nail Salons, Spas, Barbershops, Med Spas**

    Automated appointment booking:

    * "I need a haircut tomorrow afternoon"
    * Check stylist availability
    * Book specific services
    * View appointment history
    * Upsell complementary services

    **Example Conversation:**

    ```
    Customer: "Can I get a haircut and color this week?"

    Agent: [Checks Square Appointments]
           "I can help you book both services! 
           We have availability:
           - Thursday 2:00 PM (with Sarah)
           - Friday 10:00 AM (with Mike)
           - Saturday 11:30 AM (with Sarah)
           
           Which time works best for you?"

    Customer: "Thursday at 2 with Sarah"

    Agent: [Books appointment]
           "Perfect! You're all set for Thursday at 2:00 PM.
           Haircut & Color with Sarah - 2.5 hours - $150
           You'll receive a confirmation text shortly."
    ```
  </Tab>

  <Tab title="🏋️ Fitness & Training">
    **Perfect for: Personal Trainers, Yoga Studios, Gyms, Sports Coaching**
    Streamline class and session booking: - Check trainer availability - Book
    individual or group sessions - Explain class types and levels - Handle
    recurring appointments - Manage waitlists **Example Conversation:** \`\`\`
    Customer: "I want to try yoga, never done it before" Agent: \[Searches
    services] "Great! We have beginner-friendly classes: - Intro to Yoga (60 min)

    * $25 - Gentle Flow (45 min) - $20 - Private Beginner Session (60 min) - \$75 I
      recommend starting with Intro to Yoga. We have classes Monday, Wednesday,
      Friday at 6 PM." Customer: "Book me for Monday at 6" Agent: \[Books class]
      "You're booked! Monday 6 PM - Intro to Yoga Wear comfortable clothes and bring
      water. See you there!" \`\`\`
  </Tab>

  <Tab title="🏥 Healthcare & Wellness">
    **Perfect for: Medical Clinics, Therapy, Physiotherapy, Wellness Centers**
    Professional appointment management: - Book consultations and treatments -
    Check provider availability - Explain services and procedures - Handle new
    patient intake - Provide appointment preparation info **Example
    Conversation:** `Customer: "I need a physical therapy appointment for my
          knee" Agent: [Checks availability] "I can help you schedule physical therapy.
          First appointment includes: - Initial assessment (45 min) - $120 - Treatment
          plan discussion Available times this week: - Tuesday 9:00 AM (Dr. Johnson) -
          Wednesday 2:30 PM (Dr. Smith) - Friday 10:00 AM (Dr. Johnson) Which works for
          you?" Customer: "Tuesday at 9" Agent: [Books appointment] "Booked! Tuesday
          9:00 AM with Dr. Johnson Please arrive 10 minutes early to complete paperwork.
          Confirmation sent to your email."`
  </Tab>

  <Tab title="💼 Professional Services">
    **Perfect for: Consulting, Coaching, Legal Services, Financial Advisors**

    Intelligent consultation scheduling:

    * Book discovery calls
    * Schedule follow-up meetings
    * Check consultant availability
    * Explain service packages
    * Handle virtual and in-person appointments

    **Example Conversation:**

    ```
    Customer: "I need a consultation about my business taxes"

    Agent: [Retrieves services]
           "I can schedule a tax consultation.
           
           Options:
           - 30-min Discovery Call (Free)
           - 60-min Tax Consultation - $200
           - 90-min Comprehensive Review - $300
           
           I recommend starting with the Discovery Call.
           Virtual or in-person?"

    Customer: "Virtual discovery call"

    Agent: [Shows availability]
           "Great choice! Available times:
           - Today 4:00 PM
           - Tomorrow 10:00 AM
           - Tomorrow 3:00 PM"

    Customer: "Tomorrow at 10"

    Agent: [Books appointment]
           "Perfect! Discovery Call tomorrow at 10:00 AM.
           Video link will be sent before the meeting.
           Looking forward to helping you!"
    ```
  </Tab>
</Tabs>

***

## Multi-Channel Booking

Square Appointments integration works across all Lua channels:

<CardGroup>
  <Card title="Website Chat" icon="globe" href="/chat-widget/introduction">
    Embedded booking widget
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/channels/whatsapp">
    Book via WhatsApp Business
  </Card>

  <Card title="Instagram" icon="instagram" href="/channels/instagram">
    Scheduling through Instagram DMs
  </Card>

  <Card title="Facebook" icon="facebook" href="/channels/facebook-messenger">
    Messenger booking experience
  </Card>
</CardGroup>

**One booking system. Multiple booking channels. All managed by AI.**

***

## Disconnecting Square Integration

If you need to disconnect Lua from your Square account:

<Steps>
  <Step title="Open Square Dashboard">
    Log into your Square account at [squareup.com](https://squareup.com)
  </Step>

  <Step title="Navigate to App Integrations">
    Click on **Settings** in the left sidebar Select **App Integrations** from the
    settings menu

    <Frame>
      <img alt="Square app integrations" />
    </Frame>

    *Screenshot: Square Settings showing App Integrations section with Lua
    Assistant listed*
  </Step>

  <Step title="Find Lua Assistant">
    Scroll through your connected apps to find **"Lua Assistant"** or **"Lua"**
  </Step>

  <Step title="Disconnect App">
    Click the **three dots (⋮)** on the right side of the Lua Assistant row
    Select **"Disconnect App"** from the dropdown menu Confirm the disconnection
    when prompted

    <Warning>
      **This will immediately stop your Lua agent from accessing Square data.**
      Your agent will no longer be able to check availability or book
      appointments.
    </Warning>
  </Step>
</Steps>

<Note>
  **Want to reconnect?** Just go through the [integration
  setup](#integration-setup) process again. All your Lua agent configuration is
  preserved.
</Note>

***

## Real-World Examples

<Tabs>
  <Tab title="Hair Salon">
    **Luxe Hair Studio**

    "We switched to Square Appointments last year, and Lua automates 80% of our bookings now. Clients text our WhatsApp number like 'I need a haircut Thursday afternoon' and the AI books them in seconds. It even suggests add-on services like 'Would you like a deep conditioning treatment?' We've seen a 25% increase in service upgrades."

    **What they book:** Haircuts, coloring, treatments
    **Channels:** WhatsApp, Website widget
  </Tab>

  <Tab title="Fitness Studio">
    **Core Strength Yoga** "Square Appointments manages our class schedule, and
    Lua makes booking effortless. Students message us on Instagram, and the AI
    shows them available classes, explains what each class offers, and books them
    instantly. No more back-and-forth emails. Our class attendance is up 45% since
    adding Lua." **What they book:** Yoga classes, private sessions, workshops
    **Channels:** Instagram, Facebook, Website
  </Tab>

  <Tab title="Medical Clinic">
    **Wellness First Clinic**

    "Patient scheduling used to overwhelm our front desk. Now, Lua handles appointment booking 24/7 through our website and SMS. The AI understands 'I need a follow-up with Dr. Smith' and books the right appointment type. Our staff focuses on patient care instead of phone calls. Booking efficiency improved 60%."

    **What they book:** Consultations, treatments, follow-ups
    **Channels:** Website widget, SMS integration
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Integration failed or shows error">
    **Common causes:**

    1. **Square account not fully set up** - Ensure you've completed Square onboarding
    2. **Appointments not enabled** - Upgrade to Square Plus or Premium
    3. **Missing permissions** - Try disconnecting and reconnecting with all permissions granted
    4. **Browser issues** - Clear cache or try a different browser

    **Solution:** Start the integration process again at [auth.heylua.ai/square/auth](https://auth.heylua.ai/square/auth)
  </Accordion>

  <Accordion title="Appointments not showing availability">
    **Verify:** 1. Square Appointments is enabled in your Square account 2.
    Services are set up with duration and pricing 3. Staff members have
    availability hours configured 4. Booking permissions were granted during
    integration 5. Location has operating hours set **Note:** Square free plan has
    limited appointment features
  </Accordion>

  <Accordion title="No staff members showing up">
    **Check:** 1. Staff have booking profiles in Square Appointments 2. Team
    members are assigned to services 3. Staff availability hours are set 4. Staff
    are enabled at the relevant location **Fix:** Configure in Square Dashboard →
    Team → Booking Profiles
  </Accordion>

  <Accordion title="Can't book specific services">
    **Verify:** 1. Service is marked as bookable in Square 2. Service has proper
    duration and pricing set 3. At least one team member is assigned to the
    service 4. Service is available at the selected location **Solution:** Check
    Square Dashboard → Appointments → Services
  </Accordion>

  <Accordion title="Booking confirmation not received">
    **Check:**

    1. Customer email/phone is correct in Square
    2. Notification settings enabled in Square
    3. Check spam/junk folders
    4. Square SMS credits available (if using SMS)
    5. Email not blocklisted

    **Note:** Confirmations are sent by Square, not Lua
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Configure Services Clearly">
    **For booking businesses:**

    * ✅ Accurate service duration (include buffer time)
    * ✅ Clear service names ("Women's Haircut" not just "Haircut")
    * ✅ Detailed descriptions
    * ✅ Proper pricing
    * ✅ Staff availability accurately set
    * ✅ Booking windows configured

    **Example:** Instead of "Basic Package" use "Basic Facial - 60 minutes"
  </Accordion>

  <Accordion title="Set Smart Booking Policies">
    **Configure in Square Appointments:** - Minimum lead time for bookings -
    Maximum advance booking time - Cancellation policy and deadlines - Buffer time
    between appointments - Booking deposit requirements **Why:** AI will
    communicate these policies to customers automatically
  </Accordion>

  <Accordion title="Optimize Staff Schedules">
    **Best practices:** - Set realistic availability blocks - Include break times

    * Configure time off in advance - Assign services to appropriate staff -
      Enable multiple staff per service when possible **Result:** More available
      slots for customers to book
  </Accordion>

  <Accordion title="Monitor Booking Patterns">
    **Track performance:** 1. **In Lua Admin:** - Booking conversion rates - Most
    requested services - Popular time slots - Drop-off points 2. **In Square
    Dashboard:** - No-show rates - Utilization rates - Revenue per appointment -
    Customer retention 3. **Optimize:** - Adjust availability based on demand -
    Promote underbooked time slots - Refine service descriptions
  </Accordion>
</AccordionGroup>

***

## Pricing & Square Plans

Square Appointments features by plan:

* ❌ **Square Free** - Limited appointment features
* ✅ **Square Plus** (\$29/month) - Full Appointments features ⭐ Recommended
* ✅ **Square Premium** (\$69+/month) - Multi-location, advanced features

<Tip>
  **For Lua integration to work fully**, you need Square Plus or higher. This
  includes full appointment booking, staff management, and automated reminders.
</Tip>

Learn more about [Square pricing](https://squareup.com/us/en/pricing)

***

## Next Steps

<CardGroup>
  <Card title="Connect Square Now" icon="square" href="https://auth.heylua.ai/square/auth">
    Start integration in 5 minutes
  </Card>

  <Card title="Configure Channels" icon="broadcast-tower" href="/channels/introduction">
    Add WhatsApp, Instagram, Facebook
  </Card>

  <Card title="Configure Agent" icon="robot" href="/cli/persona-command">
    Set up booking assistant personality
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Test booking flows locally
  </Card>
</CardGroup>

***

<Card title="Need Help?" icon="question-circle">
  Having trouble with Square Appointments integration? Email us at
  **[support@heylua.ai](mailto:support@heylua.ai)** or check the [troubleshooting section](#troubleshooting)
  above.
</Card>


# Square
Source: https://docs.heylua.ai/integrations/square-ecommerce

Connect Square POS and online store with your AI shopping assistant

## Overview

### About Square

**Square** is the all-in-one commerce platform trusted by over 4 million businesses worldwide. From neighborhood coffee shops to global retailers, Square powers point of sale, online stores, inventory management, payments, and banking. Whether you're running a physical store, online shop, or restaurant, Square handles your entire commerce operation.

### Transform Your Square Store with AI

Integrate **Lua AI** with Square to turn your e-commerce business into an AI-powered sales machine. Your AI agent connects directly to your Square account, accessing your products, inventory, orders, and customer data to provide instant, personalized shopping assistance across all channels.

**The Business Impact:**

* 🚀 **Boost Sales** - AI converts browsers into buyers with personalized recommendations
* ⏰ **24/7 Availability** - Never miss a sale, even at 3 AM
* 💬 **Multi-Channel Commerce** - Sell on WhatsApp, Instagram, Facebook, Website
* 🎯 **Smart Upselling** - AI suggests complementary products naturally
* 📊 **Real-Time Inventory** - Access live stock levels from Square
* ⚡ **Instant Service** - No waiting, no phone calls, just instant answers
* 🛒 **Reduce Cart Abandonment** - AI guides customers through checkout
* 💰 **Higher Cart Values** - Intelligent product recommendations

<CardGroup>
  <Card title="POS + E-commerce" icon="square">
    Unified commerce platform
  </Card>

  <Card title="5-Minute Setup" icon="bolt">
    OAuth integration, zero configuration
  </Card>

  <Card title="Multi-Industry" icon="store">
    Retail, Food & Beverage, and more
  </Card>

  <Card title="AI Shopping Assistant" icon="robot">
    Intelligent product search and checkout
  </Card>
</CardGroup>

## What Square E-commerce Offers

According to [Square](https://squareup.com/us/en):

**Commerce Solutions:**

* 💳 **Payments** - Accept payments anywhere
* 🏪 **Point of Sale** - Retail and Restaurant POS
* 🌐 **Online Stores** - E-commerce websites and profiles
* 📦 **Inventory** - Real-time stock management
* 💰 **Banking** - Checking, savings, loans, credit cards
* 📊 **Analytics** - Business insights and reporting
* 👥 **Customer Engagement** - Loyalty, marketing, directories

**Business Types:**

* 🛍️ Retail (clothing, home & gift, grocery)
* 🍽️ Food & Beverage (restaurants, cafes, food trucks)
* 🎪 And many more

**Hardware:**

* Square Terminal, Register, Handheld
* Contactless readers, Kiosks, Stands

***

## Prerequisites

Before connecting Square to Lua:

1. **Active Square Account** - Sign up at [squareup.com](https://squareup.com)

<Warning>
  **Important: Email Linking**

  When you connect Square to Lua, your admin account will be automatically linked to an email address from your Square business. The system searches for an email in this priority order:

  1. **Owner Email** - The merchant owner's email address
  2. **Business Email** - Your main location's business email
  3. **Team Member Email** - The first team member with owner role

  Make sure at least one of these emails is valid and accessible, as you'll use it to access your Lua admin dashboard.
</Warning>

***

## Integration Setup

<Card title="📺 Video Tutorial" icon="video" href="https://www.loom.com/share/96947659531d4856a75bf301913d7e12?sid=cc5e40f7-6f66-487d-8d83-6a7557d3df04">
  Prefer watching a video? Follow along with our step-by-step video guide
</Card>

<Steps>
  <Step title="Navigate to Lua Square Auth">
    Open your browser and go to:
    **[https://auth.heylua.ai/square/auth](https://auth.heylua.ai/square/auth)**

    <Note>
      This secure OAuth flow connects your Square account to Lua without sharing
      your password.
    </Note>
  </Step>

  <Step title="Sign In to Square">
    Click **"Sign in with Square"** or **"Continue with Square"** Enter your
    Square account credentials: - Email address - Password - (Two-factor
    authentication if enabled)

    <Frame>
      <img alt="Square login form" />
    </Frame>

    *Screenshot: Square login form showing email and password fields*

    <Tip>
      Using Square with multiple businesses? Don't worry - you'll select which one
      to connect in the next step.
    </Tip>
  </Step>

  <Step title="Select Your Business (If Applicable)">
    If your Square account manages multiple businesses, you'll see a selection
    screen. Choose the business you want to connect to your Lua agent.

    <Frame>
      <img alt="Select Square business" />
    </Frame>

    *Screenshot: Business selection screen showing multiple Square
    locations/businesses*

    <Note>
      **Managing multiple businesses?** You can connect different Lua agents to
      different Square locations. Just repeat this process for each agent/business
      combination.
    </Note>
  </Step>

  <Step title="Grant Permissions">
    Square will display the permissions that Lua needs to function.

    **Lua requires access to:**

    * 📦 Products & Inventory (for product search and availability),
    * 🛒 Orders (for order creation and tracking),
    * 👤 Customer Info (for personalized service),
    * 💳 Payments (for checkout links)

    Review the permissions and click **"Allow"** or **"Authorize"**

    <Frame>
      <img alt="Square permissions screen" />
    </Frame>

    *Screenshot: Square OAuth permission screen listing required access scopes
    with "Allow" button*

    <Warning>
      **About Permissions**: Lua only requests the minimum permissions needed to
      help your customers. Your payment details and sensitive business data remain
      secure with Square.
    </Warning>
  </Step>

  <Step title="Integration Complete!">
    You'll be redirected to your **Lua Admin Dashboard** Your Square integration
    is now active and ready to use!

    <Frame>
      <img alt="Lua admin dashboard" />
    </Frame>

    *Screenshot: Lua admin dashboard showing successful Square integration*

    <Check>
      **Success!** Your Lua agent can now access your Square catalog, inventory,
      and order data in real-time.
    </Check>
  </Step>
</Steps>

***

## What Your Agent Can Do

With Square e-commerce integration, your AI agent becomes a powerful shopping assistant:

<CardGroup>
  <Card title="Product Search" icon="magnifying-glass">
    Find items in your Square catalog
  </Card>

  <Card title="Inventory Check" icon="boxes-stacked">
    Real-time stock availability
  </Card>

  <Card title="Product Details" icon="info-circle">
    Pricing, specs, descriptions, images
  </Card>

  <Card title="Smart Recommendations" icon="sparkles">
    AI suggests relevant products
  </Card>

  <Card title="Cart Building" icon="cart-shopping">
    Create orders in conversation
  </Card>

  <Card title="Checkout Links" icon="link">
    One-click Square checkout URLs
  </Card>

  <Card title="Order Tracking" icon="truck">
    Check order status and shipping
  </Card>

  <Card title="Customer History" icon="clock-rotate-left">
    Access past purchases
  </Card>
</CardGroup>

***

## Use Cases by Industry

<Tabs>
  <Tab title="🛍️ Retail Stores">
    **Perfect for: Clothing, Home & Gift, Grocers, Specialty Retail**

    Your AI shopping assistant can:

    * "Show me men's jackets under \$100"
    * Check if items are in stock
    * Suggest matching accessories
    * Create shopping carts
    * Generate checkout links
    * Track orders and shipping

    **Example Conversation:**

    ```
    Customer: "Do you have this dress in medium?"

    Agent: [Searches Square inventory]
           "Yes! The blue sundress is available in medium. 
           We have 3 in stock. Would you like to order it?"

    Customer: "Yes please"

    Agent: [Creates Square order]
           "Perfect! I've added it to your cart. 
           Here's your checkout link: [Square Checkout]
           You can pick it up today or have it shipped!"
    ```
  </Tab>

  <Tab title="🍽️ Restaurants & Cafes">
    **Perfect for: Quick Service, Full Service, Coffee Shops, Food Trucks** Your
    AI can help with: - Menu questions and recommendations - Dietary restrictions
    and allergens - Order ahead for pickup - Catering inquiries - Hours and
    location info **Example Conversation:** `Customer: "What vegan options do
          you have?" Agent: [Searches Square menu] "We have several vegan options: -
          Beyond Burger with sweet potato fries - $14 - Buddha Bowl with quinoa and
          veggies - $12 - Vegan Chocolate Cake - $6 Would you like to order ahead for
          pickup?" Customer: "Yes, the Buddha Bowl" Agent: "Great choice! What time
          would you like to pick it up?"`
  </Tab>

  <Tab title="🏪 Specialty Retail">
    **Perfect for: Wine & Liquor, Garden Centers, Pet Supplies, Electronics**

    Specialized product knowledge:

    * Answer detailed product questions
    * Compare similar items
    * Check compatibility
    * Provide care instructions
    * Suggest complementary products

    **Example Conversation:**

    ```
    Customer: "I need a wine that pairs well with salmon"

    Agent: [Searches Square wine catalog]
           "Great choice! For salmon, I recommend:
           - Pinot Noir ($28) - Classic pairing
           - Chardonnay ($32) - Buttery notes
           - Sauvignon Blanc ($24) - Crisp and light
           
           Would you like to know more about any of these?"
    ```
  </Tab>
</Tabs>

***

## Multi-Channel Sales

Square integration works across all Lua channels:

<CardGroup>
  <Card title="Website Chat" icon="globe" href="/chat-widget/introduction">
    Embedded chat widget on your site
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/channels/whatsapp">
    Sell via WhatsApp Business
  </Card>

  <Card title="Instagram" icon="instagram" href="/channels/instagram">
    Commerce through Instagram DMs
  </Card>

  <Card title="Facebook" icon="facebook" href="/channels/facebook-messenger">
    Messenger shopping experience
  </Card>
</CardGroup>

**One Square account. Multiple sales channels. All managed by AI.**

***

## Disconnecting Square Integration

If you need to disconnect Lua from your Square account:

<Steps>
  <Step title="Open Square Dashboard">
    Log into your Square account at [squareup.com](https://squareup.com)
  </Step>

  <Step title="Navigate to App Integrations">
    Click on **Settings** in the left sidebar Select **App Integrations** from the
    settings menu

    <Frame>
      <img alt="Square app integrations" />
    </Frame>

    *Screenshot: Square Settings showing App Integrations section with Lua
    Assistant listed*
  </Step>

  <Step title="Find Lua Assistant">
    Scroll through your connected apps to find **"Lua Assistant"** or **"Lua"**
  </Step>

  <Step title="Disconnect App">
    Click the **three dots (⋮)** on the right side of the Lua Assistant row
    Select **"Disconnect App"** from the dropdown menu Confirm the disconnection
    when prompted

    <Warning>
      **This will immediately stop your Lua agent from accessing Square data.**
      Your agent will no longer be able to search products, check inventory, or
      create orders.
    </Warning>
  </Step>
</Steps>

<Note>
  **Want to reconnect?** Just go through the [integration
  setup](#integration-setup) process again. All your Lua agent configuration is
  preserved.
</Note>

***

## Real-World Examples

<Tabs>
  <Tab title="Coffee Shop">
    **The Daily Grind Coffee**

    "We use Square for our POS and online ordering. Adding Lua was a game-changer - customers can now order ahead via WhatsApp, ask about our menu, and even purchase our coffee beans and merchandise. Our AI handles 100+ daily conversations, and sales from WhatsApp alone increased 40%."

    **What they sell:** Coffee, pastries, merchandise
    **Channels:** WhatsApp, Website widget
  </Tab>

  <Tab title="Boutique Clothing">
    **Urban Threads Boutique** "Square powers our retail store and website. Our
    Lua assistant helps customers on Instagram DMs find items, check if we have
    their size, and buy without leaving Instagram. It's like having a virtual
    sales associate in every customer's pocket. Cart conversion is up 60%." **What
    they sell:** Women's clothing, accessories **Channels:** Instagram, Website,
    Facebook
  </Tab>

  <Tab title="Restaurant">
    **Bella's Italian Kitchen**

    "Square runs our entire restaurant - POS, online ordering, everything. With Lua, customers can ask about our menu on Facebook, check if we have gluten-free options, and place orders for pickup. During lunch rush, the AI handles 50+ order inquiries while our staff focuses on cooking. Takeout orders increased 35%."

    **What they sell:** Italian food, catering
    **Channels:** Facebook Messenger, Website, WhatsApp
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Integration failed or shows error">
    **Common causes:**

    1. **Square account not fully set up** - Ensure you've completed Square onboarding
    2. **Missing permissions** - Try disconnecting and reconnecting with all permissions granted
    3. **Browser issues** - Clear cache or try a different browser
    4. **Multiple browser tabs** - Close other Square auth tabs
    5. **Business not selected** - If you have multiple locations, ensure you selected one

    **Solution:** Start the integration process again at [auth.heylua.ai/square/auth](https://auth.heylua.ai/square/auth)
  </Accordion>

  <Accordion title="Agent can't find my products">
    **Check:** 1. Products are published in Square (not in draft mode) 2. Products
    have inventory assigned 3. Square catalog sync is complete (can take a few
    minutes) 4. Integration permissions include "Items and Inventory" 5. Try
    searching with exact product names first **Test:** In Lua admin, verify your
    Square catalog is visible
  </Accordion>

  <Accordion title="Wrong business connected">
    **If you selected the wrong Square location:** 1. Go to Square Settings → App
    Integrations 2. Disconnect Lua Assistant 3. Restart integration at
    [auth.heylua.ai/square/auth](https://auth.heylua.ai/square/auth) 4. Select the
    correct business this time
  </Accordion>

  <Accordion title="Checkout links not working">
    **Requirements for Square checkouts:** 1. Square Payments enabled 2. Products
    have prices set 3. Online payment processing activated 4. Business
    verification complete **Alternative:** Use Square invoices if checkout links
    aren't available
  </Accordion>

  <Accordion title="Agent says 'out of stock' incorrectly">
    **Check Square inventory:** 1. Verify stock levels in Square Dashboard 2.
    Ensure inventory tracking is enabled for the product 3. Check if product
    variations have separate stock 4. Allow a few minutes for inventory sync after
    updates
  </Accordion>

  <Accordion title="Multiple locations not working properly">
    **For multi-location Square accounts:**

    Currently, each Lua agent connects to one Square location. To serve multiple locations:

    * Create separate Lua agents for each location
    * Connect each agent to its respective Square location
    * Use location-specific channels or routing

    Contact [support@heylua.ai](mailto:support@heylua.ai) for enterprise multi-location solutions
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Organize Your Square Catalog">
    **For better AI performance:**

    * ✅ Use clear, descriptive product names
    * ✅ Add detailed descriptions
    * ✅ Include product images
    * ✅ Use categories and tags
    * ✅ Set accurate inventory levels
    * ✅ Keep pricing up to date

    **Why:** The AI uses this information to help customers find products faster
  </Accordion>

  <Accordion title="Monitor Performance">
    **Track your AI commerce assistant:** 1. **In Lua Admin:** - Conversation
    metrics - Most requested products - Cart conversion rates - Drop-off points 2.
    **In Square Dashboard:** - Sales attributed to online channels - Average order
    value - Customer acquisition costs 3. **Optimize based on data:** - Identify
    popular products to feature - Improve agent responses for common questions -
    Adjust product descriptions based on searches
  </Accordion>

  <Accordion title="Handle Edge Cases Gracefully">
    **Prepare your agent for:**

    * Out of stock situations → Offer alternatives
    * Large orders → Confirm stock and offer bulk pricing
    * Special requests → Collect details and offer callback
    * Refunds/Returns → Direct to appropriate channel

    Set clear policies in your agent's persona
  </Accordion>
</AccordionGroup>

***

## Pricing & Square Plans

The Lua integration works with all Square plans:

* ✅ **Square Free** - Basic POS
* ✅ **Square Plus** (\$29/month) - Advanced features
* ✅ **Square Premium** (\$69+/month) - Multi-location, advanced features

<Tip>
  **Getting started?** Square's free plan is perfect for testing the Lua
  integration. Upgrade as your business grows to unlock advanced commerce
  features.
</Tip>

Learn more about [Square pricing](https://squareup.com/us/en/pricing)

***

## Next Steps

<CardGroup>
  <Card title="Connect Square Now" icon="square" href="https://auth.heylua.ai/square/auth">
    Start integration in 5 minutes
  </Card>

  <Card title="E-commerce Demo" icon="cart-shopping" href="/demos/ecommerce-assistant">
    See complete shopping assistant
  </Card>

  <Card title="Configure Channels" icon="broadcast-tower" href="/channels/introduction">
    Add WhatsApp, Instagram, Facebook
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Test Square integration locally
  </Card>
</CardGroup>

***

<Card title="Need Help?" icon="question-circle">
  Having trouble with Square integration? Email us at **[support@heylua.ai](mailto:support@heylua.ai)** or
  check the [troubleshooting section](#troubleshooting) above.
</Card>


# WooCommerce
Source: https://docs.heylua.ai/integrations/woocommerce

Add AI shopping assistant to your WooCommerce store

## Overview

### About WooCommerce

**WooCommerce** powers over 28% of all online stores worldwide, making it the most popular e-commerce platform. As a WordPress plugin, WooCommerce gives you complete control and flexibility to build exactly the online store you envision - from selling physical products to digital downloads and subscriptions.

### Supercharge Your WooCommerce Store with AI

The **Lua Shopping Assistant** transforms your WooCommerce store from a passive catalog into an active sales assistant. Give every visitor their own AI-powered personal shopper that helps them find products, answers questions, and guides them to checkout.

**Why This Matters for Your Business:**

* 💰 **Increase Sales** - AI actively helps customers buy, not just browse
* 🎯 **Reduce Cart Abandonment** - AI assists through entire purchase journey
* ⏰ **24/7 Customer Service** - Answer product questions anytime, automatically
* 📈 **Higher Engagement** - Conversations keep customers on your site longer
* 🛒 **Smart Upselling** - AI recommends complementary products naturally
* 📱 **Mobile Optimized** - Perfect chat experience on any device
* 💬 **Reduce Support Tickets** - AI handles common questions instantly

<CardGroup>
  <Card title="WordPress Plugin" icon="wordpress">
    Native WooCommerce integration
  </Card>

  <Card title="Zero Code" icon="wand-magic-sparkles">
    No developers needed
  </Card>

  <Card title="Full Customization" icon="palette">
    Match your brand perfectly
  </Card>

  <Card title="Product Catalog" icon="boxes-stacked">
    Instant access to all products
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Download Plugin">
    Download the latest WooCommerce plugin:

    <Card title="Download lua-shopping-assistant.zip" icon="download" href="https://drive.google.com/file/d/16JQu-MYA05eoTFqV2SPFLk4f9IE7-GC-/view?usp=sharing">
      Latest version of the Lua Shopping Assistant plugin for WooCommerce
    </Card>

    <Note>
      Click the link to download from [Google Drive](https://drive.google.com/file/d/16JQu-MYA05eoTFqV2SPFLk4f9IE7-GC-/view?usp=sharing). Save the `lua-shopping-assistant.zip` file to your computer.
    </Note>
  </Step>

  <Step title="Access WordPress Admin">
    Log into your WordPress admin panel

    Navigate to: **Plugins** → **Add Plugin**

    <Frame>
      <img alt="WordPress Plugins menu" />
    </Frame>

    *Screenshot: WordPress sidebar showing Plugins menu option*
  </Step>

  <Step title="Upload Plugin">
    Click "Upload Plugin" button at the top

    <Frame>
      <img alt="Upload plugin" />
    </Frame>

    *Screenshot: "Upload Plugin" button and file chooser*
  </Step>

  <Step title="Choose File">
    Click "Choose File" and select `lua-shopping-assistant.zip`

    <Frame>
      <img alt="Choose plugin file" />
    </Frame>

    *Screenshot: File chooser showing lua-shopping-assistant.zip selected*
  </Step>

  <Step title="Install Now">
    Click "Install Now" button

    <Frame>
      <img alt="Installing plugin" />
    </Frame>

    *Screenshot: Installation progress showing:*

    * "Installing plugin from uploaded file: lua-shopping-assistant.zip"
    * "Unpacking the package..."
    * "Updating the plugin..."
    * "Removing the current plugin..."
  </Step>

  <Step title="Activation Success">
    Plugin installs successfully

    <Frame>
      <img alt="Plugin updated successfully" />
    </Frame>

    *Screenshot: Success message showing:*

    * "Plugin updated successfully."
    * "Activate Plugin" button
    * "Go to Plugin Installer" link
  </Step>

  <Step title="Activate Plugin">
    Click "Activate Plugin" button

    Plugin is now active and ready to configure
  </Step>
</Steps>

## Configuration

<Steps>
  <Step title="Access WooCommerce Menu">
    After activation, find "Lua Shopping Assistant" in WooCommerce menu

    <Frame>
      <img alt="WooCommerce menu with Lua" />
    </Frame>

    *Screenshot: WooCommerce sidebar showing:*

    * Home
    * Orders
    * Customers
    * **Lua Shopping Assistant** ← New menu item
    * **Lua Widget Settings** ← Configuration page
    * Reports
    * Settings
  </Step>

  <Step title="Open Lua Widget Settings">
    Click "Lua Widget Settings"

    <Frame>
      <img alt="Lua Widget Settings" />
    </Frame>

    *Screenshot: Lua Widget Settings page showing all configuration options*
  </Step>

  <Step title="Enable Widget">
    Check "Enable Lua Pop widget on storefront"

    <Frame>
      <img alt="Enable widget" />
    </Frame>

    *Screenshot: Checkbox for enabling widget*
  </Step>

  <Step title="Configure Settings">
    The Lua Widget Settings page provides all configuration options:

    * Agent ID (auto-configured)
    * Position (Bottom Right, Bottom Left, etc.)
    * Theme (Light or Dark)
    * Button Text and Title
    * Custom styling options
  </Step>

  <Step title="Customize Appearance">
    For detailed styling and customization options, see our complete chat widget guide:

    <Card title="Chat Widget Styling Guide" icon="palette" href="/chat-widget/styling">
      Complete guide to colors, positioning, themes, and custom styles
    </Card>

    All LuaPop customization options work in the WooCommerce plugin!
  </Step>

  <Step title="Save Changes">
    Click "Save Changes" at the bottom of the page

    <Frame>
      <img alt="Save changes" />
    </Frame>

    *Screenshot: "Save Changes" button*
  </Step>
</Steps>

## Widget Configuration

The WooCommerce plugin supports all LuaPop widget features:

<CardGroup>
  <Card title="Basic Settings" icon="cog">
    * Position
    * Theme
    * Button text
    * Chat title
  </Card>

  <Card title="Advanced Styling" icon="palette">
    * Custom colors
    * Border styles
    * Shadows
    * Typography
  </Card>
</CardGroup>

<Card title="Complete Styling Guide" icon="book" href="/chat-widget/styling">
  See the Chat Widget Styling documentation for all customization options →
</Card>

## Features

<CardGroup>
  <Card title="Product Search" icon="magnifying-glass">
    Agent can search your WooCommerce catalog
  </Card>

  <Card title="Product Details" icon="info">
    Provide specs, pricing, availability
  </Card>

  <Card title="Cart Integration" icon="cart-shopping">
    Add products to cart
  </Card>

  <Card title="Order Status" icon="truck">
    Check order tracking
  </Card>
</CardGroup>

## What Your Agent Can Do

With WooCommerce integration, your agent can:

* 🔍 **Search Products** - Find items in your catalog
* 📦 **Product Details** - Provide specs, pricing, stock status
* 🛒 **Add to Cart** - Help customers add items to cart
* 💳 **Checkout Assistance** - Guide through checkout process
* 📍 **Order Tracking** - Check order status and shipping
* ❓ **Answer Questions** - Product info, shipping, returns
* 💡 **Recommendations** - Suggest relevant products

## Customization Examples

### Minimal Style

```
Position: Bottom Right
Theme: Light
Button Text: "💬 Chat"
Text Color: #000000
Background: #FFFFFF
Border Radius: 50% (circular button)
```

### Branded Style

```
Position: Bottom Right
Theme: Dark
Button Text: "Need Help?"
Text Color: #FFFFFF
Background: Your brand color
Border: 2px solid
Border Radius: 12px
Chat Header: Match brand colors
```

### Prominent Style

```
Position: Bottom Right
Theme: Light
Button Text: "🛍️ Shopping Assistant"
Background: Bright color
Border: None
Border Radius: 25px
Box Shadow: 0 4px 12px rgba(0,0,0,0.15)
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget not appearing">
    **Check:**

    1. Plugin is activated
    2. "Enable Widget" is checked
    3. Agent ID is correct
    4. Save Changes clicked
    5. Clear browser cache
    6. Check browser console for errors
  </Accordion>

  <Accordion title="Widget shows but doesn't respond">
    **Check:**

    1. Agent ID is correct
    2. Agent is deployed (`lua production`)
    3. Skills are pushed (`lua push`)
    4. Internet connection working
    5. Check browser console for API errors
  </Accordion>

  <Accordion title="Styling not applying">
    **Try:**

    1. Save Changes after each modification
    2. Clear browser cache (Cmd+Shift+R / Ctrl+Shift+R)
    3. Check for CSS conflicts
    4. Use browser dev tools to inspect
  </Accordion>

  <Accordion title="Can't find settings page">
    **Location:**

    * WooCommerce → Lua Widget Settings

    **If missing:**

    * Verify plugin is activated
    * Check Plugins → Installed Plugins
    * Reactivate if needed
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Position for Best Engagement">
    **Bottom Right** (recommended)

    * Standard placement
    * Familiar to users
    * Doesn't interfere with content

    **Bottom Left**

    * Alternative if right side is crowded
    * Good for RTL languages
  </Accordion>

  <Accordion title="Theme Selection">
    **Light Theme:**

    * Clean, professional
    * Good for bright store designs

    **Dark Theme:**

    * Modern, sleek
    * Good for dark mode stores
    * Less eye strain
  </Accordion>

  <Accordion title="Button Text">
    **Good examples:**

    * "Need Help?" - Friendly, inviting
    * "Shop Assistant" - Clear purpose
    * "💬 Chat with us" - Emoji adds personality

    **Avoid:**

    * Generic "Chat" - Too vague
    * Too long text - Keep it short
  </Accordion>

  <Accordion title="Match Your Brand">
    Use your brand colors:

    * Background: Your primary color
    * Text: Contrasting color
    * Border: Accent color
    * Ensure good contrast for readability
  </Accordion>
</AccordionGroup>

## Plugin Updates

### Updating to New Version

<Steps>
  <Step title="Download New Version">
    Get updated `lua-shopping-assistant.zip`
  </Step>

  <Step title="Upload Again">
    Plugins → Add New → Upload Plugin

    Select new zip file
  </Step>

  <Step title="Install Now">
    WordPress will update the existing plugin

    <Frame>
      <img alt="Plugin updating" />
    </Frame>

    *Screenshot: Update process screen*
  </Step>

  <Step title="Settings Preserved">
    Your configuration is automatically preserved

    No need to reconfigure!
  </Step>
</Steps>

## Features Coming Soon

<Note>
  **🚀 Upcoming WooCommerce Features:**

  * Direct "Add to Cart" from chat
  * Order status checking
  * Product recommendations
  * Abandoned cart recovery
  * Inventory notifications
  * Custom product filters
  * Multi-language support
</Note>

## Support

Need help with WooCommerce integration?

* **Documentation**: This page
* **Email**: [support@heylua.ai](mailto:support@heylua.ai)
* **Admin Dashboard**: `lua admin` for agent management
* **Test Chat**: `lua chat` to test agent behavior

## Next Steps

<CardGroup>
  <Card title="Configure Your Agent" icon="robot" href="/cli/persona-command">
    Set up agent personality for shopping
  </Card>

  <Card title="Add Product Skills" icon="wrench" href="/getting-started/first-skill">
    Build custom shopping tools
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Test shopping conversations
  </Card>

  <Card title="E-commerce Demo" icon="cart-shopping" href="/demos/ecommerce-assistant">
    See complete shopping assistant
  </Card>
</CardGroup>


# Agent Templates
Source: https://docs.heylua.ai/marketplace/agent-templates

Versioned agent blueprints: persona, skills, connections, and automations — published once, deployed anywhere

## What an agent template is

An agent template is a **published, versioned blueprint of a working agent** — everything someone needs to deploy their own copy of it:

* **Persona** — who the agent is, captured as a template with `{{variables}}` the installer fills in ("You are the sales assistant for `{{COMPANY_NAME}}`…").
* **Skills, webhooks, jobs, processors, triggers, and the model** — everything [`lua push`](/cli/skill-management) and [`lua version promote`](/cli/version-command) manage together as one agent version.
* **Connections** — what the agent plugs into, declared as capabilities ("a CRM") satisfiable by any listed platform (Salesforce *or* HubSpot), each marked required or optional.
* **Trigger presets** — the agent's schedules and event triggers, with recommended defaults and installer-editable parameters ("check every 5 minutes" — change it to 10 at deploy).
* **The env contract** — which environment variables the template's code expects, declared by name and description, never by value.
* **Runtime dependencies** — things a deploy can't create but the agent needs to fully go live, like a WhatsApp or email channel, declared so the installer sees an honest post-deploy checklist instead of a false "live".
* **Outcomes** — the template's countable units of work ("follow-ups sent", "meetings booked"), counted by the platform from real side effects, so every install gets a comparable measure of what the agent actually delivers.

Publishing a template freezes one agent's promoted version into this blueprint. Deploying it materializes the blueprint as a working agent — a brand-new agent created for you in one call, or installed onto an agent you already run.

Every attribute of the blueprint — types, defaults, constraints, and what serves where — is documented in the [Template Manifest Reference](/marketplace/template-manifest).

<Note>
  **Three things called "template" — which one is this?**

  * **Agent Templates** (this page, and the `lua marketplace template` commands) — full agent blueprints on the marketplace.
  * The **Templates runtime API** in the SDK — WhatsApp *message* templates, the pre-approved outbound message formats Meta requires. Unrelated.
  * **Project scaffolds** — the starter files `lua init` generates. Also unrelated.
</Note>

<Note>
  Looking for the single-tool equivalent? See [Skills](/marketplace/creator-guide) — a skill is one reusable tool; a template is an entire agent.
</Note>

## Persona: captured, filled in, and yours after install

A template can carry the source agent's persona as a **persona template**: the system prompt with `{{variable}}` slots, each one declared with a type, a display name, and a description, so the deploy flow renders a labeled, explained field per slot — never a bare `COMPANY_NAME`.

Three rules govern how persona behaves across a template's life:

1. **At deploy, the slots are filled from your answers.** If the template marks its persona editable, you can also tweak the resolved prompt before it lands.
2. **An agent that already has a persona keeps it.** Installing a template onto an existing agent never replaces its persona by default — overwriting is an explicit opt-in. (A fresh agent created by deploy always gets the template's persona; there's nothing to preserve.)
3. **Your post-install persona edits survive updates.** If you tune the agent's persona after install and later accept a template update, the update skips the persona write and tells you so — "re-apply template persona" is a separate, explicit action, never a side effect of updating.

What a template still **never** touches: environment variable *values* (always set per-agent via [`lua env`](/cli/env-command) or supplied at install), channels and connected numbers, and the agent's name.

<Warning>
  Voice agents can't be templated yet. Publishing from a source agent that has voices or device triggers is rejected at publish time, with a message saying why — rather than shipping a template that deploys half-working.
</Warning>

## The env contract

A template version declares an **env contract**: the variable names its code expects, each with a description and a required/optional flag — never values. Missing required variables block an install with a clear list of what's missing.

```bash theme={null}
# Declare the contract when publishing a version
lua marketplace template publish \
  --template-id tpl_abc \
  --env-contract "STRIPE_KEY=Stripe secret key for the checkout skill" \
  --env-contract "SUPPORT_EMAIL?=Fallback contact address"

# Satisfy it at install time
lua marketplace template install \
  --template-id tpl_abc \
  --env-vars "STRIPE_KEY=sk_live_xxx" \
  --force
```

`KEY=description` marks a variable required; `KEY?=description` marks it optional. Omitting `--env-contract` entirely when publishing a new version inherits the previous version's contract unchanged.

<Note>
  **`--skip-env-check` is retired.** The env-contract check is now always enforced on the server — there is no way to bypass it. The flag is still accepted so old scripts don't break, but it does nothing except print a deprecation warning. Satisfy the contract with [`lua env`](/cli/env-command) or `--env-vars` instead.
</Note>

## Connections: "a CRM", not "Salesforce"

A template declares what it plugs into as **capabilities**, each satisfiable by any platform in its allow-list:

* A capability like `crm` might list Salesforce and HubSpot — **any one** satisfies it.
* Each capability is **required** (install blocks without it) or **optional** (offered, never blocking — the parts of the agent that depend on it stay safely inactive until you connect it).
* At deploy, the platform checks the connections you've **already granted** and reuses them — a capability you've already connected is skipped silently. You're only ever asked to connect the genuine gaps, and often there are none.
* If more than one of your connections could satisfy a capability (a personal and an org Salesforce, say), you're asked which to use — never auto-picked.

See [Deploying Templates](/marketplace/deploying-templates#connections-reuse-what-you-already-have) for the installer's view of this, including required-versus-optional behavior and rebinding later.

## Trigger presets: recommended, confirmed, adjustable

Every schedule and event trigger in a template ships as a **preset**: a recommended on/off default plus the parameters the creator marked editable (an interval, a time of day). Nothing arms silently — deploy ends with an explicit confirmation listing exactly which automations go live, and anything outbound or event-driven stays off until you confirm it. Schedules render in *your* timezone, with the next run times shown before you confirm.

## Lifecycle: private by default, reviewed when public

<Steps>
  <Step title="Private by default">
    A new template is visible and installable only within your organization — built for fleets first. Public is an explicit choice.
  </Step>

  <Step title="Per-version review for public templates">
    Going public puts the template through platform review. Review is **per version**: every version published while a template is public enters review and is not installable by others — including via the update badge — until approved. A rejection leaves previously approved versions listed. Creator self-test installs on your own org's agents are exempt, so you can verify a pending version before anyone else can touch it.
  </Step>

  <Step title="Deprecate a version">
    Deprecating a version blocks **new installs of that version**; agents already running it are unaffected, and the changelog carries the reason. You can't deprecate the only approved version of a still-listed public template — unlist first.
  </Step>

  <Step title="Unlist (soft-retire)">
    Unlisting hides the template and blocks new installs and creator-pushed updates. Existing installs keep running with what they have, uninstall always works, and an installer can still re-run their **same installed version** to rebind a connection — recovery paths stay open. There is no hard delete: unlist + deprecate is the complete retirement path, keeping the audit trail intact for every agent still running the template.
  </Step>
</Steps>

## Updates and consent

Installing a template never gives its creator ongoing write access unless you explicitly opt in (`allowCreatorUpdates`, off by default for user-facing installs). Two different kinds of change are treated differently:

* **Code-only updates** — the creator improved a skill's implementation without changing what the template asks for — flow to opted-in installs under that standing consent. This is what makes fleet operations work.
* **Consent-surface changes** — widened OAuth scopes, an added connection, a changed trigger instruction — require fresh consent from **every** install, opted-in or not. A creator push carrying one of these is rejected per target until the installer reviews and accepts it.

Updates are previewed, not blind: before accepting, an installer sees the changelog, what's added/removed/changed, any scope changes, and which of their currently-armed automations survive. Their persona edits and schedule tweaks are preserved across the update. See [Deploying Templates](/marketplace/deploying-templates#updates) for the full installer view.

## Fleet operations

Template creators (and orgs running internal fleets) roll a version out to many agents at once with `apply`:

```bash theme={null}
# Canary first: a named set of agents
lua marketplace template apply \
  --template-id tpl_abc \
  --agents agent_1,agent_2,agent_3 \
  --force

# Then every consenting agent that has the template installed
lua marketplace template apply --template-id tpl_abc --all-installed --force
```

`apply` runs asynchronously on the server — the CLI starts the run, polls it, and prints a per-target result table (pass `--no-wait` to get the run ID back immediately):

```
Apply run failed (run_xyz)
AGENT ID   STATUS     LOCAL VERSION  ERROR
agent_1    applied    v4
agent_2    applied    v5
agent_3    failed     v3             Missing required environment variables: STRIPE_KEY
```

Any failed target marks the whole run `failed` and makes the CLI exit non-zero, so a partial rollout never looks like a clean success in CI. Successful targets are unaffected; re-running `apply` is safe.

`apply` only ever reaches agents that opted in with `allowCreatorUpdates` — and a creator can't use apply results to probe which agents installed without consenting. A creator push also **never arms new automations**: new or renamed triggers land disabled on the target, awaiting the installer's confirmation, and a trigger the installer paused stays paused.

### Fleet visibility and rollback

```bash theme={null}
lua marketplace template status --template-id tpl_abc     # who runs which version
lua marketplace template versions --template-id tpl_abc   # all published versions
lua marketplace template view --template-id tpl_abc --version 3
```

Rollback needs nothing template-specific: installing a template promotes a normal agent version, so `lua version promote <n>` on any single agent rolls it back, and applying an older template version re-materializes that version fleet-wide.

## Related

* [Publishing Templates](/marketplace/publishing-templates) — the creator's guide: draft, author, publish, review, roll out
* [Template Manifest Reference](/marketplace/template-manifest) — every attribute: fields, types, defaults, constraints, lints
* [Deploying Templates](/marketplace/deploying-templates) — the installer's guide: deploy, connect, operate, update, uninstall
* [Marketplace Command reference](/cli/marketplace-command)
* [Version Command](/cli/version-command) — the agent-version mechanics installs build on
* [Environment Variables Command](/cli/env-command)


# Publishing Skills
Source: https://docs.heylua.ai/marketplace/creator-guide

Publish and manage your skills on the marketplace

## Becoming a Creator

As a creator, you can share your agent skills with the entire Lua community — or keep them private to your own organization. Whether it's a specialized tool, a complex integration, or a utility job, the marketplace handles versioning, distribution, and discovery.

<Note>
  Looking to publish a whole agent — persona, skills, connections, and automations — instead of a single skill? That's an [agent template](/marketplace/agent-templates); the authoring journey is in [Publishing Templates](/marketplace/publishing-templates).
</Note>

### Listing a Skill

To list a skill, it must be defined in your project and **pushed to the server**. The marketplace verifies the skill against your agent's active skills on the server.

1. **Run the skill menu**:
   ```bash theme={null}
   lua marketplace skill
   ```
2. Select **"List a new skill on the Marketplace"**.
3. Choose the skill you want to publish (fetched from your agent on the server).
4. **Metadata**: Follow the prompts to configure your skill's listing details.
   * **Display Name**: Enter a user-friendly name (e.g., "Hotel Concierge").
   * **Visibility**: Public (default) or private — see below.
5. The skill is now listed!

Non-interactively:

```bash theme={null}
lua marketplace skill list \
  --skill-name mySkill \
  --display-name "My Skill"
```

### Private Visibility

By default, a listed skill is **public** — anyone on the marketplace can search for it, view it, and install it. Set `--visibility private` to restrict it to your own organization instead:

```bash theme={null}
lua marketplace skill list \
  --skill-name internalCrmSkill \
  --display-name "Internal CRM Helper" \
  --visibility private
```

A private skill is visible and installable only to members of the creator's organization. Everyone else — including a search that would otherwise match it — gets a plain not-found, exactly as if the listing didn't exist. There's no separate "unlisted" state to reason about: visibility is the one switch.

<Note>
  **Common use case**: an internal skill library shared across your organization's own agents — reusable tools your team builds once and installs onto every agent that needs them, without exposing them on the public marketplace.
</Note>

The review flow, versioning, and every other marketplace mechanic (publishing versions, env vars, unlisting) work identically for private and public skills — visibility only changes who can find and install the listing.

### Publishing Versions

Listing a skill creates the entry, but users can't install it until you publish a **version**.

1. Select **"Publish a new version of a skill"**.
2. Choose your listed skill.
3. Select the version to publish (e.g., `1.0.0`).
   * The CLI detects versions that have been compiled and pushed to the server.
4. **Configuration**:
   * **Environment Variables**: Define any variables your skill needs (e.g., `HOTEL_API_KEY`).
   * **Changelog**: Optionally add a note about what's new in this version.
   * Complete any other required configuration steps.

Non-interactively:

```bash theme={null}
lua marketplace skill publish \
  --marketplace-id mkt_xyz \
  --version-id v1 \
  --changelog "Adds support for European VAT" \
  --env-vars-json '[{"name":"HOTEL_API_KEY","required":true,"description":"API key for the hotel PMS"}]'
```

You'll be notified once the review is complete.

<Note>
  **Semantic Versioning**: The marketplace uses SemVer. Always ensure your version numbers (e.g., `1.0.1`, `2.0.0`) reflect the nature of your changes.
</Note>

### Managing Listings

You can manage your existing skills through the same menu:

* **Edit Metadata** (`edit`): Change the display name of your skill.
* **Unlist** (`unlist`): Remove the skill from the marketplace (hides it from search; existing installs keep working).
* **Unpublish Version** (`unpublish`): Remove a specific version if it has issues.
* **View My Listings** (`mine`): See a summary of your published skills, install counts, and latest versions.

```bash theme={null}
lua marketplace skill edit --marketplace-id mkt_xyz --display-name "My Skill (Pro)"
lua marketplace skill unlist --marketplace-id mkt_xyz --force
lua marketplace skill unpublish --marketplace-id mkt_xyz --version-id v1 --force
lua marketplace skill mine --json
```

### Best Practices

* **Clear Documentation**: Use descriptive names and helpful descriptions for your environment variables.
* **SemVer**: Increment patch versions for bug fixes, minor for features, and major for breaking changes.
* **Vector Search**: Your skill's name and description are indexed. Make them relevant to what users might search for (e.g., "moderation", "payment", "weather"). Private skills are only searchable within your own organization, so this still matters for internal discovery.

## Related

* [Marketplace Command reference](/cli/marketplace-command)
* [Installing Skills](/marketplace/installer-guide)
* [Agent Templates](/marketplace/agent-templates) / [Publishing Templates](/marketplace/publishing-templates)


# Deploying Templates
Source: https://docs.heylua.ai/marketplace/deploying-templates

Deploy an agent template in minutes: reuse your connections, confirm your automations, operate and update the install

## Two ways to get a template running

* **One-call deploy** — the consumer path. Pick a template from the catalog and deploy: a fresh agent is created for you and the template installed onto it in one call. You never need to know what "an agent" is first.
* **Install onto an existing agent** — the advanced path, for an agent you already run (behind a picker in the app, or `lua marketplace template install` from the CLI). Installing onto a shared/org agent requires org-admin rights on that agent.

Either way, the deploy flow only asks for what's genuinely missing: connections you've already granted are reused silently, and a fully-satisfied deploy goes straight from overview to confirm.

This page follows the installer's side of **Standup Sidekick** — a template that captures your wins during the day, nudges you before standup on a schedule, and optionally posts to Slack. Its creator's side is the running example in [Publishing Templates](/marketplace/publishing-templates).

## One-call deploy

`POST /marketplace/templates/:id/deploy` creates a fresh agent in your default org (pass `orgId` to target another org you belong to, and `displayName` to name the agent), installs the template's version onto it, promotes the first agent version, and registers you as the agent's admin. The response tells you exactly what went live:

```json theme={null}
{
  "agentId": "…",
  "agentVersion": 1,
  "status": "installed",
  "armedTriggers": ["standup-nudge"],
  "blockedTriggers": [
    { "key": "post-to-slack", "reason": "optional connection declined" }
  ],
  "personaSkipped": false
}
```

* **Idempotency** — send an `Idempotency-Key` header. A retry with the same key returns the original outcome and **never creates a second agent**, so a timed-out request is always safe to resend.
* **Nothing is created unless the deploy can succeed.** Required connections are checked **before anything exists**: a deploy whose required capabilities can't be satisfied fails up front with the same connections-unsatisfied error the deploy flow renders — no agent is created, nothing is billed, and nothing appears on your agent roster. And a capability you've already satisfied deploys without re-connecting — reuse is the default, not a special case (see [Connections](#connections-reuse-what-you-already-have)).
* **Rollback on failure** — if the install fails after the agent was created, the agent creation is rolled back; a retry starts clean.
* **"Live from minute one" means workspace chat.** A freshly deployed agent has no external channels (WhatsApp, email, Slack as a *channel*) until you connect them — templates that need one declare it, and your install shows a setup checklist ("connect WhatsApp to go live") instead of a false green.

## Installing onto an existing agent

The install request carries everything the deploy flow collected:

```json theme={null}
{
  "version": 3,
  "envValues": { "STANDUP_HOUR": "9" },
  "connectionSelections": {
    "notify": { "type": "slack", "connectionId": "conn_x" }
  },
  "triggerOverrides": {
    "standup-nudge": { "enabled": true, "params": { "preset.seconds": 600 } }
  },
  "personaVars": { "COMPANY_NAME": "Acme", "TONE": "brief and encouraging" },
  "model": "anthropic/claude-sonnet-5",
  "allowCreatorUpdates": false
}
```

* `connectionSelections` — which of your connections satisfies each declared capability (reused or freshly connected).
* `triggerOverrides` — which automations to arm, with your values for any installer-editable parameters.
* `personaVars` — your answers for the persona's `{{variable}}` slots. If the template's persona is marked editable, you may instead submit an edited resolved prompt, which is stored verbatim.
* `model` — the model the agent runs on. Omit it and a freshly deployed agent takes the template's model (when your workspace allows it); an agent that already has a model keeps it. Send `""` for your workspace default, or any approved model code. The choice is yours from then on: template updates never change it.
* `allowCreatorUpdates` — off by default; opt in only if you want the creator to push future versions to this install (see [Updates](#updates)).

Two persona rules protect the agent you already have: **an existing persona is kept** — overwriting it with the template's is an explicit opt-in, never a default — and everything else about your agent that the template doesn't manage (your own skills, env values, channels, name) is untouched.

From the CLI, the equivalent for fleet and development work:

```bash theme={null}
lua marketplace template install \
  --template-id tpl_standup \
  --env-vars "STANDUP_HOUR=9" \
  --allow-creator-updates \
  --force
```

<Note>
  `--skip-env-check` no longer does anything: the env-contract check is always enforced server-side. The flag is accepted for old scripts but only prints a deprecation warning. Satisfy the contract with [`lua env`](/cli/env-command) or `--env-vars`.
</Note>

## After install: the template's first run

Some templates declare a **post-install first run** — something the agent does the moment it's installed, before you've said a word to it. It's part of what you consent to: the confirm screen shows it as *"After install, the agent will: …"*, quoting the template's own instruction.

Right after a successful deploy (or install onto an existing agent), the agent performs it — typically introducing itself, checking the connections you granted, or running its own setup (a PR-review template, for example, wires provider webhooks on every repo you administer and reports back). A first run has up to two parts, in order: a **setup tool** the platform executes directly (deterministic — no conversation involved), then a **first turn** where the agent acts on the template's instruction. What to expect:

* **It runs once.** A given instruction runs at most once per install — re-installing, or updating to a version that keeps the instruction unchanged, doesn't repeat it. An update that *changes* the instruction runs the new one once.
* **It never blocks or breaks the install.** The install returns as soon as the agent is live and its automations are armed; the first run happens in the background (on a one-call deploy, only after your access to the new agent is registered). A setup-tool failure is recorded on the install rather than failing it.
* **You can see how the setup went.** `GET /agents/:agentId/templates` reports `setup` as `running`, `ok`, or `failed` for a template that declares a setup tool; the desktop shows the same next to the install. A failed setup tool can be re-run with `POST /agents/:agentId/templates/:templateId/setup/retry` — the retry runs only the tool, never a second first turn.
* **It acts as you.** Both parts carry your identity — the setup tool runs with *your* connections, and anything user-scoped the turn does (an inbox card, a memory note) lands with you, the installer.

## Connections: reuse what you already have

Before asking you for anything, the deploy flow reconciles the template's declared capabilities against the connections you (and your org) already hold:

* **Already connected** → skipped silently and bound. "3 of 4 already connected" renders before you do anything — often it's all of them.
* **Multiple matches** → if more than one of your connections could satisfy a capability (a personal Google Calendar *and* the org's, say), you're asked which to use — never auto-picked. The choice matters: the agent will act using that account's access.
* **Missing, required** → a connect chip. Pick a platform from the capability's list (any one satisfies it — "a CRM" can be Salesforce *or* HubSpot), grant access once, and the flow advances. Install is blocked until every required capability is satisfied.
* **Missing, optional** → offered, never blocking. Decline it and the parts of the agent that depend on it stay safely inactive — the install response lists them as blocked, and you can connect later.
* **Connected but with too little access** → a read-only grant never silently binds to a template that writes; you're asked to reconnect with more access instead of hitting failures at runtime.

Reusing a connection never moves or copies your grant — it binds *this agent's* use of it. Personal connections bind only to your own agents; shared/org agents use org-shared connections. If a bound connection is later revoked or its owner leaves the org, the dependent parts of the agent stop safely and you're prompted to reconnect or rebind — never a half-broken agent silently erroring.

**Rebinding later** (switching a capability to a different connection) is a re-run of the install at your same version with a new selection — it doesn't change the template version and doesn't touch your other settings.

## Automations: nothing arms silently

The template's triggers arrive as **presets** — recommended defaults, shown with what each one does and, for schedules, the next run times in *your* timezone. The rules, in your terms:

* **A fresh install arms exactly what you confirmed.** Deploy ends with an explicit confirmation listing the automations going live. Anything you didn't confirm is installed disabled. Anything event-driven or outbound defaults to off until you say so.
* **Editable parameters are validated, not clamped.** If the creator allowed "nudge every N minutes", your value is checked against the declared bounds — whole minutes only, so `90` seconds is rejected with a clear field error before anything is created.
* **Toggling later doesn't need a version change.** Re-submitting your same installed version with an override for one trigger changes just that trigger — settings you don't mention carry forward unchanged, never reset.
* **Creator updates never arm anything new.** New or renamed triggers in an update land disabled awaiting your confirmation, and a trigger you paused stays paused — even on a creator-pushed update.
* **Schedules run on your clock.** A template authored in Stockholm doesn't run at Stockholm time for you — the schedule's timezone is yours, shown explicitly at confirm.

## Operating the install

Your installed-templates view shows, per install:

* **Installed version and update availability** — the installed version, plus one action: *Update to latest* (once approved). Version browsing and rollback are creator/org-admin surfaces, not something you manage.
* **Automation health and next runs** — each trigger's armed state, health, and upcoming fire times. An armed schedule that isn't actually firing is flagged, not silent.
* **Connection binding health** — which connection backs each capability and whether it's healthy, paused, or needs reconnecting.
* **Outcomes** — the template's declared units of work, counted by the platform from real side effects: "342 follow-ups sent this month", never self-reported by template code.
* **Executions** — run history for the template's jobs and triggers, same as any of your agent's own.

## Updates

Accepting an update is one action, and it's previewed first: the changelog, what's added/removed/changed, any **scope or connection changes** (which always require your fresh consent, even if you opted into creator updates), and which of your armed automations survive.

What survives an update, guaranteed:

* **Your persona edits.** If you tuned the agent's persona after install, the update skips the persona write and says so — "re-apply template persona" is a separate explicit action.
* **Your schedule tweaks.** An interval you changed from 5 to 10 minutes is re-applied over the new version's preset. If the new version's allowed range no longer permits your value, the update blocks with a field error asking for a new value — never a silent replace.
* **Your armed set.** Triggers keep the state you left them in; genuinely new triggers land disabled.
* **Your bindings and values.** Existing connection bindings and param values carry forward; only genuinely new requirements prompt you.

If you never opt into creator updates, nothing changes on your agent until you accept an update yourself. If you do opt in, only **code-only** improvements flow automatically — anything that changes what the template can access or is instructed to do comes back to you for consent.

## Uninstall

Some templates declare a **pre-removal cleanup**. Like the post-install first run, it's shown to you before you commit: the uninstall confirmation reads *"Before removal, the agent will: …"*, quoting the template's own copy. The cleanup runs **before** anything is torn down — while the template's skills, connection bindings, and trigger URLs still work — so the agent can undo external state the install created (deregister provider webhooks, close out third-party resources) and say goodbye. Three guarantees:

* **It runs as you**, the person uninstalling — with your connections, the same as the install did.
* **It can never block removal.** Cleanup is best-effort: a deterministic cleanup tool is given a bounded run, a goodbye turn a bounded grace, and then teardown proceeds regardless.
* **You see the outcome.** The uninstall result reports whether cleanup ran and whether it succeeded — a failed cleanup is visible, never silent, and never turns into a failed uninstall.

Uninstalling removes what the install brought and nothing else:

**Removed:** every primitive the template manages (its skills, jobs, webhooks, triggers), its connection bindings (the agent's *use* of your connections — your underlying grants are never touched), its event subscriptions, and **only the env keys this install introduced** — including the platform-written `LUA_TRIGGER_URL__*` trigger-URL variables — while pre-existing keys, and keys another install also relies on, are kept. A new clean agent version is promoted.

**Kept:** the persona (it became the agent's identity at deploy; yanking it would break a running agent mid-conversation — reset it separately if you want), your own local skills and primitives, your channels, and your env values that predate the install.

```bash theme={null}
lua marketplace template uninstall --template-id tpl_standup --force
```

Deleting the whole agent runs the same teardown for every template on it — no orphaned grants or schedules survive the agent they served.

## Org template policy

Orgs govern what their members deploy. The policy has an allow/deny list, an approval mode, and a catalog on/off toggle for members.

**As a member:**

* A template your org blocks shows as *blocked by your org* up front — the deploy flow is suppressed, not failed at submit.
* In **approval mode**, your deploy submits as a request instead of executing. Your answers are kept; when an org admin approves, the deploy runs as *you* — with your connections, re-validated at execution, so a connection you revoked while it sat in the queue fails safely rather than deploying stale.
* Once you've installed something, your own updates and rebinds don't re-enter the approval queue — unless the update changes what the template can access, which requires consent anyway.

**As an org admin:**

* Set the policy: allowed/denied templates, approval mode, and whether members see the catalog at all. An admin's own deploys self-approve without queueing.
* Review pending install requests from the org installs view; a request from a since-deactivated member is voided, never executed.
* See every template install across the org's agents — filterable by template, by owner, by status. The pre-offboarding question "what has this person's identity bound, org-wide?" is one query, and when someone leaves, rebind prompts for their bindings route to you rather than a deactivated account while an agent sits dark.

## Related

* [Agent Templates](/marketplace/agent-templates) — the model: what a template contains, lifecycle, consent
* [Publishing Templates](/marketplace/publishing-templates) — the creator's side
* [Marketplace Command reference](/cli/marketplace-command)
* [Environment Variables Command](/cli/env-command)


# Installing Skills
Source: https://docs.heylua.ai/marketplace/installer-guide

Find and install skills for your agent

## Finding Skills

The marketplace offers a wide range of skills to enhance your agent.

<Note>
  A skill adds one capability to an agent you're already building. If you want a whole working agent — persona, skills, connections, and automations, deployed in minutes — that's an [agent template](/marketplace/agent-templates); see [Deploying Templates](/marketplace/deploying-templates).
</Note>

1. **Run the skill menu**:
   ```bash theme={null}
   lua marketplace skill
   ```
2. Select **"Browse & search for skills"**.
3. You can browse the full list or enter a search term.
   * Search matches against skill names, descriptions, and tags.
   * Search only ever returns skills you're allowed to see: public listings, plus any private listings from your own organization.
4. Select a skill to view details, including:
   * Description and category
   * Verified status
   * Author
   * Available versions and tools
   * Required environment variables

Non-interactively:

```bash theme={null}
lua marketplace skill search --query "CRM"
lua marketplace skill view --marketplace-id mkt_xyz --json
```

<Note>
  A private skill from another organization is indistinguishable from one that doesn't exist — search won't surface it, and looking it up by ID returns not-found. If a colleague shares a private skill's marketplace ID with you but you're not in the listing creator's organization, you'll see the same not-found.
</Note>

### Installing a Skill

Once you've found a skill:

1. Select **"Install"** (if viewing details) or choose **"Install a skill from the Marketplace"** from the main menu.
2. **Version Selection**:
   * The CLI will show available versions.
   * By default, the latest stable version is recommended.
3. **Configuration**:
   * If the skill requires environment variables (e.g., API keys), you will be prompted to enter them.
   * These values are securely stored in your agent's environment variables.
4. **Confirmation**: Review the installation details and confirm.

Non-interactively:

```bash theme={null}
lua marketplace skill install \
  --marketplace-id mkt_xyz \
  --version-id v1 \
  --env-vars "STRIPE_KEY=sk_xxx,WEBHOOK_SECRET=whsec_yyy" \
  --force
```

The skill is now installed on your agent and ready to use!

### Managing Installed Skills

You can manage your installed skills directly from the CLI:

* **List Installed** (`installed`): See all marketplace skills currently on your agent.
* **Update** (`update`): Upgrade a skill to a newer version.
  * The CLI checks for updates and lets you choose a new version.
  * You can also update environment variable configuration without changing versions.
* **Uninstall** (`uninstall`): Remove a skill and its configuration from your agent.

```bash theme={null}
lua marketplace skill installed --json
lua marketplace skill update --skill-name myCRMSkill --version-id v2
lua marketplace skill update --skill-name myCRMSkill --env-vars "STRIPE_KEY=sk_new"
lua marketplace skill uninstall --skill-name myCRMSkill --force
```

<Note>
  **Safety Check**: The CLI prevents you from installing a skill that is already present on your agent to avoid conflicts. Use `update` to modify existing installations.
</Note>

## Related

* [Marketplace Command reference](/cli/marketplace-command)
* [Publishing Skills](/marketplace/creator-guide)
* [Agent Templates](/marketplace/agent-templates) / [Deploying Templates](/marketplace/deploying-templates)


# Marketplace Overview
Source: https://docs.heylua.ai/marketplace/overview

Discover, install, and publish skills and agent templates

## The Lua Marketplace

The Marketplace is where developers share reusable pieces of agent functionality with each other — either a single **skill**, or a full **agent template**.

```bash theme={null}
lua marketplace                 # Interactive: pick Skills or Agent templates
lua marketplace skill           # Skill action menu
lua marketplace template        # Template action menu
```

<Note>
  The Marketplace command tree is `lua marketplace [noun] [action]`, where `noun` is `skill` or `template`. See the [Marketplace Command reference](/cli/marketplace-command) for every action and flag.
</Note>

## Skills vs. agent templates

Both are published, versioned, and installable — but they operate at different scopes.

<CardGroup>
  <Card title="Skill" icon="wrench">
    A single reusable tool package — e.g. a CRM lookup, a payment integration, a moderation filter. Install it into an agent that already has its own persona, other skills, webhooks, and jobs. Composable: install as many as you need alongside your existing setup.
  </Card>

  <Card title="Agent Template" icon="layer-group">
    A published blueprint of an **entire agent** — its persona (with fill-in variables), skills, webhooks, jobs, triggers with editable presets, declared connections ("a CRM" — Salesforce or HubSpot), and the model. Deploying one gives you a working agent wired into the tools you've already connected — created fresh in one call, or installed onto an agent you already run.
  </Card>
</CardGroup>

**Use a skill** when you want to add one capability to an agent you're already building. **Use an agent template** when you want a working agent from a known-good blueprint — a one-off deploy from the catalog, or a fleet of near-identical agents kept in sync as the blueprint evolves. A common pattern: build and tune one merchant's support agent by hand, then publish it as a template so every new merchant onboards from the same starting point, and every improvement rolls out to all of them with a single `apply`.

Templates never touch a target agent's environment variable *values*, channels, or name — those stay per-agent. Persona travels with the template as a fill-in-the-blanks starting point, but an agent that already has a persona keeps it, and your post-install persona edits survive updates. See [Agent Templates](/marketplace/agent-templates) for the full model.

### Ecosystem Roles

<CardGroup>
  <Card title="Publishing Skills" icon="code" href="/marketplace/creator-guide">
    Publish your skills to the world. Manage versions, environment variables, visibility, and listings.
  </Card>

  <Card title="Installing Skills" icon="download" href="/marketplace/installer-guide">
    Browse verified skills, search by capability, and install with one command.
  </Card>

  <Card title="Publishing Templates" icon="code-branch" href="/marketplace/publishing-templates">
    Turn a working agent into a template: draft, author, publish, review, and roll out updates.
  </Card>

  <Card title="Deploying Templates" icon="rocket" href="/marketplace/deploying-templates">
    Deploy a template in minutes — reuse your connections, confirm your automations, operate and update the install.
  </Card>
</CardGroup>

<Card title="Agent Templates" icon="layer-group" href="/marketplace/agent-templates">
  The model behind both: what a template contains, its lifecycle, review, and update consent.
</Card>

### Key Features

* 🌍 **Global Discovery**: Public skills and templates are indexed and searchable by name, description, and tags.
* 🔒 **Private Visibility**: List a skill or create a template as private — only your organization can find and install it. Everyone else gets a not-found, same as if it didn't exist.
* 📦 **Semantic Versioning**: Full support for `major.minor.patch` skill versioning; templates version as sequential integers per template.
* ⚙️ **Smart Configuration**: Environment variables are declared per-version and configured interactively (or via flags) at install time.
* 🔄 **Update Management**: Upgrade an installed skill to a newer version, or roll a template out to every consenting agent that has it installed — with previews before accepting, and re-consent whenever an update changes what a template can access.
* 🛡️ **Reviewed Public Catalog**: Public templates are platform-reviewed per version before anyone can install them; orgs can additionally allow, deny, or require approval for template installs.

<Note>
  You can jump directly into either domain non-interactively, e.g. `lua marketplace skill search --query "CRM"` or `lua marketplace template status --template-id tpl_abc`. See the [Marketplace Command reference](/cli/marketplace-command) for the full flag set.
</Note>


# Publishing Templates
Source: https://docs.heylua.ai/marketplace/publishing-templates

Turn a working agent into a template: draft, author, publish, review, and roll out updates

## From agent to template

You never hand-write a template manifest. You build a real agent, and the platform does the heavy lifting: publishing **freezes every primitive** from your promoted agent version automatically, and a **draft composer** infers the rest — connections, persona variables, trigger presets — into your project's `lua.skill.yaml` for you to review like a diff. Your job is the product decisions: which connections are required, what the installer-facing copy says, which automations should be on by default.

This guide follows one agent end to end: **Standup Sidekick**, a small agent that logs the wins a user mentions during the day (`log_win` / `list_wins` tools in a `standup-skill`), nudges them before standup with a scheduled `standup-nudge` job, and has a persona ("You are the Standup Sidekick for Acme Demo Co…").

<Note>
  New to templates? Read [Agent Templates](/marketplace/agent-templates) first for the model — what a template contains, lifecycle, and consent. This page is the hands-on authoring journey.
</Note>

## Step 1 — Build and promote the source agent

Nothing template-specific yet: build Standup Sidekick the normal way.

```bash theme={null}
lua push          # upload skills, jobs, persona
lua version promote <n>
```

Use it until you're happy with it. The promoted version is what publishing will freeze.

## Step 2 — Create the template listing

Run this from the project connected to your source agent:

```bash theme={null}
lua marketplace template create \
  --name standup-sidekick \
  --display-name "Standup Sidekick" \
  --description "Captures your wins during the day and has them ready for standup."
```

Templates are **private by default** — only your organization can find and install them. Add `--visibility public` to head for the public catalog (which adds a [review step](#step-6-visibility-and-review), below).

## Step 3 — Run the draft composer

```bash theme={null}
lua marketplace template draft --template-id tpl_standup
```

The draft composer writes a `template:` section into your `lua.skill.yaml`, composed from what your agent actually is:

| Section                                 | How it's composed                                                                                                                                                                                                                                             |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Skills, webhooks, jobs, triggers, model | Frozen automatically from your promoted agent version at publish — the composer doesn't need to draft these at all                                                                                                                                            |
| `connections`                           | **Inferred** from how your skill code reaches integrations, your webhook event subscriptions, and the connections live on your agent — with sibling platforms proposed for the allow-list and `required` proposed where a skill depends on it unconditionally |
| `personaTemplate`                       | **Detected**: `{{VAR}}` tokens in your persona are extracted into declared variables, with drafted display names and descriptions; hardcoded specifics (a company name) may be proposed for promotion into variables                                          |
| `triggerPresets`                        | **Derived** from your jobs: the schedule verbatim, `enabled` matching each job's current state on your agent, editable-parameter envelopes pre-filled with valid bounds                                                                                       |
| `paramsMeta`                            | Lifted from your env-contract metadata, with types and defaults proposed from examples — `string`, `number` or `boolean` only; `enum` and `model` are authoring decisions the composer never infers                                                           |

Re-running `draft` later (say, after adding a skill for v2) performs an **additive merge**: newly inferred entries are appended, your existing keys are never modified, and the CLI prints a per-section diff of what it added versus kept. A full overwrite of your authored sections requires an explicit `--force`. Use `--source-version <n>` to compose from a specific promoted agent version instead of the active one.

<Tip>
  Inference proposes; you dispose. Required-versus-optional, the platform allow-list, and every installer-facing string are product decisions the composer can only draft. Review the section like any diff before publishing.
</Tip>

## Step 4 — Edit the `template:` section

Here's a realistic authored section for Standup Sidekick after the composer ran and the creator polished it. The persona got two variables, the nudge job's interval became installer-editable, and an optional chat connection was declared for posting nudges:

```yaml theme={null}
template:
  personaTemplate:
    template: |
      You are the Standup Sidekick for {{COMPANY_NAME}}.

      You quietly capture wins your user mentions during the day and keep
      them ready for standup. Tone: {{TONE}}, zero fluff. Never invent wins.
    editable: true            # installers may tweak the resolved prompt at deploy
    vars:
      - name: COMPANY_NAME
        displayName: Your company
        description: Used in the agent's replies and signatures.
        type: string
        required: true
        placeholder: Acme Inc.
      - name: TONE
        displayName: Tone of voice
        description: How the agent phrases its nudges and summaries.
        type: enum
        enum: [brief and encouraging, strictly factual]
        default: brief and encouraging

  connections:
    - key: notify
      capability: chat
      required: false          # offered at deploy, never blocking
      displayName: Notifications channel
      description: "Optional: where standup nudges get posted."
      platforms:
        - type: slack
          name: Slack

  triggerPresets:
    standup-nudge:
      enabled: true            # recommended default — confirmed at deploy, never silent
      editableParams:
        - path: preset.seconds
          label: Nudge every
          help: How often the agent checks for unsummarized wins.
          unit: minutes
          min: 60
          step: 60             # whole minutes only

  paramsMeta:
    STANDUP_HOUR:
      displayName: Standup hour
      description: Local hour of your team's standup, 0–23.
      type: number
      default: 9
```

A few rules worth knowing while you edit:

* **Every installer-facing entry needs `displayName` and `description`.** The deploy screen renders its copy straight from this section — a raw key is never shown as a form label, and publish rejects entries missing them.
* **Keys are identity.** A connection `key`, trigger key, param name, or persona var name is its stable identity across versions — renaming one means "remove + add", which costs installers their setting for it. Keep keys stable across versions.
* **The whole section is serialized on every publish.** When a `template:` section exists, all five subsections (`connections`, `personaTemplate`, `triggerPresets`, `paramsMeta`, `onInstall`) are always sent — an empty or deleted subsection is an explicit *clear*, not "keep the previous version's". Clearing or narrowing anything prompts you with the consequence before publishing (see below).
* **The env contract is declared at publish**, via the `--env-contract` flag — `paramsMeta` carries the display metadata for those variables:

```bash theme={null}
--env-contract "STANDUP_HOUR?=Local hour of the team standup"
```

Every attribute you can author here — with types, defaults, constraints, and the exact lint each one is guarded by — is in the [Template Manifest Reference](/marketplace/template-manifest).

### Lifecycle hooks: `onInstall` and `onUninstall`

A template can declare what its agent does **immediately after being installed** — and what it does to clean up **just before being removed**:

```yaml theme={null}
template:
  onInstall:
    tool: setup_notifications          # deterministic: runs directly, no model in the loop
    instruction: >-
      Introduce yourself and report which channel the notifications
      self-check just posted to.
  onUninstall:
    tool: remove_notification_hooks    # inverse of the setup — undo external state
    instruction: >-
      Tell the user the notification hooks were removed and say goodbye.
```

Each hook takes `tool` and/or `instruction` (at least one), and they run **tool first, then instruction**:

* **`tool`** names a tool from the template's own skills, executed **directly** with empty input — no agent turn, no model — as the installing (or removing) user, with a 180-second budget. Its outcome is recorded on the install. This is the deterministic half: wiring things up, tearing things down.
* **`instruction`** fires one background agent turn, delivered as the agent's message with the lifecycle marker: `[Install: Standup Sidekick] …` or `[Uninstall: Standup Sidekick] …`. This is the conversational half: greeting, reporting, saying goodbye.

**The recommended split: the tool does the work, the instruction is the conversation.** A tool run can't wander off-script, is awaited, and reports success or failure; an agent turn is the right place for the human-facing summary of what just happened — not for cleanup that must not be skipped.

The authoring rules:

* **Both hooks are consent-surface copy.** They're served verbatim on the manifest: the deploy screen shows *"After install, the agent will: …"* and the uninstall confirmation shows *"Before removal, the agent will: …"*. Write instructions for the installer to read — plain text, 1–2000 characters, no `{{var}}` tokens (nothing is substituted). A `tool` must name a tool that exists in the version's frozen skills; publish rejects a name that doesn't resolve.
* **`onInstall` fires at most once per distinct instruction.** Repeat installs and updates that keep the instruction unchanged never re-fire it; changing the instruction in a new version fires it once more on update.
* **`onUninstall` runs before teardown, and never blocks it.** Your cleanup gets the live agent — skills, bound connections, injected trigger URLs all still work. The tool run is awaited; the instruction turn gets a bounded grace before teardown proceeds regardless. Cleanup failure is recorded and reported in the uninstall result, but an uninstall **never** fails because cleanup did — design `onUninstall` as best-effort, and put anything that must happen in the `tool`.
* **Fail-soft, background, as the acting user.** Installs never wait on (or fail because of) `onInstall`; both hooks run with the acting user's identity — an [Inbox push](/api/inbox) inside one reaches the installer's (or remover's) own desk. Make both tools **idempotent**: a re-fired hook or a retried run must be safe.

### Self-wiring webhooks

The best template installs ask for **nothing**: no URL pasting, no provider settings screens. Two shipped pieces make that possible for webhook-driven templates:

1. **The platform injects each install's trigger URLs into the agent's env.** Every webhook trigger in your template gets its per-install URL written as `LUA_TRIGGER_URL__<TRIGGER_KEY>` (the trigger key upper-snaked — `github-pr-assigned` becomes `LUA_TRIGGER_URL__GITHUB_PR_ASSIGNED`), readable with [`env()`](/api/environment) from tools and trigger slots, kept fresh across token rotation, and removed at uninstall. See [LuaTrigger — Agents know their own URL](/api/luatrigger#agents-know-their-own-url).
2. **`onInstall` runs your setup tool on install.** Declare the tool in the hook so the platform executes it deterministically the moment the install completes, and pair it with an instruction so the agent reports the outcome.

A PR-review template wires GitHub this way — a `setup_github_watch` tool that discovers every repo the connected GitHub account administers and creates `pull_request` webhooks pointing at the injected URL:

```typescript theme={null}
// tools/SetupGithubWatch.ts (sketch)
import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

const TRIGGER_URL_ENV = 'LUA_TRIGGER_URL__GITHUB_PR_ASSIGNED';

export class SetupGithubWatchTool implements LuaTool {
  name = 'setup_github_watch';
  description = 'Wire pull_request webhooks on every repo the connected account administers.';
  inputSchema = z.object({});

  async execute() {
    const triggerUrl = env(TRIGGER_URL_ENV)?.trim();
    if (!triggerUrl) {
      return { ok: false, message: `${TRIGGER_URL_ENV} is not set — was this agent installed from a template?` };
    }
    // Idempotent: an existing hook with the same URL counts as already wired.
    return wireWebhooks(triggerUrl);
  }
}
```

```yaml theme={null}
template:
  onInstall:
    tool: setup_github_watch
    instruction: >-
      Tell the user which orgs and repos setup_github_watch just wired, and
      that a daily job keeps discovery current.
  onUninstall:
    tool: unwire_github_watch          # deletes the hooks the install created
    instruction: >-
      Tell the user the GitHub webhooks were removed.
```

The installer's whole experience: connect GitHub, confirm, and the agent's first message reports which repos it is now watching — and on uninstall, the hooks are deregistered before the install's trigger URLs stop existing. Make the setup tool **idempotent** (safe to re-run) and have it read the URL from the env at call time, never cache it (the platform rewrites the variable if the trigger's token is rotated).

## Step 5 — Publish

```bash theme={null}
lua marketplace template publish \
  --template-id tpl_standup \
  --changelog "v1: win capture, standup nudges, Slack notifications (optional)"
```

Publishing freezes your agent's active promoted version plus the authored `template:` section into an immutable, integer-numbered template version (v1, v2, v3 — not semver). Use `--source-version <n>` to freeze a specific promoted version instead of the active one.

If this publish **clears or narrows** previously authored sections (you removed a declared connection, dropped a persona var), the CLI prints the consequence per section and asks for confirmation. `--yes` auto-confirms *only* that consequence prompt — useful in CI — without skipping any other confirmation the way `--force` does.

### The lint battery

Publish is the quality gate: a version that would fail on an installer's agent — or render an unusable deploy screen — is rejected **at publish**, with actionable errors, and a rejected publish burns no version number. Among what it checks:

* **Schedules must actually be schedulable.** Interval schedules run on whole minutes only — a fractional-minute interval would silently never fire, so it's rejected up front. Publishing Standup Sidekick with `seconds: 90` fails with:

  ```
  ✖ Publish rejected

  triggerPresets.standup-nudge → preset.seconds: 90 is not a whole number
  of minutes. Interval schedules must be a multiple of 60 (minimum 60).
  Did you mean 60 or 120?
  ```

* **Persona variables must be declared, both ways.** Every `{{VAR}}` in the persona template needs a matching `vars` entry, and vice versa — across every persona branch, including voice text. Reserved names (like `persona`) are rejected.

* **Declarations must be self-consistent.** Enum lists non-empty, defaults satisfying their own type, every `editableParams.path` resolving into its trigger entry, optional vars carrying a default.

* **Connections must be real.** Every platform in an allow-list must exist in the integration catalog and match the declared capability; OAuth platforms must declare their scopes (that's what the installer consents to).

* **Portability must be authored, not hoped.** A capability may list multiple platforms only when the skills bound to it reach the connection through the capability, not through platform-specific calls — otherwise the allow-list is narrowed to the platform the code actually uses.

* **No secrets in frozen code.** A hardcoded API key in skill source is caught and rejected, pointing at the file and line, with the fix: declare it in the env contract so each installer supplies their own.

* **No voice yet.** A source agent with voices or device triggers can't publish — voice templates aren't supported in V1, and the error says so rather than shipping a template that deploys half-working.

## Step 6 — Visibility and review

Private templates are installable by your org the moment they're published — this is the fleet path, and it needs no review.

Going **public** adds platform review, and review is **per version**:

* Flipping a private template public enqueues its latest version for review; it lists publicly once approved. Older published versions stay org-only unless republished.
* Every version you publish while public enters review, and isn't installable by others — including through the update badge — until approved.
* **Your own self-test installs are exempt**: you can install a pending version onto your org's agents to verify it before anyone else can.
* A rejection leaves your prior approved versions listed. Versions are immutable — resubmitting means publishing a new version with the fix.

## Step 7 — Versioning and consent

Two kinds of change behave differently when you ship v-next, and it pays to know which you're making:

* **Code-only changes** — you rewrote a tool's implementation, fixed a bug, improved a prompt inside a skill — flow to opted-in installs (`allowCreatorUpdates`) under their standing consent. This is the everyday fleet-update path.
* **Consent-surface changes** — a widened OAuth scope, an added or changed connection, a changed trigger instruction — require **re-consent from every install**, opted-in included. Your push is rejected per target until the installer reviews and accepts the new surface themselves.

Installers also always get a server-computed **update preview** before accepting: your changelog, what's added/removed/changed, scope deltas, and which of their armed automations survive. Their persona edits and schedule tweaks are preserved across your update — see [what survives an update](/marketplace/deploying-templates#updates) for the installer's side.

## Step 8 — Roll out

```bash theme={null}
lua marketplace template publish \
  --template-id tpl_standup \
  --changelog "v2: weekly summary skill, nudge copy fixes"

# Canary against a couple of agents first
lua marketplace template apply \
  --template-id tpl_standup \
  --agents agent_team_a,agent_team_b \
  --force

# Then the consenting fleet
lua marketplace template apply --template-id tpl_standup --all-installed --force
```

There's no separate canary flag — a canary is the same `apply` aimed at a smaller target list. Check the per-target result table (and the agents themselves) before going wide. Pass `--no-wait` to get the run ID immediately and check on it later with `status`.

What a rollout will and won't do on each target:

* **Won't arm anything new.** Renamed or newly added triggers land disabled, awaiting the installer's confirmation. A trigger the installer paused stays paused.
* **Won't strand targets on a new required env key.** Targets missing it flip to a pending-input state with an installer prompt, rather than shipping a broken agent.
* **Won't overwrite installer customizations silently.** Installer-edited personas are skipped; installer-tuned schedule params are re-applied over your new preset; hand-edits to managed primitives surface an explicit confirm instead of a silent revert.
* **Fails loudly.** Any failed target marks the run `failed` and exits non-zero; successful targets are unaffected and a re-run is safe.

```bash theme={null}
lua marketplace template status --template-id tpl_standup   # who runs which version
```

## Step 9 — Retire

* **Deprecate a version** to block new installs of it — existing installs are unaffected, and the changelog carries the reason. You can't deprecate the only approved version of a still-listed public template; unlist first.
* **Unlist the template** to soft-retire it: no new installs, no more creator applies. Existing installs keep running with what they have, can still uninstall, and can still re-run their same installed version to rebind a connection.

There is no hard delete — unlist + deprecate is the complete retirement path, and it keeps the audit trail and install ledger intact for every agent still running your template.

## Related

* [Agent Templates](/marketplace/agent-templates) — the model: what a template contains, lifecycle, consent
* [Template Manifest Reference](/marketplace/template-manifest) — every attribute: fields, types, defaults, constraints, lints
* [Deploying Templates](/marketplace/deploying-templates) — what your installers experience
* [Marketplace Command reference](/cli/marketplace-command)
* [Publishing Skills](/marketplace/creator-guide) — the single-skill equivalent


# Template Manifest Reference
Source: https://docs.heylua.ai/marketplace/template-manifest

Every attribute of an Agent Template manifest — authored, frozen, and served — with types, defaults, constraints, and the publish lints that guard them

This is the complete attribute reference for Agent Template manifests. For the concepts and lifecycle, read [Agent Templates](/marketplace/agent-templates); for the authoring journey, [Publishing Templates](/marketplace/publishing-templates); for the installer's experience, [Deploying Templates](/marketplace/deploying-templates).

## Where the manifest lives

A template's manifest exists in three forms. Knowing which form an attribute belongs to tells you where you set it, where it's stored, and where an installer reads it:

1. **The authored sections** — what you write. The `template:` section of your project's `lua.skill.yaml` carries the six authored sections (`connections`, `personaTemplate`, `triggerPresets`, `paramsMeta`, `onInstall`, `onUninstall`). The publish request can additionally carry sections that have no yaml home yet: the env contract (declared with `--env-contract`), connection-event triggers (`declaredTriggers`), `outcomes`, `channels`, `features`, and marketplace-skill composition refs. The publish request also carries three version-level fields: `sourceAgentVersion` (which promoted agent version to freeze; defaults to the active one), `changelog`, and `referenceEvalRunId` (the eval run satisfying the publish gate, when an eval set exists).
2. **The frozen published version** — what publish produces. An immutable, integer-numbered version that combines your promoted agent's primitives (skills, webhooks, jobs, processors, triggers, model — frozen **by value**) with your authored sections (validated, normalized, and stored alongside), plus derived integrity digests: `contentHash`, and the `codeHash` / `consentSurfaceHash` pair that powers update diffing and re-consent (creator-side version reads only — the two are never in the public manifest).
3. **The served manifest** — what installers read. `GET /marketplace/templates/:id/versions/:v/manifest` serves a **safe projection** of the frozen version: display metadata and requirements only, never source code, trigger instructions, or values. Fields are lifted by an explicit allow-list — anything not deliberately made public never serves. The serving layer also *enriches* it at read time: platform display names and auth modes from the live integration catalog, scope display copy, next run times, the per-caller `reconciliation` block, and the org `policy` block.

| Attribute group                                                                    | Authored by you                   | Frozen at publish                                | In the served manifest                                                             |
| ---------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Metadata (`name`, `displayName`, …)                                                | at `create` / `patch`             | header, not per-version                          | yes                                                                                |
| `agent.model`, `agent.modelSettings`                                               | no — frozen from the source agent | yes                                              | `model` only                                                                       |
| `personaTemplate`                                                                  | yes (yaml)                        | yes (normalized)                                 | yes — the template text is part of the consent surface                             |
| `skills[]` (and webhooks, jobs, processors, triggers)                              | no — frozen from the source agent | yes, by value                                    | display metadata only (skills; schedule/webhook triggers)                          |
| `connections[]`                                                                    | yes (yaml)                        | yes                                              | yes, platform entries enriched                                                     |
| `triggerPresets`                                                                   | yes (yaml)                        | yes (normalized over the full trigger key-space) | merged into `triggers[]`                                                           |
| `declaredTriggers[]`                                                               | yes (publish request)             | yes                                              | display fields only — `event` and `instruction` never serve                        |
| `envContract` + `paramsMeta`                                                       | yes (`--env-contract` + yaml)     | yes                                              | merged into `params[]`                                                             |
| `onInstall` / `onUninstall`                                                        | yes (yaml)                        | yes (normalized)                                 | yes, verbatim — the hooks are part of the consent surface                          |
| `channels[]`, `features[]`                                                         | yes (publish request)             | yes                                              | yes                                                                                |
| `outcomes`                                                                         | yes (publish request)             | yes                                              | creator/version reads and outcome summaries (not the deploy-screen manifest in V1) |
| `contentHash`, `installable`, `deprecated`, `reconciliation`, `policy`, `nextRuns` | never                             | derived                                          | yes — served-only, see [below](#served-manifest-only-fields)                       |

**Inheritance vs. clearing.** On the publish API, an *omitted* authored section inherits the previous version's (re-validated against the new content); an explicit empty value (`[]`, `{}`, `{ units: [] }` for `outcomes`, or `null` for `personaTemplate`) **clears** it. The CLI is stricter: when a `template:` section exists in `lua.skill.yaml`, all six yaml sections are always sent — an absent or empty subsection is an explicit clear, never "keep the previous version's". Omitting `--env-contract` inherits the previous contract. `onInstall` and `onUninstall` follow the same rule: on the publish API an omitted section inherits and an explicit `null` clears; from the CLI, deleting the section from your yaml clears it.

**Keys are identity.** Every keyed entry — a skill key, connection key, trigger key, param name, persona var name, outcome unit key — is its stable identity across versions. Renaming a key means *remove + add*: installers lose their binding, toggle, or setting for the old key. Keep keys stable.

***

## metadata

Template-level, not per-version: set at `lua marketplace template create`, editable later (except `name`).

| Field                                 | Type                  | Required | Default   | Constraints                                   | Description                                                                                      |
| ------------------------------------- | --------------------- | -------- | --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `name`                                | string                | yes      | —         | unique per creator organization               | Machine name of the template, e.g. `sales-followup`.                                             |
| `displayName`                         | string                | yes      | —         | —                                             | Catalog and deploy-screen title.                                                                 |
| `description`                         | string                | no       | `''`      | —                                             | Catalog card copy.                                                                               |
| `visibility`                          | `public` \| `private` | no       | `private` | flipping to `public` enqueues platform review | Private templates are org-only; public templates list in the catalog once a version is approved. |
| `id`                                  | string (UUID)         | derived  | —         | server-assigned                               | Opaque template id, no prefix.                                                                   |
| `listed`                              | boolean               | derived  | `true`    | —                                             | `false` after unlisting (soft retire).                                                           |
| `latestVersion`                       | integer               | derived  | —         | monotonic                                     | Highest published version number.                                                                |
| `latestApprovedVersion`               | integer               | derived  | —         | absent = no approved version                  | Highest *approved* version — what public installers resolve "latest" to.                         |
| `installCount` / `activeInstallCount` | integer               | derived  | `0`       | —                                             | Lifetime installs / currently-installed count.                                                   |

<Note>
  Versions are **integers** (v1, v2, v3 — not semver), monotonic per template. A rejected publish burns no version number. Catalog categories and icons are not part of the V1 manifest.
</Note>

## agent

| Field             | Type   | Required | Default | Constraints                                                               | Description                                                                                                              |
| ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `model`           | string | frozen   | —       | validated against the installer org's model catalog at install pre-flight | The model frozen from the source agent, e.g. `anthropic/claude-sonnet-4`. The only `agent` field in the served manifest. |
| `modelSettings`   | object | frozen   | —       | —                                                                         | The source agent's model settings, frozen by value. Applied at install; not served in the public manifest.               |
| `personaTemplate` | object | no       | absent  | see below                                                                 | The persona section — authored, not frozen from the source agent.                                                        |

### agent.personaTemplate

The system prompt as a template with `{{VAR}}` slots, each declared, typed, and explained. Authored in the yaml `template:` section.

| Field      | Type                                 | Required | Default | Constraints                                                      | Description                                                                                                                                          |
| ---------- | ------------------------------------ | -------- | ------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template` | string \| `{ base?, voice?, text? }` | yes      | —       | must keep ≥ 40 literal (non-slot) characters across all branches | The prompt text. The object form matches the persona's channel-aware branches.                                                                       |
| `vars`     | array                                | yes      | —       | exact bijection with `{{TOKEN}}`s (see below)                    | One declaration per `{{slot}}`.                                                                                                                      |
| `editable` | boolean                              | yes      | `false` | enforced server-side at install                                  | When `true`, the installer may edit the resolved prompt at deploy; the edited text wins over substitution and is stored verbatim, never re-expanded. |

Each entry of `vars[]`:

| Field         | Type                                                   | Required          | Default | Constraints                                                                                                              | Description                                         |
| ------------- | ------------------------------------------------------ | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `name`        | string                                                 | yes               | —       | `[A-Za-z_][A-Za-z0-9_]*`; `persona` is reserved (case-insensitive); must not collide with any declared param name        | The `{{TOKEN}}` this declares.                      |
| `displayName` | string                                                 | yes               | —       | non-empty                                                                                                                | Form label — the installer never sees a bare token. |
| `description` | string                                                 | yes               | —       | non-empty                                                                                                                | Help copy under the field.                          |
| `type`        | `string` \| `number` \| `boolean` \| `enum` \| `model` | yes               | —       | `model` holds a provider-prefixed model code; `enum` and `maxLength` are illegal on it, and a `default` must be a string | Drives the input control and value validation.      |
| `required`    | boolean                                                | no                | `false` | a non-required var **must** carry a `default`                                                                            | Whether the installer must answer.                  |
| `default`     | string \| number \| boolean                            | no                | —       | must satisfy its own `type`; for `enum`, must be a member                                                                | Pre-filled answer.                                  |
| `enum`        | string\[]                                              | when `type: enum` | —       | non-empty, unique, strings; illegal on other types                                                                       | The choices.                                        |
| `placeholder` | string                                                 | no                | —       | —                                                                                                                        | Input placeholder, e.g. `Acme Inc.`.                |
| `maxLength`   | integer                                                | no                | `256`   | strings only; 1–2000                                                                                                     | Length cap on the supplied value (injection floor). |

**Substitution rules** (what happens to `{{vars}}` at deploy):

* **Single-pass.** The template is scanned once; each declared token is replaced with the installer's answer. Substituted values are never re-scanned — a value containing `{{OTHER_VAR}}` lands as inert text, not a new slot.
* **Brace-escaped.** Inside supplied values, `{{` becomes `{ {` and `}}` becomes `} }` — a value can never mint a slot or reach runtime substitution targets.
* **The bijection lint.** Every `{{TOKEN}}` in any branch (`base`/`voice`/`text`) must have a `vars[]` entry, and every declared var must appear in at least one branch. Publish rejects both directions.
* **Values are never stored in the manifest.** Answers land on the installed agent's persona; the manifest carries only the declarations.

```yaml theme={null}
template:
  personaTemplate:
    template: |
      You are the sales assistant for {{COMPANY_NAME}}. Chase deals in the
      {{PIPELINE}} pipeline. Never discount past {{MAX_DISCOUNT}}%.
    editable: true
    vars:
      - name: COMPANY_NAME
        displayName: Your company
        description: Used in the agent's replies and signatures.
        type: string
        required: true
        placeholder: Acme Inc.
      - name: PIPELINE
        displayName: Pipeline to work
        description: Which sales pipeline the agent chases.
        type: string
        default: Enterprise
      - name: MAX_DISCOUNT
        displayName: Max discount %
        description: The agent never offers more than this.
        type: number
        default: 15
```

## skills\[]

Skills (like webhooks, jobs, processors, and code triggers) are **frozen from your promoted agent version, by value** — you never author these entries. The served manifest lifts display metadata only; source code, tool schemas, and gating conditions never serve publicly. Webhooks and processors serve nothing in the V1 manifest at all — they're internal wiring, not an installer decision surface.

Served shape per entry:

| Field                | Type                     | Required                   | Default            | Constraints                                                       | Description                                                                               |
| -------------------- | ------------------------ | -------------------------- | ------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `key`                | string                   | always                     | —                  | stable identity; rename = remove + add                            | The skill's name on the source agent.                                                     |
| `displayName`        | string                   | always                     | derived from `key` | —                                                                 | The skill's title; when none was set, the key is humanized (`crm-sync` → `Crm sync`).     |
| `description`        | string                   | always                     | `''`               | —                                                                 | "What this agent can do" copy on the deploy screen.                                       |
| `version`            | string                   | always                     | —                  | —                                                                 | The frozen skill version.                                                                 |
| `source`             | `agent` \| `marketplace` | when present               | `agent`            | —                                                                 | Provenance: frozen from the source agent, or composed from a published marketplace skill. |
| `marketplaceSkillId` | string                   | `source: marketplace` only | —                  | —                                                                 | The referenced marketplace skill's id.                                                    |
| `versionId`          | string                   | `source: marketplace` only | —                  | an immutable version-document id — never a semver, never "latest" | The exact pinned marketplace skill version.                                               |

Marketplace composition is authored on the publish request as `marketplaceSkills: [{ marketplaceSkillId, versionId }]` (max 50) — content is still frozen by value into the version; the refs record where it came from and pin the exact version.

## connections\[]

Declared runtime connection requirements — "this agent needs a CRM" — authored in the yaml `template:` section. Each entry is a **capability** satisfiable by any platform in its allow-list.

| Field         | Type            | Required | Default | Constraints                                                            | Description                                                                                                                                                                      |
| ------------- | --------------- | -------- | ------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | string          | yes      | —       | non-empty, unique; stable identity                                     | The capability key. Referenced by `boundSkills`-owning outcomes evidence (`match.connectionKey`), connection-event triggers (`connectionKey`), and the install's binding ledger. |
| `capability`  | string          | yes      | —       | must equal the **primary** catalog category of every declared platform | Discovery label ("crm", "calendar", "chat"). The `platforms[]` allow-list, not this label, is what decides satisfiability.                                                       |
| `required`    | boolean         | yes      | —       | —                                                                      | `true`: install blocks until satisfied. `false`: offered at deploy, never blocking — primitives depending on a declined optional connection are materialized inert, fail-closed. |
| `ownerType`   | `user` \| `org` | no       | either  | —                                                                      | Constrains which grant identity may satisfy the capability — declare `org` when the connection must be the organization's (finance systems), never someone's personal key.       |
| `displayName` | string          | yes      | —       | non-empty                                                              | The connect chip label ("Your CRM").                                                                                                                                             |
| `description` | string          | yes      | —       | non-empty                                                              | The *why*, shown under the chip ("Used to read deals and write follow-up notes.").                                                                                               |
| `platforms`   | array           | yes      | —       | at least one; unique `type`s                                           | The ANY-OF allow-list — any one platform satisfies the capability.                                                                                                               |
| `boundSkills` | string\[]       | no       | —       | every entry must be a skill key in this version                        | Which of the template's skills depend on this connection. Drives the portability lint and outcome attribution.                                                                   |

Each entry of `platforms[]`:

| Field         | Type      | Required            | Default | Constraints                                                    | Description                                                                                                                                                                                                    |
| ------------- | --------- | ------------------- | ------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | string    | yes                 | —       | must be a live integration in the catalog                      | Integration type, e.g. `salesforce`, `hubspot`, `slack`.                                                                                                                                                       |
| `oauthScopes` | string\[] | for OAuth platforms | —       | scope names must exist in the platform's scope-copy vocabulary | The scopes this template needs on that platform — what the installer consents to. **Currently disabled at publish** while granted-scope capture rolls out; a declaration is rejected with a message saying so. |

**In the served manifest**, each platform entry is enriched from the live integration catalog at read time — the frozen declaration stores only `{type, oauthScopes}`:

```json theme={null}
{ "type": "salesforce", "name": "Salesforce", "authSupport": "oauth",
  "oauthScopes": [
    { "scope": "crm_contact_read", "displayName": "Read contacts" },
    { "scope": "crm_deal_write", "displayName": "Create & edit deals" } ] }
```

Raw scope tokens never reach a screen — `oauthScopes` (and `missingScopes` in reconciliation) always serve as `{scope, displayName, description?}` objects with platform-owned display copy.

**Reconciliation semantics, per attribute.** At deploy, the platform reconciles each capability against the connections the installer already holds (personal + the target org's shared ones): a connection whose `type` is in `platforms[]` and whose granted scopes cover the declared `oauthScopes` → `satisfied`, bound without asking; several matches → `multiple-matches`, the installer picks (never auto-picked); a match lacking scopes → `insufficient-scope` with the exact missing scopes; a pre-scope-capture row whose live scope query failed → `verify-access` (informational, resolved at pre-flight); no match → `unmet-required` (blocks) or `unmet-optional` (offered). `ownerType` filters which grants qualify at all. Install proceeds only when every `required` capability is satisfied — re-verified server-side, never trusted from the client.

**The portability lint.** A capability may list *multiple* platforms only when its `boundSkills` reach the connection through the capability itself. A bound skill that calls platform-native tools (e.g. `salesforce_*`-prefixed calls, or a platform-typed integration helper) pins the entry: publish rejects with a migration hint — narrow `platforms[]` to that platform, or migrate the skill to capability-level access. Single-platform entries lint nothing; narrowing is the author's escape hatch.

```yaml theme={null}
template:
  connections:
    - key: crm
      capability: crm
      required: true
      displayName: Your CRM
      description: Used to read deals and write follow-up notes.
      platforms:
        - type: salesforce
        - type: hubspot
      boundSkills: [crm-sync]
    - key: notify
      capability: chat
      required: false
      displayName: Notifications channel
      description: "Optional: where follow-up alerts get posted."
      platforms:
        - type: slack
```

## triggerPresets and the served triggers\[]

Schedules and code triggers are frozen from the source agent; **triggerPresets** is your authored layer over them — recommended defaults, installer-facing copy, and which schedule fields the installer may edit. It's a map keyed by trigger key, covering the union of the version's job, webhook, code-trigger, and connection-event keys. Keys you don't author get defaults at publish: `{ enabled: true }` for job/webhook/code-trigger keys, always-off for connection-event keys.

| Field            | Type    | Required | Default                                                           | Constraints                                                                    | Description                                                                                                                                                             |
| ---------------- | ------- | -------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`        | boolean | yes      | `true` (schedule/webhook) / `false` (connection-event, immutable) | connection-event keys may never author `true`                                  | A **recommended default**, pre-checked in the configure step — confirmed at deploy, never silently applied. Nothing arms without the installer's explicit confirmation. |
| `displayName`    | string  | no       | the primitive's name, else humanized key                          | —                                                                              | Deploy-screen title for the automation.                                                                                                                                 |
| `description`    | string  | no       | the primitive's description                                       | —                                                                              | What enabling *does* ("Looks for deals needing a follow-up and drafts one.").                                                                                           |
| `editableParams` | array   | no       | —                                                                 | not allowed on connection-event keys; timezone auto-declared on every cron job | Which schedule fields the installer may adjust.                                                                                                                         |

Each entry of `editableParams[]`:

| Field   | Type                                  | Required | Default | Constraints                                                                                                            | Description                                                                                              |
| ------- | ------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `path`  | `preset.seconds` \| `preset.timezone` | yes      | —       | closed allow-list; `preset.seconds` only on interval presets, `preset.timezone` only on cron; one declaration per path | The schedule field this exposes. Cron *expressions* are never editable — no client-side cron math, ever. |
| `label` | string                                | yes      | —       | non-empty                                                                                                              | Form label ("Check every") — a raw path is never rendered.                                               |
| `help`  | string                                | no       | —       | —                                                                                                                      | Copy under the field.                                                                                    |
| `unit`  | string                                | no       | —       | display only                                                                                                           | e.g. `minutes`.                                                                                          |
| `min`   | number                                | no       | `60`    | ≥ 60 and a multiple of 60 (`preset.seconds`)                                                                           | Lower bound.                                                                                             |
| `max`   | number                                | no       | —       | ≥ `min`                                                                                                                | Upper bound.                                                                                             |
| `step`  | number                                | no       | `60`    | multiple of 60 (`preset.seconds`)                                                                                      | Input step.                                                                                              |

**The whole-minutes constraint.** Interval schedules run on whole minutes only: `seconds` must be ≥ 60 and a multiple of 60, both in the frozen schedule and in any authored envelope — a fractional-minute interval would silently never fire, so publish rejects it. Frozen `once` schedules are rejected too (a frozen instant is stale by construction), and a frozen schedule must satisfy its *own* declared envelope.

**The timezone override.** Cron presets carry an IANA timezone — but a frozen cron carries the *creator's* timezone, so every cron job automatically gets a `preset.timezone` editable param (label "Timezone", defaulting to the installer's profile timezone) even if you don't declare one. A Stockholm-authored 08:00 job must not run at Stockholm time for a Nairobi installer.

```yaml theme={null}
template:
  triggerPresets:
    poll-crm:
      enabled: true
      displayName: Check for new deals
      description: Looks for deals needing a follow-up and drafts one.
      editableParams:
        - path: preset.seconds
          label: Check every
          help: How often the agent looks for new deals.
          unit: minutes
          min: 60
          step: 60
```

**The served `triggers[]`** merges the frozen schedules, your presets, and the declared connection-event triggers into one list:

| Field                         | Type                                                           | Present               | Description                                                                                                                                                                  |
| ----------------------------- | -------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`                         | string                                                         | always                | The trigger key.                                                                                                                                                             |
| `type`                        | `schedule` \| `webhook` \| `connection-event`                  | always                | Scheduled job, webhook-source code trigger, or connection event.                                                                                                             |
| `displayName` / `description` | string                                                         | always / when set     | Authored preset copy, falling back to the primitive's name/description, then the humanized key.                                                                              |
| `enabled`                     | boolean                                                        | always                | The recommended default. Connection-event entries always serve `false`.                                                                                                      |
| `preset`                      | `{ type: cron \| interval, expression?, seconds?, timezone? }` | schedule only         | The frozen schedule.                                                                                                                                                         |
| `connectionKey`               | string                                                         | connection-event only | The capability the event arrives on.                                                                                                                                         |
| `editableParams`              | array                                                          | when declared         | Verbatim from the authored preset (plus the auto-declared timezone param).                                                                                                   |
| `nextRuns`                    | `{ at, timezone }[]`                                           | schedule only         | The next fire times — **computed at read time by the serving layer**, never authored, so the UI can say "runs 2:00 AM New York — 8:00 AM your time" without doing cron math. |

At install, the deploy request answers this section with `triggerOverrides: { <key>: { enabled?, params? } }` — e.g. `params: { "preset.seconds": 600, "preset.timezone": "Africa/Nairobi" }`.

## declaredTriggers\[]

Connection-event triggers — "when a deal is won" — are **authored declarations** (publish request only; no yaml home in V1), since no frozen primitive can carry them. Each materializes at install as a managed trigger plus a webhook subscription on the bound connection.

| Field              | Type                                | Required | Default | Constraints                                                                                                                                        | Description                                                                                         |
| ------------------ | ----------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `key`              | string                              | yes      | —       | shares the one trigger key-space (clash-checked)                                                                                                   | Stable identity.                                                                                    |
| `connectionKey`    | string                              | yes      | —       | must be a declared `connections[]` key                                                                                                             | Which capability's bound connection emits the event.                                                |
| `displayName`      | string                              | yes      | —       | non-empty                                                                                                                                          | Deploy-screen title ("When a deal is won").                                                         |
| `description`      | string                              | yes      | —       | non-empty                                                                                                                                          | What enabling does.                                                                                 |
| `event.objectType` | string                              | yes      | —       | provider object vocabulary                                                                                                                         | e.g. `deal`.                                                                                        |
| `event.event`      | `created` \| `updated` \| `deleted` | yes      | —       | —                                                                                                                                                  | The change type.                                                                                    |
| `event.filters`    | object (string → string)            | no       | —       | —                                                                                                                                                  | Field filters, e.g. `{ "stage": "won" }`.                                                           |
| `instruction`      | string                              | yes      | —       | non-empty, ≤ 2000 chars, must not interpolate event-payload fields (the fencing lint); part of the consent surface — changing it forces re-consent | The instruction prepended to the fired agent turn ("A deal was won — send a thank-you follow-up."). |

**The event-support join.** Each declared `{objectType, event}` must be deliverable on **every** platform in the referenced capability's `platforms[]` — checked at publish against the live webhook-event listing, with each `filters` key limited to that event's available filters on that platform. A listing fetch failure fails the publish loudly (`could not verify event support — try again`) — never publish-unverified.

Two fences apply everywhere:

* **Never armed by default.** A connection-event trigger always serves (and materializes) disabled; authoring `enabled: true` in its preset is rejected. The installer must switch it on explicitly.
* **`event` and `instruction` never serve publicly.** The served manifest lifts only `key`, `connectionKey`, `displayName`, `description` (as a `triggers[]` entry with `type: "connection-event"`). Event payloads are untrusted input at runtime and instruction text is consent-surface material — it's shown through consent flows, not the anonymous catalog.

## Lifecycle hooks: onInstall and onUninstall

The two optional **lifecycle hooks** are symmetric: `onInstall` runs right after a successful deploy or install-onto-agent; `onUninstall` runs at the start of an uninstall, **before** any teardown — while the template's skills, connection bindings, and injected trigger URLs all still work. Both take the same shape, with **at least one** of the two fields:

| Field         | Type   | Required                | Default | Constraints                                                                                                                   | Description                                                                                           |
| ------------- | ------ | ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `tool`        | string | at least one of the two | —       | the bare name of a tool that exists in **this version's frozen skills** — never live agent state                              | A tool executed **directly** (input `{}`), without an agent turn: the deterministic half of the hook. |
| `instruction` | string | at least one of the two | —       | 1–2000 chars after trimming; plain text — `{{var}}` tokens are rejected (nothing is substituted); part of the consent surface | One background agent turn: the conversational half.                                                   |

```yaml theme={null}
template:
  onInstall:
    tool: setup_github_watch
    instruction: 'Report what setup_github_watch just wired, briefly.'
  onUninstall:
    tool: unwire_github_watch
    instruction: 'Tell the user which webhooks were removed and say goodbye.'
```

**Execution order is tool, then instruction.** The recommended split: **the tool does the work, the instruction is the conversation.** A tool run is deterministic — no model in the loop — executed as the acting user (the installer for `onInstall`, the removing user for `onUninstall`) with the same runtime context as a chat-turn tool call and a 180-second budget, and its outcome (success or failure, with a result summary) is recorded on the install. The instruction fires as one background agent turn, prefixed so the agent knows why it woke:

```
[Install: <template displayName>] <instruction>
[Uninstall: <template displayName>] <instruction>
```

### onInstall semantics

* **Consumer-visible.** Both fields are served on the manifest, so the deploy flow's consent screen can show *"After install, the agent will: …"*. Write the instruction as copy an installer will read.
* **At most once per distinct instruction.** Each install runs a given instruction at most once: re-installing or updating to a version with the *same* instruction never fires a second turn; an update that *changes* the instruction fires again once.
* **Fail-soft.** The install/deploy never waits on the turn and never fails because of the hook; failures are recorded on the install for inspection.
* **Runs as the installer.** User-scoped work inside the hook (an [Inbox push](/api/inbox), a memory deposit) reaches the person who installed.

### onUninstall semantics

* **Runs before teardown.** The hook executes while everything the cleanup needs still exists — the version's skills, the bound connections, the injected `LUA_TRIGGER_URL__*` variables. Use it to undo external state the install created: deregister provider webhooks, close out third-party resources, say goodbye.
* **Cleanup is best-effort and never blocks removal.** The tool run is awaited (within its budget); the instruction turn is given a bounded grace and then teardown proceeds regardless — a slow turn can lose its access mid-flight. If cleanup **must** happen, put it in `tool`, not `instruction`.
* **The outcome is reported.** The uninstall result carries the hook's outcome (`{ ran, ok?, error? }`), and it is recorded on the install before teardown proceeds — a failed cleanup is visible, never silent, but it never fails the uninstall.
* **Runs as the removing user.** The tool executes with the identity of whoever is uninstalling (so their connections resolve); with no real acting user (internal removal paths), the tool is skipped and the turn falls back to a system identity.
* **Consumer-visible.** Served on the manifest so the uninstall confirmation can show *"Before removal, the agent will: …"*.

The full authoring pattern — a setup tool wired to `onInstall` and its inverse wired to `onUninstall` — is walked through in [Publishing Templates](/marketplace/publishing-templates#self-wiring-webhooks).

## envContract and params

The **declare-vs-supply** rule: the manifest declares *which* environment variables the template's code expects — names and metadata, **never values**. Values are supplied per install and stored on the agent.

`envContract` — keyed by variable name, declared with `--env-contract "KEY=description"` (required) or `"KEY?=description"` (optional):

| Field         | Type    | Required | Default | Constraints                                                 | Description                         |
| ------------- | ------- | -------- | ------- | ----------------------------------------------------------- | ----------------------------------- |
| `description` | string  | yes      | —       | —                                                           | What the variable is for.           |
| `required`    | boolean | yes      | —       | missing required values block the install with a named list | Whether the install must supply it. |
| `example`     | string  | no       | —       | never a real value                                          | Illustrative example.               |

`paramsMeta` — the typed display layer over the contract, authored in yaml, keyed by the same names. Keys must be a subset of `envContract`'s — and supplying a `paramsMeta` section at all makes coverage total: every contract key must then carry an entry with a `displayName` (rejection: `<KEY>: user-facing params require displayName`). Key-derived display names appear only on versions published without any `paramsMeta` section (API/legacy publishers), so a served manifest never mixes authored and derived entries:

| Field                                            | Type                                                   | Required | Default                                  | Constraints                                                                                                                                                                         | Description                                                                   |
| ------------------------------------------------ | ------------------------------------------------------ | -------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `displayName`                                    | string                                                 | yes      | —                                        | non-empty                                                                                                                                                                           | Form label.                                                                   |
| `description`                                    | string                                                 | no       | falls back to the contract's description | —                                                                                                                                                                                   | Help copy.                                                                    |
| `type`                                           | `string` \| `number` \| `boolean` \| `enum` \| `model` | yes      | —                                        | env values are stored as strings; the type drives validation and coercion. `model` holds a provider-prefixed model code (`anthropic/claude-sonnet-5`) and renders as a model picker | Input type.                                                                   |
| `default` / `enum` / `placeholder` / `maxLength` | —                                                      | no       | as for persona vars                      | same typed-declaration rules as persona vars; on `model`, `enum` and `maxLength` are rejected and `default` must be a string                                                        | One shared vocabulary — persona vars and params render as one configure form. |

A `model` value is **not** checked against the approved-model catalog at install. An unrecognised code falls back to the platform default at request time rather than failing the install, so an org exclusion added after install can never break a template update. The 256-character cap and the control-character check still apply.

**The served `params[]`** merges both, one entry per contract key:

| Field                                                    | Type    | Description                                                                                       |
| -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `name`                                                   | string  | The env variable name.                                                                            |
| `displayName`                                            | string  | From `paramsMeta`; without it, derived from the key (`CRM_DEFAULT_OWNER` → `Crm default owner`).  |
| `derivedDisplay`                                         | boolean | Present (`true`) only when the display name was key-derived — omitted when authored metadata won. |
| `description`                                            | string  | `paramsMeta` description, falling back to the contract's.                                         |
| `required`                                               | boolean | Always from the contract.                                                                         |
| `type`                                                   | string  | From `paramsMeta`; `string` for derived entries.                                                  |
| `example`, `default`, `enum`, `placeholder`, `maxLength` | —       | Passed through when present.                                                                      |

```yaml theme={null}
template:
  paramsMeta:
    CRM_DEFAULT_OWNER:
      displayName: Default deal owner
      description: Fallback owner when a deal has none.
      type: string
    TONE:
      displayName: Tone of voice
      type: enum
      enum: [formal, casual]
      default: casual
    CLASSIFIER_MODEL:
      displayName: Classifier model
      description: Which model reads and sorts incoming items.
      type: model
      default: anthropic/claude-sonnet-5
```

### The reserved `LUA_TRIGGER_URL__` prefix

Environment keys starting with `LUA_TRIGGER_URL__` are **platform-owned** and cannot appear in an env contract — publish rejects them with `ENV_CONTRACT_RESERVED_PREFIX`. At install, the platform writes one `LUA_TRIGGER_URL__<TRIGGER_KEY>` variable per webhook trigger in the template (the trigger key upper-snaked), holding that install's own trigger URL. The keys are tracked as install-introduced — refreshed if the trigger's token is rotated, overwriting any hand-set value of the same name, and removed at uninstall along with the rest of what the install introduced. See [LuaTrigger — Agents know their own URL](/api/luatrigger#agents-know-their-own-url).

## channels\[] and features\[]

**Declare-only runtime dependencies** — things a deploy can never create but the agent needs to fully go live. Declaring them doesn't bind anything; it drives the honest **post-deploy setup checklist** ("connect WhatsApp to go live") and installer health, instead of a false "live". Authored on the publish request.

`channels[]` — messaging/voice channels the template sends or receives on:

| Field         | Type    | Required | Default | Constraints                                                                                                                                                                                                             | Description                                                                                           |
| ------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `channel`     | string  | yes      | —       | one of the known channel vocabulary: `whatsapp`, `instagram`, `facebook`, `webchat`, `slack`, `email`, `front`, `messagebird`, `phone`, `teams`, `rcs`, `imessage`, `telegram`, `google`, `meeting`; unique per version | Channel type the agent depends on.                                                                    |
| `required`    | boolean | yes      | —       | —                                                                                                                                                                                                                       | `true`: the agent can't do its job without it — checklist blocks "fully live". `false`: nice-to-have. |
| `displayName` | string  | no       | —       | ≤ 120 chars, non-empty when present                                                                                                                                                                                     | Checklist row title.                                                                                  |
| `description` | string  | no       | —       | ≤ 2000 chars                                                                                                                                                                                                            | Why the agent needs it.                                                                               |

`features[]` — platform feature flags the agent depends on (e.g. the RAG feature for a docs-answering template):

| Field                         | Type    | Required | Default | Constraints                                                    | Description                        |
| ----------------------------- | ------- | -------- | ------- | -------------------------------------------------------------- | ---------------------------------- |
| `feature`                     | string  | yes      | —       | must exist in the platform feature catalog; unique per version | Feature name.                      |
| `required`                    | boolean | no       | `false` | —                                                              | Absent = informational dependency. |
| `displayName` / `description` | string  | no       | —       | same limits as channels                                        | Checklist copy.                    |

<Warning>
  A WhatsApp declaration deserves a scope note in your description: outbound message-template assets are WABA-scoped and need Meta approval — expect days, not minutes, for outreach beyond the 24-hour window.
</Warning>

## outcomes

The template's countable **units of work** — "follow-ups sent", "meetings booked" — declared at publish (publish request only in V1). Counting is **platform-attested**: a unit is recorded only when the platform itself observes the declared evidence — a matching tool call executed on the install's *bound* connection for the named capability, or a platform-recorded event (message delivery, sandbox commerce writes, completed voice calls). Creator code can cause real side effects but cannot mint a count, evidence on an unbound or declined capability is inert rather than counted, and each recorded unit settles when its window passes without reversal — with verification (sampled LLM-judge review before a unit counts as `verified`) owned entirely by the platform: `verification`, `samplingRate`, and `judge` are rejected as creator fields.

`outcomes.units[]` (max 25 per version):

| Field         | Type                                            | Required                                          | Default | Constraints                              | Description                                                                                                                                                           |
| ------------- | ----------------------------------------------- | ------------------------------------------------- | ------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | string                                          | yes                                               | —       | unique, non-empty; stable identity       | The unit's id, e.g. `followup_sent`.                                                                                                                                  |
| `title`       | string                                          | yes                                               | —       | non-empty                                | Display title ("Follow-ups sent").                                                                                                                                    |
| `description` | string                                          | no                                                | —       | —                                        | What counts as one.                                                                                                                                                   |
| `unitLabel`   | string                                          | no                                                | —       | —                                        | Display noun for one counted unit, e.g. `booking`.                                                                                                                    |
| `match`       | object                                          | at least one of `match` / `events`                | —       | see below                                | Tool-call evidence on a bound connection.                                                                                                                             |
| `events`      | array                                           | at least one of `match` / `events`                | —       | see below                                | Platform-recorded event evidence.                                                                                                                                     |
| `dedupe`      | `thread` \| `occurrence` \| `event` \| `entity` | yes                                               | —       | —                                        | How repeat evidence collapses into counts: one per conversation, per job run, per external event, or per external entity (a batch job posting 20 invoices counts 20). |
| `window`      | string                                          | no                                                | `24h`   | `<n>h` or `<n>d`, between `1h` and `30d` | Settlement window — a recorded unit settles when it passes without reversal.                                                                                          |
| `entityPath`  | string                                          | required for `dedupe: entity` with a tool matcher | —       | dot-path starting `input.` or `result.`  | Where in the tool dispatch the external entity id lives. Optional on other modes (enables entity-precise reversal).                                                   |
| `reversals`   | array                                           | no                                                | —       | see below                                | Evidence that *un-counts* a prior unit.                                                                                                                               |

`match` — tool-call evidence:

| Field           | Type      | Required | Constraints                                       | Description                                                                                                                           |
| --------------- | --------- | -------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `tools`         | string\[] | yes      | at least one; ≤ 128 chars each; `*` wildcard only | **Bare** tool-name globs, matched with the runtime server-name prefix stripped (`crm_update_deal`, `calendar_event_*`).               |
| `connectionKey` | string    | yes      | must be a declared `connections[]` key            | The capability the call must have executed on — the unit records only when the dispatch ran on the install's bound connection for it. |

`events[]` — platform-recorded event evidence (a **closed** vocabulary; anything else is rejected at publish):

| Field     | Type   | Required                    | Constraints                                                                       | Description                    |
| --------- | ------ | --------------------------- | --------------------------------------------------------------------------------- | ------------------------------ |
| `event`   | string | yes                         | one of `message.sent`, `order.created`, `basket.checked_out`, `call.completed`    | The recordable platform event. |
| `channel` | string | required for `message.sent` | delivery-emitting channels only (`whatsapp` today); illegal on non-channel events | The emitting channel.          |

`reversals[]` — each entry needs at least one evidence source:

| Field               | Type    | Required                             | Constraints                                | Description                                                                                             |
| ------------------- | ------- | ------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `match`             | object  | one of `match` / `onDeliveryFailure` | same shape and rules as the unit's `match` | A tool call that signals the outcome was undone (a deal reopened).                                      |
| `onDeliveryFailure` | boolean | one of `match` / `onDeliveryFailure` | —                                          | Reverse on delivery failure (bounce) of the unit's thread.                                              |
| `entityPath`        | string  | no                                   | `input.` / `result.` path                  | Which entity the reversal targets; absent → the unit's most recent recorded outcome on the same thread. |

<Note>
  Reversals are **platform-owned**, never installer-toggleable — declining a trigger must not silently disable clawback while units keep settling. And the lifecycle counters (`recorded` → `settled` → `verified` / `reversed`) are served as separate tiers, never summed: only `verified` may feed pricing or catalog badges.
</Note>

## Served-manifest-only fields

These exist only in the served manifest — derived or attached at read time, never authored:

| Field                       | Type             | Description                                                                                                                                                                                                     |
| --------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` / `latestVersion` | integer          | The version served / the newest published version (resolved from version records, never a counter).                                                                                                             |
| `contentHash`               | string           | sha256 over the canonical frozen content. Echo it back on install as the **hash-seal**: pre-flight re-verifies the content still matches what you consented to, and answers `409 CONTENT_HASH_MISMATCH` if not. |
| `installable`               | boolean          | The derived install verdict: the version is not deprecated, and — for public templates — approved.                                                                                                              |
| `latestApprovedVersion`     | integer          | Highest approved version; absent when none is.                                                                                                                                                                  |
| `deprecated`                | boolean          | Present (`true`) when this version is deprecated — blocks *new* installs of it only.                                                                                                                            |
| `reconciliation`            | object \| `null` | The per-caller connection reconciliation, pre-computed at read time (below). `null` for anonymous callers.                                                                                                      |
| `policy`                    | object           | Present only when the resolved org's template policy blocks this template: `{ blocked: true, reason, message }` — `reconciliation` stays `null` for a blocked template.                                         |

### The reconciliation block

```json theme={null}
"reconciliation": {
  "summary": { "satisfied": 3, "total": 4 },
  "capabilities": {
    "crm": { "status": "satisfied",
      "connection": { "id": "conn_x", "integrationType": "salesforce", "ownerType": "user" } },
    "calendar": { "status": "multiple-matches",
      "candidates": [
        { "id": "conn_a", "integrationType": "googlecalendar",
          "platformDisplayName": "Google Calendar", "ownerType": "user",
          "accountLabel": "stefan@heylua.ai", "default": true },
        { "id": "conn_b", "integrationType": "googlecalendar",
          "platformDisplayName": "Google Calendar", "ownerType": "org",
          "accountLabel": "Acme (org)", "default": false } ] },
    "email": { "status": "insufficient-scope",
      "connection": { "id": "conn_y", "integrationType": "gmail", "ownerType": "user" },
      "missingScopes": [ { "scope": "email_message_write", "displayName": "Send email" } ] },
    "notify": { "status": "unmet-optional", "connectFrom": ["slack"] }
  }
}
```

Per capability key:

| Field           | Type                                  | Description                                                                                                                                                                                                              |
| --------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`        | enum                                  | `satisfied` · `multiple-matches` · `insufficient-scope` · `verify-access` · `unmet-required` · `unmet-optional`.                                                                                                         |
| `connection`    | `{ id?, integrationType, ownerType }` | The matched connection. `id` is redacted on rows the caller may see but not use.                                                                                                                                         |
| `candidates`    | array                                 | On `multiple-matches`: full objects (`id`, `integrationType`, `platformDisplayName`, `ownerType`, `accountLabel?`, `default`) — the picker renders from these fields alone, defaulting per the deploy target's identity. |
| `missingScopes` | array                                 | On `insufficient-scope`: the missing scopes as enriched `{scope, displayName}` objects — never raw tokens.                                                                                                               |
| `connectFrom`   | string\[]                             | On unmet statuses: the platform types the installer may connect.                                                                                                                                                         |
| `reason`        | string                                | Machine-readable detail, e.g. `scope-query-failed` behind `verify-access`.                                                                                                                                               |

Every install-time rejection (a 409 on the deploy exchange) carries a **freshly recomputed** reconciliation block — the UI never needs a blind re-fetch.

***

## A complete example

The authored `template:` section of `lua.skill.yaml` for a Sales Follow-up agent — all four yaml sections:

```yaml theme={null}
template:
  personaTemplate:
    template: |
      You are the sales assistant for {{COMPANY_NAME}}. Chase deals in the
      {{PIPELINE}} pipeline. Never discount past {{MAX_DISCOUNT}}%.
    editable: true                      # installer may tweak the resolved prompt
    vars:
      - name: COMPANY_NAME
        displayName: Your company
        description: Used in the agent's replies and signatures.
        type: string
        required: true
        placeholder: Acme Inc.
      - name: PIPELINE
        displayName: Pipeline to work
        description: Which sales pipeline the agent chases.
        type: string
        default: Enterprise             # optional vars must carry a default
      - name: MAX_DISCOUNT
        displayName: Max discount %
        description: The agent never offers more than this.
        type: number
        default: 15

  connections:
    - key: crm                          # stable identity — rename = remove + add
      capability: crm                   # discovery label; platforms[] decides
      required: true                    # install blocks until satisfied
      displayName: Your CRM
      description: Used to read deals and write follow-up notes.
      platforms:                        # ANY ONE satisfies the capability
        - type: salesforce
        - type: hubspot
      boundSkills: [crm-sync]           # these skills must use capability-level
                                        # access, or publish narrows the list
    - key: notify
      capability: chat
      required: false                   # offered at deploy, never blocking
      displayName: Notifications channel
      description: "Optional: where follow-up alerts get posted."
      platforms:
        - type: slack

  triggerPresets:
    poll-crm:                           # a frozen interval job on the agent
      enabled: true                     # recommended default — confirmed at deploy
      displayName: Check for new deals
      description: Looks for deals needing a follow-up and drafts one.
      editableParams:
        - path: preset.seconds          # closed path list; cron expressions never
          label: Check every            # editable
          help: How often the agent looks for new deals.
          unit: minutes
          min: 60
          step: 60                      # whole minutes only

  paramsMeta:                           # display layer over the env contract
    CRM_DEFAULT_OWNER:                  # declared: --env-contract "CRM_DEFAULT_OWNER=…"
      displayName: Default deal owner
      description: Fallback owner when a deal has none.
      type: string
    TONE:
      displayName: Tone of voice
      type: enum
      enum: [formal, casual]
      default: casual
    CLASSIFIER_MODEL:                   # declared: --env-contract "CLASSIFIER_MODEL?=…"
      displayName: Classifier model
      description: Which model reads and sorts incoming items.
      type: model
      default: anthropic/claude-sonnet-5

  onInstall:                            # consumer-visible: "After install, the agent will: …"
    instruction: >-
      Introduce yourself, then check the CRM connection by listing the three
      most recent open deals and reporting what you found.

  onUninstall:                          # consumer-visible: "Before removal, the agent will: …"
    tool: remove_crm_followup_notes     # deterministic cleanup — a tool from this version's skills
    instruction: >-
      Tell the user the follow-up tracking notes were removed from the CRM
      and say goodbye.
```

The publish-request-only sections for the same template — connection-event triggers, runtime dependencies, and outcomes:

```json theme={null}
{
  "declaredTriggers": [
    { "key": "deal-won", "connectionKey": "crm",
      "displayName": "When a deal is won",
      "description": "Drafts a thank-you follow-up the moment a deal closes.",
      "event": { "objectType": "deal", "event": "updated",
                 "filters": { "stage": "won" } },
      "instruction": "A deal was won — send a thank-you follow-up." }
  ],
  "channels": [
    { "channel": "whatsapp", "required": false,
      "description": "Follow-ups can go out on WhatsApp once a number is connected." }
  ],
  "outcomes": {
    "units": [
      { "key": "followup_sent", "title": "Follow-ups sent",
        "description": "A drafted follow-up approved and delivered to the prospect.",
        "unitLabel": "follow-up",
        "match": { "tools": ["crm_update_deal"], "connectionKey": "crm" },
        "events": [ { "event": "message.sent", "channel": "whatsapp" } ],
        "dedupe": "thread", "window": "24h",
        "reversals": [ { "onDeliveryFailure": true } ] },
      { "key": "deal_advanced", "title": "Deals advanced",
        "description": "A deal moved forward a stage after the agent's follow-up.",
        "match": { "tools": ["crm_update_deal"], "connectionKey": "crm" },
        "dedupe": "entity", "entityPath": "result.dealId", "window": "7d" }
    ]
  }
}
```

And the served manifest an installer's deploy screen reads (excerpt):

```json theme={null}
{
  "id": "9f2c1a8e-…", "name": "sales-followup",
  "displayName": "Sales Follow-up Agent",
  "description": "Chases deals with drafted follow-ups.",
  "version": 3, "latestVersion": 3, "visibility": "public",
  "contentHash": "sha256:…",                       // echo on install: the hash-seal
  "agent": { "model": "anthropic/claude-sonnet-4" },

  "skills": [
    { "key": "crm-sync", "displayName": "CRM sync",
      "description": "Reads deals and writes follow-up notes.", "version": "1.4.0" },
    { "key": "scheduler", "displayName": "Meeting scheduler",
      "description": "Books follow-up calls on your calendar.", "version": "2.0.1",
      "source": "marketplace",
      "marketplaceSkillId": "mskill_abc", "versionId": "mver_123" }
  ],

  "connections": [
    { "key": "crm", "capability": "crm", "required": true,
      "displayName": "Your CRM",
      "description": "Used to read deals and write follow-up notes.",
      "platforms": [                                // enriched from the catalog at read time
        { "type": "salesforce", "name": "Salesforce", "authSupport": "oauth" },
        { "type": "hubspot", "name": "HubSpot", "authSupport": "both" } ],
      "boundSkills": ["crm-sync"] },
    { "key": "notify", "capability": "chat", "required": false,
      "displayName": "Notifications channel",
      "description": "Optional: where follow-up alerts get posted.",
      "platforms": [ { "type": "slack", "name": "Slack", "authSupport": "oauth" } ] }
  ],

  "triggers": [
    { "key": "poll-crm", "type": "schedule",
      "displayName": "Check for new deals",
      "description": "Looks for deals needing a follow-up and drafts one.",
      "enabled": true,                              // recommended default, confirmed at deploy
      "preset": { "type": "interval", "seconds": 300 },
      "editableParams": [
        { "path": "preset.seconds", "label": "Check every",
          "help": "How often the agent looks for new deals.",
          "unit": "minutes", "min": 60, "step": 60 } ],
      "nextRuns": [ { "at": "2026-08-24T14:05:00Z",  // computed at read time
                      "timezone": "Europe/Copenhagen" } ] },
    { "key": "deal-won", "type": "connection-event", "connectionKey": "crm",
      "displayName": "When a deal is won",
      "description": "Drafts a thank-you follow-up the moment a deal closes.",
      "enabled": false }                            // event + instruction never serve
  ],

  "params": [
    { "name": "CRM_DEFAULT_OWNER", "displayName": "Default deal owner",
      "description": "Fallback owner when a deal has none.",
      "required": true, "type": "string" },
    { "name": "TONE", "displayName": "Tone of voice", "required": false,
      "type": "enum", "enum": ["formal", "casual"], "default": "casual" }
  ],

  "personaTemplate": {
    "template": "You are the sales assistant for {{COMPANY_NAME}}. …",
    "vars": [ { "name": "COMPANY_NAME", "displayName": "Your company",
                "description": "Used in the agent's replies and signatures.",
                "type": "string", "required": true, "placeholder": "Acme Inc.",
                "maxLength": 256 } ],
    "editable": true
  },

  "channels": [
    { "channel": "whatsapp", "required": false,
      "description": "Follow-ups can go out on WhatsApp once a number is connected." }
  ],

  "onInstall": {
    "instruction": "Introduce yourself, then check the CRM connection by listing the three most recent open deals and reporting what you found."
  },
  "onUninstall": {
    "tool": "remove_crm_followup_notes",
    "instruction": "Tell the user the follow-up tracking notes were removed from the CRM and say goodbye."
  },

  "latestApprovedVersion": 3,
  "installable": true,
  "reconciliation": { "summary": { "satisfied": 1, "total": 2 },
                      "capabilities": { "…": "see the reconciliation block above" } }
}
```

***

## What the lints check

Publish is the quality gate: every violation is collected and returned in **one** response with field-path messages, and a rejected publish burns no version number. What you'll see, by field:

| Field                                                                             | Rejection you'll see                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| any frozen string field (skill code, job prompts, descriptions, env descriptions) | `SECRET_DETECTED: <pattern-name> in <kind>/<key>` — a hardcoded credential pattern; the location is named, never the value. Declare it in the env contract instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| any frozen code pointer                                                           | `CODE_BLOB_MISSING: <kind>/<key> references <hash>` — frozen code that could not be hydrated at apply time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `jobs[].schedule`                                                                 | `SCHEDULE_INVALID:` — a `once` schedule (a frozen instant is stale by construction); interval seconds not a whole number of minutes ≥ 60; a cron that doesn't compile (5 fields required).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `triggerPresets.<key>`                                                            | `TRIGGER_PRESET_INVALID:` — no such trigger in this version; `enabled: true` on a connection-event key; `editableParams` on a connection-event key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `triggerPresets.<key>.editableParams[]`                                           | `TRIGGER_PRESET_INVALID:` — a `path` outside `preset.seconds` / `preset.timezone`; duplicate path; missing `label`; `preset.seconds` on a non-interval (or `preset.timezone` on a non-cron) schedule; `min`/`step` not multiples of 60; `max < min`; the frozen schedule violating its own declared envelope.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `personaTemplate.template`                                                        | `PERSONA_TEMPLATE_INVALID:` — a `{{TOKEN}}` with no `vars[]` entry; fewer than 40 literal author characters beside the slots.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `personaTemplate.vars[]`                                                          | `PERSONA_TEMPLATE_INVALID:` — a var appearing in no branch; a duplicate var name; a reserved name (`persona`); an invalid name; missing `displayName`/`description`; a name colliding with a declared param; `enum` empty/duplicated or on a non-enum type; a `default` not matching its type; a non-required var without a `default`; `maxLength` outside 1–2000 or on a non-string.                                                                                                                                                                                                                                                                                                                               |
| `paramsMeta.<key>`                                                                | `PERSONA_TEMPLATE_INVALID:` — no matching `envContract` entry; missing `displayName`; the same typed-declaration self-consistency rules as vars.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `connections[]`                                                                   | `CONNECTION_DECLARATION_INVALID:` — empty/duplicate `key`; missing `displayName`/`description`; non-boolean `required`; invalid `ownerType`; empty `platforms` or duplicate platform types; a `boundSkills` entry naming no skill in the version; scope declarations while scope capture is disabled.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `connections[].platforms` (multi-platform)                                        | the portability lint: `Skill '<key>' calls platform-native tools ('<match>') — narrow connections['<key>'].platforms to that platform or migrate the skill to useCapability('<key>')`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `declaredTriggers[]`                                                              | field-path errors — key clashes with the version's trigger key-space; missing `displayName`/`description`/`instruction`; `instruction` over 2000 characters or interpolating event-payload fields; `connectionKey` naming no declared connection; an event not deliverable on every declared platform, or a filter that platform doesn't offer.                                                                                                                                                                                                                                                                                                                                                                     |
| `channels[]` / `features[]`                                                       | field-path errors — unknown channel/feature name (the known vocabulary is listed in the message); duplicates; non-boolean `required`; `displayName` over 120 or `description` over 2000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `outcomes`                                                                        | field-path errors (`outcomes.units[2].window: …`; evidence-attribution failures carry `OUTCOMES_MANIFEST_INVALID:`) — `verification`/`samplingRate`/`judge` present (platform-owned); more than 25 units; missing/duplicate unit `key` or missing `title`; an invalid `dedupe` mode; `window` outside `1h`–`30d` or malformed; a unit with neither `match` nor `events`; empty or over-long (128+ char) tool globs; a `connectionKey` that isn't a declared connection; an `event` outside the recordable vocabulary; a missing/wrong `channel` on `message.sent`; duplicate event evidence; an `entityPath` not starting `input.`/`result.` (or missing for `dedupe: entity`); a reversal with no evidence source. |
| `onInstall` / `onUninstall`                                                       | `ON_INSTALL_INVALID:` / `ON_UNINSTALL_INVALID:` — not an object; a field other than `tool` or `instruction`; neither field present; a `tool` that is empty or names no tool in this version's frozen skills; an empty or over-2000-character instruction; `{{var}}` tokens in the instruction (nothing is substituted — write plain text).                                                                                                                                                                                                                                                                                                                                                                          |
| `envContract` keys                                                                | `ENV_CONTRACT_RESERVED_PREFIX:` — a contract key under the reserved `LUA_TRIGGER_URL__` prefix (platform-written per webhook trigger at install; the installer could never supply it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| source agent with voices or device triggers                                       | `UNSUPPORTED_SOURCE:` — templates don't freeze voice or device surfaces in V1; the error names each surface and says to remove it from the source agent before publishing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## Related

* [Agent Templates](/marketplace/agent-templates) — the model: what a template contains, lifecycle, consent
* [Publishing Templates](/marketplace/publishing-templates) — the authoring journey this reference backs
* [Deploying Templates](/marketplace/deploying-templates) — how installers experience each section
* [Marketplace Command reference](/cli/marketplace-command)


# Use Lua with Claude, Cursor & AI IDEs
Source: https://docs.heylua.ai/mcp-for-builders

Connect Lua's documentation to your AI coding assistant in minutes via MCP

## Overview

Lua publishes an MCP (Model Context Protocol) server at `https://docs.heylua.ai/mcp`. Add it to any MCP-compatible AI tool — Claude Desktop, Cursor, Windsurf, and others — and your assistant gains direct, always-up-to-date access to the full Lua CLI documentation.

Once connected, you can ask questions like *"How do I create a scheduled job?"* or *"Show me the LuaJob API"* and get answers grounded in the real docs, not stale training data.

<Note>
  The MCP server is hosted and maintained by Mintlify. It auto-updates whenever the Lua docs are published, so it is always current.
</Note>

## What you get

Two tools become available inside your AI tool the moment it connects:

| Tool                            | What it does                                                                                                                                                                             |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_lua_cli`                | Semantic search across all Lua CLI documentation                                                                                                                                         |
| `query_docs_filesystem_lua_cli` | Run read-only shell-like queries (`head`, `cat`, `rg`, `ls`, `tree`, `grep`, `find`, `jq`, ...) against a virtualized, in-memory filesystem of every documentation page and OpenAPI spec |

Your AI assistant will use these automatically when you ask Lua-related questions: `search_lua_cli` for broad/conceptual queries ("how do I authenticate?") and `query_docs_filesystem_lua_cli` to read the full content of a specific page by path (e.g. `head -200 /cli/debugging.mdx`) or to do exact keyword/regex matches across the docs.

***

## Claude Desktop

<Steps>
  <Step title="Open your Claude Desktop config">
    On **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

    On **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

    Create the file if it does not exist.
  </Step>

  <Step title="Add the Lua MCP server">
    ```json theme={null}
    {
      "mcpServers": {
        "lua-docs": {
          "type": "http",
          "url": "https://docs.heylua.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Quit and reopen the app. You should see the Lua tools listed in the MCP tools panel.
  </Step>
</Steps>

***

## Cursor

<Steps>
  <Step title="Create or open your MCP config">
    **Project-level** (only active in this project):

    ```
    .cursor/mcp.json
    ```

    **Global** (active in all projects):

    ```
    ~/.cursor/mcp.json
    ```
  </Step>

  <Step title="Add the Lua MCP server">
    ```json theme={null}
    {
      "mcpServers": {
        "lua-docs": {
          "url": "https://docs.heylua.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Reload Cursor">
    Open the Command Palette (`Cmd/Ctrl + Shift + P`) and run **Reload Window**, or restart Cursor. The Lua tools will appear in the MCP section of your Cursor settings.
  </Step>
</Steps>

***

## Windsurf

<Steps>
  <Step title="Open your Windsurf MCP config">
    ```
    ~/.codeium/windsurf/mcp_config.json
    ```
  </Step>

  <Step title="Add the Lua MCP server">
    ```json theme={null}
    {
      "mcpServers": {
        "lua-docs": {
          "serverUrl": "https://docs.heylua.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Windsurf">
    Restart the editor to pick up the new server.
  </Step>
</Steps>

***

## Other tools (mcp-remote fallback)

For AI tools that only support the **stdio** transport (rather than HTTP), use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge:

```json theme={null}
{
  "mcpServers": {
    "lua-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.heylua.ai/mcp"]
    }
  }
}
```

This works with any tool that accepts an `npx`-style stdio MCP server definition.

***

## What to ask

Once connected, your AI assistant can answer questions like:

* *"How do I define a LuaJob with a cron schedule?"*
* *"What flags does `lua jobs deploy` accept?"*
* *"Show me the full Jobs API reference."*
* *"How do I test a webhook locally?"*
* *"What's the difference between a preprocessor and a postprocessor?"*

The assistant will call `search_lua_cli` to find the relevant pages and `query_docs_filesystem_lua_cli` (with commands like `head -200 /cli/logs-command.mdx` or `rg -il "agent_error" /`) to pull their full content or do precise keyword matches — so answers come from the actual documentation, not guesswork.

***

## Related

<CardGroup>
  <Card title="AI Agent Building Guide" icon="wand-magic-sparkles" href="/ai-guide">
    Complete workflow for building Lua agents with Cursor, Windsurf, or GitHub Copilot
  </Card>

  <Card title="MCP Servers Overview" icon="plug" href="/overview/mcp-servers">
    Connect external MCP servers to your Lua agent
  </Card>

  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    All available Lua CLI commands
  </Card>

  <Card title="LuaMCPServer API" icon="book" href="/api/luamcpserver">
    Connect external tools to your agent via MCP
  </Card>
</CardGroup>


# Lua — AI Agent Platform
Source: https://docs.heylua.ai/overview

Build AI agents that integrate with your entire business using TypeScript

<img alt="Build AI Agents That Do Anything" />

<Note>
  **Vibe Code Your AI Agent** - Lua is built for AI-assisted development. Use Cursor, Windsurf, GitHub Copilot, or any AI coding IDE to build, test, and deploy agents fast.
</Note>

## Connect Your AI IDE to Lua Docs

Get instant access to Lua documentation directly in your coding environment via MCP (Model Context Protocol).

<CardGroup>
  <Card title="Connect to Cursor" icon="bolt" href="cursor://anysphere.cursor-deeplink/mcp/install?name=lua-docs&config=eyJ1cmwiOiJodHRwczovL2RvY3MuaGV5bHVhLmFpL21jcCJ9">
    **One-click install** - Click to add Lua docs to Cursor
  </Card>

  <Card title="Connect to VS Code" icon="code" href="vscode://settings/mcp">
    Add `https://docs.heylua.ai/mcp` to your MCP servers
  </Card>
</CardGroup>

<Accordion title="Manual MCP Setup (Cursor, VS Code, Claude, etc.)">
  Add this to your MCP configuration:

  ```json theme={null}
  {
    "mcpServers": {
      "lua-docs": {
        "url": "https://docs.heylua.ai/mcp"
      }
    }
  }
  ```

  **MCP Server URL:** `https://docs.heylua.ai/mcp`

  Works with: Cursor, VS Code, Claude, Windsurf, and any MCP-compatible tool.
</Accordion>

<Card title="AI Agent Building Guide" icon="robot" href="/ai-guide">
  **Complete workflow for AI IDEs** - Authentication, testing strategies, sandbox vs production, common gotchas, and the full build-test-deploy cycle optimized for Cursor, Windsurf, and GitHub Copilot.
</Card>

***

## What is Lua?

**Lua is a developer platform for building AI agents that integrate with your entire business.**

Write TypeScript functions that connect to any API - your CRM, payment processor, inventory system, or any third-party service - and Lua transforms them into conversational AI capabilities. Your customers chat naturally ("Where's my order?" or "Book me a table"), and your AI agent takes real actions by calling the functions you wrote.

<CardGroup>
  <Card title="Vibe Coding Ready" icon="wand-magic-sparkles">
    **Built for AI IDEs** - Cursor, Windsurf, GitHub Copilot

    All commands are non-interactive. Let AI write your agent.
  </Card>

  <Card title="Integrate With ANY API" icon="plug">
    **Your Backend** - CRM, ERP, databases

    **External Services** - Stripe, Shopify, SendGrid
  </Card>

  <Card title="TypeScript-Native" icon="code">
    Full type safety with Zod validation

    Live reload, testing, instant deployment
  </Card>
</CardGroup>

## Two Powerful Products

<Tabs>
  <Tab title="🛠️ Lua CLI">
    **Build AI agents with custom capabilities using TypeScript**

    The development framework for creating AI skills that connect to your APIs.

    ### What You Get

    * TypeScript framework for building tools
    * Live reload development environment
    * Optional Platform APIs (Products, Baskets, Orders, Vector Search, Templates)
    * 30+ working examples
    * One-command deployment

    ### Quick Start

    <CodeGroup>
      ```bash npm theme={null}
      npm install -g lua-cli
      lua auth configure
      lua init
      lua chat
      ```

      ```bash yarn theme={null}
      yarn global add lua-cli
      lua auth configure
      lua init
      lua chat
      ```

      ```bash pnpm theme={null}
      pnpm add -g lua-cli
      lua auth configure
      lua init
      lua chat
      ```
    </CodeGroup>

    <Card title="Explore Lua CLI" icon="terminal" href="/getting-started/quick-start">
      Build your first AI agent in 5 minutes
    </Card>
  </Tab>

  <Tab title="💬 LuaPop Widget">
    **Embeddable AI chat widget for your website**

    Add your AI agent to any website with a single script tag.

    ### What You Get

    * One-line integration (CDN or NPM)
    * Fully customizable styling
    * Voice chat capabilities
    * Mobile-responsive
    * Event tracking
    * Works with any framework

    ### Quick Start

    ```html theme={null}
    <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
    <script>
      window.LuaPop.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    </script>
    ```

    <Card title="Explore LuaPop Widget" icon="comments" href="/chat-widget/introduction">
      Add AI chat to your website in 2 minutes
    </Card>
  </Tab>
</Tabs>

## How It Works

<Steps>
  <Step title="Write TypeScript Functions">
    Create tools that integrate with your APIs

    ```typescript theme={null}
    class OrderLookupTool implements LuaTool {
      async execute(input: { orderId: string }) {
        // Call YOUR API
        const response = await fetch(`https://your-api.com/orders/${input.orderId}`);
        return await response.json();
      }
    }
    ```
  </Step>

  <Step title="Bundle Into Skills">
    Group related tools together

    ```typescript theme={null}
    const customerService = new LuaSkill({
      name: "customer-service",
      tools: [new OrderLookupTool(), new CreateTicketTool()]
    });
    ```
  </Step>

  <Step title="Configure Your Agent">
    Use `LuaAgent` to configure everything in one place

    ```typescript theme={null}
    export const agent = new LuaAgent({
      name: "support-assistant",
      persona: "You are a helpful customer support agent...",
      skills: [customerService]
    });
    ```
  </Step>

  <Step title="Test with Interactive Chat">
    Chat with your agent to test everything works

    ```bash theme={null}
    lua chat
    ```

    Select sandbox mode to test with your local skills
  </Step>

  <Step title="Deploy Your Agent">
    Push to production with one command

    ```bash theme={null}
    lua push && lua deploy
    ```
  </Step>

  <Step title="Users Chat, AI Takes Actions">
    Your users interact naturally, AI calls your tools

    **User**: "What's the status of order #12345?"

    **AI**: *Calls OrderLookupTool with your API* → "Your order shipped yesterday and will arrive tomorrow!"
  </Step>
</Steps>

<Note>
  **Testing Individual Tools**: Need to test a specific tool with exact inputs? Use `lua test` to test tools one at a time. For most development, `lua chat` is faster for testing complete workflows.
</Note>

## Beyond Skills and Tools

Lua agents go beyond skills and tools with a full set of primitives for production use cases:

<CardGroup>
  <Card title="LuaAgent" icon="robot">
    **Unified Configuration** - Configure your entire agent in one place

    Combines persona, skills, webhooks, jobs, and processors
  </Card>

  <Card title="LuaWebhook" icon="webhook">
    **HTTP Endpoints** - Receive events from external services

    Stripe payments, Shopify orders, GitHub deployments, etc.
  </Card>

  <Card title="LuaJob" icon="clock">
    **Scheduled Tasks** - Automate recurring operations

    Daily reports, cleanup jobs, monitoring with cron patterns
  </Card>

  <Card title="Jobs API" icon="plus">
    **Dynamic Scheduling** - Create jobs from tools at runtime

    User reminders, follow-ups, deferred work
  </Card>

  <Card title="PreProcessor" icon="filter">
    **Message Filtering** - Process messages before your agent

    Spam detection, profanity filters, routing, validation
  </Card>

  <Card title="PostProcessor" icon="paper-plane">
    **Response Formatting** - Enhance responses after generation

    Disclaimers, branding, translation, formatting
  </Card>
</CardGroup>

### Complete Example

```typescript theme={null}
import { 
  LuaAgent, 
  LuaSkill, 
  LuaWebhook, 
  LuaJob,
  PreProcessor,
  PostProcessor 
} from 'lua-cli';

// Skills
import { customerServiceSkill } from './skills/customer-service';
import { productSkill } from './skills/products';

// Webhooks
const paymentWebhook = new LuaWebhook({
  name: 'stripe-payment',
  execute: async (event) => {
    if (event.type === 'payment.succeeded') {
      // Handle payment confirmation
      await notifyCustomer(event.data);
    }
  }
});

// Scheduled Jobs
const dailyReportJob = new LuaJob({
  name: 'daily-report',
  schedule: { type: 'cron', pattern: '0 9 * * *' },
  execute: async (job) => {
    const user = await job.user();
    await user.send([{ type: 'text', text: 'Daily report ready!' }]);
  }
});

// Message Processing
const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  execute: async (message, user) => {
    if (containsProfanity(message.content)) {
      return { block: true, response: "Please keep it respectful." };
    }
    return { block: false };
  }
});

const addDisclaimer = new PostProcessor({
  name: 'add-disclaimer',
  execute: async (user, message, response, channel) => {
    return {
      modifiedResponse: response + "\n\n_AI-generated content for informational purposes._"
    };
  }
});

// Complete Agent Configuration
export const agent = new LuaAgent({
  name: "enterprise-assistant",
  
  persona: `You are a professional enterprise assistant.
  
Your role:
- Help with customer inquiries
- Process orders and payments
- Provide product information

Communication:
- Professional and efficient
- Clear and accurate
- Proactive and helpful`,

  
  skills: [customerServiceSkill, productSkill],
  webhooks: [paymentWebhook],
  jobs: [dailyReportJob],
  preProcessors: [profanityFilter],
  postProcessors: [addDisclaimer]
});
```

**Learn more:**

* [LuaAgent API](/api/luaagent)
* [LuaWebhook API](/api/luawebhook)
* [LuaJob API](/api/luajob)
* [Jobs API](/api/jobs)
* [PreProcessor API](/api/preprocessor)
* [PostProcessor API](/api/postprocessor)

## Complete Flexibility: Choose Your Integration Approach

One of Lua's core strengths is flexibility. You can integrate with your existing systems, use our optional Platform APIs, or mix both approaches. Here's how each approach works:

<Tabs>
  <Tab title="Your APIs Only">
    ### 100% Custom Integration

    Connect directly to your existing backend, databases, and third-party services. This gives you complete control over your business logic, data, and infrastructure.

    ```typescript theme={null}
    import { LuaTool, env } from 'lua-cli';
    import { z } from 'zod';

    // Connect to YOUR systems
    class YourCustomTool implements LuaTool {
      name = "your_custom_action";
      description = "Performs actions specific to your business";
      inputSchema = z.object({ param: z.string() });
      
      async execute(input) {
        // YOUR API
        const apiKey = env('YOUR_API_KEY');
        const response = await fetch('https://your-backend.com/api/endpoint', {
          headers: { 'Authorization': `Bearer ${apiKey}` }
        });
        
        // YOUR business logic
        const data = await response.json();
        return processYourData(data);
      }
    }
    ```

    **Perfect for:**

    * Existing infrastructure and systems
    * Custom business requirements
    * Enterprise integrations
    * Any industry or use case
    * Complete control over data and logic

    **Real Examples:**

    * CRM: Salesforce, HubSpot, your custom CRM
    * E-commerce: Shopify, WooCommerce, Magento, your custom store
    * ERP: SAP, Oracle, your internal systems
    * Payments: Stripe, PayPal, Square, your payment gateway
    * Databases: PostgreSQL, MongoDB, MySQL, your data warehouse
  </Tab>

  <Tab title="Platform APIs">
    ### Optional Built-In Helpers

    For common e-commerce and data storage needs, we provide ready-to-use APIs. These are completely optional shortcuts.

    ```typescript theme={null}
    import { Products, Baskets, Orders, Data } from 'lua-cli';

    class QuickShopTool implements LuaTool {
      name = "shop_assistant";
      description = "Help users browse and purchase products";
      
      async execute(input: { query: string }) {
        // Platform APIs - no backend needed
        const products = await Products.search(input.query);
        const basket = await Baskets.create({ currency: 'USD' });
        
        // Add items to cart
        await Baskets.addItem(basket.id, {
          id: products[0].id,
          price: products[0].price,
          quantity: 1
        });
        
        return { products, basketId: basket.id };
      }
    }
    ```

    **Available Platform APIs:**

    * **Products** - E-commerce catalog management
    * **Baskets** - Shopping cart functionality
    * **Orders** - Order processing and tracking
    * **Data** - Vector search and data storage
    * **User** - User profile management

    **Perfect for:**

    * Building e-commerce quickly
    * Need vector/semantic search
    * Rapid prototyping and MVPs
    * Don't have backend infrastructure yet
    * Want to focus on AI experience first
  </Tab>

  <Tab title="Mix Both (Recommended)">
    ### Best of Both Worlds

    Most production applications use a hybrid approach: your critical business systems combined with Platform helpers where they add value.

    ```typescript theme={null}
    import { Data, env } from 'lua-cli';

    class HybridSearchTool implements LuaTool {
      name = "comprehensive_search";
      description = "Search across all your data sources";
      
      async execute(input: { query: string }) {
        // 1. YOUR Shopify store for products
        const shopifyProducts = await fetch(
          `https://your-store.myshopify.com/admin/api/2024-01/products.json`,
          { 
            headers: { 
              'X-Shopify-Access-Token': env('SHOPIFY_TOKEN') 
            }
          }
        ).then(r => r.json());
        
        // 2. Platform vector search for FAQs and docs
        const helpArticles = await Data.search('help_articles', input.query, 5);
        
        // 3. YOUR custom database for user history
        const userHistory = await fetch(
          `https://your-api.com/users/${input.userId}/history`,
          {
            headers: { 'Authorization': `Bearer ${env('YOUR_API_KEY')}` }
          }
        ).then(r => r.json());
        
        return {
          products: shopifyProducts.products,
          help: helpArticles.data,
          history: userHistory
        };
      }
    }
    ```

    **Perfect for:**

    * Most production applications
    * Pragmatic, flexible solutions
    * Using best tool for each job
    * Extending existing systems
    * Adding AI-powered search to your stack

    **Common Patterns:**

    * Your product catalog + Platform vector search
    * Your authentication + Platform data storage
    * Your payment system + Platform product management
    * Your CRM + Platform semantic search
  </Tab>
</Tabs>

## Detailed Integration Examples

### Example 1: Pure Custom - CRM Integration

Connect to your existing CRM system (Salesforce, HubSpot, or custom):

```typescript theme={null}
import { LuaTool, LuaSkill, env } from 'lua-cli';
import { z } from 'zod';

class GetCustomerTool implements LuaTool {
  name = "get_customer";
  description = "Look up customer in your CRM";
  inputSchema = z.object({ 
    email: z.string().email() 
  });

  async execute(input: { email: string }) {
    // Call YOUR CRM API
    const response = await fetch(
      `https://your-crm.com/api/customers/${input.email}`,
      {
        headers: { 
          'X-API-Key': env('YOUR_CRM_API_KEY'),
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error('Customer not found');
    }
    
    return await response.json();
  }
}

class CreateTicketTool implements LuaTool {
  name = "create_ticket";
  description = "Create support ticket in your system";
  inputSchema = z.object({
    customerId: z.string(),
    subject: z.string(),
    description: z.string()
  });

  async execute(input) {
    const response = await fetch('https://your-crm.com/api/tickets', {
      method: 'POST',
      headers: {
        'X-API-Key': env('YOUR_CRM_API_KEY'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(input)
    });
    
    return await response.json();
  }
}

const crmSkill = new LuaSkill({
  name: "crm-integration",
  description: "Access our CRM system for customer support",
  tools: [new GetCustomerTool(), new CreateTicketTool()]
});

// Configure agent
export const agent = new LuaAgent({
  name: "crm-support-agent",
  persona: "You are a customer support specialist. Help users by looking up their information and creating support tickets when needed.",
  skills: [crmSkill]
});
```

### Example 2: Platform APIs - Quick E-commerce

Build an e-commerce assistant using Platform APIs:

```typescript theme={null}
import { LuaAgent, LuaTool, LuaSkill, Products, Baskets } from 'lua-cli';
import { z } from 'zod';

class ShopAssistantTool implements LuaTool {
  name = "add_to_cart";
  description = "Add product to shopping cart";
  inputSchema = z.object({
    productId: z.string(),
    quantity: z.number().min(1)
  });
  
  async execute(input: { productId: string; quantity: number }) {
    // Use Platform APIs
    const product = await Products.getById(input.productId);
    const basket = await Baskets.create({ currency: 'USD' });
    
    await Baskets.addItem(basket.id, {
      id: input.productId,
      price: product.price,
      quantity: input.quantity
    });
    
    return { 
      basketId: basket.id,
      product: product.name,
      quantity: input.quantity,
      total: product.price * input.quantity
    };
  }
}

const shopSkill = new LuaSkill({
  name: "shop-assistant",
  description: "Help users shop and add items to cart",
  tools: [new ShopAssistantTool()]
});

// Configure agent
export const agent = new LuaAgent({
  name: "shop-assistant",
  persona: "You are a friendly shopping assistant. Help users find products and add them to their cart.",
  skills: [shopSkill]
});
```

### Example 3: Hybrid - Real Business Solution

Combine your systems with Platform helpers:

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaTool, Data, env } from 'lua-cli';
import { z } from 'zod';

class CompleteSearchTool implements LuaTool {
  name = "smart_search";
  description = "Search across all data sources intelligently";
  inputSchema = z.object({
    query: z.string(),
    userId: z.string().optional()
  });
  
  async execute(input: { query: string; userId?: string }) {
    // 1. Search YOUR product API/database
    const yourProducts = await fetch('https://your-api.com/search', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${env('YOUR_API_KEY')}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query: input.query })
    }).then(r => r.json());
    
    // 2. Use Platform vector search for FAQs and documentation
    const faqResults = await Data.search('faqs', input.query, 5, 0.7);
    
    // 3. If user provided, get their purchase history from YOUR system
    let userHistory = null;
    if (input.userId) {
      userHistory = await fetch(
        `https://your-api.com/users/${input.userId}/purchases`,
        {
          headers: { 'Authorization': `Bearer ${env('YOUR_API_KEY')}` }
        }
      ).then(r => r.json());
    }
    
    // 4. Combine and return all results
    return {
      products: yourProducts,
      faqs: faqResults.map(e => ({ id: e.id, question: e.question, answer: e.answer })),
      userHistory,
      message: `Found ${yourProducts.length} products and ${faqResults.length} help articles`
    };
  }
}

const hybridSkill = new LuaSkill({
  name: "hybrid-search",
  description: "Search across all your systems and our platform",
  tools: [new CompleteSearchTool()]
});

// Configure agent
export const agent = new LuaAgent({
  name: "hybrid-assistant",
  persona: "You are a comprehensive search assistant. Help users find information across products, FAQs, and their history.",
  skills: [hybridSkill]
});
```

## Real-World Use Cases

Lua can power AI agents for virtually any industry or use case. Here are some common scenarios:

<CardGroup>
  <Card title="E-commerce" icon="cart-shopping">
    **Shopping Assistant**

    * Product search and recommendations
    * Cart management and checkout
    * Order tracking and updates
    * Customer support and FAQs

    **Integrate with:** Shopify, WooCommerce, Magento, your custom store, or Platform APIs
  </Card>

  <Card title="Customer Support" icon="headset">
    **24/7 AI Support Agent**

    * Ticket creation and management
    * Knowledge base search
    * Order lookups and status updates
    * Escalation to human agents

    **Integrate with:** Zendesk, Freshdesk, Intercom, your ticketing system
  </Card>

  <Card title="SaaS Products" icon="window-maximize">
    **In-App AI Assistant**

    * User onboarding and tutorials
    * Feature guidance and help
    * Account management
    * Usage analytics and insights

    **Integrate with:** Your product APIs, analytics platforms, auth systems
  </Card>

  <Card title="Internal Tools" icon="building">
    **AI-Powered Operations**

    * Access ERP, CRM, and databases
    * Generate reports and analytics
    * Automate workflows
    * Data lookups and updates

    **Integrate with:** Your internal systems, SAP, Oracle, Salesforce
  </Card>

  <Card title="Finance & Banking" icon="building-columns">
    **Account Management**

    * Balance inquiries and transfers
    * Transaction history
    * Payment processing
    * Report generation

    **Integrate with:** Your banking APIs, Stripe, Plaid, accounting systems
  </Card>

  <Card title="Healthcare" icon="heart-pulse">
    **Patient Portal Assistant**

    * Appointment scheduling
    * Prescription lookups
    * Doctor directory search
    * Health record access

    **Integrate with:** Your EMR, appointment systems, patient databases
  </Card>

  <Card title="HR & Recruiting" icon="user-tie">
    **Employee Assistant**

    * Policy and benefits search
    * Leave requests and approvals
    * Onboarding support
    * Document access

    **Integrate with:** BambooHR, Workday, your HR systems
  </Card>

  <Card title="Logistics" icon="truck">
    **Shipping & Tracking**

    * Multi-carrier tracking
    * Shipping quotes and labels
    * Delivery status updates
    * Route optimization

    **Integrate with:** UPS, FedEx, USPS APIs, your logistics system
  </Card>
</CardGroup>

## Why Developers Love Lua

<AccordionGroup>
  <Accordion title="🤖 Vibe Coding Ready">
    Built for AI-assisted development. All CLI commands are non-interactive, meaning Cursor, Windsurf, GitHub Copilot, and other AI coding tools can execute commands directly. Connect docs via MCP for instant context. Build agents faster with AI helping you code.
  </Accordion>

  <Accordion title="🔓 No Vendor Lock-In">
    Build on your own infrastructure. Integrate with any API you choose. Not tied to our Platform APIs - they're completely optional. Your data stays with your systems, your authentication remains yours.
  </Accordion>

  <Accordion title="⚡ Fast Development">
    Live reload during development means instant feedback. TypeScript autocomplete guides you. Test your agent with `lua chat` immediately. Deploy with one command. Build in minutes what would take days with other platforms.
  </Accordion>

  <Accordion title="🎯 Full Control">
    Your code, your logic, your data. Complete control over authentication, business rules, error handling, and integrations. Not limited by platform constraints - if you can code it in TypeScript, you can build it.
  </Accordion>

  <Accordion title="🚀 Production Ready">
    Version management built-in. Sandbox for testing before production. Environment variables for secrets. One-command deployment. Monitoring and logs. Everything you need for enterprise production use.
  </Accordion>

  <Accordion title="🛠️ Real Developer Tools">
    Actual TypeScript code, not YAML configs or no-code builders. Zod validation for type-safe inputs. Proper testing with `lua test` and `lua chat`. Modern dev workflow you already know.
  </Accordion>

  <Accordion title="🎁 Optional Platform Helpers">
    Platform APIs available when you need quick e-commerce or vector search. But they're completely optional - use them or don't, it's your choice. Most developers use a hybrid approach.
  </Accordion>
</AccordionGroup>

## Platform Architecture

Understanding how Lua works helps you build better agents:

### Skills and Tools

**Tools** are TypeScript classes that implement `LuaTool`:

* Each tool performs one specific action
* Tools have names, descriptions, and input schemas
* The AI decides when to call each tool based on context

**Skills** are bundles of related tools:

* Group tools that work together
* Each skill can have multiple tools
* Skills can be versioned and deployed independently

### Development Workflow

```bash theme={null}
# Local development with live reload
lua chat

# Test specific tools with exact inputs
lua test

# Push your code to the cloud
lua push

# Deploy to production
lua deploy

# Or combine push and deploy
lua push && lua deploy
```

### Testing Strategies

**Interactive Testing (`lua chat`):**

* Best for testing complete workflows
* Chat naturally and see tools called in real-time
* Choose sandbox mode to test local code before deploying
* Fast iteration during development

**Individual Tool Testing (`lua test`):**

* Test specific tools with exact inputs
* Useful for debugging edge cases
* Validates schemas and error handling
* Good for automated testing

## Security and Best Practices

### Environment Variables

Always use environment variables for API keys and secrets:

```typescript theme={null}
import { env } from 'lua-cli';

const apiKey = env('YOUR_API_KEY');
const dbPassword = env('DATABASE_PASSWORD');
```

Set environment variables with:

```bash theme={null}
lua env set YOUR_API_KEY "your-key-here"
```

### Error Handling

Implement proper error handling in your tools:

```typescript theme={null}
class SafeTool implements LuaTool {
  async execute(input) {
    try {
      const response = await fetch('https://api.example.com/data');
      
      if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
      }
      
      return await response.json();
    } catch (error) {
      // Log error for debugging
      console.error('Tool execution failed:', error);
      
      // Return user-friendly message
      return {
        error: true,
        message: 'Sorry, I encountered an issue. Please try again.'
      };
    }
  }
}
```

### Input Validation

Use Zod schemas for type-safe validation:

```typescript theme={null}
import { z } from 'zod';

class ValidatedTool implements LuaTool {
  inputSchema = z.object({
    email: z.string().email(),
    amount: z.number().positive(),
    date: z.string().datetime()
  });
  
  async execute(input) {
    // Input is guaranteed to match schema
    // TypeScript knows the types
  }
}
```

## Feature Highlights

<CardGroup>
  <Card title="Any API" icon="link">
    REST, GraphQL, WebSockets - integrate with anything callable from TypeScript
  </Card>

  <Card title="TypeScript" icon="code">
    Full type safety with autocomplete and IntelliSense
  </Card>

  <Card title="Live Reload" icon="bolt">
    Instant feedback during development with auto-recompilation
  </Card>

  <Card title="Optional Platform APIs" icon="database">
    Ready-to-use helpers for e-commerce and vector search
  </Card>

  <Card title="Voice Chat" icon="microphone">
    Voice interactions built into LuaPop widget
  </Card>

  <Card title="One-Command Deploy" icon="rocket">
    Production deployment in seconds
  </Card>
</CardGroup>

## Get Started

<CardGroup>
  <Card title="🤖 AI Agent Building Guide" icon="robot" href="/ai-guide">
    **For Cursor, Windsurf, Copilot** - Complete workflow for AI IDEs

    Non-interactive commands, testing strategies, deployment

    → Best for vibe coding
  </Card>

  <Card title="🛠️ Quick Start Tutorial" icon="code" href="/getting-started/quick-start">
    **Lua CLI** - Create AI agents that integrate with your APIs

    Install CLI, write TypeScript tools, deploy instantly

    → 5 minute quick start
  </Card>

  <Card title="💬 Add Chat Widget" icon="comments" href="/chat-widget/quick-start">
    **LuaPop Widget** - Embed AI chat on your website

    One script tag, fully customizable, works anywhere

    → 2 minute setup
  </Card>

  <Card title="📚 Connect Docs to Your IDE" icon="plug" href="#connect-your-ai-ide-to-lua-docs">
    **MCP Server** - Get Lua docs in Cursor, VS Code, Claude

    One-click install for instant documentation access

    → Scroll up for setup
  </Card>
</CardGroup>

## Learning Path

<Steps>
  <Step title="Understand Core Concepts">
    Learn how Lua enables AI agents to take real actions through your code

    <Card title="Skills and Tools" icon="book" href="/concepts/skills-and-tools" />
  </Step>

  <Step title="Build Your First Agent">
    Follow a complete tutorial from installation to deployment

    <Card title="First Skill Tutorial" icon="graduation-cap" href="/getting-started/first-skill" />
  </Step>

  <Step title="Explore Integration Options">
    See examples of external APIs, Platform APIs, and hybrid approaches

    <Card title="API Integration Guide" icon="plug" href="/concepts/platform-apis" />
  </Step>

  <Step title="Deploy to Production">
    Add the chat widget to your website and go live

    <Card title="Chat Widget Setup" icon="rocket" href="/chat-widget/installation" />
  </Step>
</Steps>

## Popular Resources

<CardGroup>
  <Card title="Quick Start Guide" icon="play" href="/getting-started/quick-start">
    Get your first AI agent running in 5 minutes
  </Card>

  <Card title="API Integration" icon="plug" href="/concepts/platform-apis">
    Learn how to integrate with your APIs or use Platform APIs
  </Card>

  <Card title="Complete API Reference" icon="book-open" href="/api/overview">
    Full documentation for all classes and methods
  </Card>

  <Card title="30+ Working Examples" icon="layer-group" href="/examples/overview">
    External APIs, Platform APIs, and hybrid approaches
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/cli/overview">
    Complete command reference and workflows
  </Card>

  <Card title="Chat Widget Setup" icon="comments" href="/chat-widget/quick-start">
    Add AI chat to your website in 2 minutes
  </Card>
</CardGroup>

## Featured Demos

See complete, production-ready implementations:

<CardGroup>
  <Card title="E-commerce Assistant" icon="cart-shopping" href="/demos/ecommerce-assistant">
    Complete shopping experience with cart and checkout

    **Uses:** Platform APIs (Products, Baskets, Orders)
  </Card>

  <Card title="Customer Support" icon="headset" href="/demos/customer-support">
    Zendesk integration with AI knowledge base

    **Uses:** Zendesk API + Platform Data (vector search)
  </Card>

  <Card title="Financial Onboarding" icon="building-columns" href="/demos/financial-onboarding">
    KYC verification with document upload

    **Uses:** Stripe Identity + Platform Data
  </Card>

  <Card title="HR Assistant" icon="user-tie" href="/demos/hr-assistant">
    Employee management and policy search

    **Uses:** BambooHR + Platform Data
  </Card>

  <Card title="Logistics Tracker" icon="truck" href="/demos/logistics-tracker">
    Multi-carrier shipping (UPS, FedEx, USPS)

    **Uses:** Multiple external APIs
  </Card>

  <Card title="View All 11 Demos" icon="layer-group" href="/demos/overview">
    Customer-facing and internal agent solutions

    **See:** Complete code for all use cases
  </Card>
</CardGroup>

## Enterprise Features

<CardGroup>
  <Card title="Security" icon="shield">
    Token-based auth, HTTPS only, secure environment variables, session isolation
  </Card>

  <Card title="Scalability" icon="chart-line">
    Auto-scaling infrastructure, CDN delivery, WebSocket optimization
  </Card>

  <Card title="Compliance" icon="check-circle">
    GDPR ready, SOC 2 compliant, data residency options, audit logs
  </Card>

  <Card title="Support" icon="life-ring">
    Technical support, migration assistance, dedicated success team
  </Card>
</CardGroup>

## Need Help?

<CardGroup>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Chat with other builders and get real-time help
  </Card>

  <Card title="Documentation" icon="book" href="/getting-started/quick-start">
    Complete guides and tutorials
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@heylua.ai">
    Email our team
  </Card>
</CardGroup>

***

<Card title="Ready to Build Your First Agent?" icon="rocket" href="/getting-started/quick-start">
  Complete quick start tutorial with step-by-step instructions →
</Card>


# Agent
Source: https://docs.heylua.ai/overview/agent

Unified configuration for your entire AI agent

## What is LuaAgent?

**LuaAgent** is the main configuration object for your entire AI agent. It brings together your persona, skills, webhooks, jobs, and message processors in one unified structure.

<Card title="Think of it as:" icon="robot">
  The "brain" of your AI - where you define who the agent is, what it can do, and how it behaves
</Card>

<Note>
  LuaAgent replaces the old pattern of exporting individual skills. It's now the recommended way to configure agents.
</Note>

## Why LuaAgent?

<CardGroup>
  <Card title="Single Source of Truth" icon="bullseye">
    All agent configuration in one place instead of scattered exports
  </Card>

  <Card title="Better Organization" icon="layer-group">
    Clear separation between persona, skills, webhooks, jobs, and processors
  </Card>

  <Card title="State Tracking" icon="arrows-rotate">
    Component IDs and versions auto-tracked in `lua.skill.yaml` (do not edit manually)
  </Card>

  <Card title="More Powerful" icon="bolt">
    Support for webhooks, jobs, preprocessors, and postprocessors
  </Card>
</CardGroup>

## Anatomy of an Agent

```typescript theme={null}
import { LuaAgent } from 'lua-cli';

export const agent = new LuaAgent({
  // Required: Who is this agent?
  name: "customer-support-agent",
  
  // Required: What's its personality and behavior?
  persona: `You are a friendly customer support specialist.
  
Your role:
- Help customers with orders and inquiries
- Use inquiry forms or your knowledge base when structured intake is needed
- Provide accurate information

Communication style:
- Patient and empathetic
- Clear and professional
- Proactive with solutions`,

  
  // Optional: Which LLM to use (default: google/gemini-2.5-flash)
  model: 'openai/gpt-4o',

  // Optional: Skills with tools
  skills: [customerServiceSkill, productSkill],
  
  // Optional: HTTP endpoints for external events
  webhooks: [stripeWebhook, shopifyWebhook],
  
  // Optional: Scheduled automated tasks
  jobs: [dailyReportJob, cleanupJob],
  
  // Optional: Filter messages before processing
  preProcessors: [profanityFilter, rateLimiter],
  
  // Optional: Format responses before sending
  postProcessors: [addDisclaimer, addBranding]
});
```

## The Three Required Elements

### 1. Name

Unique identifier for your agent:

```typescript theme={null}
name: "customer-support-agent"
```

**Best Practices:**

* Use lowercase with hyphens
* Be descriptive and specific
* Keep it short (2-4 words)

### 2. Persona

Defines your agent's personality, behavior, and capabilities:

```typescript theme={null}
persona: `You are Dr. Health, a medical information assistant.

Role: Provide general health information and wellness tips.

Guidelines:
- Always clarify you're not a licensed doctor
- Recommend seeing professionals for serious concerns
- Use clear, non-technical language
- Be empathetic and supportive

Tone: Professional, caring, informative`
```

**Best Practices:**

* Clearly define the role
* List specific capabilities
* Set boundaries and limitations
* Define communication style
* Include do's and don'ts

### 3. Skills

At least one skill with tools:

```typescript theme={null}
skills: [mySkill]
```

Without skills, the agent has no capabilities!

## Optional Components

### Model

Which LLM your agent uses to generate responses:

```typescript theme={null}
model: 'openai/gpt-4o'
```

**Use for:** Choosing a model with different capabilities, context window, or cost profile. You can also select models dynamically per user or channel.

**See:** [Model Selection](/overview/model-selection) for available models and dynamic selection patterns.

### Welcome Message

First message users see:

### Webhooks

HTTP endpoints for external events:

```typescript theme={null}
webhooks: [paymentWebhook, orderWebhook]
```

**Use for:** Stripe payments, Shopify orders, GitHub events

### Jobs

Scheduled automated tasks:

```typescript theme={null}
jobs: [dailyReportJob, weeklyCleanupJob]
```

**Use for:** Daily reports, cleanup tasks, monitoring

### PreProcessors

Filter messages before they reach your agent:

```typescript theme={null}
preProcessors: [profanityFilter, businessHoursFilter]
```

**Use for:** Spam filtering, routing, validation

### PostProcessors

Format responses after agent generation:

```typescript theme={null}
postProcessors: [addDisclaimer, addBranding]
```

**Use for:** Disclaimers, branding, translation

## Real-World Example

Complete agent with all features:

```typescript theme={null}
import { 
  LuaAgent, 
  LuaSkill, 
  LuaWebhook, 
  LuaJob,
  PreProcessor,
  PostProcessor 
} from 'lua-cli';

export const agent = new LuaAgent({
  name: "ecommerce-assistant",
  
  persona: `You are Emma, a helpful e-commerce assistant for Acme Store.
  
Your role:
- Help customers find products
- Assist with orders and cart management
- Answer product questions

Communication style:
- Friendly and professional
- Patient and helpful
- Proactive with suggestions

Limitations:
- Cannot modify pricing
- Cannot cancel shipped orders
- Escalate refunds over $100 to manager`,

  skills: [
    productSearchSkill,
    cartManagementSkill,
    orderTrackingSkill
  ],
  
  webhooks: [
    stripePaymentWebhook,
    shopifyOrderWebhook
  ],
  
  jobs: [
    dailySalesReport,
    abandonedCartReminder
  ],
  
  preProcessors: [
    profanityFilter,
    rateLimiter
  ],
  
  postProcessors: [
    addLegalDisclaimer,
    addBrandingFooter
  ]
});
```

## How It All Works Together

```
User Message
    ↓
PreProcessors (filter/validate)
    ↓
AI Agent (uses Persona)
    ↓
Calls Tools (from Skills)
    ↓
PostProcessors (format/enhance)
    ↓
Response to User

External Events → Webhooks → Trigger Actions
Scheduled Time → Jobs → Automated Tasks
```

## Try Your Agent

Every agent gets a **free, hosted chat page** on HeyLua — no setup, no embedding, no code. It's the fastest way to talk to your agent, share it with teammates, or demo it to others.

Just open the agent chat page and pass your agent's ID:

```
https://heylua.ai/agent?agentId=<your-agent-id>
```

<Frame>
  <img alt="A Lua agent running on its free hosted chat page" />
</Frame>

The hosted page is fully branded with your agent's name, icon, and welcome message, and shows starter prompts to help users begin the conversation.

<Tip>
  This also works for [Spaces](/overview/spaces) — pass a Space ID as the `agentId` and the hosted page will coordinate all of the Space's supervised agents in one conversation.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Skills Concept" icon="puzzle-piece" href="/overview/skill">
    Learn about organizing tools into skills
  </Card>

  <Card title="Tools Concept" icon="wrench" href="/overview/tools">
    Understand individual tools
  </Card>

  <Card title="Webhooks Concept" icon="webhook" href="/overview/webhooks">
    Learn about HTTP endpoints
  </Card>

  <Card title="Jobs Concept" icon="clock" href="/overview/jobs">
    Understand scheduled tasks
  </Card>

  <Card title="Full API Reference" icon="book" href="/api/luaagent">
    Complete LuaAgent API documentation
  </Card>

  <Card title="Build Your First Agent" icon="rocket" href="/getting-started/first-skill">
    Step-by-step tutorial
  </Card>
</CardGroup>


# Channels
Source: https://docs.heylua.ai/overview/channels

How users connect with your AI agent

## What are Channels?

**Channels** are the communication platforms where users interact with your AI agent - like WhatsApp, Facebook Messenger, Email, Instagram, Slack, and your website.

<Card title="Think of it as:" icon="broadcast-tower">
  The connection points between your users and your AI agent - where conversations happen
</Card>

## Why Channels Matter

Your agent can both **respond to** and **reach out to** users across **all their preferred platforms** - not just one. Inbound messages wake your agent; the [Channels API](/api/channels) lets it send messages out — notifications, reminders, follow-ups — from tools, jobs, and webhooks. See [Proactive Messaging](/channels/proactive-messaging).

<CardGroup>
  <Card title="Multi-Platform" icon="globe">
    One agent, many channels
  </Card>

  <Card title="Unified Experience" icon="equals">
    Same agent everywhere
  </Card>

  <Card title="Meet Users Anywhere" icon="location-dot">
    Users choose their platform
  </Card>

  <Card title="Centralized" icon="grip">
    Manage all from one place
  </Card>
</CardGroup>

## Currently Supported Channels

We currently support 7 communication channels:

<Tabs>
  <Tab title="Messaging Apps">
    * 📱 **WhatsApp** - Business messaging
    * 💬 **Facebook Messenger** - Page messaging
    * 📸 **Instagram Messenger** - Direct messages
    * 💼 **Slack** - Workspace integration
    * 🟣 **Microsoft Teams** - Business communication
  </Tab>

  <Tab title="Web & Email">
    * 📧 **Email** - Professional communication
    * 💻 **WebChat (LuaPop)** - Website chat widget
  </Tab>
</Tabs>

<Note>
  **🚀 More channels coming soon!** SMS, Discord, Telegram, and more are in development.
</Note>

## How It Works

```
Customer sends message on WhatsApp
            ↓
   Message forwarded to Lua
            ↓
    Your agent processes it
            ↓
    Agent calls your tools
            ↓
   Response sent back to WhatsApp
            ↓
  Customer receives reply
```

**Same process for all channels!**

## Two Ways to Connect

<Tabs>
  <Tab title="CLI (Quick)">
    ```bash theme={null}
    lua channels
    ```

    **Supports:**

    * WhatsApp
    * Facebook
    * Email
    * Slack

    **Best for:** Developers, terminal workflow
  </Tab>

  <Tab title="Admin Dashboard (Visual)">
    ```bash theme={null}
    lua admin
    ```

    **Supports:**

    * All channels
    * OAuth flows
    * Visual setup
    * Analytics

    **Best for:** All users, OAuth platforms
  </Tab>
</Tabs>

## Example: Multi-Channel Agent

```
Your agent on all platforms:

📱 WhatsApp: +1-555-BUSINESS
💬 Facebook: Business Page
📧 Email: support@company.com
💻 Website: Chat widget
💼 Slack: #support channel

Result: Customers reach you anywhere,
        agent responds consistently everywhere
```

## Quick Setup

<Steps>
  <Step title="Deploy Agent">
    ```bash theme={null}
    lua push && lua deploy
    ```
  </Step>

  <Step title="Connect Channels">
    ```bash theme={null}
    lua channels
    ```

    Or use admin dashboard
  </Step>

  <Step title="Test">
    Send message on each platform
  </Step>

  <Step title="Monitor">
    ```bash theme={null}
    lua admin
    ```

    View conversations in real-time
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Complete Channels Guide" icon="book" href="/channels/introduction">
    Detailed setup for every channel type
  </Card>

  <Card title="WhatsApp Setup" icon="whatsapp" href="/channels/whatsapp">
    Connect WhatsApp Business
  </Card>

  <Card title="Website Widget" icon="globe" href="/channels/website-widget">
    Add chat to your website
  </Card>

  <Card title="Admin Dashboard" icon="gauge" href="/channels/admin-dashboard">
    Visual channel management
  </Card>
</CardGroup>


# Devices
Source: https://docs.heylua.ai/overview/devices

Connect physical hardware to your AI agent for bidirectional real-time control

## What are Devices?

**Devices** are physical hardware -- sensors, scanners, displays, controllers -- that connect directly to your AI agent over the internet. When a device connects, it tells the agent what commands it supports. Those commands instantly become tools the agent can use. No compile, no push, no middleware.

<Card title="Think of it as:" icon="satellite-dish">
  A remote control for your agent to reach into the physical world -- send commands to hardware, receive sensor data back, all in real time
</Card>

## How It Works

<Steps>
  <Step title="Device connects">
    A device client (Node.js or MicroPython) opens a persistent connection to the Lua gateway and declares its capabilities.
  </Step>

  <Step title="Agent gets tools">
    Each device command becomes a tool the agent can call, just like skill tools.
  </Step>

  <Step title="Bidirectional communication">
    The agent sends commands to devices. Devices fire triggers back to the agent. Both directions are instant.
  </Step>
</Steps>

## Key Features

<CardGroup>
  <Card title="Self-Describing" icon="list-check">
    Devices declare their commands at connect time. No server-side schema to maintain.
  </Card>

  <Card title="Two Transports" icon="arrows-left-right">
    Socket.IO for Node.js devices. MQTT for microcontrollers and constrained hardware.
  </Card>

  <Card title="Triggers" icon="bolt">
    Devices push events to the agent (e.g., "temperature exceeded threshold") with server-side handler logic.
  </Card>

  <Card title="Runs on Pico W" icon="microchip">
    The MicroPython client fits on a Raspberry Pi Pico W with 264KB of RAM.
  </Card>
</CardGroup>

## Quick Example

```typescript theme={null}
import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: 'your-agent-id',
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  deviceName: 'temp-sensor',
  commands: [
    { name: 'read_temperature', description: 'Read current temperature in celsius' },
  ],
});

device.onCommand('read_temperature', async () => {
  return { temperature: 22.5, unit: 'celsius' };
});

await device.connect();
```

[Provision a device credential](/devices/credentials#provision-a-device-credential) for the same agent and device name before you connect. Existing `apiKey` configurations and non-dotted legacy keys remain supported indefinitely.

The agent can now say: "The temperature is 22.5 degrees celsius" when a user asks.

## Learn More

<CardGroup>
  <Card title="Devices Overview" icon="book" href="/devices/overview">
    Full introduction to the Device Gateway
  </Card>

  <Card title="5-Minute Quickstart" icon="rocket" href="/devices/quickstart">
    Connect your first device
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Complete Node.js device client reference
  </Card>

  <Card title="MicroPython Client" icon="microchip" href="/devices/micropython-client">
    Run on a Raspberry Pi Pico W
  </Card>

  <Card title="Examples" icon="layer-group" href="/devices/examples/warehouse-inventory">
    Full working examples across industries
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/devices/how-it-works">
    How commands and triggers flow through the system
  </Card>
</CardGroup>


# Features
Source: https://docs.heylua.ai/overview/features

Built-in agent capabilities you can turn on or off per agent

## What are features?

**Features** are optional platform capabilities attached to your agent. When a feature is enabled, the runtime adds the right tools and prompt instructions so the model knows when and how to use them.

You toggle features per agent using the CLI (`lua features`) or via the platform APIs. For full command options and interactive flows, see the [Features command](/cli/features-command) reference.

<Card title="Current features" icon="toggle-on">
  There are three built-in features: **Knowledge Search** (`rag`), **Web Search** (`webSearch`), and **Inquiry Forms** (`inquiry`).
</Card>

## Knowledge Search (`rag`)

RAG-based search over your agent’s **resources** (documents you upload as the knowledge base).

**What it does:** Lets the agent retrieve relevant passages from your uploaded materials and answer with citations.

**How you add knowledge:** Use [`lua resources`](/cli/resources-command) from a skill project, or upload documents in the **Admin Dashboard** (recommended for many teams). Almost any common document type can be processed and used for retrieval.

**Best for:** FAQs, policies, product docs, internal knowledge that should stay in *your* data—not the open web.

See also: [Resources](/overview/resources).

***

## Web Search (`webSearch`)

Real-time answers grounded in web search results, with source links attached to the response.

**What it does:** The agent can run a web search for a natural-language query and get a synthesized answer plus source links. It is **not** a web scraper: it does not open arbitrary URLs or extract full page HTML.

Depending on your agent's model, search runs one of two ways under the hood:

* **Native search** — models with a built-in, cited web search path (OpenAI, Anthropic, Google/Gemini, xAI, and Zhipu AI's GLM models) use the provider's own search tool, with real source links.
* **Assisted search** — every other model falls back to Lua's own web-search tool, which still returns source links alongside the answer.

Either way, responses come back with the same citation format, so nothing about how you consume search results changes based on which model your agent uses.

**Best for:** Current events, public facts, or anything not in your uploaded resources.

**On by default.** Like the other built-in features, new agents start with Web Search enabled. If your agent doesn't need it — or you want to avoid the extra latency and per-search cost that native search adds on some models — turn it off with `lua features disable --feature-name webSearch` or from the Admin Dashboard.

For details and limitations, see the [Features command](/cli/features-command) reference (Web Search section).

***

## Inquiry Forms (`inquiry`)

Structured data collection through conversational **forms** you define.

**What it does:** The agent can present forms (questions/fields), collect responses, and store submissions. Submissions appear in the **Admin Dashboard** so your team can review them—similar to how legacy “support tickets” worked, but inquiry forms are general-purpose (leads, intake, feedback, or support-style flows).

**Best for:** Lead capture, onboarding questionnaires, support intake, or any workflow where you need structured answers from users.

***

## Enabling and disabling features

<Card title="Defaults" icon="sparkles">
  Every new agent you create starts with **all built-in features enabled** — Knowledge Search, Web Search, and Inquiry Forms. Turn off what you don't need on a per-agent basis.
</Card>

You can toggle features and customize their per-agent instructions from either the CLI or the Admin Dashboard — both call the same API, so changes in one show up in the other.

### From the CLI

From your skill project directory (with `lua.skill.yaml` configured):

```bash theme={null}
lua features list
lua features enable --feature-name webSearch
lua features disable --feature-name rag
lua features view --feature-name inquiry
```

See [Features command](/cli/features-command) for interactive mode, context editing, and troubleshooting.

### From the Admin Dashboard

The dashboard mirrors the CLI with two surfaces:

1. **Create Agent dialog** — when you create an agent, a **Capabilities** section lets you pre-select which features to enable. All features are ticked by default; untick any your agent doesn't need.
2. **Features section** — on an existing agent's workspace, the **Features** section appears in the overview sidebar (next to Webhooks, Knowledge, and other primitives) with an inline toggle per feature. Click **View all** to open the full `/admin/agents/<agentId>/features` page (also reachable from the settings gear → **Features**) where you can:
   * Flip each feature on or off.
   * Override the per-agent instructions that the model sees when the feature is active.
   * Reset an override back to the platform default without disabling the feature.

The dashboard edits the same `featuresOverride` map on the agent that `lua features` writes to, so customizations flow straight through to the runtime's dynamic tool injection.


# Jobs
Source: https://docs.heylua.ai/overview/jobs

Scheduled tasks that run automatically

## What are Jobs?

**Jobs** are scheduled tasks that run automatically at specified times or intervals, without requiring user interaction. They enable your agent to perform automated operations like sending reports, cleaning up data, or monitoring systems.

<Card title="Think of it as:" icon="clock">
  A scheduled assistant - tasks that run on their own schedule, like daily reports or weekly cleanup
</Card>

<Note>
  Two ways to create jobs - pre-defined with LuaJob or dynamically with Jobs API.
</Note>

## Why Jobs?

<CardGroup>
  <Card title="Automation" icon="gears">
    Run tasks automatically without user requests
  </Card>

  <Card title="Proactive Engagement" icon="bullhorn">
    Send reminders, reports, and updates at the right time
  </Card>

  <Card title="Maintenance" icon="broom">
    Clean up old data, monitor health, maintain systems
  </Card>

  <Card title="Scheduled Communication" icon="calendar">
    Send daily summaries, weekly reports, monthly newsletters
  </Card>
</CardGroup>

## Two Types of Jobs

<Tabs>
  <Tab title="LuaJob (Pre-defined)">
    **Static jobs defined at agent setup**

    ```typescript theme={null}
    import { LuaJob, User } from 'lua-cli';

    const dailyReport = new LuaJob({
      name: 'daily-sales-report',
      schedule: {
        type: 'cron',
        expression: '0 9 * * *'  // Every day at 9 AM
      },
      metadata: {
        userId: 'user_abc123'  // Store user ID in metadata
      },
      execute: async (job) => {
        // ⚠️ Pre-defined jobs have NO conversational context
        // Get user by ID from metadata
        const user = await User.get(job.metadata.userId);
        await user.send([{
          type: 'text',
          text: 'Your daily report is ready!'
        }]);
      }
    });
    ```

    **Best for:**

    * Daily/weekly reports
    * Cleanup tasks
    * System monitoring
    * Recurring notifications

    <Warning>
      **No Context:** LuaJob executes outside conversations. Use `User.get(userId)` with ID from metadata.
    </Warning>
  </Tab>

  <Tab title="Jobs API (Dynamic)">
    **Jobs created on-demand from tools (has user context!)**

    ```typescript theme={null}
    import { Jobs } from 'lua-cli';

    // Inside a tool's execute function
    const job = await Jobs.create({
      name: 'user-reminder',
      metadata: { message: 'Meeting in 10 minutes' },
      schedule: {
        type: 'once',
        executeAt: new Date(Date.now() + 600000)
      },
      execute: async (jobInstance) => {
        // ✅ Dynamic jobs automatically have user context
        const user = await jobInstance.user();  // No userId needed!
        await user.send([{
          type: 'text',
          text: jobInstance.metadata.message
        }]);
      }
    });
    ```

    **Best for:**

    * User-requested reminders
    * Follow-up messages
    * One-time notifications
    * Context-specific tasks

    <Note>
      **Has Context:** Dynamic jobs created in tools automatically know which user triggered them. Use `jobInstance.user()` - no userId needed!
    </Note>
  </Tab>
</Tabs>

## Schedule Types

### Cron (Specific Times)

```typescript theme={null}
schedule: {
  type: 'cron',
  expression: '0 9 * * *'  // Every day at 9 AM
  timezone?: 'America/New_York'  // Optional timezone
}
```

**Common patterns:**

* `'0 9 * * *'` - Every day at 9 AM
* `'0 9 * * 1'` - Every Monday at 9 AM
* `'0 0 1 * *'` - First of every month at midnight
* `'*/15 * * * *'` - Every 15 minutes

### Interval (Regular Periods)

```typescript theme={null}
schedule: {
  type: 'interval',
  seconds: 3600  // Every hour
}
```

**Common intervals:**

* `300` - Every 5 minutes
* `3600` - Every hour
* `86400` - Every day

### Once (One-time)

```typescript theme={null}
schedule: {
  type: 'once',
  executeAt: new Date('2025-12-25T09:00:00Z')
}
```

**Use for:**

* Specific future date/time
* User-requested reminders
* Follow-up messages

## Example Use Cases

<CardGroup>
  <Card title="Daily Reports" icon="chart-line">
    Send sales summaries, analytics, or metrics every day
  </Card>

  <Card title="Cleanup Tasks" icon="broom">
    Delete old data, archive records, maintain database
  </Card>

  <Card title="User Reminders" icon="bell">
    Remind users about appointments, tasks, or deadlines
  </Card>

  <Card title="Monitoring" icon="gauge">
    Check system health, API status, or thresholds
  </Card>

  <Card title="Follow-ups" icon="envelope">
    Send follow-up messages after support tickets
  </Card>

  <Card title="Notifications" icon="megaphone">
    Proactive updates about orders, shipments, or events
  </Card>
</CardGroup>

## Adding Jobs to Your Agent

Pre-defined jobs are added to your LuaAgent:

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import dailyReport from './jobs/daily-report';
import weeklyCleanup from './jobs/weekly-cleanup';

export const agent = new LuaAgent({
  name: "my-agent",
  persona: "...",
  skills: [...],
  
  // Add scheduled jobs
  jobs: [
    dailyReport,
    weeklyCleanup
  ]
});
```

Dynamic jobs are created from within tools using the Jobs API.

## Testing Jobs

```bash theme={null}
lua test
# Select: Job → daily-report
# Job executes immediately for testing
```

## Next Steps

<CardGroup>
  <Card title="LuaJob API Reference" icon="book" href="/api/luajob">
    Pre-defined jobs documentation
  </Card>

  <Card title="Jobs API Reference" icon="plus" href="/api/jobs">
    Dynamic job creation documentation
  </Card>

  <Card title="Agent Concept" icon="robot" href="/overview/agent">
    Learn about LuaAgent configuration
  </Card>

  <Card title="Webhooks Concept" icon="webhook" href="/overview/webhooks">
    Understand HTTP endpoints
  </Card>
</CardGroup>


# MCP Servers
Source: https://docs.heylua.ai/overview/mcp-servers

Extend your agent with external tools via Model Context Protocol

## What are MCP Servers?

**MCP Servers** are remote services that provide additional tools to your agent using the Model Context Protocol (MCP). Instead of building every tool from scratch, you can connect to existing MCP servers that provide database queries, web searches, documentation access, and more.

<Card title="Think of it as:" icon="plug">
  Plug-and-play extensions for your agent - connect to pre-built tools without writing code
</Card>

<Note>
  **What is MCP?** The Model Context Protocol is an open standard developed by Anthropic for connecting AI models to external tools and data sources. Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io).
</Note>

## Why MCP Servers?

<CardGroup>
  <Card title="No Code Required" icon="magic-wand-sparkles">
    Use existing MCP servers - just configure and connect
  </Card>

  <Card title="Open Standard" icon="lock-open">
    MCP is an open protocol with a growing ecosystem
  </Card>

  <Card title="Extend Capabilities" icon="puzzle-piece">
    Add databases, web search, documentation access, and more
  </Card>

  <Card title="Mix & Match" icon="layer-group">
    Combine MCP servers with your custom LuaSkills
  </Card>
</CardGroup>

## How MCP Servers Work

<Steps>
  <Step title="Configure Server">
    Define the MCP server in your code with transport and connection details
  </Step>

  <Step title="Compile & Push">
    Run `lua compile` and `lua push mcp` to register with the platform
  </Step>

  <Step title="Activate">
    Activate the server to make its tools available to your agent
  </Step>

  <Step title="Agent Uses Tools">
    Your agent automatically discovers and uses the MCP server's tools
  </Step>
</Steps>

## Transport Types

MCP servers connect via HTTP-based transports:

<Tabs>
  <Tab title="Streamable HTTP (Recommended)">
    **Modern MCP standard - Best for most use cases**

    * Single endpoint for bidirectional communication
    * Supports session management and resumability
    * Works with all modern MCP servers

    ```typescript theme={null}
    import { LuaMCPServer, env } from 'lua-cli';

    const docsServer = new LuaMCPServer({
      name: 'docs',
      transport: 'streamable-http',
      url: 'https://mcp.example.com/mcp',
      headers: () => ({ 
        'Authorization': `Bearer ${env("MCP_API_TOKEN")}` 
      })
    });
    ```
  </Tab>

  <Tab title="SSE (Legacy)">
    **For older MCP servers that don't support Streamable HTTP**

    * Uses Server-Sent Events for server-to-client streaming
    * Separate endpoints for requests and events
    * Use when connecting to legacy MCP services

    ```typescript theme={null}
    import { LuaMCPServer, env } from 'lua-cli';

    const legacyServer = new LuaMCPServer({
      name: 'legacy-api',
      transport: 'sse',
      url: 'https://old-mcp.example.com/sse',
      headers: () => ({ 
        'Authorization': `Bearer ${env("API_KEY")}` 
      })
    });
    ```
  </Tab>
</Tabs>

<Warning>
  **stdio transport not supported yet**: Local MCP servers (using `npx`, `node`, etc.) are not supported yet.
  Please use remote MCP servers with `streamable-http` or `sse` transport instead.
</Warning>

## Simple Example

```typescript theme={null}
import { LuaAgent, LuaMCPServer, LuaSkill, env } from 'lua-cli';

// Connect to a remote MCP server
const docsServer = new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://docs.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("DOCS_API_KEY")}`
  })
});

// Your custom skill
const coreSkill = new LuaSkill({
  name: 'core-skill',
  description: 'Core tools',
  tools: [...]
});

export const agent = new LuaAgent({
  name: 'docs-assistant',
  persona: 'You are a helpful assistant with access to documentation.',
  skills: [coreSkill],
  
  // Add MCP server
  mcpServers: [docsServer]
});
```

## Common Use Cases

<Tabs>
  <Tab title="Documentation">
    **Access documentation and knowledge bases**

    ```typescript theme={null}
    import { LuaMCPServer, env } from 'lua-cli';

    const docsServer = new LuaMCPServer({
      name: 'docs',
      transport: 'streamable-http',
      url: 'https://docs.example.com/mcp',
      headers: () => ({
        'Authorization': `Bearer ${env("DOCS_API_KEY")}`
      })
    });
    ```

    Tools provided vary by server:

    * `search_docs` - Search documentation
    * `get_page` - Get specific page content
    * `list_sections` - Browse documentation structure
  </Tab>

  <Tab title="APIs">
    **Connect to API services**

    ```typescript theme={null}
    import { LuaMCPServer, env } from 'lua-cli';

    const apiServer = new LuaMCPServer({
      name: 'my-api',
      transport: 'streamable-http',
      url: 'https://api.example.com/mcp',
      headers: () => ({
        'Authorization': `Bearer ${env("API_KEY")}`,
        'X-Api-Version': '2024-01'
      })
    });
    ```

    Connect to any MCP-compatible API service.
  </Tab>

  <Tab title="Databases">
    **Query hosted database services**

    ```typescript theme={null}
    import { LuaMCPServer, env } from 'lua-cli';

    const dbServer = new LuaMCPServer({
      name: 'database',
      transport: 'streamable-http',
      url: 'https://db-mcp.example.com/mcp',
      headers: () => ({
        'Authorization': `Bearer ${env("DB_API_KEY")}`
      })
    });
    ```

    Tools provided vary by server:

    * `query` - Execute queries
    * `list_tables` - Show tables
    * `describe_table` - Show schema
  </Tab>

  <Tab title="Search">
    **Web and content search**

    ```typescript theme={null}
    import { LuaMCPServer, env } from 'lua-cli';

    const searchServer = new LuaMCPServer({
      name: 'search',
      transport: 'streamable-http',
      url: 'https://search-mcp.example.com/mcp',
      headers: () => ({
        'X-Api-Key': env("SEARCH_API_KEY")
      })
    });
    ```

    Tools provided vary by server:

    * `web_search` - Search the web
    * `image_search` - Search images
    * `news_search` - Search news
  </Tab>
</Tabs>

## Environment Variables

MCP servers often need API keys or connection strings. Use the `env()` function to securely access environment variables at runtime:

<Tabs>
  <Tab title="Using env() (Recommended)">
    **Resolved at runtime from agent's environment**

    ```typescript theme={null}
    import { LuaMCPServer, env } from 'lua-cli';

    const apiServer = new LuaMCPServer({
      name: 'my-api',
      transport: 'streamable-http',
      url: 'https://api.example.com/mcp',
      headers: () => ({
        'Authorization': `Bearer ${env("API_TOKEN")}`,
        'X-Api-Key': env("API_KEY")
      })
    });
    ```

    * Function is compiled and executed at runtime
    * Values come from `lua env production` settings
    * Consistent with `env()` in tool execute functions
    * **Recommended for secrets and API keys**
  </Tab>

  <Tab title="Static Values">
    **Stored directly in configuration**

    ```typescript theme={null}
    const apiServer = new LuaMCPServer({
      name: 'my-api',
      transport: 'streamable-http',
      url: 'https://api.example.com/mcp',
      headers: { 
        'X-Custom-Header': 'value',
        'Accept': 'application/json'
      }
    });
    ```

    * Values are stored as-is in the database
    * Use only for non-sensitive configuration
    * **Not recommended for secrets**
  </Tab>
</Tabs>

<Note>
  **Setting Environment Variables:** Use `lua env production` to manage your agent's environment variables. These are securely stored and made available to the `env()` function at runtime.
</Note>

### Dynamic URL with env()

You can also use `env()` to resolve the URL at runtime:

```typescript theme={null}
import { LuaMCPServer, env } from 'lua-cli';

const apiServer = new LuaMCPServer({
  name: 'my-api',
  transport: 'streamable-http',
  url: () => env("MCP_SERVER_URL"),
  headers: () => ({
    'Authorization': `Bearer ${env("API_TOKEN")}`
  })
});
```

## MCP vs Custom Skills

| Aspect            | MCP Servers               | LuaSkill              |
| ----------------- | ------------------------- | --------------------- |
| **Code Required** | None (just config)        | Yes (TypeScript)      |
| **Customization** | Limited to server options | Full control          |
| **Availability**  | Growing ecosystem         | Unlimited             |
| **Best For**      | Standard integrations     | Custom business logic |

<Note>
  **Best practice:** Use MCP servers for standard integrations (docs, APIs, databases) and LuaSkill for custom business logic. They work great together!
</Note>

## Lifecycle

MCP servers have a simple lifecycle:

```
Define → Compile → Push → Activate → Use → Deactivate
```

<AccordionGroup>
  <Accordion title="1. Define">
    Create `LuaMCPServer` in your source code
  </Accordion>

  <Accordion title="2. Compile">
    Run `lua compile` - registers server and gets ID
  </Accordion>

  <Accordion title="3. Push">
    Run `lua push mcp` or `lua push all --force` - syncs configuration
  </Accordion>

  <Accordion title="4. Activate">
    Run `lua mcp activate` - makes tools available to agent
  </Accordion>

  <Accordion title="5. Use">
    Agent discovers and uses MCP server tools at runtime
  </Accordion>

  <Accordion title="6. Deactivate">
    Run `lua mcp deactivate` - removes tools from agent
  </Accordion>
</AccordionGroup>

## Managing MCP Servers

Use the `lua mcp` command to manage servers:

```bash theme={null}
lua mcp list        # List all MCP servers and their status
lua mcp activate    # Activate a server (make tools available)
lua mcp deactivate  # Deactivate a server (remove tools)
lua mcp delete      # Delete a server from the platform
```

## Next Steps

<CardGroup>
  <Card title="LuaMCPServer API" icon="book" href="/api/luamcpserver">
    Complete API reference and examples
  </Card>

  <Card title="MCP Command" icon="terminal" href="/cli/mcp-command">
    CLI commands for managing servers
  </Card>

  <Card title="LuaAgent" icon="robot" href="/overview/agent">
    Adding MCP servers to your agent
  </Card>

  <Card title="Skills Concept" icon="puzzle-piece" href="/overview/skill">
    Custom tools with LuaSkill
  </Card>

  <Card title="Use Lua with Claude & Cursor" icon="wand-magic-sparkles" href="/mcp-for-builders">
    Connect Lua's docs to your AI coding assistant via MCP
  </Card>
</CardGroup>


# Model Selection
Source: https://docs.heylua.ai/overview/model-selection

Choose which LLM powers your agent — statically or dynamically per request

## Overview

By default, every Lua agent uses **Google Gemini 2.5 Flash**. The `model` property on `LuaAgent` lets you choose a different model or select one dynamically based on the request context.

```typescript theme={null}
export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  model: 'openai/gpt-5.4',  // ← add this
  skills: [mySkill]
});
```

<Note>
  **Lua manages the API credentials.** You don't need to configure any API keys or provider accounts — Lua handles all LLM infrastructure on your behalf.

  Support for user-provided API keys (Bring Your Own Key) is coming in a future release.
</Note>

***

## Available Models

### Google (Vertex AI)

| Model string                           | Context window | Notes                                                |
| -------------------------------------- | -------------- | ---------------------------------------------------- |
| `google/gemini-2.5-flash`              | 1M tokens      | **Default** — fast reasoning, best price-performance |
| `google/gemini-2.5-pro`                | 1M tokens      | Advanced reasoning for complex analysis              |
| `google/gemini-2.5-flash-lite`         | 1M tokens      | Budget-friendly in the 2.5 family                    |
| `google/gemini-3.1-pro-preview`        | 1M tokens      | Most capable Gemini (preview)                        |
| `google/gemini-3-flash-preview`        | 1M tokens      | Next-gen frontier flash (preview)                    |
| `google/gemini-3.1-flash-lite-preview` | 1M tokens      | Next-gen lite (preview)                              |

### OpenAI

| Model string          | Context window | Notes                           |
| --------------------- | -------------- | ------------------------------- |
| `openai/gpt-5.4`      | 1.1M tokens    | Current flagship                |
| `openai/gpt-5.4-mini` | 400K tokens    | Fast flagship variant           |
| `openai/gpt-5.4-nano` | 400K tokens    | Ultra-low-latency               |
| `openai/gpt-5`        | 400K tokens    | Strong general-purpose          |
| `openai/gpt-5-mini`   | 400K tokens    | Compact GPT-5                   |
| `openai/gpt-4.1`      | 1M tokens      | Stable, previous gen            |
| `openai/gpt-4.1-mini` | 1M tokens      | Budget variant of 4.1           |
| `openai/gpt-4.1-nano` | 1M tokens      | Fastest 4.1 variant             |
| `openai/o3`           | 200K tokens    | Most powerful reasoning         |
| `openai/o3-mini`      | 200K tokens    | Fast reasoning                  |
| `openai/o3-pro`       | 200K tokens    | Premium reasoning               |
| `openai/o4-mini`      | 200K tokens    | Latest cost-efficient reasoning |

### Anthropic

| Model string                  | Context window | Notes                           |
| ----------------------------- | -------------- | ------------------------------- |
| `anthropic/claude-opus-4-6`   | 1M tokens      | Most intelligent                |
| `anthropic/claude-sonnet-4-6` | 1M tokens      | Best speed/intelligence balance |
| `anthropic/claude-haiku-4-5`  | 200K tokens    | Fastest model                   |
| `anthropic/claude-opus-4-5`   | 200K tokens    | Previous gen, still active      |
| `anthropic/claude-sonnet-4-5` | 200K tokens    | Previous gen, still active      |
| `anthropic/claude-opus-4-1`   | 200K tokens    | Older gen, still active         |

### DeepSeek

| Model string                 | Context window | Notes                        |
| ---------------------------- | -------------- | ---------------------------- |
| `deepseek/deepseek-chat`     | 131K tokens    | DeepSeek-V3, general purpose |
| `deepseek/deepseek-reasoner` | 128K tokens    | DeepSeek-R1, reasoning       |

### Groq

| Model string                                     | Context window | Notes                        |
| ------------------------------------------------ | -------------- | ---------------------------- |
| `groq/llama-3.3-70b-versatile`                   | 131K tokens    | Production, tool use capable |
| `groq/meta-llama/llama-4-scout-17b-16e-instruct` | 131K tokens    | Latest Llama 4               |
| `groq/openai/gpt-oss-120b`                       | 131K tokens    | GPT-OSS on Groq LPU hardware |
| `groq/groq/compound`                             | 131K tokens    | Groq Compound agentic system |
| `groq/llama-3.1-8b-instant`                      | 131K tokens    | Fast, budget-friendly        |

### xAI (Grok)

| Model string           | Context window | Notes                      |
| ---------------------- | -------------- | -------------------------- |
| `xai/grok-4`           | 256K tokens    | Current flagship           |
| `xai/grok-4-fast`      | 2M tokens      | Fast variant               |
| `xai/grok-3`           | 131K tokens    | Previous gen, still active |
| `xai/grok-3-mini`      | 131K tokens    | Previous gen mini          |
| `xai/grok-3-mini-fast` | 131K tokens    | Previous gen fast          |

### Alibaba (Qwen)

| Model string              | Context window | Notes                      |
| ------------------------- | -------------- | -------------------------- |
| `alibaba/qwen3.6-plus`    | 1M tokens      | Latest flagship (Apr 2026) |
| `alibaba/qwen3-max`       | 262K tokens    | Flagship                   |
| `alibaba/qwen3-235b-a22b` | 131K tokens    | Large MoE model            |
| `alibaba/qwen3-32b`       | 131K tokens    | Mid-size, fast             |
| `alibaba/qwq-plus`        | 131K tokens    | Reasoning model            |

### ZhipuAI (GLM)

| Model string            | Context window | Notes               |
| ----------------------- | -------------- | ------------------- |
| `zhipuai/glm-5.1`       | 203K tokens    | Latest              |
| `zhipuai/glm-5`         | 80K tokens     | Flagship (Feb 2026) |
| `zhipuai/glm-5-turbo`   | 203K tokens    | Fast variant        |
| `zhipuai/glm-4.7`       | 203K tokens    | Previous gen        |
| `zhipuai/glm-4.7-flash` | 203K tokens    | Previous gen flash  |
| `zhipuai/glm-4.6`       | 205K tokens    | Previous gen        |
| `zhipuai/glm-4.5`       | 131K tokens    | Previous gen        |
| `zhipuai/glm-4.5-air`   | 131K tokens    | Previous gen lite   |

<Note>
  **Fallback routing.** If a model is not in Lua's approved list, the request is automatically routed through OpenRouter as a best-effort fallback. If that also isn't available, the request falls back to the default model (`google/gemini-2.5-flash`).
</Note>

***

## Static Model

The simplest form — one model for all requests:

```typescript theme={null}
export const agent = new LuaAgent({
  name: 'support-agent',
  persona: '...',
  model: 'openai/gpt-5.4',
  skills: [supportSkill]
});
```

**When to use:** When you want a specific model across all users and channels.

***

## Dynamic Model Resolver

Use a function to select the model per request. The resolver receives the full request with access to all platform APIs — `User`, `Baskets`, `Products`, `Data`, and more.

```typescript theme={null}
export const agent = new LuaAgent({
  name: 'smart-agent',
  persona: '...',
  model: async (request) => {
    const user = await User.get();
    return user.data?.isPremium ? 'openai/gpt-5.4' : 'google/gemini-2.5-flash';
  },
  skills: [mySkill]
});
```

The resolver must return a `'provider/model'` string synchronously or asynchronously.

***

## Common Patterns

### Premium vs free users

```typescript theme={null}
model: async (request) => {
  const user = await User.get();
  const tier = user.data?.subscriptionTier;

  if (tier === 'pro') return 'openai/gpt-5.4';          // flagship
  if (tier === 'standard') return 'openai/gpt-4.1';     // 1M context, balanced
  return 'google/gemini-2.5-flash';                      // default
}
```

### Channel-based selection

```typescript theme={null}
model: (request) => {
  // Use a faster/cheaper model for voice channels
  if (request.channel === 'voice') return 'google/gemini-2.5-flash-lite';
  // Use a more capable model for complex web requests
  return 'openai/gpt-5.4';
}
```

### Content-based routing

```typescript theme={null}
model: async (request) => {
  // Use a model with large context for document-heavy workflows
  const basketCount = await Baskets.getCount();
  if (basketCount > 50) return 'openai/gpt-4.1';  // 1M context
  return 'openai/gpt-5.4-mini';
}
```

### Environment-based

```typescript theme={null}
import { env } from 'lua-cli';

model: env('PREFERRED_MODEL') || 'google/gemini-2.5-flash'
```

***

## Default Model

If you don't set `model`, your agent uses `google/gemini-2.5-flash`. This is a fast, capable model with a 1M token context window — suitable for most use cases.

***

## Reasoning Effort

Most reasoning-capable models above — across Claude, GPT/o-series, Gemini, Groq, DeepSeek, xAI, and Qwen — support a tunable reasoning effort: how much the model "thinks" before responding. Set a default for your agent via `modelSettings.reasoning`:

```typescript theme={null}
export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  modelSettings: {
    reasoning: { effort: 'low' },
  },
  skills: [mySkill],
});
```

`effort` uses one normalized scale (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'`) across every provider — Lua translates it into that model's native dialect (Claude's `thinking` budget/adaptive modes, OpenAI's `reasoningEffort`, Gemini's `thinkingConfig`, etc.), clamping to the nearest supported tier rather than erroring. A few models have narrower ranges: GPT's top-tier reasoning variant floors at medium, DeepSeek's reasoning model has no tier below high, and Qwen's reasoning is on/off only. A non-reasoning model ignores the setting entirely.

**Leaving `effort` unset** doesn't mean "no reasoning" — Lua's platform default is **adaptive reasoning where the model supports it** (Claude's newest generations, Gemini 2.5's dynamic thinking budget) and an **explicit low effort otherwise**, biasing toward lower cost and latency on turns that don't ask for deeper thinking.

See [LuaAgent → modelSettings](/api/luaagent) for the full field reference, including how this interacts with a per-request override.

***

## Related

<CardGroup>
  <Card title="LuaAgent API" href="/api/luaagent" icon="code">
    Full constructor reference including the model param
  </Card>

  <Card title="Platform APIs" href="/concepts/platform-apis" icon="plug">
    APIs available inside a model resolver function
  </Card>
</CardGroup>


# Persona
Source: https://docs.heylua.ai/overview/persona

Define your agent's personality and behavior

## What is a Persona?

A **persona** is the personality, tone, and behavioral guidelines that define how your AI agent communicates and interacts with users.

<Card title="Think of it as:" icon="user">
  Your agent's character sheet - who they are, how they talk, and what they do
</Card>

<Note>
  Personas are now configured through the `LuaAgent` class along with skills, webhooks, jobs, and processors. See [Agent Concept](/overview/agent) for the complete pattern.
</Note>

## Why Personas Matter

<CardGroup>
  <Card title="Consistency" icon="check">
    Same personality across all conversations
  </Card>

  <Card title="Brand Alignment" icon="palette">
    Matches your company's voice and values
  </Card>

  <Card title="User Experience" icon="heart">
    Creates connection and trust
  </Card>

  <Card title="Effectiveness" icon="bullseye">
    Guidelines ensure helpful responses
  </Card>
</CardGroup>

## Persona Structure

A good persona includes:

<Steps>
  <Step title="Role & Mission">
    Who the agent is and their primary purpose

    ```
    You are a customer service representative for AcmeCorp,
    specializing in electronics support.
    ```
  </Step>

  <Step title="Responsibilities">
    What the agent helps with

    ```
    Your responsibilities:
    - Answer product questions
    - Check order status
    - Process returns
    - Provide technical guidance
    ```
  </Step>

  <Step title="Personality Traits">
    How the agent behaves

    ```
    Your personality:
    - Friendly and approachable
    - Professional and knowledgeable
    - Patient with frustrated customers
    - Solution-oriented
    ```
  </Step>

  <Step title="Guidelines">
    Rules the agent follows

    ```
    Always:
    - Greet warmly
    - Ask clarifying questions
    - Confirm understanding

    Never:
    - Make promises you can't keep
    - Blame customers
    - Rush conversations
    ```
  </Step>

  <Step title="Context">
    Background information

    ```
    Context:
    AcmeCorp serves 50,000+ customers.
    2-day shipping standard.
    30-day return policy.
    ```
  </Step>
</Steps>

## Good vs Bad Examples

<Tabs>
  <Tab title="❌ Bad Persona">
    ```
    You help customers.
    Be nice.
    ```

    **Problems:**

    * Too vague
    * No specific guidance
    * No personality
    * No context
  </Tab>

  <Tab title="✅ Good Persona">
    ```
    You are a customer service representative for AcmeCorp,
    specializing in electronics and home goods support.

    Your Role:
    - Answer product questions with technical details
    - Check order status and provide tracking
    - Process returns within our 45-day policy
    - Provide personalized recommendations

    Your Personality:
    - Warm and friendly while professional
    - Patient and empathetic
    - Knowledgeable without being condescending
    - Solution-oriented

    Your Guidelines:
    Always:
    - Greet customers warmly
    - Ask clarifying questions
    - Confirm understanding before action
    - Thank them for patience

    Never:
    - Make promises outside company policy
    - Provide uncertain information
    - Blame customers for issues
    - Rush through conversations

    When customer is frustrated:
    1. Acknowledge their feelings
    2. Apologize genuinely
    3. Focus on solution
    4. Offer escalation if needed

    Context:
    AcmeCorp is an online retailer since 2010.
    10,000+ products.
    Free shipping over $50.
    45-day return policy.
    Business hours: 9 AM - 6 PM EST.
    ```

    **Why it's good:**

    * Specific role defined
    * Clear personality
    * Actionable guidelines
    * Relevant context
  </Tab>
</Tabs>

## How to Write a Great Persona

### 1. Define the Role Clearly

```
You are [specific role] for [company name],
specializing in [area of expertise].
```

### 2. List Specific Responsibilities

```
You help with:
- [Specific task 1]
- [Specific task 2]
- [Specific task 3]

You do NOT:
- [What's outside scope]
- [What needs escalation]
```

### 3. Describe Personality

```
Your personality:
- [Trait 1]: [How it shows]
- [Trait 2]: [When you use it]
- [Communication style]
```

### 4. Provide Clear Guidelines

```
Always:
- [Action 1]
- [Action 2]

Never:
- [Avoid 1]
- [Avoid 2]

When [situation]:
- [Specific response]
```

### 5. Add Business Context

```
Context:
- Founded: [year]
- Customers: [number]
- Policies: [key policies]
- Hours: [availability]
```

## Managing Your Persona

<CardGroup>
  <Card title="Edit" icon="pen" href="/cli/persona-command">
    ```bash theme={null}
    lua persona
    ```

    Edit and test persona
  </Card>

  <Card title="Test" icon="comments" href="/cli/chat-command">
    ```bash theme={null}
    lua chat
    ```

    Test persona in sandbox
  </Card>

  <Card title="Deploy" icon="rocket" href="/cli/persona-command">
    Create versions and deploy to production
  </Card>

  <Card title="Monitor" icon="eye" href="/cli/production-command">
    ```bash theme={null}
    lua production
    ```

    View deployed persona
  </Card>
</CardGroup>

## Advanced: Channel-Aware Personas

For most agents, a single persona works great. But if you need different behavior on voice vs text channels (e.g., conversational tone on voice, structured formatting on text), see [Channel-aware Prompts](/concepts/channel-aware-prompts).

## Next Steps

<Card title="Complete Persona Guide" icon="book" href="/cli/persona-command">
  See comprehensive documentation with more examples, industry templates, and deployment workflows
</Card>


# PostProcessors
Source: https://docs.heylua.ai/overview/postprocessors

Transform and enhance AI responses before sending to users

## What are PostProcessors?

**PostProcessors** modify or enhance AI-generated responses before they're sent to users. They allow you to add disclaimers, apply formatting, inject dynamic content, or transform the output in any way.

<Card title="Think of it as:" icon="paper-plane">
  A final editor - reviews and enhances responses before they go to users
</Card>

<Note>
  Response postprocessing for consistent formatting, branding, and enhancement.
</Note>

## Why PostProcessors?

<CardGroup>
  <Card title="Consistency" icon="check-double">
    Apply consistent formatting and style to all responses
  </Card>

  <Card title="Branding" icon="palette">
    Add company branding, signatures, or footers automatically
  </Card>

  <Card title="Legal Protection" icon="gavel">
    Add disclaimers to medical, financial, or legal advice
  </Card>

  <Card title="Personalization" icon="user">
    Inject user-specific information or context
  </Card>
</CardGroup>

## How PostProcessors Work

<Steps>
  <Step title="AI Generates Response">
    Your agent creates a response using its tools and knowledge
  </Step>

  <Step title="PostProcessors Run">
    Each postprocessor modifies the response in priority order
  </Step>

  <Step title="Transformation">
    PostProcessors can:

    * Add content (disclaimers, footers)
    * Format text (markdown, styling)
    * Replace placeholders
    * Translate or enhance
  </Step>

  <Step title="Final Response">
    Modified response is sent to the user
  </Step>
</Steps>

## Simple Example

```typescript theme={null}
import { PostProcessor, UserDataInstance } from 'lua-cli';

const addDisclaimer = new PostProcessor({
  name: 'add-disclaimer',
  description: 'Add legal disclaimer to responses',
  
  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
    return {
      modifiedResponse: response + 
        "\n\n_Disclaimer: This is AI-generated content for informational purposes only._"
    };
  }
});
```

<Note>
  **Tip:** You can also access the channel via `Lua.request.channel`, the user via `User.get()`, and raw webhook data via `Lua.request.webhook?.payload`. See the [Lua API](/api/lua) for details.
</Note>

## Common Use Cases

<Tabs>
  <Tab title="Disclaimers">
    **Add legal or informational disclaimers**

    ```typescript theme={null}
    execute: async (user, message, response, channel) => {
      if (containsMedicalAdvice(response)) {
        return {
          modifiedResponse: response + 
            "\n\n⚠️ **Medical Disclaimer:** Please consult a healthcare professional."
        };
      }
      return { modifiedResponse: response };
    }
    ```
  </Tab>

  <Tab title="Branding">
    **Add company branding and signatures**

    ```typescript theme={null}
    execute: async (user, message, response, channel) => {
      const footer = "\n\n---\n" +
        "_Powered by Acme Corp_\n" +
        "Need help? support@acme.com";
      
      return {
        modifiedResponse: response + footer
      };
    }
    ```
  </Tab>

  <Tab title="Formatting">
    **Apply consistent text formatting**

    ```typescript theme={null}
    execute: async (user, message, response, channel) => {
      // Capitalize sentences
      let formatted = capitalizeFirst(response);
      
      // Add spacing
      formatted = addProperSpacing(formatted);
      
      // Highlight important terms
      formatted = highlightKeywords(formatted);
      
      return { modifiedResponse: formatted };
    }
    ```
  </Tab>

  <Tab title="Personalization">
    **Add user-specific context**

    ```typescript theme={null}
    execute: async (user, message, response, channel) => {
      const greeting = `Hi ${user.name}! `;
      const userData = await user.data;
      
      if (userData.vipStatus) {
        return {
          modifiedResponse: greeting + response + 
            "\n\n✨ VIP members get priority support!"
        };
      }
      
      return {
        modifiedResponse: greeting + response
      };
    }
    ```
  </Tab>
</Tabs>

## Execution Order

PostProcessors run in the order they are defined in the `postProcessors` array of your `LuaAgent` configuration. Each postprocessor receives the output of the previous one in the chain.

```
AI Agent Response
    ↓
PostProcessor 1 → Runs first
    ↓
PostProcessor 2 → Runs second
    ↓
PostProcessor 3 → Runs last
    ↓
Final Response to User
```

## Channel Compatibility

PostProcessors are now supported on **all channels**, including streaming endpoints.

| Channel                | PostProcessors Supported | Notes                                 |
| ---------------------- | ------------------------ | ------------------------------------- |
| Email                  | Yes                      | Uses generate (non-streaming)         |
| HTTP API (`/generate`) | Yes                      | Non-streaming endpoint                |
| HTTP API (`/stream`)   | Yes                      | Post-processes after stream completes |
| WhatsApp               | Yes                      | Post-processes after stream completes |
| LuaPop (Web Widget)    | Yes                      | Post-processes after stream completes |
| Slack                  | Yes                      | Post-processes after stream completes |
| Facebook Messenger     | Yes                      | Post-processes after stream completes |
| Instagram              | Yes                      | Post-processes after stream completes |

### Streaming Behavior

For streaming channels, post-processing works as follows:

1. **Real-time streaming**: Users see the response as it's generated (original, unprocessed text)
2. **Post-processing**: After the stream completes, post-processors run on the full response
3. **Final event**: A `postprocess-complete` event is emitted with the modified response
4. **Storage**: The post-processed response is saved to the conversation history

<Note>
  **UX Consideration:** With streaming, users briefly see the original response before post-processing completes. For use cases requiring immediate post-processed content (e.g., strict compliance), consider using the non-streaming `/generate` endpoint instead.
</Note>

### Handling the `postprocess-complete` Event

If you're building a custom client, you can listen for the `postprocess-complete` event to update the displayed response:

```typescript theme={null}
// Example: Handling postprocess-complete in a streaming client
stream.on('chunk', (chunk) => {
  if (chunk.type === 'text-delta') {
    appendToDisplay(chunk.textDelta);
  } else if (chunk.type === 'postprocess-complete') {
    // Replace displayed content with post-processed version
    replaceDisplay(chunk.modifiedResponse);
  }
});
```

## Adding to Your Agent

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import addDisclaimer from './postprocessors/disclaimer';
import addBranding from './postprocessors/branding';

export const agent = new LuaAgent({
  name: "my-agent",
  persona: "...",
  skills: [...],
  
  // Add postprocessors
  postProcessors: [
    addDisclaimer,  // Runs first
    addBranding     // Runs second
  ]
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Preserve Original Meaning">
    Don't alter the core message

    ```typescript theme={null}
    // ✅ Add to response
    modifiedResponse: response + "\n\nAdditional info..."

    // ❌ Don't completely replace
    modifiedResponse: "Something different"
    ```
  </Accordion>

  <Accordion title="✅ Chain Thoughtfully">
    Order matters - structure flows logically

    ```typescript theme={null}
    priority: 1   // Translation (first)
    priority: 10  // Formatting
    priority: 50  // Content injection
    priority: 100 // Disclaimer (last)
    ```
  </Accordion>

  <Accordion title="✅ Handle Errors Gracefully">
    Fall back to original response on errors

    ```typescript theme={null}
    execute: async (user, message, response, channel) => {
      try {
        return { modifiedResponse: process(response) };
      } catch (error) {
        return { modifiedResponse: response };
      }
    }
    ```
  </Accordion>

  <Accordion title="✅ Keep It Fast">
    PostProcessors should be quick (\< 50ms)

    Avoid heavy computations or external API calls
  </Accordion>
</AccordionGroup>

## Testing PostProcessors

```bash theme={null}
lua test
# Select: PostProcessor → add-disclaimer
# Provide test response
# See transformed output
```

## Next Steps

<CardGroup>
  <Card title="PostProcessor API" icon="book" href="/api/postprocessor">
    Complete API documentation
  </Card>

  <Card title="PreProcessor Concept" icon="filter" href="/overview/preprocessors">
    Learn about message filtering
  </Card>

  <Card title="Agent Concept" icon="robot" href="/overview/agent">
    Learn about LuaAgent
  </Card>

  <Card title="Workflows Guide" icon="diagram-project" href="/concepts/workflows">
    Development best practices
  </Card>
</CardGroup>


# PreProcessors
Source: https://docs.heylua.ai/overview/preprocessors

Filter and validate messages before they reach your agent

## What are PreProcessors?

**PreProcessors** intercept user messages before they reach your AI agent. They act as a middleware layer, allowing you to filter spam, validate inputs, route messages, or modify content before the agent processes it.

<Card title="Think of it as:" icon="filter">
  A security checkpoint and enrichment station - messages pass through preprocessors before reaching your agent's brain.
</Card>

<Note>
  Message preprocessing for content filtering, routing, and validation.
</Note>

## Why PreProcessors?

PreProcessors handle "meta" tasks that shouldn't consume your agent's context window or reasoning capabilities.

<CardGroup>
  <Card title="Content Filtering" icon="shield">
    Block spam, profanity, or inappropriate content before it costs you tokens.
  </Card>

  <Card title="Input Validation" icon="check-circle">
    Ensure messages meet requirements (e.g., "must include an email") before the agent sees them.
  </Card>

  <Card title="Context Injection" icon="syringe">
    Fetch data from a CRM or database and append it to the user's message.
  </Card>

  <Card title="Rate Limiting" icon="gauge">
    Prevent abuse by limiting message frequency per user.
  </Card>
</CardGroup>

## PreProcessors vs Skills

| Feature      | PreProcessor                           | Skill                                      |
| :----------- | :------------------------------------- | :----------------------------------------- |
| **Timing**   | Runs **before** the agent thinks       | Runs **when** the agent decides to call it |
| **Decision** | Deterministic (code-based)             | Probabilistic (LLM-based)                  |
| **Use Case** | Security, formatting, required context | Actions, data retrieval, business logic    |
| **Access**   | Can block the agent completely         | Cannot block, returns data to agent        |

## How PreProcessors Work

<Steps>
  <Step title="User Sends Message">
    User types a message (e.g., "Check my order status") via WhatsApp, Web, or API.
  </Step>

  <Step title="Pipeline Execution">
    The system runs your active PreProcessors in order of **priority** (lowest first).
  </Step>

  <Step title="Transformation & Decision">
    Each preprocessor receives the output of the previous one. It can:

    * ✅ **Proceed**: Pass the (potentially modified) message to the next step.
    * ❌ **Block**: Stop the pipeline and return a response immediately.
  </Step>

  <Step title="Agent Handover">
    If no preprocessor blocks, the final message reaches the AI agent.
  </Step>
</Steps>

## Simple Example

Here is a simple profanity filter that runs early in the pipeline.

```typescript theme={null}
import { PreProcessor } from 'lua-cli';

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Block inappropriate content',
  priority: 10, // Run early (low number)
  
  execute: async (user, messages, channel) => {
    const text = messages
      .filter(m => m.type === 'text')
      .map(m => m.text.toLowerCase())
      .join(' ');
    
    if (text.includes('badword')) {
      // Block the message
      return {
        action: 'block',
        response: "Please keep the conversation respectful."
      };
    }
    
    // Allow message through
    return { action: 'proceed' };
  }
});
```

<Note>
  **Tip:** You can also access the channel via `Lua.request.channel`, the user via `User.get()`, and raw webhook data via `Lua.request.webhook?.payload`. See the [Lua API](/api/lua) for details.
</Note>

## Advanced Patterns

### Context Injection (RAG Lite)

You can use a preprocessor to fetch user data and "inject" it into the message, giving the agent context without it needing to ask tools.

```typescript theme={null}
execute: async (user, messages, channel) => {
  // Fetch recent order from your DB
  const recentOrder = await fetchRecentOrder(user.email);
  
  if (recentOrder) {
    // Append order info to the message
    const enrichedMessages = messages.map(msg => {
      if (msg.type === 'text') {
        return {
          ...msg,
          text: `${msg.text}\n\n[System Context: Last Order #${recentOrder.id} is ${recentOrder.status}]`
        };
      }
      return msg;
    });
    
    return { 
      action: 'proceed', 
      modifiedMessage: enrichedMessages 
    };
  }
  
  return { action: 'proceed' };
}
```

### Channel-Specific Logic

You can apply different rules based on where the user is chatting from.

```typescript theme={null}
execute: async (user, messages, channel) => {
  if (channel === 'whatsapp' && messages.some(m => m.type === 'file')) {
    return {
      action: 'block',
      response: "Sorry, we don't accept file uploads on WhatsApp yet."
    };
  }
  return { action: 'proceed' };
}
```

## Execution Pipeline

PreProcessors run in a **pipeline**. The output of one preprocessor becomes the input of the next.

1. **Priority 10**: `RateLimiter` checks if user is spamming.
2. **Priority 20**: `ProfanityFilter` checks for bad words.
3. **Priority 50**: `ContextInjector` adds user account info.
4. **Agent**: Receives a clean, verified, and context-rich message.

## Adding to Your Agent

Add preprocessors to your `LuaAgent` configuration.

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import profanityFilter from './preprocessors/profanity-filter';
import rateLimiter from './preprocessors/rate-limiter';

export const agent = new LuaAgent({
  name: "my-agent",
  persona: "...",
  skills: [...],
  
  // Add preprocessors here
  preProcessors: [
    rateLimiter,      // Will run first (assuming priority 5)
    profanityFilter   // Will run second (assuming priority 10)
  ]
});
```

## Testing PreProcessors

You can test preprocessors in isolation using the Lua CLI.

```bash theme={null}
lua test
# Select: PreProcessor → profanity-filter
# Provide test message
# See if it's blocked or allowed
```

## Next Steps

<CardGroup>
  <Card title="PreProcessor API" icon="book" href="/api/preprocessor">
    Complete API documentation
  </Card>

  <Card title="PostProcessor Concept" icon="paper-plane" href="/overview/postprocessors">
    Learn about response formatting
  </Card>

  <Card title="Agent Concept" icon="robot" href="/overview/agent">
    Learn about LuaAgent
  </Card>

  <Card title="Workflows Guide" icon="diagram-project" href="/concepts/workflows">
    Development best practices
  </Card>
</CardGroup>


# Resources
Source: https://docs.heylua.ai/overview/resources

Your agent's knowledge base and reference materials

## What are Resources?

**Resources** are documents that your AI agent can access and reference during conversations - like a knowledge library.

<Card title="Think of it as:" icon="book">
  Reference materials your agent can look up - product catalogs, policies, FAQs, guides
</Card>

## Why Resources Matter

<CardGroup>
  <Card title="Accurate Information" icon="check">
    Agent provides facts, not guesses
  </Card>

  <Card title="Consistent Answers" icon="arrows-repeat">
    Same info every time
  </Card>

  <Card title="Easy Updates" icon="pen">
    Update knowledge without changing code
  </Card>

  <Card title="Scalable Knowledge" icon="chart-line">
    Add unlimited reference materials
  </Card>
</CardGroup>

## What to Put in Resources

### Product Information

```
Resource: Product Catalog 2024

Our complete product line:

Laptops:
- UltraBook Pro: $1299
  • 16GB RAM, 512GB SSD
  • Best for professionals
  • 2-year warranty

- Student Laptop: $599
  • 8GB RAM, 256GB SSD
  • Perfect for students
  • 1-year warranty
```

### Company Policies

```
Resource: Return Policy

Returns accepted within 45 days.

Conditions:
- Unused, original packaging
- Receipt required
- Free return shipping on defects

Process:
1. Contact support
2. Get return authorization
3. Ship within 7 days
4. Refund in 3-5 days
```

### FAQs

```
Resource: Shipping FAQ

Q: How long does shipping take?
A: Standard 3-5 days, Express 1-2 days

Q: Do you ship internationally?
A: US and Canada only

Q: Can I track my order?
A: Yes, tracking link sent via email
```

### Troubleshooting Guides

```
Resource: Login Issues

Can't log in?
1. Verify email is correct
2. Check caps lock
3. Try "Forgot Password"
4. Clear browser cache
5. Try different browser
6. Contact support: support@company.com
```

## How Agents Use Resources

**Automatically during conversations:**

```
User: "What's your return policy?"

Agent: [Searches resources]
       [Finds "Return Policy"]
       [Reads content]
       
Response: "We accept returns within 45 days.
The item must be unused in original packaging..."
```

**The agent decides when to search resources based on:**

* Question keywords
* Context of conversation
* Relevance to query
* Semantic similarity

## Creating Resources

<Steps>
  <Step title="Open Resources Command">
    ```bash theme={null}
    lua resources
    ```
  </Step>

  <Step title="Create New Resource">
    ```
    ? What would you like to do? ➕ Create new resource
    ? Resource name: Product Catalog
    ```
  </Step>

  <Step title="Write Content">
    Opens your editor. Write your content:

    ```
    Our products for 2024...

    [Save and close]
    ```
  </Step>

  <Step title="Test with Agent">
    ```bash theme={null}
    lua chat
    ```

    Ask agent about products, verify it uses the resource
  </Step>
</Steps>

## Resource Best Practices

### 1. Keep Resources Focused

<CodeGroup>
  ```text Bad: Everything in one theme={null}
  Resource: Everything About Company
  - Products
  - Policies  
  - FAQ
  - History
  - Contact
  [10,000 characters of mixed info]
  ```

  ```text Good: Separate resources theme={null}
  Resource: Product Catalog
  [Products only]

  Resource: Return Policy
  [Return info only]

  Resource: Company FAQ
  [Common questions only]

  Resource: Contact Information
  [Contact details only]
  ```
</CodeGroup>

### 2. Use Clear Structure

```
Resource: Electronics Catalog

## Laptops

### UltraBook Pro - $1299
- Specs: 16GB RAM, 512GB SSD
- Best for: Professionals, creators
- Warranty: 2 years

### Student Laptop - $599
- Specs: 8GB RAM, 256GB SSD
- Best for: Students, basic use
- Warranty: 1 year

## Tablets

### Pro Tablet - $899
...
```

### 3. Include Timestamps

```
Resource: Pricing Information
Last Updated: January 15, 2024
Valid Through: March 31, 2024

[This helps track when info needs updating]
```

### 4. Update Regularly

<AccordionGroup>
  <Accordion title="Weekly">
    * Time-sensitive promotions
    * Seasonal information
    * Limited-time offers
  </Accordion>

  <Accordion title="Monthly">
    * Product availability
    * Pricing updates
    * Policy changes
  </Accordion>

  <Accordion title="Quarterly">
    * Complete review
    * Archive old resources
    * Reorganize if needed
  </Accordion>
</AccordionGroup>

## Resources + Persona

Resources work best when referenced in your persona:

```typescript theme={null}
// In lua persona
persona: `
  You are a customer service agent for AcmeCorp.
  
  When answering questions, check your resources:
  - Product questions → Product Catalog
  - Return questions → Return Policy  
  - Shipping questions → Shipping Information
  
  Always provide accurate info from resources.
`
```

## Common Use Cases

<Tabs>
  <Tab title="E-commerce">
    **Resources:**

    * Product Catalog
    * Size Guide
    * Return Policy
    * Shipping Options
    * Gift Services

    **Agent can answer:**

    * "Do you have this in size medium?"
    * "What's your return policy?"
    * "How long does shipping take?"
  </Tab>

  <Tab title="Support">
    **Resources:**

    * Troubleshooting Guides
    * FAQ Database
    * Known Issues
    * Contact Information
    * Service Hours

    **Agent can answer:**

    * "How do I reset my password?"
    * "App won't open, what do I do?"
    * "How do I contact support?"
  </Tab>

  <Tab title="Booking">
    **Resources:**

    * Room Types
    * Amenities List
    * Cancellation Policy
    * Local Attractions
    * Check-in Process

    **Agent can answer:**

    * "What room types do you have?"
    * "Can I cancel my reservation?"
    * "What's nearby?"
  </Tab>
</Tabs>

## Managing Resources

<CardGroup>
  <Card title="Create" icon="plus">
    ```bash theme={null}
    lua resources
    ```

    Add new knowledge documents
  </Card>

  <Card title="Update" icon="pen">
    Keep information current
  </Card>

  <Card title="Test" icon="comments">
    ```bash theme={null}
    lua chat
    ```

    Verify agent uses resources
  </Card>

  <Card title="Monitor" icon="eye">
    Track what users ask about
  </Card>
</CardGroup>

## Quick Tips

<AccordionGroup>
  <Accordion title="Start Small">
    Begin with 3-5 core resources:

    * Company overview
    * Main products/services
    * Top FAQ
    * Contact information
    * Key policy

    Add more as needed
  </Accordion>

  <Accordion title="Use Clear Names">
    ```
    ✅ Product Catalog 2024
    ✅ Return Policy - Updated Jan 2024
    ✅ FAQ - Shipping Questions

    ❌ Doc1
    ❌ Stuff
    ❌ Notes
    ```
  </Accordion>

  <Accordion title="Test After Adding">
    ```bash theme={null}
    # Add resource
    $ lua resources → Create

    # Test immediately
    $ lua chat
    💬: "Ask about the new resource topic"
    🤖: [Should reference the resource]
    ```
  </Accordion>
</AccordionGroup>

## Resources vs Tools vs Skills

| Concept      | Purpose        | Example                               |
| ------------ | -------------- | ------------------------------------- |
| **Tool**     | Execute action | `search_products` - Searches catalog  |
| **Skill**    | Group of tools | E-commerce - Search, cart, checkout   |
| **Resource** | Reference info | Product Catalog - What products exist |

**How they work together:**

* **Resources** provide knowledge
* **Tools** take actions
* **Skills** organize tools
* **Persona** defines personality

**Example:**

```
User: "Do you have laptops under $1000?"

1. Persona: "Be friendly and helpful"
2. Resource: Agent checks Product Catalog
3. Tool: Calls search_products tool
4. Skill: E-commerce skill coordinates everything
5. Result: "Yes! We have 3 laptops under $1000..."
```

## Next Steps

<CardGroup>
  <Card title="Manage Resources" icon="database" href="/cli/resources-command">
    Complete guide to resources command
  </Card>

  <Card title="Learn About Persona" icon="user" href="/overview/persona">
    How persona uses resources
  </Card>

  <Card title="Learn About Skills" icon="puzzle-piece" href="/overview/skill">
    How skills organize tools
  </Card>

  <Card title="See Complete Examples" icon="layer-group" href="/demos/overview">
    11 demos using resources
  </Card>
</CardGroup>


# Skill
Source: https://docs.heylua.ai/overview/skill

Collections of tools that give your agent capabilities

## What is a Skill?

A **skill** is a collection of related tools bundled together. It defines what capabilities your agent has and how to use them.

<Card title="Think of it as:" icon="puzzle-piece">
  A capability module - like "Customer Service" or "Order Management" - that groups related tools together
</Card>

<Note>
  Skills are now added to your agent through the `LuaAgent` class. See [Agent Concept](/overview/agent) for the complete configuration pattern.
</Note>

## Anatomy of a Skill

```typescript theme={null}
const customerServiceSkill = new LuaSkill({
  name: "customer-service",
  description: "Customer support and order management",
  context: `...`,  // ← Critical! Tells agent how to use tools
  tools: [
    new SearchOrdersTool(),
    new CreateTicketTool(),
    new CheckStatusTool()
  ]
});
```

<CardGroup>
  <Card title="Name" icon="tag">
    Unique identifier for the skill
  </Card>

  <Card title="Version" icon="code-branch">
    Semantic version tracking
  </Card>

  <Card title="Description" icon="file-text">
    Brief summary of capability
  </Card>

  <Card title="Context" icon="brain">
    **Most Important**: How/when to use tools
  </Card>

  <Card title="Tools" icon="wrench">
    Array of tool instances
  </Card>

  <Card title="Condition" icon="lock">
    Optional gate that hides the whole skill from the agent
  </Card>
</CardGroup>

## The Context Field: Most Important Part

The **context** field tells the AI agent **how and when** to use the tools in your skill.

<Warning>
  **The context field is critical!** Without good context, the AI won't know when to use your tools or how to use them correctly.
</Warning>

### What Good Context Looks Like

<Tabs>
  <Tab title="❌ Bad Context">
    ```typescript theme={null}
    context: "A skill with tools for stuff"
    ```

    **Problems:**

    * Too vague
    * No tool guidance
    * No usage instructions
    * Agent won't know what to do
  </Tab>

  <Tab title="✅ Good Context">
    ```typescript theme={null}
    context: `
      This skill manages customer orders and support tickets.
      
      Tool Usage:
      - search_orders: Use when customers ask about order status,
        tracking, or "where is my order". Requires order number or email.
      
      - create_ticket: Use when customer has an unresolved issue
        that needs human follow-up. Ask for issue details first.
      
      - check_status: Use to get current status of existing ticket.
        Requires ticket ID from previous create_ticket call.
      
      Guidelines:
      - Always ask for order number before searching
      - Confirm issue details before creating ticket
      - Provide ticket ID after creation
      - Set expectations for response time (24 hours)
      
      Do NOT create tickets for:
      - Simple questions answered by FAQ
      - Order status checks (use search_orders instead)
      - Product questions (use product-skill instead)
    `
    ```

    **Why it's good:**

    * Explains when to use each tool
    * Provides usage guidelines
    * Sets expectations
    * Defines boundaries
  </Tab>
</Tabs>

## Context Field Structure

```typescript theme={null}
context: `
  [1. What this skill does - one sentence]
  
  Tool Usage:
  - tool_name_1: [When to use] [What it needs] [What it returns]
  - tool_name_2: [When to use] [What it needs] [What it returns]
  
  Guidelines:
  - [Important rule 1]
  - [Important rule 2]
  - [Edge case handling]
  
  [Optional] Do NOT:
  - [Boundary 1]
  - [Boundary 2]
  
  [Optional] When [situation]:
  - [Specific action]
`
```

## Good Skill Examples

### Example 1: E-commerce Skill

```typescript theme={null}
const ecommerceSkill = new LuaSkill({
  name: "ecommerce-assistant",
  description: "Shopping and checkout assistance",
  context: `
    This skill helps customers shop and complete purchases.
    
    Tool Usage:
    - search_products: When users describe what they want to buy.
      Returns matching products with prices and availability.
    
    - add_to_cart: When customer decides to purchase something.
      Confirm product and quantity before adding.
    
    - checkout: When customer is ready to complete purchase.
      Must have items in cart. Ask for shipping address.
    
    Guidelines:
    - Always confirm product details before adding to cart
    - Show total price before checkout
    - Mention free shipping over $50
    - Ask about gift wrapping for orders > $100
    
    Do NOT:
    - Add items without confirmation
    - Checkout without shipping address
    - Promise delivery dates you can't guarantee
  `,
  tools: [
    new SearchProductsTool(),
    new AddToCartTool(),
    new CheckoutTool()
  ]
});
```

### Example 2: Support Skill

```typescript theme={null}
const supportSkill = new LuaSkill({
  name: "customer-support",
  description: "Help desk and troubleshooting",
  context: `
    This skill provides technical support and issue resolution.
    
    Tool Usage:
    - search_kb: ALWAYS check knowledge base FIRST before asking
      user for details. Search for relevant articles.
    
    - create_ticket: Create support ticket ONLY if knowledge base
      doesn't solve the issue. Ask for full problem description.
    
    - get_ticket_status: Check status of existing ticket.
      Requires ticket ID from previous conversation.
    
    Workflow:
    1. User describes issue
    2. Search knowledge base (search_kb)
    3. If found: Provide solution from KB
    4. If not found: Create ticket (create_ticket)
    5. Provide ticket ID and set expectations
    
    Guidelines:
    - Search KB before bothering user with questions
    - Ask diagnostic questions if KB search unclear
    - Always provide ticket ID after creation
    - Mention 24-hour response time for tickets
    - Be empathetic with frustrated users
  `,
  tools: [
    new SearchKnowledgeBaseTool(),
    new CreateTicketTool(),
    new GetTicketStatusTool()
  ]
});
```

### Example 3: Booking Skill

```typescript theme={null}
const bookingSkill = new LuaSkill({
  name: "hotel-booking",
  description: "Hotel reservations and room service",
  context: `
    This skill manages hotel bookings and guest services.
    
    Tool Usage:
    - check_availability: Search for available rooms.
      Needs: check-in date, check-out date, number of guests.
      Always ask for these before searching.
    
    - create_reservation: Book a room after confirming availability.
      Needs: guest name, email, phone, room selection.
      Confirm all details before booking.
    
    - get_reservation: Look up existing reservation.
      Needs: confirmation code OR email.
      Useful for modifications or cancellations.
    
    - cancel_reservation: Cancel existing booking.
      Confirm cancellation policy first (24-hour notice).
    
    - order_room_service: In-room dining or amenities.
      Needs: confirmation code to link to room.
    
    Guidelines:
    - Always ask for check-in/out dates and guest count first
    - Confirm reservation details before creating
    - Provide confirmation code after booking
    - Mention cancellation policy (24-hour notice)
    - Ask about special requests (early check-in, late checkout)
    - Suggest room upgrades when available
    
    Room Types:
    - Standard: $150/night (2 guests)
    - Deluxe: $200/night (2 guests, city view)
    - Suite: $350/night (4 guests, separate living area)
  `,
  tools: [
    new CheckAvailabilityTool(),
    new CreateReservationTool(),
    new GetReservationTool(),
    new CancelReservationTool(),
    new RoomServiceTool()
  ]
});
```

## Key Principles

### 1. One Skill = One Purpose

<CodeGroup>
  ```typescript Good: Focused theme={null}
  const orderSkill = new LuaSkill({
    name: "order-management",
    description: "Order processing and tracking",
    tools: [
      new CreateOrderTool(),
      new TrackOrderTool(),
      new CancelOrderTool()
    ]
  });
  ```

  ```typescript Bad: Unfocused theme={null}
  const everythingSkill = new LuaSkill({
    name: "all-features",
    description: "Does everything",
    tools: [
      new OrderTool(),
      new WeatherTool(),
      new EmailTool(),
      new RandomTool()
      // Unrelated tools mixed together
    ]
  });
  ```
</CodeGroup>

### 2. Context is Your Guide

The context field is where you teach the AI how to be effective:

```typescript theme={null}
// ✅ Good context teaches the agent
context: `
  Tool Usage:
  - search_orders: When user says "where is my order",
    "track my package", or "order status". 
    Ask for order number if not provided.
  
  When NOT to use:
  - Don't search_orders for product questions
  - Don't search_orders without order number
`

// ❌ Bad context doesn't teach
context: "Use the tools when needed"
```

### 3. Include Tool Descriptions

Explain **when** and **how** to use each tool:

```typescript theme={null}
context: `
  - search_products: Use when users describe what they want to buy
    (e.g., "looking for laptop", "need running shoes").
    Returns: List of matching products.
    
  - get_product_details: Use when user wants more info about
    a specific product (e.g., "tell me more about item #123").
    Returns: Full specs, reviews, availability.
`
```

## Managing Skills

<CardGroup>
  <Card title="Build" icon="code">
    Write skills in `src/index.ts`
  </Card>

  <Card title="Test" icon="flask">
    ```bash theme={null}
    lua test
    ```

    Test individual tools
  </Card>

  <Card title="Deploy" icon="upload">
    ```bash theme={null}
    lua push
    lua deploy
    ```

    Push to production
  </Card>

  <Card title="Monitor" icon="chart-line">
    ```bash theme={null}
    lua production
    ```

    View deployed versions
  </Card>
</CardGroup>

## Multi-Skill Projects

You can have multiple skills in one project:

```typescript theme={null}
// Skill 1: Product browsing
const catalogSkill = new LuaSkill({
  name: "product-catalog",
  description: "Product search and details",
  tools: [new SearchTool(), new DetailsTool()]
});

// Skill 2: Shopping cart
const cartSkill = new LuaSkill({
  name: "shopping-cart",
  description: "Cart and checkout",
  tools: [new AddToCartTool(), new CheckoutTool()]
});

// Skill 3: Orders
const orderSkill = new LuaSkill({
  name: "order-tracking",
  description: "Order status and tracking",
  tools: [new TrackOrderTool()]
});
```

**Benefits:**

* Logical separation
* Independent versioning
* Clear ownership
* Easier maintenance

## Advanced: Conditional Skills

An optional `condition` decides, per message and per user, whether the skill exists at all:

```typescript theme={null}
const loyaltySkill = new LuaSkill({
  name: "loyalty-rewards",
  description: "Loyalty points balance and reward redemption",
  context: `
    Tool Usage:
    - check_points: Use when the customer asks about their balance.
    - redeem_points: Use when the customer wants to spend points.
  `,
  condition: async () => {
    const user = await User.get();
    return user.data?.loyaltyEnrolled === true;
  },
  tools: [new CheckPointsTool(), new RedeemPointsTool()]
});
```

When it returns `false`, the skill's tools can't be called **and** its name, context, and tool names never reach the agent's prompt. A customer who isn't enrolled talks to an agent that has no idea a loyalty programme exists — unlike a [tool-level condition](/overview/tools), which leaves the skill's name and context in place so the agent can still say "you're not eligible for that".

If the condition throws or times out, the skill is hidden (fail-closed). See [Conditional Skills](/api/luaskill#conditional-skills) for the full comparison.

## Advanced: Channel-Aware Contexts

For most skills, a single context works great. But if you need different instructions per channel (e.g., voice gets conversational guidance, text gets structured formatting tips), see [Channel-aware Prompts](/concepts/channel-aware-prompts).

## Next Steps

<CardGroup>
  <Card title="Learn About Tools" icon="wrench" href="/overview/tools">
    Understand what tools are and how to build them
  </Card>

  <Card title="Persona Command" icon="terminal" href="/cli/persona-command">
    Complete guide to managing personas
  </Card>

  <Card title="See Examples" icon="layer-group" href="/demos/overview">
    11 complete skill implementations
  </Card>

  <Card title="Build Your First Skill" icon="rocket" href="/getting-started/first-skill">
    Step-by-step tutorial
  </Card>
</CardGroup>


# Spaces
Source: https://docs.heylua.ai/overview/spaces

Supervisor agents that delegate work to specialised agents in one conversation

## What is a Space?

A **Space** is a supervisor agent with a curated roster of specialised agents. The user talks to the Space, the Space decides whether a specialist would help, and the Space synthesises the specialist's result into its own final response.

<Card title="Think of it as:" icon="diagram-project">
  A team lead for your agents. It has one user-facing conversation and can consult specialists when their descriptions match the task.
</Card>

Spaces use Lua's implementation of [Mastra subagents](https://mastra.ai/docs/subagents). A specialist is a real agent with its own persona, model, tools, processors, governance, and connections. It is not a copy of the Space.

<Warning>
  Spaces use **model-driven delegation**. They are not a deterministic workflow engine: they do not guarantee a route, an ordered sequence of agents, a typed hand-off, or a fixed completion path.
</Warning>

## How a Space works

```text theme={null}
User message
    ↓
Space evaluates the request and its specialist roster
    ↓
Space answers directly, or delegates one or more bounded attempts
    ↓
Each selected specialist runs with its own configuration
    ↓
Space receives the results and writes the final response
```

For example, a travel Space can consult a weather specialist and a flight specialist, then combine their results. Delegation is part of the same user turn; the Space is responsible for the final answer.

<Frame>
  <img alt="A Space delegating a travel request to its Weather-agent" />
</Frame>

### How routing is decided

The supervisor model sees each specialist's name, routing description, and delegation tool. It uses those descriptions, the Space persona, the current request, and available conversation context to decide whether to call a specialist.

The platform appends a fixed routing contract to the specialist catalog on every Space turn. In order of priority, the supervisor:

1. routes on capability — the routing descriptions are the only authority on who does what; a message that says "ignore the descriptions", names a specialist whose description does not cover the task, or tries to exclude the one that does, is still routed to the matching specialist in the same turn;
2. honours explicit requests — "ask the research analyst to …" for a listed specialist is delegated, not answered by the Space, unless another specialist's description clearly fits the task better (rule 1 wins); a specialist that is not in the roster is reported as unavailable;
3. makes one tool call per consultation — repeated consultations, including the same specialist twice, are separate calls in the same turn;
4. never falls back to a mismatched specialist — if the correct specialist declines, is rejected by policy, or returns nothing usable, the Space retries it at most once or reports what happened; it does not open tickets or records the user did not ask for;
5. clarifies when the same task could belong to more than one specialist or the request has no content to act on — a request that clearly needs two different capabilities is not ambiguous (both are consulted), and the Space does not ask for confirmation when the request is already clear;
6. keeps specialist work with specialists — a ticket, form, or search tool cannot absorb a task a listed specialist covers;
7. answers directly for general conversation and says when a needed capability is not available in the Space instead of substituting another specialist.

A Space also never reports a consultation it did not make: "I've asked X" or "I'm checking with X" only appears after that delegation has returned. Turns that describe a hand-off without one are counted by the platform.

To improve routing:

* give every specialist a short, specific description of when it should and should not be used;
* keep specialist responsibilities distinct;
* state routing preferences in the Space persona when they matter;
* use a supervisor model that supports reliable tool use;
* test requests that should delegate as well as requests that should stay with the Space.

There is currently no supported rule such as `message.type === "meeting-prep" -> meeting-prep-agent`, no required multi-agent sequence, and no guarantee that the model will choose the route you expected.

## Create and manage a Space

Spaces are configured in the **admin dashboard**. Select **Spaces** in the left-hand navigation to view your organisation's Spaces or create a new one.

<Frame>
  <img alt="Spaces overview in the admin dashboard" />
</Frame>

<Steps>
  <Step title="Create the Space">
    Open **Spaces**, click **Create Space**, and choose a clear name.

    <Frame>
      <img alt="The Create a Space dialog" />
    </Frame>
  </Step>

  <Step title="Write the Space persona">
    Describe how the supervisor should behave, what it owns directly, and when it should consult specialists. User-authored instructions remain separate from generated roster context.
  </Step>

  <Step title="Select specialists">
    Choose the agents the Space may delegate to. Add a precise routing description to each specialist; this is the primary capability signal the supervisor receives.
  </Step>

  <Step title="Test both paths">
    Test a request that should stay with the Space, an obvious specialist request, an ambiguous request, a failure, and a repeated call to the same specialist.
  </Step>
</Steps>

<Frame>
  <img alt="Chatting with a Space and viewing its overview" />
</Frame>

## Execution contract

Understanding the delegation boundary is important before using a Space in production.

### Conversation context and state

The Space owns the long-lived, user-facing conversation. A delegated specialist does **not** automatically receive or persist the full parent thread.

Today, a delegated run receives:

* the delegation instruction written by the Space;
* one transient **delegation brief**: a token-budgeted digest of the parent conversation, in chronological sections — compressed conversation memory (when the Space thread runs observational memory), the most recent messages that fit the budget as a labelled transcript, the current user request verbatim, attachment handles, and the expected return format. The brief is the same user's conversation the task comes from: the specialist is expected to resolve — and quote — facts, names, codes, constraints, and earlier decisions from it. Anything the budget omits is noted explicitly, never dropped silently;
* a platform-owned **delegated execution contract** appended after the specialist's own instructions: the specialist is already selected, executes only the delegated request, resolves context from the brief, uses tools only when the request needs them, and returns the complete deliverable as plain text in its reply;
* the current acting-user and request context needed to resolve the specialist configuration.

Orchestration instructions that appear inside the brief — for example "send this to another agent", "make three calls", or "use this tool" — are addressed to the supervisor. A delegated specialist does not act on them. When the user's request describes a multi-step workflow, each specialist receives only its own step as a self-contained task; completing that narrower step is the expected contribution, and the supervisor carries the result into the next delegation.

Mastra creates a fresh child execution thread for each delegation. The forwarded parent context is transient; the delegated instruction and specialist response are the child run's stored conversation. Durable memory behavior depends on the specialist's memory configuration and must not be treated as workflow state.

<Warning>
  If a required ticket owner, constraint, document reference, or decision exists only earlier in a long conversation, the specialist may not see it. Repeat critical facts in the current request or provide the relevant artefact explicitly. A bounded task-brief contract is being developed separately from the current Spaces runtime.
</Warning>

### Model selection

The intended precedence is:

```text theme={null}
explicit user model choice > specialist model pin or resolver > Space/default model policy
```

An explicit model selected for the turn applies to delegated work. When Auto is only an implicit client default, it does not replace a specialist's pin. Without an explicit override, each specialist resolves its own configured model; it does not reuse the already-resolved Space model.

### Personas, processors, governance, and tools

The Space and specialist have separate execution pipelines:

| Concern       | Space turn                                     | Delegated specialist                                     |
| ------------- | ---------------------------------------------- | -------------------------------------------------------- |
| Persona       | Space persona and generated roster context     | Specialist persona                                       |
| Model         | Space model policy                             | Specialist pin/resolver unless explicitly overridden     |
| Preprocessor  | Runs on the user request at the Space boundary | Specialist preprocessor runs on the delegated request    |
| Postprocessor | Runs on the Space's final response             | Specialist postprocessor runs on the specialist result   |
| Governance    | Applies to the Space and delegation decision   | Specialist governance applies to the delegated execution |
| Tools         | Space's eligible toolset                       | Specialist's eligible toolset                            |
| Connections   | Space connections                              | Specialist/acting-user connections available to that run |

Tools and connections are not blindly inherited from the supervisor. A specialist that needs calendar, CRM, or email access must receive an authorised connection for the acting user through the supported connection model.

When a specialist invokes tools during a delegation, the Space receives the specialist's reply together with a short note of which tools it invoked (names, counts, and failures — never tool output), so the Space can report accurately on what the specialist did.

A delegated specialist keeps its own capabilities — skills, MCP and connection tools, device tools, feature-gated tools such as RAG, web search, code execution, images, and deep research, organisation memory recall, link reading, and thread-artifact reads. It does **not** receive the supervisor's user-facing surface while running as a Space child: share preparation, artefact, project, chart, calendar, choice, and template-change cards, scheduled-task and automation client operations, inbox questions and connection requests, meeting preparation, and desktop session tools. The Space keeps those tools and uses them on the specialist's returned text. Direct chats with the same specialist are unchanged.

Be careful with side-effectful processors configured at both levels: the Space boundary and specialist boundary are distinct scopes, so each configured processor can run at its own scope.

### Attempts, outcomes, and limits

Every new delegated attempt receives a stable attempt ID linked to the parent Space run and the underlying tool call. Repeated calls to the same specialist remain separate attempts.

An attempt can:

* **succeed** after the specialist returns a result;
* **fail** because the specialist execution failed;
* **fail with an unusable result** when the specialist ran but returned an empty reply. The Space then receives a bounded description of what happened — including the names of tools the specialist invoked, never their output — instead of a successful empty hand-off, and can delegate again or report honestly;
* be **rejected** before specialist execution by Space governance, specialist governance or preprocessing, billing, policy resolution, or the per-turn attempt budget.

Supported clients render failed and rejected attempts separately. Runtime logs and traces retain the parent run, specialist, tool-call identity, duration, and bounded outcome so failures can be attributed to the correct layer.

The platform enforces a bounded number of delegation attempts per user turn and can disable delegation with an operator kill switch. A Space should not be used as an unbounded agent loop.

## Connections and shared specialists

A connection grant has an owner and an acting-user boundary. Do not assume that attaching a connection to a Space makes it available to every specialist, or that a connection attached to a shared specialist is automatically isolated per user.

Until user-scoped connections are enabled for every execution surface in your workspace:

* do not attach a personal account to a public/shared specialist unless every authorised user may act through that account;
* use private, per-user agents for personal integrations;
* verify direct chat, Space delegation, scheduled jobs, and triggers separately;
* fail closed when the acting user cannot be established.

Connection ownership and direct-specialist parity are platform concerns. A supervisor prompt cannot make an unsafe connection safe.

## Invoke and deploy a Space

At the API boundary, a Space is an agent. You can use its ID on supported chat endpoints and clients that accept an `agentId`.

### Find the Space ID

Open the Space detail page. The final URL segment after `/spaces/` is the Space ID:

```text theme={null}
https://admin.heylua.ai/admin/spaces/<your-space-id>
```

For example, `.../admin/spaces/space_1234567890123_ab1cd2e` has the ID `space_1234567890123_ab1cd2e`.

### Supported configuration surface

Space **configuration is dashboard-only** today. The `lua` CLI does not provide a first-class Space manifest, versioning, diff, deploy, rollback, or local Space test contract.

Using a Space ID through the HTTP API or a chat client is invocation support; it is not configuration-as-code.

### Channel and client parity

An endpoint accepting a Space ID does not guarantee that every specialist tool works on every surface. Device tools, client-rendered capabilities, approvals, connection tools, voice, jobs, and triggers have their own availability and acting-user requirements.

Test every production surface you intend to support. Do not infer channel parity from a successful dashboard chat.

## Production readiness

Spaces are best used today for a small, curated roster and short, reversible specialist tasks where model-driven routing is acceptable.

| Good current fit                            | Requires a different or future contract                      |
| ------------------------------------------- | ------------------------------------------------------------ |
| One obvious specialist for a request        | Deterministic ownership or compliance routing                |
| Short research or synthesis within one turn | Long-running or resumable background research                |
| Reversible read-only work                   | Unsupervised high-impact side effects                        |
| Human-reviewed specialist output            | Required ordered or parallel stages                          |
| Active monitoring of outcomes               | SLA-critical processing without release evals                |
| Explicitly tested channels and connections  | Assumed parity across direct chat, jobs, triggers, and voice |

Before a production rollout, verify:

* specialist descriptions route the expected dataset;
* explicit user model choices and specialist pins behave as intended;
* required context fits the current bounded delegation input;
* Space and specialist processors/governance run at the intended scopes;
* every connection is authorised for the acting user on that surface;
* failed and rejected attempts are observable and have a user-safe explanation;
* no internal child execution is presented as a normal user conversation;
* latency, token use, delegation count, and cost stay within your limits;
* you have a direct-specialist fallback and an owner monitoring real outcomes.

<Note>
  Mastra Workflows and Dynamic Workflows are **not part of the current Spaces implementation**. Ordered stages, durable workflow state, resumability, and workflow configuration will be considered in a separate future initiative.
</Note>

## Troubleshooting

### The Space did not delegate

Check that the specialist is enabled and included, its routing description clearly matches the request, the supervisor model supports reliable tool use, and the final model-visible toolset contains the specialist. A narrated hand-off is not evidence that a delegation ran; look for a delegation attempt in the response trace. If the request could fit more than one specialist, the Space asks a clarifying question first — tighten the descriptions so only one fits.

### The wrong model handled specialist work

Check whether the user explicitly chose a model for the turn. Explicit choice wins. Otherwise, inspect the specialist pin/resolver and the recorded parent/child model provenance.

### The specialist lost an earlier constraint

Delegated context is bounded and is not the full Space thread: the specialist receives a token-budgeted brief of the recent conversation and, when the Space thread runs observational memory, its compressed observations. A constraint far outside that window may still be missing — restate it in the current request or attach the relevant artefact. Do not rely on an internal child thread as durable process state.

### An attempt says Rejected

The specialist may not have executed. Inspect the outcome for governance, preprocessing, billing, policy, or attempt-budget rejection before debugging the specialist itself.

### The specialist cannot use a connection

Confirm who owns the grant, which user the turn is acting as, whether that connection is mounted for delegated execution, and whether the same behavior works in direct chat. Do not copy a personal credential into a shared agent as a workaround.

## Next steps

<CardGroup>
  <Card title="Agent Concept" icon="robot" href="/overview/agent">
    Build the specialised agents a Space can consult.
  </Card>

  <Card title="Model Selection" icon="microchip" href="/overview/model-selection">
    Understand model pins, dynamic selection, and explicit overrides.
  </Card>

  <Card title="Channels" icon="tower-broadcast" href="/overview/channels">
    Validate the surfaces where your Space will run.
  </Card>

  <Card title="Read the announcement" icon="newspaper" href="https://blog.heylua.ai/introducing-spaces-one-conversation-many-experts/">
    Introducing Spaces — one conversation, many experts.
  </Card>
</CardGroup>


# Tools
Source: https://docs.heylua.ai/overview/tools

Individual functions your agent can execute

## What is a Tool?

A **tool** is a single function that your AI agent can execute. Tools are the building blocks that give your agent real capabilities.

<Card title="Think of it as:" icon="wrench">
  A TypeScript function that does ONE specific thing - like "search products" or "check order status"
</Card>

<Note>
  Tools are bundled into skills, which are then added to your agent through the `LuaAgent` class. See [Agent Concept](/overview/agent) for the complete pattern.
</Note>

## Anatomy of a Tool

```typescript theme={null}
import { LuaTool } from 'lua-cli';
import { z } from 'zod';

class SearchProductsTool implements LuaTool {
  // 1. Name - unique identifier
  name = "search_products";
  
  // 2. Description - what it does
  description = "Search for products in catalog";
  
  // 3. Input Schema - what it needs
  inputSchema = z.object({
    query: z.string().describe("Search query")
  });
  
  // 4. Execute - what it does
  async execute(input: { query: string }) {
    // Call your API or external service
    const response = await fetch(`https://your-api.com/search?q=${input.query}`);
    return await response.json();
  }
}
```

<CardGroup>
  <Card title="Name" icon="tag">
    Unique identifier (snake\_case)
  </Card>

  <Card title="Description" icon="file-text">
    Clear explanation of purpose
  </Card>

  <Card title="Input Schema" icon="shield-check">
    Zod validation for inputs
  </Card>

  <Card title="Execute Function" icon="bolt">
    The actual logic
  </Card>
</CardGroup>

## Good vs Bad Tools

<Tabs>
  <Tab title="❌ Bad Tool">
    ```typescript theme={null}
    class BadTool implements LuaTool {
      name = "tool1";  // Unclear name
      description = "Does stuff";  // Vague description
      
      inputSchema = z.object({
        input: z.string()  // Unclear parameter
      });
      
      async execute(input) {
        // No error handling
        // No validation
        // Returns unclear data
        return "done";
      }
    }
    ```

    **Problems:**

    * Unclear name
    * Vague description
    * Generic input
    * No error handling
    * Unclear return value
  </Tab>

  <Tab title="✅ Good Tool">
    ```typescript theme={null}
    class SearchProductsTool implements LuaTool {
      name = "search_products";  // Clear, descriptive
      description = "Search product catalog by name, category, or keyword";  // Specific
      
      inputSchema = z.object({
        query: z.string().describe("Search query (e.g., 'laptop', 'running shoes')"),
        maxPrice: z.number().optional().describe("Maximum price filter")
      });
      
      async execute(input: { query: string; maxPrice?: number }) {
        try {
          // Call your API
          const response = await fetch(
            `https://your-api.com/search?q=${input.query}`
          );
          
          if (!response.ok) {
            throw new Error(`Search failed: ${response.statusText}`);
          }
          
          let products = await response.json();
          
          // Apply price filter if specified
          if (input.maxPrice) {
            products = products.filter(p => p.price <= input.maxPrice);
          }
          
          // Return structured data
          return {
            products: products.map(p => ({
              id: p.id,
              name: p.name,
              price: `$${p.price.toFixed(2)}`,
              category: p.category,
              inStock: p.inStock
            })),
            count: products.length,
            query: input.query
          };
          
        } catch (error) {
          throw new Error(`Failed to search products: ${error.message}`);
        }
      }
    }
    ```

    **Why it's good:**

    * Clear, descriptive name
    * Detailed description
    * Validated inputs
    * Error handling
    * Structured return value
    * Comments explain logic
  </Tab>
</Tabs>

## Tool Types

### 1. External API Tools

Connect to any external service:

```typescript theme={null}
class GetWeatherTool implements LuaTool {
  name = "get_weather";
  description = "Get current weather for a city";
  
  inputSchema = z.object({
    city: z.string()
  });
  
  async execute(input: { city: string }) {
    // Call external weather API
    const response = await fetch(
      `https://api.weather.com/v1/current?city=${input.city}`
    );
    return await response.json();
  }
}
```

### 2. Platform API Tools

Use Lua's built-in APIs:

```typescript theme={null}
import { Products } from 'lua-cli';

class SearchProductsTool implements LuaTool {
  name = "search_products";
  description = "Search product catalog";
  
  inputSchema = z.object({
    query: z.string()
  });
  
  async execute(input: { query: string }) {
    // Use Platform API
    return await Products.search(input.query);
  }
}
```

### 3. Hybrid Tools

Mix both approaches:

```typescript theme={null}
import { Data } from 'lua-cli';

class SmartSearchTool implements LuaTool {
  async execute(input: { query: string }) {
    // 1. Search YOUR external API
    const yourProducts = await fetch('https://your-api.com/search');
    
    // 2. Search Platform vector search
    const docs = await Data.search('help_docs', input.query);
    
    // 3. Combine results
    return { yourProducts, docs };
  }
}
```

### 4. Conditional Tools

Tools that are only available under certain conditions:

```typescript theme={null}
import { User } from 'lua-cli';

class PremiumFeatureTool implements LuaTool {
  name = "premium_feature";
  description = "Advanced feature for premium users";
  
  inputSchema = z.object({ query: z.string() });
  
  // Only show to premium users
  condition = async () => {
    const user = await User.get();
    return user.data?.isPremium === true;
  };
  
  async execute(input) {
    // Only runs if condition returned true
    return { result: "premium data" };
  }
}
```

<Note>
  The `condition` function runs before the tool is offered to the AI. If it returns `false` or throws an error, the tool is hidden from the conversation.
</Note>

**Use cases for conditional tools:**

* Premium/paid features
* User verification status
* Feature flags & A/B testing
* Region-specific tools
* Time-based access

A hidden tool is left out of the prompt's tool list, but the agent still sees the skill's name and context, so it can say "that's a premium feature". When the *existence* of the capability is itself sensitive, gate the whole skill instead — `LuaSkill` takes the same `condition`, and a hidden skill's name, context, and tool names are left out of the prompt entirely. See [Conditional Skills](/api/luaskill#conditional-skills).

## Tool Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Names">
    ```typescript theme={null}
    // ✅ Good
    name = "search_products"
    name = "create_order"
    name = "cancel_booking"

    // ❌ Bad
    name = "search"  // Too generic
    name = "tool1"   // Not descriptive
    name = "do_stuff"  // Unclear
    ```
  </Accordion>

  <Accordion title="Write Clear Descriptions">
    ```typescript theme={null}
    // ✅ Good
    description = "Search product catalog by name, category, or keyword"

    // ❌ Bad
    description = "Searches stuff"
    ```
  </Accordion>

  <Accordion title="Validate Inputs">
    ```typescript theme={null}
    inputSchema = z.object({
      email: z.string().email(),
      age: z.number().min(0).max(120),
      priority: z.enum(['low', 'medium', 'high'])
    });
    ```
  </Accordion>

  <Accordion title="Handle Errors">
    ```typescript theme={null}
    async execute(input) {
      try {
        const result = await api.call(input);
        return result;
      } catch (error) {
        throw new Error(`Operation failed: ${error.message}`);
      }
    }
    ```
  </Accordion>

  <Accordion title="Return Structured Data">
    ```typescript theme={null}
    // ✅ Good - Structured
    return {
      success: true,
      data: { id, name, price },
      message: "Product found"
    };

    // ❌ Bad - Unstructured string
    return "Product found: ID 123";
    ```
  </Accordion>
</AccordionGroup>

## Testing Tools

<Tabs>
  <Tab title="Test Individual Tool">
    ```bash theme={null}
    lua test
    ```

    * Select specific tool
    * Enter test inputs
    * Verify output
    * Debug tool logic
  </Tab>

  <Tab title="Test in Conversation">
    ```bash theme={null}
    lua chat
    ```

    * Test how AI selects tool
    * Verify tool execution
    * Check output formatting
    * Test error cases
  </Tab>
</Tabs>

## Managing Tools

<CardGroup>
  <Card title="Create" icon="plus">
    Write tools in `src/tools/`
  </Card>

  <Card title="Bundle" icon="box">
    Add to skills in `src/index.ts`
  </Card>

  <Card title="Test" icon="flask">
    ```bash theme={null}
    lua test
    ```
  </Card>

  <Card title="Deploy" icon="rocket">
    ```bash theme={null}
    lua push
    lua deploy
    ```
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Learn About Skills" icon="puzzle-piece" href="/overview/skill">
    How tools are bundled into skills
  </Card>

  <Card title="See Tool Examples" icon="layer-group" href="/examples/overview">
    30+ working tool examples
  </Card>

  <Card title="API Reference" icon="book" href="/api/luatool">
    Complete LuaTool interface documentation
  </Card>

  <Card title="Build Your First Tool" icon="hammer" href="/getting-started/first-skill">
    Step-by-step tutorial
  </Card>
</CardGroup>


# Webhooks
Source: https://docs.heylua.ai/overview/webhooks

HTTP endpoints for receiving external events

## What are Webhooks?

**Webhooks** are HTTP endpoints that allow external services to send events to your agent. When something happens in an external system (like a payment completing or an order shipping), that system can notify your agent in real-time.

<Card title="Think of it as:" icon="webhook">
  A phone number for your agent - external services can "call" it when events happen
</Card>

<Warning>
  **No Conversational Context:** Webhooks execute outside of user conversations. You MUST provide a userId when calling `User.get(userId)` to notify specific users. Store user IDs in your payment/order metadata.
</Warning>

<Note>
  Built-in webhook support for seamless external integrations.
</Note>

## Why Webhooks?

<CardGroup>
  <Card title="Real-Time Events" icon="bolt">
    Get notified instantly when events happen in external systems
  </Card>

  <Card title="Automated Actions" icon="gears">
    Automatically respond to external events without user interaction
  </Card>

  <Card title="Seamless Integration" icon="plug">
    Connect with Stripe, Shopify, GitHub, and any webhook-enabled service
  </Card>

  <Card title="Event-Driven" icon="satellite-dish">
    Build reactive agents that respond to real-world events
  </Card>
</CardGroup>

## How Webhooks Work

<Steps>
  <Step title="External Event Occurs">
    Something happens: payment completes, order ships, PR merges, etc.
  </Step>

  <Step title="Service Sends HTTP Request">
    The external service (Stripe, Shopify) sends a POST request to your webhook URL
  </Step>

  <Step title="Your Webhook Receives Event">
    Your LuaWebhook's execute function is called with the event data
  </Step>

  <Step title="Your Code Takes Action">
    Process the event: update orders, notify users, trigger jobs, etc.
  </Step>

  <Step title="Return Response">
    Return acknowledgment to the external service
  </Step>
</Steps>

## Simple Example

```typescript theme={null}
import { LuaWebhook, User } from 'lua-cli';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  description: 'Handle Stripe payment events',
  
  execute: async (event) => {
    const { body } = event;
    if (body?.type === 'payment_intent.succeeded') {
      // ⚠️ Webhooks have NO conversational context
      // You MUST provide userId to User.get()
      
      // Get user ID from payment metadata
      const customerId = body.data?.object?.metadata?.customerId;
      
      if (!customerId) {
        console.error('No customerId in payment metadata');
        return { received: true, error: 'No customer ID' };
      }
      
      // Retrieve specific user by ID
      const user = await User.get(customerId);
      
      // Send payment confirmation to that user
      await user.send([{
        type: 'text',
        text: `✅ Payment confirmed! Amount: ${body.data.object.amount} ${body.data.object.currency.toUpperCase()}`
      }]);
    }
    
    return { received: true };
  }
});
```

<Warning>
  **Critical:** Webhooks execute outside conversational context. `User.get()` REQUIRES a userId parameter. Always store the user ID in your payment/order metadata when creating transactions.
</Warning>

## Common Use Cases

<Tabs>
  <Tab title="Payments">
    **Stripe, PayPal, Square**

    Handle payment events:

    * Payment succeeded
    * Payment failed
    * Refund processed
    * Subscription updated

    Actions:

    * Update order status
    * Notify customer
    * Trigger fulfillment
  </Tab>

  <Tab title="E-commerce">
    **Shopify, WooCommerce**

    Handle order events:

    * Order created
    * Order fulfilled
    * Order cancelled
    * Inventory updated

    Actions:

    * Sync order data
    * Update inventory
    * Send confirmations
  </Tab>

  <Tab title="Development">
    **GitHub, GitLab**

    Handle code events:

    * Push to repository
    * Pull request opened
    * Deployment completed
    * Release published

    Actions:

    * Notify team
    * Trigger workflows
    * Update dashboards
  </Tab>

  <Tab title="Custom">
    **Your Internal Systems**

    Any event from your backend:

    * User signup
    * Task completed
    * Threshold exceeded
    * Data changed

    Actions:

    * Whatever you need!
  </Tab>
</Tabs>

## Event Subscriptions

Webhooks can also subscribe to **platform events** — real-time notifications from your messaging channels. When you send a template message via WhatsApp, for example, you can track whether it was delivered, read, or failed.

<Note>
  Webhook event subscriptions for message delivery tracking. Currently supports WhatsApp status events; additional channels may be added in the future.
</Note>

### Available Event Types

| Event               | Description                                     | Channel  |
| ------------------- | ----------------------------------------------- | -------- |
| `message.sent`      | Message was sent to the recipient               | WhatsApp |
| `message.delivered` | Message was delivered to the recipient's device | WhatsApp |
| `message.read`      | Recipient read the message                      | WhatsApp |
| `message.failed`    | Message failed to send                          | WhatsApp |
| `message.played`    | Recipient played a voice/video message          | WhatsApp |

### How It Works

<Steps>
  <Step title="Create a webhook">
    Define a `LuaWebhook` that handles delivery status events
  </Step>

  <Step title="Subscribe to events">
    Use the CLI to subscribe your webhook to the event types you care about

    ```bash theme={null}
    lua webhooks subscribe --webhook-name delivery-tracker --event message.delivered
    lua webhooks subscribe --webhook-name delivery-tracker --event message.read
    lua webhooks subscribe --webhook-name delivery-tracker --event message.failed
    ```
  </Step>

  <Step title="Receive events">
    Your webhook's `execute` function is called with the event payload whenever a status update arrives
  </Step>
</Steps>

### Delivery Semantics

Subscribed platform events are delivered **at least once**. Each event is durably queued and processed on isolated infrastructure, so a subscribed handler may run **more than once** for a single logical event:

* Delivery is retried automatically — up to **3 attempts total**, with a fixed 60-second wait between attempts, and only when an attempt fails.
* Because retries (and occasional redeliveries) can repeat an event, your handler's side effects should be **idempotent** — safe to run twice.

Each invocation receives execution metadata on `event.execution`:

| Field         | Description                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `eventId`     | Stable identifier for the logical event. Unchanged across retries and redeliveries — use it as your idempotency / dedup key. |
| `executionId` | Unique identifier for this individual attempt. Not a dedup key.                                                              |
| `attempt`     | 1-based attempt counter (`1` on the first delivery, `2` on the first retry, and so on).                                      |

```typescript theme={null}
execute: async (event) => {
  const { eventId } = event.execution ?? {};

  // Key side effects on eventId so a repeated delivery is a no-op
  await Data.create('delivery-events', {
    idempotencyKey: eventId,
    status: event.body.status,
  }, `${event.body.status} ${eventId}`);

  return { received: true };
}
```

<Note>
  `event.execution` is only present for durably-delivered platform events. It is `undefined` during local `lua test` / `lua dev` runs, which execute in-process. Very large event payloads (over 50,000 characters, which is rare) are delivered without the at-least-once retry guarantee.
</Note>

<Warning>
  **Direct requests are unchanged.** Requests sent straight to your webhook URL (Stripe, Shopify, GitHub, etc.) are still handled **synchronously** with no automatic retries — the caller receives your handler's return value and applies its own retry policy. At-least-once delivery and `event.execution` apply only to subscribed platform events.
</Warning>

### Example: Delivery Tracking Webhook

```typescript theme={null}
import { LuaWebhook, Data } from 'lua-cli';

const deliveryTracker = new LuaWebhook({
  name: 'delivery-tracker',
  description: 'Track WhatsApp message delivery status',
  
  execute: async (event) => {
    const { body } = event;
    const { eventType, recipientId, status, messageWamid } = body;
    
    await Data.create('delivery-events', {
      messageId: messageWamid,
      recipient: recipientId,
      status: status,
      eventType: eventType,
      trackedAt: new Date().toISOString()
    }, `${status} - ${recipientId}`);
    
    if (status === 'failed') {
      console.error(`Message ${messageWamid} failed for ${recipientId}`);
    }
    
    return { received: true };
  }
});

export default deliveryTracker;
```

### Managing Subscriptions via CLI

```bash theme={null}
# List all available event types
lua webhooks list-events

# Subscribe a webhook to an event
lua webhooks subscribe --webhook-name delivery-tracker --event message.delivered

# Unsubscribe a webhook from an event
lua webhooks unsubscribe --webhook-name delivery-tracker --event message.delivered
```

## Adding Webhooks to Your Agent

Webhooks are added to your LuaAgent configuration:

```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import paymentWebhook from './webhooks/payment';
import orderWebhook from './webhooks/order';

export const agent = new LuaAgent({
  name: "my-agent",
  persona: "...",
  skills: [...],
  
  // Add webhooks
  webhooks: [
    paymentWebhook,
    orderWebhook
  ]
});
```

## Webhook URLs

After deploying, you can call webhooks by ID **or** by name:

```
https://webhook.heylua.ai/{agentId}/{webhookId}
https://webhook.heylua.ai/{agentId}/{webhook-name}
```

**Notes:**

* `agentId` is your agent identifier (e.g., `agent_abc123`)
* `webhookId` is the UUID shown when the webhook is created
* `webhook-name` is the friendly name from your code
* `lua push webhook` prints both links

Configure either URL in your external service's webhook settings.

## Verify Requests

A webhook URL is public: anyone who knows or guesses it can invoke your `execute` function. Add a `secret` to the webhook definition and Lua will only run it for requests that prove they know that secret.

```typescript theme={null}
import { LuaWebhook } from 'lua-cli';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  description: 'Handle payment events',
  secret: 'a-long-random-string',

  execute: async (event) => {
    // Only reached when the signature checks out
    return { received: true };
  },
});
```

With a secret set, every request must carry:

```
x-lua-signature: sha256=<hex HMAC-SHA256 of the raw request body, keyed with the secret>
```

Requests with a missing, malformed, or incorrect signature get **401** and your code never runs. Webhooks with no `secret` behave exactly as before — this is opt-in.

<Warning>
  The signature is computed over the **exact bytes** of the request body, not over a re-serialized copy. A sender that pretty-prints or reorders JSON after signing will fail verification.
</Warning>

<Note>
  Signing covers JSON request bodies. A sender that posts `application/x-www-form-urlencoded` or `text/plain` will always be rejected, so leave `secret` unset for those and verify inside your `execute` function instead.
</Note>

### Computing the signature

The sender computes the HMAC. In a shell:

```bash theme={null}
SECRET='a-long-random-string'
BODY='{"type":"payment_intent.succeeded","amount":2000}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "https://webhook.heylua.ai/{agentId}/payment-webhook" \
  -H "Content-Type: application/json" \
  -H "x-lua-signature: sha256=$SIG" \
  -d "$BODY"
```

In Node.js:

```typescript theme={null}
import { createHmac } from 'crypto';

const body = JSON.stringify({ type: 'payment_intent.succeeded', amount: 2000 });
const signature = 'sha256=' + createHmac('sha256', SECRET).update(body).digest('hex');

await fetch(`https://webhook.heylua.ai/${agentId}/payment-webhook`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-lua-signature': signature },
  body, // the same string that was signed
});
```

### Rotating the secret

Change the value in your webhook definition and re-deploy — `lua push webhook` applies the current secret to the webhook on every push:

```bash theme={null}
lua push webhook
lua webhooks deploy --webhook-name payment-webhook --webhook-version latest
```

Update the sender at the same time; requests signed with the old secret start failing as soon as the push lands. To turn verification off again, set `secret: ''` and push.

<Note>
  The secret must be a literal string or a constant the CLI can read at build time — a value like `process.env.WEBHOOK_SECRET` cannot be resolved during compilation and fails the build rather than silently deploying an unprotected webhook. Treat the file holding it as a credential.
</Note>

<Warning>
  **Don't put a signing secret on a webhook you publish as a marketplace template.** The secret is part of the compiled webhook code, and publishing a template freezes that code for every installer — they would all receive your key. Publish the webhook without a `secret` and let each installer set their own.
</Warning>

Vendors that sign with their own scheme (Stripe's `stripe-signature`, GitHub's `x-hub-signature-256`) won't produce an `x-lua-signature` header. Leave `secret` unset for those and verify the vendor's header inside your `execute` function.

## Best Practices

<AccordionGroup>
  <Accordion title="✅ Store User IDs in Metadata">
    **Always include user ID in payment/order metadata**

    When creating payments or orders, store the Lua user ID:

    ```typescript theme={null}
    // When creating Stripe payment
    const paymentIntent = await stripe.paymentIntents.create({
      amount: 2000,
      currency: 'usd',
      metadata: {
        customerId: user.id,  // ← Lua user ID
        orderId: order.id
      }
    });
    ```

    Then in your webhook, retrieve the specific user:

    ```typescript theme={null}
    execute: async (event) => {
      const { body } = event;
      const customerId = body.data.object.metadata.customerId;
      const user = await User.get(customerId);
      await user.send([{ type: 'text', text: 'Payment confirmed!' }]);
    }
    ```
  </Accordion>

  <Accordion title="✅ Handle Errors Gracefully">
    **Don't throw errors - return error status**

    ```typescript theme={null}
    execute: async (event) => {
      const { body } = event;
      try {
        // Process webhook
        return { success: true };
      } catch (error) {
        console.error('Webhook error:', error);
        return { success: false, error: error.message };
      }
    }
    ```
  </Accordion>

  <Accordion title="✅ Return Quickly">
    **Webhooks should respond within 5 seconds**

    For long-running work, queue a job:

    ```typescript theme={null}
    execute: async (event) => {
      const { body } = event;
      // Quick validation
      if (!isValid(body)) return { error: 'Invalid' };
      
      // Queue long-running work
      await Jobs.create({
        execute: async () => {
          // Process here
        }
      });
      
      return { received: true };
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Webhooks API Reference" icon="book" href="/api/luawebhook">
    Complete API documentation with examples
  </Card>

  <Card title="Agent Concept" icon="robot" href="/overview/agent">
    Learn about LuaAgent configuration
  </Card>

  <Card title="Jobs Concept" icon="clock" href="/overview/jobs">
    Understand scheduled tasks
  </Card>

  <Card title="Skills Concept" icon="puzzle-piece" href="/overview/skill">
    Learn about skills and tools
  </Card>
</CardGroup>


# Workflows
Source: https://docs.heylua.ai/overview/workflows

Durable, multi-step runs that combine code, agent turns, specialist reviews and human approvals

## What is a Workflow?

A **workflow** is a durable, multi-step run. You declare the steps and how they connect once, in TypeScript; the platform then executes every run of it, records every step and event, survives restarts, waits for people when a step needs a decision, and lets you watch, cancel, retry and replay the run from the CLI or the desktop.

<Card title="Think of it as:" icon="diagram-project">
  A checklist the platform runs for you - each item is a piece of code, a turn of an agent, a review by a specialist role, or a question for a person - with a full record of what happened at every step.
</Card>

A run can be started by a person (CLI, desktop, chat), by a skill or tool your agent runs, by a schedule, by a trigger or webhook, by a template, or by another workflow.

## Anatomy of a workflow

<CardGroup>
  <Card title="Definition" icon="file-code">
    A `createWorkflow({...})` chain in your project. Pushed and versioned like a skill; deployed with `lua workflows deploy`.
  </Card>

  <Card title="Run" icon="play">
    One execution of a definition with a given input. Has an id (`wfr_...`), a status, a budget, an input and an output.
  </Card>

  <Card title="Steps" icon="list-check">
    The units of work inside a run. Each step has its own status, attempts, input, output and error.
  </Card>

  <Card title="Events" icon="timeline">
    The append-only ledger of everything that happened to a run, streamed live over SSE and kept after the run ends.
  </Card>
</CardGroup>

### Step kinds

| Kind            | Builder call                      | What it does                                                                                                             |
| --------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Code step       | `.then(createStep({...}))`        | Runs your `execute` function with typed input and output.                                                                |
| Agent step      | `.agentStep(id, {...})`           | One turn of an agent (yours, or `$self`), with a prompt template and an optional output schema.                          |
| Specialist step | `.specialistStep(id, {...})`      | A turn of your own agent under an additive role (name, instructions, tool allowlist) - for example a sceptical reviewer. |
| Tool step       | `.toolStep(id, tool, {...})`      | Calls one of your `LuaTool`s directly, without a model turn.                                                             |
| Approval        | `.approval(id, {...})`            | Pauses the run until a person approves or denies (optionally editing the payload).                                       |
| Signal wait     | `.waitForSignal(id, {...})`       | Pauses the run until an external system delivers a named signal.                                                         |
| Sleep           | `.sleep(ms)` / `.sleepUntil(iso)` | Waits without holding compute.                                                                                           |
| Map             | `.map({...})`                     | Reshapes data between steps.                                                                                             |
| Nested workflow | `.workflow(id, ref, input)`       | Runs another workflow as a child run.                                                                                    |

Steps are arranged with containers: `.parallel([...])`, `.switch([...], otherwise)` / `.branch([...])`, `.foreach(step, {...})` and `.dowhile(...)` / `.dountil(...)`.

### Graph form

A workflow's control flow is a static graph, not a program that runs at push time. Predicates are built from typed helpers (`eq`, `gt`, `exists`, `and`, ...) and data flow from mapping helpers (`fromInit`, `fromStep`, `template`, ...). A closure where a predicate or a binding is expected is a build error. This is what lets the platform draw the graph, replay a run locally, and resume a run on a fresh machine.

### Two execution tiers

| Tier             | Where a step runs                                 | Step timeout                                       | Use for                                                           |
| ---------------- | ------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
| Worker (default) | The agent's sandbox                               | 1-600 s (default 300 s)                            | API calls, data shaping, short model turns                        |
| Job              | Its own container, with an optional git workspace | Up to 4 h per code step, up to 24 h per agent step | Cloning a repository, running a test suite, a full coding session |

See [Job tier](/workflows/job-tier).

## Example

```typescript theme={null}
import { z } from 'zod';
import { createStep, createWorkflow, fromStep, template } from 'lua-cli';

const fetchSources = createStep({
  id: 'fetchSources',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ urls: z.array(z.string().url()) }),
  timeoutSeconds: 60,
  async execute({ inputData, log }) {
    const res = await fetch(`https://api.example.com/search?q=${encodeURIComponent(inputData.topic)}`);
    const json = (await res.json()) as { url: string }[];
    log(`found ${json.length} sources`);
    return { urls: json.slice(0, 10).map((r) => r.url) };
  },
});

export const researchBrief = createWorkflow({
  name: 'research-brief',
  description: 'Fetch sources, summarise, ask for sign-off.',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ brief: z.string() }),
  budget: { maxCredits: 40 },
})
  .then(fetchSources)
  .agentStep('draft', {
    agentId: 'analyst',
    prompt: template('Write a one-page brief on ${initData.topic} using ${stepResults.fetchSources.urls}'),
    outputSchema: z.object({ brief: z.string() }),
  })
  .approval('signOff', { title: 'Publish this brief?', approver: 'org-admins', timeoutHours: 48 })
  .map({ brief: fromStep('draft', 'brief') }, { id: 'result' })
  .commit();
```

## Workflows next to skills, jobs and templates

|                   | Skill                                       | Job                          | Workflow                                                                                    | Agent template                                                         |
| ----------------- | ------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| What it is        | Tools the agent calls during a conversation | Code that runs on a schedule | A durable graph of steps with its own runs                                                  | A packaged agent (skills, jobs, workflows, persona) others can install |
| Runs for          | One tool call                               | One execution                | Minutes to weeks                                                                            | n/a                                                                    |
| Waits for people  | No                                          | No                           | Yes (approvals, input, signals)                                                             | n/a                                                                    |
| Survives restarts | n/a                                         | No                           | Yes - every step and event is recorded                                                      | n/a                                                                    |
| Starts from       | The model, in chat                          | The scheduler                | CLI, desktop, chat, a skill, a schedule, a trigger, a webhook, a template, another workflow | The marketplace                                                        |

A workflow can carry its own `schedule`, so a scheduled workflow replaces the "job that calls an agent" pattern when you want step-level visibility, retries and approvals.

## When to use a workflow

<CardGroup>
  <Card title="Use a workflow when" icon="check">
    * The work has more than one step and you want each step recorded and retryable
    * A person must approve, edit or answer something part-way through
    * Steps run in parallel, over a list, or in a review loop
    * A step needs hours, a repository checkout, or a coding session
    * An external system reports back later (a PR review, a payment webhook)
  </Card>

  <Card title="Use a skill or job when" icon="xmark">
    * One tool call answers the user in the same turn (skill)
    * A short piece of code runs on a timer and nobody needs to intervene (job)
    * You do not need per-step history, replay or a human in the loop
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/workflows/quick-start">
    Define, push, deploy, start and approve your first workflow
  </Card>

  <Card title="Authoring" icon="code" href="/workflows/authoring">
    The SDK: steps, containers, bindings, approvals and `Workflows.start`
  </Card>

  <Card title="Job tier" icon="server" href="/workflows/job-tier">
    Long steps, git workspaces and coding turns
  </Card>

  <Card title="Runs and events" icon="timeline" href="/workflows/runs-and-events">
    Run lifecycle, the events ledger, SSE, approvals and the desktop Runs pages
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli/workflows-command">
    Every `lua workflows` subcommand
  </Card>
</CardGroup>


# Best Practices
Source: https://docs.heylua.ai/template/best-practices

Tips and patterns for building great skills

## Tool Design

### Single Responsibility

Each tool should do one thing well.

<CodeGroup>
  ```typescript Good theme={null}
  class CreateProductTool { ... }
  class UpdateProductTool { ... }
  class DeleteProductTool { ... }
  ```

  ```typescript Bad theme={null}
  class ProductTool {
    // Does create, update, delete, search...
    // Too many responsibilities!
  }
  ```
</CodeGroup>

### Clear Names

Use descriptive, action-oriented names.

<CodeGroup>
  ```typescript Good theme={null}
  name = "search_products"
  name = "create_order"
  name = "cancel_booking"
  ```

  ```typescript Bad theme={null}
  name = "products"      // Not specific
  name = "do_stuff"      // Too vague
  name = "tool1"         // Not descriptive
  ```
</CodeGroup>

### Input Validation

Always use Zod schemas with descriptions.

```typescript theme={null}
// ✅ Excellent - Comprehensive validation
inputSchema = z.object({
  email: z.string()
    .email()
    .describe("User's email address"),
  age: z.number()
    .min(0)
    .max(120)
    .describe("User's age in years"),
  priority: z.enum(['low', 'medium', 'high'])
    .default('medium')
    .describe("Task priority level")
});
```

### Error Handling

Provide helpful error messages.

```typescript theme={null}
async execute(input: any) {
  // Validate business logic
  if (input.amount <= 0) {
    throw new Error("Amount must be positive");
  }
  
  // Check prerequisites
  const user = await User.get();
  if (!user.verified) {
    throw new Error("Please verify your email before proceeding");
  }
  
  // Handle API errors
  try {
    return await externalApi.call(input);
  } catch (error) {
    throw new Error(
      `External API failed: ${error.message}. Please try again later.`
    );
  }
}
```

## Skill Configuration

### Write Comprehensive Context

The context field guides AI decision-making.

```typescript theme={null}
// ✅ Good - Detailed and actionable
context: `
  This skill manages customer orders for a restaurant.

  Tool Usage:
  - show_menu: Use when customers ask what's available. Returns food and drinks.
  - create_order: Use when taking an order. Always confirm items and sizes first.
  - modify_order: Use to add/remove items. Ask which item to modify.
  - check_status: Use to get order status. Returns estimated time.

  Guidelines:
  - Always ask about drink sizes (small/medium/large)
  - Mention daily specials when showing menu
  - Confirm total price before finalizing orders
  - Ask about dietary restrictions for food items
  - Be friendly and patient with customers
`
```

### Version Appropriately

Use semantic versioning.

```typescript theme={null}
// 1.0.0 → 1.0.1 (Patch)
// Bug fixes, minor improvements
version: "1.0.1"

// 1.0.1 → 1.1.0 (Minor)
// New features, backward compatible
version: "1.1.0"

// 1.1.0 → 2.0.0 (Major)
// Breaking changes
version: "2.0.0"
```

## Code Organization

### File Structure

Organize by functionality.

```
src/
├── index.ts                  # Skill definitions
├── tools/
│   ├── products/             # Product-related tools
│   │   ├── SearchTool.ts
│   │   ├── CreateTool.ts
│   │   └── UpdateTool.ts
│   ├── orders/               # Order-related tools
│   │   ├── CreateTool.ts
│   │   └── TrackTool.ts
│   └── shared/               # Shared tools
│       └── HelperTool.ts
└── services/                 # Shared utilities
    ├── ApiClient.ts
    └── Validator.ts
```

### Reuse Code

Extract common logic into services.

```typescript theme={null}
// services/EmailService.ts
export class EmailService {
  async send(to: string, subject: string, body: string) {
    const apiKey = env('SENDGRID_API_KEY');
    // Email sending logic
  }
}

// tools/OrderTool.ts
import { EmailService } from '../services/EmailService';

export class CreateOrderTool {
  private emailService = new EmailService();
  
  async execute(input: any) {
    const order = await createOrder(input);
    
    // Reuse email service
    await this.emailService.send(
      input.email,
      'Order Confirmation',
      `Your order ${order.id} is confirmed`
    );
    
    return order;
  }
}
```

## Security

### Never Hardcode Secrets

Always use environment variables.

<CodeGroup>
  ```typescript Good theme={null}
  import { env } from 'lua-cli';

  const apiKey = env('STRIPE_API_KEY');
  if (!apiKey) {
    throw new Error('STRIPE_API_KEY not configured');
  }
  ```

  ```typescript Bad theme={null}
  const apiKey = 'sk_test_abc123';  // DON'T DO THIS!
  ```
</CodeGroup>

### Validate User Input

Don't trust user input blindly.

```typescript theme={null}
async execute(input: any) {
  // Sanitize HTML
  const cleanTitle = input.title.replace(/<[^>]*>/g, '');
  
  // Validate URLs
  if (input.url && !isValidUrl(input.url)) {
    throw new Error('Invalid URL format');
  }
  
  // Check permissions
  const user = await User.get();
  if (!user.isAdmin && input.action === 'delete') {
    throw new Error('Insufficient permissions');
  }
}
```

### Don't Expose Sensitive Data

Be careful what you return.

```typescript theme={null}
// ✅ Good
return {
  name: user.name,
  email: user.email
};

// ❌ Bad
return { user };  // May include password hash, tokens, etc.
```

## Performance

### Cache When Appropriate

Avoid repeated API calls.

```typescript theme={null}
export class MyTool {
  private static configCache: any = null;
  
  async execute(input: any) {
    // Cache configuration
    if (!MyTool.configCache) {
      MyTool.configCache = await fetchConfig();
    }
    
    // Use cached data
    return processWithConfig(input, MyTool.configCache);
  }
}
```

### Pagination

Handle large datasets efficiently.

```typescript theme={null}
async execute(input: { page?: number, limit?: number }) {
  const page = input.page || 1;
  const limit = Math.min(input.limit || 20, 100); // Max 100
  
  const results = await Data.get('items', {}, page, limit);
  
  return {
    items: results.data,
    pagination: {
      current: page,
      total: results.pagination.totalPages,
      hasMore: results.pagination.hasNextPage
    }
  };
}
```

## Testing

### Test Edge Cases

Don't just test happy paths.

```typescript theme={null}
// Test with lua test:
// - Empty strings
// - Very large numbers
// - Special characters
// - Missing optional fields
// - Invalid formats
// - Boundary values
```

### Use Dev Mode

Test conversationally before deploying.

```bash theme={null}
lua chat  # Choose sandbox mode

# Test in chat:
# - "What's the weather in London?"  ✅
# - "What's the weather?"            ❌ Missing city
# - "Weather in XYZ123"              ❌ Invalid city
# - "Show me weather"                ❌ Unclear intent
```

## Deployment

### Pre-Deployment Checklist

* ✅ All tools tested with `lua chat` (sandbox mode)
* ✅ Individual tools tested with `lua test` if needed
* ✅ Version number updated
* ✅ Tool descriptions updated
* ✅ Error messages are helpful
* ✅ No hardcoded secrets
* ✅ Environment variables documented in `.env.example`
* ✅ Environment configured with `lua env`
* ✅ README updated

### Gradual Rollout

Test in sandbox before production.

```bash theme={null}
# 1. Push to server
lua push

# 2. Test in sandbox
lua chat  # Choose sandbox mode

# 3. If good, deploy
lua deploy
```

## Monitoring

### Log Important Events

```typescript theme={null}
async execute(input: any) {
  console.log(`Processing order for ${input.productId}`);
  
  try {
    const result = await processOrder(input);
    console.log(`Order created: ${result.id}`);
    return result;
  } catch (error) {
    console.error(`Order failed: ${error.message}`);
    throw error;
  }
}
```

### Track Errors

```typescript theme={null}
async execute(input: any) {
  try {
    return await riskyOperation(input);
  } catch (error) {
    // Log for monitoring
    console.error('Operation failed:', {
      tool: this.name,
      input,
      error: error.message,
      timestamp: new Date().toISOString()
    });
    
    // User-friendly error
    throw new Error('Unable to complete request. Please try again.');
  }
}
```

## Documentation

### Comment Complex Logic

```typescript theme={null}
async execute(input: any) {
  // Calculate discount based on loyalty tier
  // Bronze: 5%, Silver: 10%, Gold: 15%
  const discount = calculateDiscount(user.loyaltyTier);
  
  // Apply discount with maximum cap of $50
  const finalPrice = Math.max(
    price - discount,
    price - 50
  );
  
  return { finalPrice };
}
```

### Update README

Keep project README current with:

* What the skill does
* How to set it up
* Required environment variables
* How to test
* How to deploy

## Next Steps

<CardGroup>
  <Card title="Tool Examples" icon="layer-group" href="/examples/overview">
    See 30+ examples following these practices
  </Card>

  <Card title="API Reference" icon="book" href="/api/overview">
    Complete API documentation
  </Card>
</CardGroup>


# Building Skills
Source: https://docs.heylua.ai/template/building-skills

Step-by-step guide to creating custom skills

## Building Process

<Steps>
  <Step title="Plan Your Skill">
    Define what your skill will do and what tools it needs
  </Step>

  <Step title="Create Tools">
    Implement tools as TypeScript classes
  </Step>

  <Step title="Define Skill">
    Add tools to a LuaSkill instance in `index.ts`
  </Step>

  <Step title="Test Locally">
    Test with `lua chat` (sandbox mode) and optionally `lua test`
  </Step>

  <Step title="Deploy">
    Push and deploy to production
  </Step>
</Steps>

## Complete Example: Task Management Skill

### Step 1: Plan

**Goal**: Build a skill to manage tasks

**Tools needed**:

* `create_task` - Add new tasks
* `list_tasks` - View all tasks
* `complete_task` - Mark tasks as done
* `search_tasks` - Find tasks

### Step 2: Create Tools

Create `src/tools/TaskTools.ts`:

```typescript theme={null}
import { LuaTool, Data } from "lua-cli";
import { z } from "zod";

export class CreateTaskTool implements LuaTool {
  name = "create_task";
  description = "Create a new task";
  
  inputSchema = z.object({
    title: z.string(),
    description: z.string().optional(),
    priority: z.enum(['low', 'medium', 'high']).default('medium')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const task = await Data.create('tasks', {
      ...input,
      status: 'pending',
      createdAt: new Date().toISOString()
    }, `${input.title} ${input.description || ''}`);
    
    return {
      taskId: task.id,
      message: `Task "${input.title}" created`
    };
  }
}

export class ListTasksTool implements LuaTool {
  name = "list_tasks";
  description = "List all tasks";
  inputSchema = z.object({});

  async execute(input: any) {
    const result = await Data.get('tasks', {}, 1, 50);
    
    return {
      tasks: result.data.map(entry => ({
        id: entry.id,
        ...entry.data
      })),
      count: result.pagination.totalCount
    };
  }
}

export class CompleteTaskTool implements LuaTool {
  name = "complete_task";
  description = "Mark a task as completed";
  
  inputSchema = z.object({
    taskId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const task = await Data.getEntry('tasks', input.taskId);
    
    await Data.update('tasks', input.taskId, {
      ...task.data,
      status: 'completed',
      completedAt: new Date().toISOString()
    });
    
    return {
      success: true,
      message: `Task completed!`
    };
  }
}
```

### Step 3: Configure Agent with Skill

Update `src/index.ts` to use the **LuaAgent pattern**:

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  CreateTaskTool,
  ListTasksTool,
  CompleteTaskTool
} from "./tools/TaskTools";

// Create skill
const taskSkill = new LuaSkill({
  name: "task-management-skill",
  description: "Manage tasks and to-do lists",
  context: `
    This skill helps users manage their tasks.
    
    - Use create_task when users want to add a new task
    - Use list_tasks to show all tasks
    - Use complete_task when users finish a task
    
    Always confirm task details before creating.
    When listing tasks, organize by priority.
  `,
  tools: [
    new CreateTaskTool(),
    new ListTasksTool(),
    new CompleteTaskTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "task-assistant",
  
  persona: `You are a helpful task management assistant.
  
Your role:
- Help users create and organize tasks
- Keep track of todos and deadlines
- Help users stay productive

Communication style:
- Friendly and encouraging
- Clear and concise
- Confirm before creating tasks`,

  
  skills: [taskSkill]
});
```

<Note>
  Use `LuaAgent` to configure your agent's persona, welcome message, and skills together. This is now the recommended pattern.
</Note>

### Step 4: Test

```bash theme={null}
# Test conversationally (primary)
lua chat

# Optional: Test individual tools
lua test
```

Select sandbox mode to test with your local skills.

### Step 5: Deploy

```bash theme={null}
lua push
lua deploy
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start Simple">
    Build one tool at a time:

    1. Create basic version
    2. Test thoroughly
    3. Add more features
    4. Test again
  </Accordion>

  <Accordion title="Use Descriptive Names">
    ```typescript theme={null}
    // ✅ Good
    name = "create_task"
    name = "search_products"
    name = "send_email"

    // ❌ Bad
    name = "task1"
    name = "do_stuff"
    name = "tool"
    ```
  </Accordion>

  <Accordion title="Write Clear Descriptions">
    ```typescript theme={null}
    // ✅ Good
    description = "Create a new task with title, description, and priority"

    // ❌ Bad
    description = "Creates tasks"
    ```
  </Accordion>

  <Accordion title="Validate Inputs">
    Use Zod for comprehensive validation:

    ```typescript theme={null}
    inputSchema = z.object({
      email: z.string().email(),
      age: z.number().min(0).max(120),
      priority: z.enum(['low', 'medium', 'high'])
    });
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    ```typescript theme={null}
    async execute(input: any) {
      try {
        const result = await api.call(input);
        return result;
      } catch (error) {
        throw new Error(
          `Failed to process request: ${error.message}`
        );
      }
    }
    ```
  </Accordion>

  <Accordion title="Return Structured Data">
    ```typescript theme={null}
    // ✅ Good - Structured
    return {
      success: true,
      taskId: task.id,
      message: "Task created"
    };

    // ❌ Bad - Unstructured
    return "Task created with ID 123";
    ```
  </Accordion>
</AccordionGroup>

## Common Patterns

### CRUD Pattern

```typescript theme={null}
// Create
export class CreateItemTool {
  async execute(input) {
    return await Data.create('items', input);
  }
}

// Read
export class GetItemTool {
  async execute(input) {
    return await Data.getEntry('items', input.id);
  }
}

// Update
export class UpdateItemTool {
  async execute(input) {
    return await Data.update('items', input.id, input.data);
  }
}

// Delete
export class DeleteItemTool {
  async execute(input) {
    return await Data.delete('items', input.id);
  }
}
```

### Search Pattern

```typescript theme={null}
export class SearchTool {
  async execute(input: { query: string }) {
    // Vector search
    const results = await Data.search(
      'items',
      input.query,
      10,
      0.7
    );
    
    return {
      items: results.map(entry => ({ id: entry.id, ...entry.data })),
      count: results.length
    };
  }
}
```

### External API Pattern

```typescript theme={null}
export class ExternalApiTool {
  async execute(input: any) {
    // Get API key from environment
    const apiKey = env('EXTERNAL_API_KEY');
    
    if (!apiKey) {
      throw new Error('API key not configured');
    }
    
    // Call external API
    const response = await fetch(apiUrl, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    return await response.json();
  }
}
```

## Next Steps

<CardGroup>
  <Card title="Multi-Skill Projects" icon="layer-group" href="/template/multi-skill-projects">
    Organize tools into multiple skills
  </Card>

  <Card title="Best Practices" icon="star" href="/template/best-practices">
    Advanced tips and patterns
  </Card>

  <Card title="Tool Examples" icon="wrench" href="/examples/overview">
    See 30+ working examples
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Follow complete tutorial
  </Card>
</CardGroup>


# Multi-Skill Projects
Source: https://docs.heylua.ai/template/multi-skill-projects

Organizing tools into multiple skills

## Overview

You can define multiple skills in one project to organize tools logically, then add them all to your agent.

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

// Single project, multiple skills
const catalogSkill = new LuaSkill({...});
const cartSkill = new LuaSkill({...});
const orderSkill = new LuaSkill({...});

// Configure agent with all skills
export const agent = new LuaAgent({
  name: "ecommerce-agent",
  persona: "You are a helpful shopping assistant...",
  skills: [catalogSkill, cartSkill, orderSkill]
});
```

## When to Use Multiple Skills

<Tabs>
  <Tab title="Use Multiple When">
    ✅ Tools serve different purposes

    ✅ Different teams own different skills

    ✅ Skills need different deployment schedules

    ✅ Clear logical separation
  </Tab>

  <Tab title="Use Single When">
    ✅ Tools work together closely

    ✅ Small to medium number (\< 20 tools)

    ✅ All tools deploy together

    ✅ Simple use case
  </Tab>
</Tabs>

## Example: E-commerce Platform

```typescript theme={null}
import { LuaAgent, LuaSkill } from "lua-cli";
import {
  SearchProductsTool,
  GetProductTool
} from "./tools/ProductTools";
import {
  CreateBasketTool,
  AddItemTool
} from "./tools/BasketTools";
import {
  CreateOrderTool,
  TrackOrderTool
} from "./tools/OrderTools";

// Skill 1: Product Catalog
const catalogSkill = new LuaSkill({
  name: "catalog-skill",
  description: "Product browsing and search",
  context: `
    Use search_products when users want to find items.
    Use get_product for detailed product information.
  `,
  tools: [
    new SearchProductsTool(),
    new GetProductTool()
  ]
});

// Skill 2: Shopping Cart
const cartSkill = new LuaSkill({
  name: "cart-skill",
  description: "Shopping cart management",
  context: `
    Use create_basket to start shopping.
    Use add_item to add products to cart.
  `,
  tools: [
    new CreateBasketTool(),
    new AddItemTool()
  ]
});

// Skill 3: Order Management
const orderSkill = new LuaSkill({
  name: "order-skill",
  description: "Order creation and tracking",
  context: `
    Use create_order to finalize purchase.
    Use track_order for delivery status.
  `,
  tools: [
    new CreateOrderTool(),
    new TrackOrderTool()
  ]
});

// Configure agent with all skills
export const agent = new LuaAgent({
  name: "ecommerce-assistant",
  
  persona: `You are a helpful e-commerce shopping assistant.
  
Your role:
- Help customers find products
- Assist with shopping cart management
- Process orders and track deliveries

Communication style:
- Friendly and professional
- Proactive with suggestions
- Clear about pricing and availability`,

  
  skills: [catalogSkill, cartSkill, orderSkill]
});
```

## Benefits

<CardGroup>
  <Card title="Logical Organization" icon="folder-tree">
    Group related tools together
  </Card>

  <Card title="Independent Versions" icon="code-branch">
    Version each skill separately
  </Card>

  <Card title="Clear Ownership" icon="users">
    Different teams maintain different skills
  </Card>

  <Card title="Flexible Deployment" icon="rocket">
    Deploy skills independently
  </Card>
</CardGroup>

## How It Works

### Configuration

`lua.skill.yaml` tracks all skills:

```yaml theme={null}
agent:
  agentId: agent_abc123
  orgId: org_xyz789

skills:
  - name: catalog-skill
    version: 1.0.0
    skillId: skill_abc123
  - name: cart-skill
    version: 1.0.0
    skillId: skill_def456
  - name: order-skill
    version: 1.0.0
    skillId: skill_ghi789
```

### Deployment

All skills push and deploy together:

```bash theme={null}
lua push    # Uploads all 3 skills
lua deploy  # Deploys all 3 skills
```

## Real-World Examples

### Customer Service Platform

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

// FAQ & Knowledge Base
const knowledgeSkill = new LuaSkill({
  name: "knowledge-skill",
  tools: [
    new SearchArticlesTool(),
    new GetArticleTool()
  ]
});

// Ticket Management
const ticketSkill = new LuaSkill({
  name: "ticket-skill",
  tools: [
    new CreateTicketTool(),
    new UpdateTicketTool(),
    new GetTicketStatusTool()
  ]
});

// Account Management
const accountSkill = new LuaSkill({
  name: "account-skill",
  tools: [
    new GetAccountTool(),
    new UpdateAccountTool(),
    new ResetPasswordTool()
  ]
});

// Configure support agent
export const agent = new LuaAgent({
  name: "support-agent",
  persona: "You are a customer support specialist. Help users with their questions, create tickets when needed, and manage accounts.",
  skills: [knowledgeSkill, ticketSkill, accountSkill]
});
```

### Restaurant Management

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

// Menu & Orders
const menuSkill = new LuaSkill({
  name: "menu-skill",
  tools: [
    new ShowMenuTool(),
    new CreateOrderTool()
  ]
});

// Reservations
const reservationSkill = new LuaSkill({
  name: "reservation-skill",
  tools: [
    new MakeReservationTool(),
    new CheckAvailabilityTool(),
    new CancelReservationTool()
  ]
});

// Loyalty Program
const loyaltySkill = new LuaSkill({
  name: "loyalty-skill",
  tools: [
    new CheckPointsTool(),
    new RedeemRewardTool()
  ]
});

// Configure restaurant agent
export const agent = new LuaAgent({
  name: "restaurant-assistant",
  persona: "You are a friendly restaurant assistant. Help with menu questions, take orders, manage reservations, and handle loyalty rewards.",
  skills: [menuSkill, reservationSkill, loyaltySkill]
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Skills Focused">
    Each skill should have a clear, single purpose:

    ✅ Good: "product-catalog-skill", "order-management-skill"

    ❌ Bad: "general-skill", "everything-skill"
  </Accordion>

  <Accordion title="Limit Tools Per Skill">
    Keep skills manageable:

    * Small: 2-5 tools
    * Medium: 6-10 tools
    * Large: 11-20 tools
    * Too large: > 20 tools (consider splitting)
  </Accordion>

  <Accordion title="Version Independently">
    Each skill is versioned independently in `lua.skill.yaml`:

    ```yaml theme={null}
    skills:
      - name: skill-1
        version: "2.0.0"  # Major update
        skillId: "..."
      - name: skill-2
        version: "1.0.1"  # Bug fix only
        skillId: "..."
    ```
  </Accordion>

  <Accordion title="Share Common Code">
    Use services for shared logic:

    ```typescript theme={null}
    // services/ApiClient.ts
    export class ApiClient {
      // Shared API logic
    }

    // Use in multiple skills
    import { ApiClient } from '../services/ApiClient';
    ```
  </Accordion>
</AccordionGroup>

## Migration Strategies

### From Single to Multiple Skills

<Steps>
  <Step title="Identify Groups">
    Group related tools together
  </Step>

  <Step title="Create New Skills">
    Define new LuaSkill instances
  </Step>

  <Step title="Move Tools">
    Assign tools to appropriate skills
  </Step>

  <Step title="Update Context">
    Write specific context for each skill
  </Step>

  <Step title="Test">
    Test all skills together
  </Step>

  <Step title="Deploy">
    Push and deploy as usual
  </Step>
</Steps>

### Example Migration

**Before (Single Skill):**

```typescript theme={null}
const allInOne = new LuaSkill({
  name: "all-in-one",
  tools: [
    new SearchProductsTool(),
    new CreateBasketTool(),
    new CreateOrderTool(),
    // 20 more tools...
  ]
});
```

**After (multiple skills):**

```typescript theme={null}
import { LuaAgent, LuaSkill } from 'lua-cli';

const productsSkill = new LuaSkill({
  name: "products",
  tools: [new SearchProductsTool(), ...]
});

const cartSkill = new LuaSkill({
  name: "cart",
  tools: [new CreateBasketTool(), ...]
});

const orderSkill = new LuaSkill({
  name: "orders",
  tools: [new CreateOrderTool(), ...]
});

// Configure agent with organized skills
export const agent = new LuaAgent({
  name: "ecommerce-agent",
  persona: "You are a helpful shopping assistant...",
  skills: [productsSkill, cartSkill, orderSkill]
});
```

## Next Steps

<CardGroup>
  <Card title="Best Practices" icon="star" href="/template/best-practices">
    Advanced tips and patterns
  </Card>

  <Card title="Tool Examples" icon="layer-group" href="/examples/overview">
    See working multi-skill examples
  </Card>
</CardGroup>


# Template Overview
Source: https://docs.heylua.ai/template/overview

Understanding the project template and optional examples

## What You Get

When you run `lua init`, you get a **minimal, clean project** ready for you to build your agent:

<CardGroup>
  <Card title="Empty Agent" icon="rocket">
    A clean slate - no example code cluttering your project
  </Card>

  <Card title="TypeScript Setup" icon="code">
    Full type safety and configuration included
  </Card>

  <Card title="Ready to Deploy" icon="upload">
    All configuration files in place
  </Card>

  <Card title="Quick Start Guide" icon="book">
    Step-by-step instructions included
  </Card>
</CardGroup>

## Minimal vs Full Template

<Tabs>
  <Tab title="Minimal (Default)">
    ```bash theme={null}
    lua init
    ```

    Creates a clean project with just the essentials:

    ```
    your-project/
    ├── src/
    │   └── index.ts          # Empty agent ready to customize
    ├── lua.skill.yaml        # Configuration
    ├── package.json          # Dependencies
    └── tsconfig.json         # TypeScript config
    ```

    **Best for:** Experienced developers who want a clean slate
  </Tab>

  <Tab title="With Examples">
    ```bash theme={null}
    lua init --with-examples
    ```

    Creates a full project with 30+ working examples:

    ```
    your-project/
    ├── src/
    │   └── index.ts          # Agent configuration
    ├── examples/             # 👈 Example code
    │   ├── skills/           # Example skills & tools
    │   ├── webhooks/         # Example HTTP endpoints
    │   ├── jobs/             # Example scheduled tasks
    │   ├── preprocessors/    # Example message filters
    │   └── postprocessors/   # Example response formatters
    ├── lua.skill.yaml
    ├── package.json
    └── tsconfig.json
    ```

    **Best for:** New users who want to learn by example
  </Tab>
</Tabs>

## Quick Start (Minimal Template)

<Steps>
  <Step title="Initialize Your Project">
    ```bash theme={null}
    mkdir my-agent && cd my-agent
    lua init
    ```
  </Step>

  <Step title="Chat with Your Agent">
    ```bash theme={null}
    lua chat
    ```

    Select sandbox mode. Your agent works out of the box!
  </Step>

  <Step title="Create Your First Tool">
    Create `src/skills/tools/GreetingTool.ts`:

    ```typescript theme={null}
    import { LuaTool } from "lua-cli";
    import { z } from "zod";

    export default class GreetingTool implements LuaTool {
        name = "greet_user";
        description = "Generate a personalized greeting";
        
        inputSchema = z.object({
            name: z.string()
        });

        async execute(input: z.infer<typeof this.inputSchema>) {
            return { greeting: `Hello, ${input.name}!` };
        }
    }
    ```
  </Step>

  <Step title="Create a Skill">
    Create `src/skills/greeting.skill.ts`:

    ```typescript theme={null}
    import { LuaSkill } from "lua-cli";
    import GreetingTool from "./tools/GreetingTool";

    export default new LuaSkill({
        name: "greeting-skill",
        description: "Greeting tools",
        context: "Use when users want greetings",
        tools: [new GreetingTool()],
    });
    ```
  </Step>

  <Step title="Add to Your Agent">
    Update `src/index.ts`:

    ```typescript theme={null}
    import { LuaAgent } from "lua-cli";
    import greetingSkill from "./skills/greeting.skill";

    const agent = new LuaAgent({
        name: `My Agent`,
        persona: `You are a friendly assistant.`,
        skills: [greetingSkill],
    });
    ```
  </Step>

  <Step title="Test & Deploy">
    ```bash theme={null}
    lua test                           # Test your tool
    lua chat                           # Chat with your agent
    lua push all --force --auto-deploy # Deploy
    ```
  </Step>
</Steps>

## Examples (--with-examples)

When you use `lua init --with-examples`, you get comprehensive examples:

### Example Skills & Tools

<Tabs>
  <Tab title="Platform APIs">
    * `UserDataTool.ts` - User API (get/update user data)
    * `ProductsTool.ts` - Products API (CRUD operations)
    * `BasketTool.ts` - Baskets API (shopping cart)
    * `OrderTool.ts` - Orders API (order management)
    * `CustomDataTool.ts` - Data API (custom collections + semantic search)
  </Tab>

  <Tab title="External APIs">
    * `GetWeatherTool.ts` - External HTTP API integration
    * `PaymentTool.ts` - Stripe payment links
    * `CreatePostTool.ts` - Simple POST request example
  </Tab>

  <Tab title="Advanced Patterns">
    * `SmartBasketTool.ts` - Dynamic job creation from tools
    * `GameScoreTrackerTool.ts` - Interval jobs that self-deactivate
  </Tab>
</Tabs>

### Example Webhooks

HTTP endpoints for external integrations:

| File                  | Purpose                              |
| --------------------- | ------------------------------------ |
| `PaymentWebhook.ts`   | Stripe payment notifications         |
| `UserEventWebhook.ts` | External events + WhatsApp templates |

### Example Jobs

Scheduled background tasks:

| File                             | Schedule Type               |
| -------------------------------- | --------------------------- |
| `HealthCheckJob.ts`              | Interval (every 5 minutes)  |
| `DailyCleanupJob.ts`             | Cron (daily at 2 AM)        |
| `DataMigrationJob.ts`            | One-time (specific date)    |
| `AbandonedBasketProcessorJob.ts` | Interval (batch processing) |

### Example Processors

| Type | File                 | Purpose                        |
| ---- | -------------------- | ------------------------------ |
| Pre  | `messageMatching.ts` | Modify/block incoming messages |
| Post | `modifyResponse.ts`  | Transform agent responses      |

## Using the Examples

### Copy What You Need

```bash theme={null}
# Initialize with examples
lua init --with-examples

# Copy a tool to your src
cp examples/skills/tools/GetWeatherTool.ts src/skills/tools/

# Import and use it
```

### Move the Entire Structure

```bash theme={null}
# Move all examples into your src
mv examples/skills src/
mv examples/webhooks src/
mv examples/jobs src/
```

## Key Files

### src/index.ts

Your agent's main configuration:

```typescript theme={null}
import { LuaAgent } from "lua-cli";

const agent = new LuaAgent({
    name: `your-agent-name`,
    persona: `Your agent's personality...`,
    skills: [],        // Add your skills here
    // webhooks: [],   // Optional: HTTP endpoints
    // jobs: [],       // Optional: Scheduled tasks
});
```

### lua.skill.yaml

Auto-managed configuration file:

```yaml theme={null}
agent:
  agentId: agent_abc123
  orgId: org_xyz789
  persona: "..."

skills:
  - name: my-skill
    version: 1.0.0
    skillId: skill_xyz  # Auto-created
```

<Warning>
  Don't manually edit `skillId`, `webhookId`, or `jobId` - they're auto-managed by the CLI!
</Warning>

## Next Steps

<CardGroup>
  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Step-by-step tutorial
  </Card>

  <Card title="Project Structure" icon="folder-tree" href="/template/project-structure">
    Understanding file organization
  </Card>

  <Card title="API Reference" icon="server" href="/api/overview">
    Available platform APIs
  </Card>

  <Card title="Best Practices" icon="star" href="/template/best-practices">
    Tips for building great agents
  </Card>
</CardGroup>


# Project Structure
Source: https://docs.heylua.ai/template/project-structure

Understanding the template project organization

## Overview

The Lua CLI creates a clean, minimal project structure by default. You can optionally include examples with `--with-examples`.

<Tabs>
  <Tab title="Minimal (Default)">
    ```
    your-project/
    ├── src/
    │   └── index.ts           # Agent configuration (LuaAgent)
    ├── lua.skill.yaml         # Configuration (auto-managed)
    ├── package.json           # Dependencies
    ├── tsconfig.json          # TypeScript config
    ├── .env.example           # Environment template
    └── README.md              # Quick start guide
    ```
  </Tab>

  <Tab title="With Examples">
    ```
    your-project/
    ├── src/
    │   └── index.ts           # Agent configuration
    ├── examples/              # Example code (reference only)
    │   ├── skills/            # Example skills & tools
    │   │   ├── tools/         # Tool implementations
    │   │   └── *.skill.ts     # Skill definitions
    │   ├── webhooks/          # HTTP endpoint examples
    │   ├── jobs/              # Scheduled task examples
    │   ├── preprocessors/     # Message filter examples
    │   ├── postprocessors/    # Response formatter examples
    │   └── services/          # Helper utilities
    ├── lua.skill.yaml
    ├── package.json
    ├── tsconfig.json
    └── README.md
    ```
  </Tab>

  <Tab title="After You Build">
    ```
    your-project/
    ├── src/
    │   ├── index.ts           # Agent configuration
    │   ├── skills/            # Your skills
    │   │   ├── tools/         # Your tools
    │   │   └── my.skill.ts
    │   ├── webhooks/          # Your webhooks (optional)
    │   ├── jobs/              # Your jobs (optional)
    │   └── services/          # Your utilities (optional)
    ├── dist/                  # Compiled output (auto-generated)
    ├── .lua/                  # CLI cache (auto-generated)
    ├── node_modules/          # Dependencies
    ├── lua.skill.yaml
    ├── package.json
    ├── tsconfig.json
    └── .env                   # Your environment variables
    ```
  </Tab>
</Tabs>

## Core Files

### src/index.ts

**Your agent's main configuration file.**

```typescript theme={null}
import { LuaAgent } from "lua-cli";

const agent = new LuaAgent({
    name: `my-agent`,
    persona: `You are a helpful assistant...`,
    
    skills: [],        // Add your skills here
    
    // Optional components:
    // webhooks: [],
    // jobs: [],
    // preProcessors: [],
    // postProcessors: [],
});
```

### lua.skill.yaml

**Auto-managed configuration file.** Created during `lua init`, updated automatically by CLI commands.

```yaml theme={null}
agent:
  agentId: agent_abc123
  orgId: org_xyz789

skills:
  - name: my-skill
    version: 1.0.0
    skillId: skill_xyz  # Auto-created during compile
```

<Warning>
  **Do not manually edit this file!** The `lua.skill.yaml` is managed by the CLI and stores state only (IDs and versions). All configuration belongs in your code:

  * **Persona** → `LuaAgent` in `src/index.ts`
  * **Tool definitions** → Your tool files
  * **Skill configuration** → `LuaSkill` in code
  * **Environment variables** → `.env` file or `lua env` command

  The only exception: you may manually increment the `version` number before pushing a new release.
</Warning>

<Note>
  IDs like `skillId`, `webhookId`, and `jobId` are auto-generated during compilation. Never edit these manually.
</Note>

### package.json

Standard Node.js package configuration:

```json theme={null}
{
  "name": "lua-skill",
  "type": "module",
  "dependencies": {
    "lua-cli": "^3.1.0",
    "zod": "^3.24.1"
  }
}
```

## Building Your Project

### Recommended Structure

As your project grows, organize it like this:

```
src/
├── index.ts                    # Agent configuration
├── skills/
│   ├── tools/                  # Tool implementations
│   │   ├── WeatherTool.ts
│   │   ├── ProductTools.ts     # Multiple related tools
│   │   └── OrderTool.ts
│   ├── weather.skill.ts        # Weather skill
│   └── ecommerce.skill.ts      # E-commerce skill
├── webhooks/                   # (Optional) HTTP endpoints
│   └── PaymentWebhook.ts
├── jobs/                       # (Optional) Scheduled tasks
│   └── DailyReportJob.ts
└── services/                   # (Optional) Shared utilities
    └── ApiClient.ts
```

### File Naming Conventions

| Type           | Pattern                   | Example                             |
| -------------- | ------------------------- | ----------------------------------- |
| Tools          | `*Tool.ts` or `*Tools.ts` | `WeatherTool.ts`, `ProductTools.ts` |
| Skills         | `*.skill.ts`              | `weather.skill.ts`                  |
| Webhooks       | `*Webhook.ts`             | `PaymentWebhook.ts`                 |
| Jobs           | `*Job.ts`                 | `DailyReportJob.ts`                 |
| Preprocessors  | `*.preprocessor.ts`       | `filter.preprocessor.ts`            |
| Postprocessors | `*.postprocessor.ts`      | `format.postprocessor.ts`           |

## Auto-Generated Directories

### dist/

Compiled JavaScript output. Created by `lua compile`.

```
dist/
├── deployment.json       # Deployment metadata
├── index.js             # Compiled main file
└── tools/               # Compiled tool bundles
```

### .lua/

CLI cache directory. Safe to delete - will be regenerated.

## Environment Files

### .env

Your local environment variables (create this file):

```bash theme={null}
# External API Keys
STRIPE_API_KEY=sk_test_abc123
OPENAI_API_KEY=sk-...

# Configuration
API_BASE_URL=https://api.example.com
```

<Warning>
  Add `.env` to `.gitignore` - never commit secrets!
</Warning>

### .env.example

Template for environment variables (commit this):

```bash theme={null}
STRIPE_API_KEY=your_stripe_key_here
OPENAI_API_KEY=your_openai_key_here
```

## Git Configuration

### ✅ Commit These

```
.gitignore
.env.example
lua.skill.yaml
package.json
tsconfig.json
README.md
src/
```

### ❌ Don't Commit These

```
.env
node_modules/
dist/
.lua/
```

### Sample .gitignore

```
# Dependencies
node_modules/

# Build output
dist/
.lua/

# Environment
.env
.env.local
.env.*.local

# OS
.DS_Store

# IDE
.vscode/
.idea/
```

## Project Size Patterns

<Tabs>
  <Tab title="Small (1-5 tools)">
    ```
    src/
    ├── index.ts
    └── skills/
        ├── tools/
        │   └── MyTools.ts    # All tools in one file
        └── my.skill.ts
    ```
  </Tab>

  <Tab title="Medium (5-15 tools)">
    ```
    src/
    ├── index.ts
    └── skills/
        ├── tools/
        │   ├── WeatherTool.ts
        │   ├── UserTools.ts
        │   └── ProductTools.ts
        ├── weather.skill.ts
        └── commerce.skill.ts
    ```
  </Tab>

  <Tab title="Large (15+ tools)">
    ```
    src/
    ├── index.ts
    ├── skills/
    │   ├── weather/
    │   │   ├── tools/
    │   │   └── weather.skill.ts
    │   ├── commerce/
    │   │   ├── tools/
    │   │   └── commerce.skill.ts
    │   └── support/
    │       ├── tools/
    │       └── support.skill.ts
    ├── webhooks/
    ├── jobs/
    └── services/
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Building Skills" icon="hammer" href="/template/building-skills">
    Learn how to build custom skills
  </Card>

  <Card title="Best Practices" icon="star" href="/template/best-practices">
    Follow recommended patterns
  </Card>

  <Card title="API Reference" icon="server" href="/api/overview">
    Available platform APIs
  </Card>

  <Card title="Examples" icon="code" href="/examples/overview">
    See working code examples
  </Card>
</CardGroup>


# Authoring Workflows
Source: https://docs.heylua.ai/workflows/authoring

The workflow SDK - steps, containers, bindings, predicates, approvals, signals, budgets and starting runs from code

## Overview

A workflow is written with two functions from `lua-cli`:

* `createStep({...})` declares a code step: typed input and output plus an `execute` function.
* `createWorkflow({...})` returns a builder; chain steps and containers on it and finish with `.commit()`.

```typescript theme={null}
import { z } from 'zod';
import { createStep, createWorkflow, fromStep, template, step, eq, lit } from 'lua-cli';

const wf = createWorkflow({ name: 'my-flow', inputSchema: z.object({ id: z.string() }) })
  .then(loadThing)
  .agentStep('summarise', { agentId: '$self', prompt: template('Summarise ${stepResults.loadThing.text}') })
  .switch([[eq(step(loadThing).path('kind'), lit('bug')), 'triage']], 'done')
  .agentStep('triage', { agentId: '$self', prompt: template('Triage ${stepResults.summarise.text}') })
  .then(done)
  .commit();
```

`defineWorkflow(config, (wf) => wf.then(...).commit())` is equivalent sugar. Put workflows anywhere under `src/` (the compiler finds every `createWorkflow(...).commit()` chain and every `defineWorkflow` call); `src/workflows/` is the convention. Optionally list them on your `LuaAgent` under `workflows: [...]`.

<Warning>
  The graph must be static. Predicates and bindings are built with the helpers below - a function where a predicate, a template or a mapping is expected fails the build with `closure-predicate` / `closure-binding`. Anything that must be computed goes inside a step's `execute`.
</Warning>

## `createWorkflow` config

| Field               | Type                                              | Notes                                                                                                                                              |
| ------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | `string`                                          | `^[a-z][a-z0-9-_]*$`. The server identifier and what the CLI addresses.                                                                            |
| `description`       | `string`                                          | Shown in `lua workflows list` and the desktop.                                                                                                     |
| `inputSchema`       | zod schema                                        | Validated on every start (a bad input is a 400).                                                                                                   |
| `outputSchema`      | zod schema                                        | Validates the run output.                                                                                                                          |
| `stateSchema`       | zod schema                                        | Types `ctx.state`; the run-scoped store is capped at 64 KB.                                                                                        |
| `budget`            | `{ maxCredits?, maxSteps?, maxDurationSeconds? }` | `maxDurationSeconds` defaults to 604 800 (7 days), or 2 592 000 (30 days) when the graph has an approval, a signal wait or a suspend-capable step. |
| `concurrencyPolicy` | `'allow' \| 'forbid'`                             | `'forbid'` refuses a new start while a run is in flight (409 `RUNS_IN_FLIGHT` with the blocking run id).                                           |
| `schedule`          | job schedule                                      | The same `{ type: 'cron' \| 'interval' \| 'once', ... }` shape as a `LuaJob`.                                                                      |
| `scheduleInput`     | object                                            | Literal run input for every scheduled fire; required when `inputSchema` has required keys and validated against it.                                |
| `backfillOnEnable`  | `{ maxOccurrences? }`                             | 1..200 missed occurrences to replay when a paused schedule is re-enabled.                                                                          |
| `outputVisibility`  | `{ roles, users?, ownerBypass? }`                 | Restricts who can read run outputs (at most 20 roles and 50 users).                                                                                |
| `workspace`         | workspace spec                                    | A git or empty volume for Job-tier steps. See [Job tier](/workflows/job-tier).                                                                     |

## `createStep`

```typescript theme={null}
const sendEmails = createStep({
  id: 'sendEmails',
  inputSchema: z.object({ drafts: z.array(draft) }),
  outputSchema: z.object({ sent: z.number() }),
  timeoutSeconds: 120,
  retry: { maxAttempts: 3, backoffSeconds: 10, backoff: 'exponential' },
  sideEffects: 'external',
  onError: 'park',
  async execute({ inputData, once, log }) {
    let sent = 0;
    for (const d of inputData.drafts) {
      const r = await once(d.to, () => Channels.email.send({ to: { email: d.to }, subject: 'Hello', body: d.body }));
      if (r) sent++;
    }
    log(`sent ${sent}`);
    return { sent };
  },
});
```

| Field                                           | Notes                                                                                                                                                                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                            | `^[a-z][a-zA-Z0-9_-]{0,63}$`, unique within the workflow.                                                                                                                                                                         |
| `inputSchema` / `outputSchema`                  | zod. The output is validated by the engine; a mismatch fails the attempt.                                                                                                                                                         |
| `execute(ctx)`                                  | Returns the output. Re-runs from the top after a resume.                                                                                                                                                                          |
| `timeoutSeconds`                                | Worker tier 1..600 (default 300). Job tier up to 14 400 for a code step (default 3600).                                                                                                                                           |
| `retry`                                         | `{ maxAttempts, backoffSeconds?, backoff?: 'fixed' \| 'exponential', maxBackoffSeconds? }`. Default `{ maxAttempts: 1 }`. Backoff is an engine timer, not a sleep in your code.                                                   |
| `sideEffects`                                   | `'none'` (default) or `'external'`. An external step that is interrupted by a platform fault is parked for a person instead of being retried automatically.                                                                       |
| `onError`                                       | What the final failure does to the run: `'fail'` (default), `'continue'` (the step's output is `null` and the run goes on), `'park'` (the run waits on an exception gate for a person to retry, skip, complete or fail the step). |
| `requiredConnections`                           | Connection ids the step needs; an unmountable one fails the step with `credentials_revoked`.                                                                                                                                      |
| `suspendSchema` / `resumeSchema`                | Types for `ctx.suspend(payload)` and the `resumeData` a person supplies.                                                                                                                                                          |
| `resumeTimeoutHours`                            | Deadline for a `ctx.suspend()` park (default 168, max 720).                                                                                                                                                                       |
| `businessHours`                                 | `{ tz, calendar?: 'mon-fri' \| { days, start, end, holidays? } }` - deadlines count business time.                                                                                                                                |
| `onSuspendTimeout`                              | `'fail'` or `'cancel-run'`.                                                                                                                                                                                                       |
| `tier`, `workspace`, `jobResources`, `jobTools` | Job tier. See [Job tier](/workflows/job-tier).                                                                                                                                                                                    |

### The step context

`execute` receives one object:

| Member                                                          | What it is                                                                                                          |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `runId`, `workflowId`, `workflowVersionId`, `stepId`, `attempt` | Identity of this invocation.                                                                                        |
| `occurrenceId`                                                  | `<lineageId>:<stepId>` - the same across retries, resumes and repair runs. The key for de-duplicating side effects. |
| `lineageId`                                                     | The first run's id in a repair chain (equal to `runId` otherwise).                                                  |
| `inputData`                                                     | The step input after bindings are applied.                                                                          |
| `resumeData`, `suspendData`                                     | Present after a resume: what the person supplied, and what you passed to `suspend()`.                               |
| `getInitData()`                                                 | The run input.                                                                                                      |
| `getStepResult(stepId)`                                         | The output of an upstream step. Throws `STEP_RESULT_NOT_ANCESTOR` for a step that is not upstream.                  |
| `state.get(k)` / `state.set(k, v)`                              | Run-scoped key-value store (64 KB total).                                                                           |
| `suspend(payload)`                                              | Park this step until a person resumes it with data. Never returns.                                                  |
| `bail(result)`                                                  | Finish this step early with `result` as its output.                                                                 |
| `bailRun(output)`                                               | Finish the whole run successfully with `output`.                                                                    |
| `log(message)`                                                  | Emits a `step.progress` event (at most 1000 per attempt, 1 KB each).                                                |
| `signal`                                                        | An `AbortSignal` that fires on cancel and at the step wall.                                                         |
| `env`                                                           | The agent's environment variables.                                                                                  |
| `once(key, fn)`                                                 | Runs `fn` exactly once per `{ occurrenceId, key }`; a re-run returns the stored result.                             |
| `workspace`                                                     | Job tier only: `{ path, mount, branch?, baseSha?, arm? }`.                                                          |
| `artefacts.put / get / list`                                    | The run's artefact store (files, datasets, images, documents).                                                      |
| `runtime`                                                       | `{ trigger, parentRunId?, correlationKey?, tags?, principalKind, replyTo? }`.                                       |

<Note>
  Execution is at-least-once: a step can run again after a crash, a retry, a resume or a repair run. Wrap anything with an external effect in `ctx.once(key, fn)`, or send your own idempotency key (for example `refund:${ticketId}`) when the effect must be unique across independent runs.
</Note>

## The builder chain

| Call                                                                                | What it adds                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.then(step)`                                                                       | A code step (or a string naming a step declared elsewhere in the chain).                                                                                                                                      |
| `.parallel([a, b, ...], { merge? })`                                                | 2..16 arms run concurrently. Output is `{ [stepId]: output }`. `merge` applies to Job-tier worktree arms.                                                                                                     |
| `.switch([[predicate, step], ...], otherwise?)`                                     | The first true arm runs.                                                                                                                                                                                      |
| `.branch([[predicate, step], ...], { exclusive? })`                                 | Every true arm runs (`exclusive: true` behaves like `switch`).                                                                                                                                                |
| `.foreach(step, { items?, concurrency?, maxItems?, chunk?, rateLimit? })`           | Runs the step once per item. `concurrency` 1..16 (default 4); `maxItems` default 256, hard ceiling 20 000 - exceeding it fails fast, never truncates. The body receives the raw item; the output is an array. |
| `.dowhile(step, predicate, { maxIterations?, intervalSeconds? })` / `.dountil(...)` | A loop. `maxIterations` default 100; a predicate that is still true at the cap fails the run, so make the predicate bound itself. `intervalSeconds` 1..86 400 waits between iterations.                       |
| `.map({ key: descriptor, ... }, { id })`                                            | Reshapes data. Once a workflow has two or more maps every map needs an explicit `id`. The key `''` means "the output is this value".                                                                          |
| `.sleep(ms)` / `.sleepUntil(iso \| template)`                                       | Engine-side waits; accept `businessHours`.                                                                                                                                                                    |
| `.agentStep(id, opts)`                                                              | An agent turn.                                                                                                                                                                                                |
| `.specialistStep(id, opts)`                                                         | A turn of the owning agent under a role.                                                                                                                                                                      |
| `.toolStep(id, tool, opts)`                                                         | A direct tool call.                                                                                                                                                                                           |
| `.approval(id, opts)`                                                               | A human decision. Top-level only.                                                                                                                                                                             |
| `.waitForSignal(id, opts)`                                                          | Waits for an external signal. Top-level only.                                                                                                                                                                 |
| `.workflow(id, refOrName, input?, { workspace?: 'inherit' })`                       | A child run (nesting depth at most 3).                                                                                                                                                                        |
| `.commit()`                                                                         | Validates and returns the `LuaWorkflow`.                                                                                                                                                                      |

### Placement: declare inside the container

A string in a container refers to a step declared by `agentStep` / `specialistStep` / `toolStep` / `map(..., { id })` anywhere else in the same chain, and places that step **inside** the container:

```typescript theme={null}
createWorkflow({ ... })
  .parallel(['techAngle', 'marketAngle'])                 // two arms, declared below
  .agentStep('techAngle', { ... })                          // placed by the parallel above, not a new entry
  .agentStep('marketAngle', { ... })
  .switch([[gt(stepOf<typeof angle>('techAngle').path('confidence'), lit(0.6)), 'merge']], 'lowConfidence')
  .map({ brief: fromStep('techAngle', 'summary') }, { id: 'merge' })   // inside the switch arm
  .agentStep('lowConfidence', { ... })                      // the switch's otherwise
  .commit();
```

If a conditional is the last entry, the taken arm's output is the run output.

## Data flow

### Mapping helpers

| Helper                                                              | Meaning                                                                                        |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `fromInit(path)`                                                    | A value from the run input.                                                                    |
| `fromStep(step, path?)`                                             | A value from an upstream step's output (`path` omitted = the whole output).                    |
| `value(v)`                                                          | A literal.                                                                                     |
| `rows(step, path, { offset, limit })`                               | A page of rows from an array-typed output that was stored as a dataset.                        |
| `fromKnowledge({ source, query, maxChars?, topK?, connectionId? })` | Text retrieved from `org-docs`, `memory` or a `connection`, rendered with a provenance header. |
| `fromRequest(path)`                                                 | A value from the request that started the run.                                                 |
| `env.template(KEY)`                                                 | A per-environment value resolved at push time (see below).                                     |

### Prompt bindings

`template('...')` strings are resolved by the engine when the step is dispatched:

* `${initData.<path>}` - the run input
* `${stepResults.<stepId>.<path>}` - an upstream output
* `${state.<key>}` - the run state

Objects and arrays are JSON-encoded inside the prompt; a missing value is left verbatim. Prompt strings are plain single-quoted strings so TypeScript never interpolates them.

### Predicates

Build predicates from typed references and literals:

```typescript theme={null}
import { step, stepOf, init, state, lit, eq, ne, gt, gte, lt, lte, inSet, notIn, exists, notExists, truthy, falsy, and, or, not } from 'lua-cli';

step(fetchSources).path('urls')                    // typed by the step's outputSchema
stepOf<typeof Review>('reviewFix').path('verdict')  // typed string ref for an agentStep id
init<string>('kind')                                // the run input
state<number>('attempts')                           // run state

and(eq(reviewRef.path('verdict'), lit('revise')), lt(reviewRef.path('round'), lit(2)))
```

## Agent, specialist and tool steps

### `agentStep(id, opts)`

| Option                                                      | Notes                                                                                                                                                                                        |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentId`                                                   | A sub-agent id, `'$self'` for the owning agent, or `env.template(KEY)`.                                                                                                                      |
| `prompt`                                                    | A string, `template('...')` or `env.template(KEY)`.                                                                                                                                          |
| `outputSchema`                                              | zod. The model's reply is validated; a reply that does not match fails the attempt (`output_schema_invalid`), so pair it with `retry`.                                                       |
| `model`                                                     | Override the agent's model for this turn.                                                                                                                                                    |
| `toolScope`                                                 | `{ connectionIds?, skillIds?, toolIds?, jobTools? }`. `{}` means no tools. A step whose prompt carries external content (customer messages, retrieved knowledge) must declare a `toolScope`. |
| `systemPrompt`                                              | A static persona override for the turn.                                                                                                                                                      |
| `timeoutSeconds`, `retry`, `onError`, `requiredConnections` | As for code steps.                                                                                                                                                                           |
| `tier`, `workspace`, `jobResources`, `harness`, `maxTurns`  | Job tier only. See [Job tier](/workflows/job-tier).                                                                                                                                          |

### `specialistStep(id, opts)`

Runs **your own agent** with an additive role - a name, instructions (at most 4000 characters) and a tool allowlist drawn from the agent's own tools (at most 64; delegation tools cannot be allowlisted). Use it for a reviewer, a verifier or a planner without creating another agent:

```typescript theme={null}
.specialistStep('review', {
  role: {
    name: 'Reviewer',
    instructions: 'You are a sceptical reviewer. Check every claim against a source you can cite; flag anything unsupported. Never rewrite the draft - return findings only.',
    tools: ['searchWeb', 'fetchUrl'],
  },
  prompt: template('Review the draft: ${stepResults.draft.text}'),
  outputSchema: z.object({ findings: z.array(z.string()), verdict: z.enum(['pass', 'revise']) }),
})
```

`role: { ref: 'reviewer' }` points at a role from your organisation's role library instead of an inline definition.

### `toolStep(id, tool, opts)`

Calls a `LuaTool` directly with `input` built from mapping helpers, plus `timeoutSeconds`, `retry`, `sideEffects`, `onError` and `requiredConnections`.

## Approvals

```typescript theme={null}
.approval('approveRefund', {
  title: 'Refund request',
  details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
  approver: { role: 'support-lead' },
  excludeInitiator: true,
  timeoutHours: 8,
  businessHours: { tz: 'Europe/London', calendar: 'mon-fri' },
  onTimeout: [{ escalateTo: { role: 'finance-controller' }, timeoutHours: 16 }, { escalateTo: 'org-admins', timeoutHours: 24 }, 'deny'],
  editable: true,
  editablePaths: ['amount'],
  editedPayloadSchema: z.object({ ticketId: z.string(), amount: z.number().positive().max(500) }),
  fourEyes: { edit: { role: 'support-lead' }, approve: { role: 'finance-controller' } },
})
```

| Option                                             | Notes                                                                                                                           |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `title`                                            | Plain string, required.                                                                                                         |
| `details`                                          | `template('...')`, shown on the card.                                                                                           |
| `approver`                                         | `'creator'` (default), `'org-admins'`, `{ users: [...] }`, `{ role }`, `{ group }` or `{ governance: { policyId } }`.           |
| `excludeInitiator`                                 | The person who started the run can never approve it. Not allowed with `approver: 'creator'`.                                    |
| `timeoutHours`                                     | Default 168, 1..720; may be a template binding.                                                                                 |
| `onTimeout`                                        | `'deny'` (default), `'cancel-run'`, `'fail'`, or a chain of up to 3 `{ escalateTo, timeoutHours }` hops ending in one of those. |
| `onDeny`                                           | `'continue'` (default - a denial is data your next step reads) or `'fail'`.                                                     |
| `businessHours`                                    | Deadlines count business time.                                                                                                  |
| `editable`, `editablePaths`, `editedPayloadSchema` | Let the approver change the payload. Paths follow `drafts`, `drafts[*].body`, `drafts[3].body`, `summary.title`.                |
| `fourEyes`                                         | `{ edit, approve }` - whoever edits cannot be the one who approves. Requires `editable: true`.                                  |
| `itemsPath`, `itemApprover`, `itemTimeout`         | Per-item approvals over an array in the payload, each routed to its own approver (`{ fromItem: 'approverEmail' }`).             |

The card shows the previous step's output as the payload. The approval's own output is what the next step reads:

```typescript theme={null}
{ approved: boolean, timedOut?: boolean, note?: string, editedPayload?: T, input: T, escalations?: number }
```

Approvals and signal waits are top-level entries - they cannot sit inside `parallel`, `foreach` or a loop.

## Signals

A `waitForSignal` step parks the run until something outside delivers a named signal:

```typescript theme={null}
.waitForSignal('review', {
  signal: 'github.review',
  schema: z.object({ state: z.enum(['approved', 'changes_requested', 'commented']) }),
  timeoutHours: 168,
  acceptedSources: ['webhook'],
  onTimeout: 'continue',
})
```

| Option            | Notes                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `signal`          | 1..64 characters of `[a-zA-Z0-9_.-]`.                                                                           |
| `schema`          | zod; a payload that does not match is rejected with `SIGNAL_SCHEMA_INVALID`.                                    |
| `timeoutHours`    | Deadline; `onTimeout: 'fail'` (default) or `'continue'` (output `{ received: false, timedOut: true }`).         |
| `acceptedSources` | Which callers may deliver it: `'webhook'`, `'api'`, `'user'`, `'agent'` (default `['webhook', 'api', 'user']`). |

The step's output is `{ received: true, payload }` (or the timed-out shape above). Deliver signals from a webhook with `Workflows.signal`:

```typescript theme={null}
import { LuaWebhook, Workflows } from 'lua-cli';

export default new LuaWebhook({
  name: 'github-pr-review',
  async execute({ headers, body }) {
    if (headers['x-github-event'] !== 'pull_request_review') return { ignored: true };
    const runId = /<!-- lua-run:(wfr_[A-Za-z0-9_-]+) -->/.exec(body.pull_request?.body ?? '')?.[1];
    if (!runId) return { ignored: true };
    const r = await Workflows.signal(runId, 'github.review', { state: body.review.state }, { dedupeKey: `review:${body.review.id}` });
    return { runId, accepted: r.accepted, reason: r.reason };
  },
});
```

A signal that arrives before the run waits for it is parked and consumed when the wait begins (each run holds at most 256 parked signals; payloads are at most 64 KB). `dedupeKey` makes a redelivered webhook a no-op. A signal that reaches a parent run is handed down to a waiting child run.

## Nested workflows

```typescript theme={null}
.workflow('reviewRound', prReviewRound, { prNumber: fromStep('openPr', 'prNumber'), repo: fromInit('repo') }, { workspace: 'inherit' })
```

The child is a run of its own (`trigger: 'workflow'`), nested at most 3 deep. Reference another workflow by its `LuaWorkflow` value or by name on the same agent. `workspace: 'inherit'` runs the child on the parent's Job-tier workspace.

## Starting runs from code

`Workflows` is available in tools, jobs, webhooks, triggers and workflow code steps:

```typescript theme={null}
import { Workflows } from 'lua-cli';

const { runId, status, idempotentReplay } = await Workflows.start('outreach', { leads }, {
  idempotencyKey: `outreach:${batchId}`,
  correlationKey: batchId,
  tags: ['weekly'],
  budget: { maxCredits: 40 },
});
```

| Method                                                                | Notes                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start(nameOrId, input?, opts?)`                                      | Fire-and-return; never awaits execution. `opts`: `idempotencyKey`, `budget`, `waitSeconds` (0..55, a server long-poll), `initialState`, `correlationKey`, `tags` (at most 10), `replyTo`, `onBehalfOf`, `workflowVersionId`. Returns `{ runId, status }` where `status` is `queued` or `gated`. |
| `get(runId)`                                                          | The run (a restricted run comes back with `restricted: true` and no `output`).                                                                                                                                                                                                                  |
| `list({ limit?, status?, workflow?, correlationKey?, tags?, sort? })` | Runs on the agent.                                                                                                                                                                                                                                                                              |
| `cancel(runId, { mode?: 'request' \| 'force', reason? })`             | See [cancel](/workflows/runs-and-events#cancelling).                                                                                                                                                                                                                                            |
| `resume(runId, stepId, resumeData)`                                   | Resume a step parked by `ctx.suspend()`.                                                                                                                                                                                                                                                        |
| `signal(runId, name, payload?, { dedupeKey? })`                       | Deliver a signal.                                                                                                                                                                                                                                                                               |
| `signalByKey(nameOrId, correlationKey, name, payload?, opts?)`        | Deliver to the live run(s) with that correlation key.                                                                                                                                                                                                                                           |
| `startBatch(nameOrId, items, opts?)`                                  | Start many runs; each item carries its own `idempotencyKey`.                                                                                                                                                                                                                                    |
| `raiseBudget(runId, patch)`                                           | Raise a parked run's budget.                                                                                                                                                                                                                                                                    |

**Idempotency.** A second `start` with the same `idempotencyKey` on the same agent returns the original run (`idempotentReplay: true`) instead of creating another. Keys are at most 128 characters. A `concurrencyPolicy: 'forbid'` workflow with a run in flight throws `RUNS_IN_FLIGHT` with `blockingRunId`.

From a code step, `Workflows.start` creates a detached run; use the `.workflow()` node when the parent should wait for the child.

### From a trigger

A `LuaTrigger` can start a run by returning `startWorkflow` from `transform`:

```typescript theme={null}
export default new LuaTrigger({
  name: 'linear-ready-for-agent',
  source: 'webhook',
  filter: (ctx) => ctx.payload?.type === 'Issue' && (ctx.payload.data?.labels ?? []).some((l) => l.name === 'ready-for-agent'),
  transform: (ctx) => ({
    startWorkflow: {
      name: 'ticket-to-pr',
      input: { ticketId: ctx.payload.data.identifier, title: ctx.payload.data.title },
      idempotencyKey: `linear:${ctx.payload.data.identifier}:ready-for-agent`,
    },
  }),
});
```

## Budgets and policy hooks

* `budget.maxCredits`, `maxSteps` and `maxDurationSeconds` on the definition are the per-run defaults; `Workflows.start` and `lua workflows start --budget-credits` can lower or override them. When a dimension runs out the run parks on a `budget` gate and can be raised (`raiseBudget`, or the desktop).
* `concurrencyPolicy: 'forbid'` is the overlap guard for scheduled workflows.
* `sideEffects: 'external'` plus `onError: 'park'` is the pattern for money-moving or PR-opening steps: a platform fault never re-runs them and a final failure waits for a person.
* `outputVisibility` restricts who can read a workflow's outputs; readers without access see `restricted: true`.
* `toolScope` on agent steps is mandatory when the prompt carries external content.

### Per-environment values

`env.template('KEY')` is resolved from the target environment when you `lua push workflow`, so staging and production can route to different agents or timezones from one source file:

```typescript theme={null}
createWorkflow({
  name: 'vendor-invoices',
  inputSchema: z.object({ batchId: z.string() }),
  schedule: { type: 'cron', expression: '0 6 * * 1-5', timezone: env.template('FINANCE_TZ') },
})
  .agentStep('policyCheck', { agentId: env.template('FINANCE_AGENT_ID'), prompt: template('...') })
```

A missing key aborts the push before anything is sent. Keys that look like secrets (ending in `SECRET`, `TOKEN`, `KEY`, `PASSWORD`) are refused - read those with `env('KEY')` inside `execute` instead. `lua workflows env-overlay <name>` shows which keys a version carries and whether each is present (values are never printed).

## Build errors

`commit()` and `lua compile` refuse graphs that cannot run. The most common codes:

| Code                                                          | Cause                                                                                |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `duplicate-step-id` / `unknown-step-ref`                      | A step id declared twice, or a string ref that names nothing in the chain.           |
| `map-id-required`                                             | Two or more `map()` calls without explicit ids.                                      |
| `closure-predicate` / `closure-binding`                       | A function where a predicate, template or mapping was expected.                      |
| `timeout-exceeds-tier`                                        | `timeoutSeconds` above 600 on a worker-tier step - add `tier: 'job'`.                |
| `long-job-requires-workspace`                                 | A Job-tier agent step longer than 4 h without a workspace.                           |
| `workspace-not-declared` / `workspace-requires-job-tier`      | A step mounts a workspace the workflow does not declare, or is not `tier: 'job'`.    |
| `approval-inside-container`                                   | An approval or signal wait inside `parallel`, `foreach` or a loop.                   |
| `escalation-chain-too-long` / `escalation-chain-not-terminal` | More than 3 hops, or a chain that does not end in `deny`, `cancel-run` or `fail`.    |
| `four-eyes-requires-editable`                                 | `fourEyes` without `editable: true`.                                                 |
| `env-template-secret-key`                                     | `env.template()` on a secret-shaped key.                                             |
| `hitl-duration-defaulted` (warning)                           | The graph waits for people and `budget.maxDurationSeconds` was defaulted to 30 days. |

## Script form

Workflows can also be written as a plain JavaScript script in `src/workflows/<name>.workflow.script.js` that exports `meta` (`name`, `description`, `phases`, `concurrency`, `sampleArgs`) and uses `agent(...)`, `parallel(...)`, `foreach(...)`, `step(...)` and `log(...)` as top-level awaits. `lua push workflow` and `lua test workflow` accept both forms; the desktop shows a **Phases** view instead of the graph for script runs.

## Testing locally

`lua test workflow --name <name>` (or `lua workflows run <name>`) compiles the project and drives the graph offline. Agent steps are faked unless `--agents live`; every approval, input suspend and signal can be pre-answered:

| Flag                                                  | Purpose                                                                  |
| ----------------------------------------------------- | ------------------------------------------------------------------------ |
| `--input <json\|@file>`                               | Run input.                                                               |
| `--step-output <id=json>`                             | Complete a step with this output (repeatable).                           |
| `--approve <id[=@payload]>` / `--deny <id[=@reason]>` | Pre-answer an approval (repeatable).                                     |
| `--signal <name=json>`                                | Pre-supply a signal payload (repeatable).                                |
| `--from-run <runId>`                                  | Seed completed steps from a real run (`--force` when the graph changed). |
| `--record <dir>` / `--fixtures <dir>`                 | Record agent and tool outputs, then replay them.                         |
| `--park <id>`                                         | Simulate a platform-fault park of a step (repeatable).                   |
| `--fast-retries` / `--real-time`                      | Collapse backoff waits, or actually wait on sleeps and backoffs.         |
| `--step-wall <s>` / `--job-wall <s>`                  | Per-step wall (default 600) and the virtual wall for Job-tier steps.     |
| `--now <iso>`                                         | Virtual clock start.                                                     |
| `--artefacts-dir <dir>`                               | Back `ctx.artefacts.*` on disk.                                          |
| `--env <KEY=value>`                                   | Local `env.template()` overlay (repeatable).                             |
| `--ledger-out <file>`                                 | Write the in-memory ledger as JSON.                                      |
| `--max-ticks <n>`                                     | Script form: tick cap (default 64).                                      |
| `--json`                                              | Print the ledger envelope instead of the timeline.                       |

Give every predicate both truth values: the fake agent stub alone cannot reach a `gt(confidence, 0.6)` arm, so pass `--step-output` for the agent step that feeds it.

## Related

* [Workflows](/overview/workflows) - the concept
* [Job tier](/workflows/job-tier) - workspaces, coding turns, size classes
* [Runs and events](/workflows/runs-and-events) - statuses, the ledger, SSE
* [Workflows Command](/cli/workflows-command) - the CLI reference


# Job Tier
Source: https://docs.heylua.ai/workflows/job-tier

Run a step for hours in its own container, with a git workspace and a coding session

## Overview

Worker-tier steps run in the agent's sandbox and are capped at 10 minutes. A step declared with `tier: 'job'` runs instead in its own Kubernetes Job: an isolated container with a mounted workspace volume, a checkpoint every few hours, and - for agent steps - a full coding session driven by a harness such as Claude Code.

Use the Job tier for anything that needs a repository checkout, a long test suite, or an agent that reads and edits files and runs commands.

```typescript theme={null}
const runTests = createStep({
  id: 'runTests',
  inputSchema: z.any(),
  outputSchema: z.object({ passed: z.boolean(), summary: z.string() }),
  tier: 'job',
  workspace: { mount: 'rw' },
  jobResources: 'large',
  timeoutSeconds: 3600,
  async execute({ workspace, log }) {
    const r = await $`cd ${workspace!.path} && npm ci && npm test -- --maxWorkers=2`.nothrow();
    log(r.stdout.slice(-4000));
    return { passed: r.exitCode === 0, summary: r.stdout.slice(-2000) };
  },
});
```

`$` is the Job image's shell helper; a plain `child_process` spawn also works in a Job-tier code step.

## Declaring a Job-tier step

| Option                             | Where                 | Notes                                                                                                                                                        |
| ---------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tier: 'job'`                      | code step, agent step | Runs the step as a Job. Implied by `workspace`.                                                                                                              |
| `workspace: { mount, isolation? }` | code step, agent step | `mount: 'rw' \| 'ro'`; `isolation: 'shared'` (default) or `'worktree'`. The workflow must declare a `workspace`.                                             |
| `jobResources`                     | code step, agent step | `'small'` (default), `'medium'` or `'large'`.                                                                                                                |
| `timeoutSeconds`                   | code step, agent step | Code steps up to 14 400 s (4 h); agent steps up to 86 400 s (24 h). An agent step longer than 4 h must mount a workspace so it can checkpoint. Default 3600. |
| `jobTools`                         | code step             | Tools the code step may use, e.g. `['gh']` to mint a GitHub token for the step.                                                                              |
| `toolScope.jobTools`               | agent step            | The coding turn's tool allowlist (below).                                                                                                                    |
| `harness`                          | agent step            | `'claude-code'` (default) or `'generic'`.                                                                                                                    |
| `maxTurns`                         | agent step            | Coding-turn cap, 1..500. Absent means the platform default; a monorepo change usually needs more.                                                            |

## The workspace

Declare the volume once on `createWorkflow`:

```typescript theme={null}
export const delivery = createWorkflow({
  name: 'ticket-pilot-delivery',
  inputSchema: z.object({ repoUrl: z.string(), baseRef: z.string(), /* ... */ }),
  budget: { maxCredits: 120, maxDurationSeconds: 24 * 3600 },
  workspace: {
    kind: 'git',
    repo: template('input.repoUrl'),
    ref: template('input.baseRef'),
    credentialsRef: 'github',
    sizeGb: 10,
  },
})
```

| Field                | Notes                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`               | `'git'` (a clone) or `'empty'` (a blank volume).                                                                                        |
| `repo`, `ref`        | A literal, or `template('input.<field>')` resolved over the run input. The clone URL must be a `https://github.com/<owner>/<repo>` URL. |
| `credentialsRef`     | The id of the GitHub connection that mints the token. In an agent template it is the declared connection key.                           |
| `sizeGb`, `ttlHours` | Volume size and how long it is kept after the run.                                                                                      |
| `verify`             | A command recorded on the workspace (for example `npm test`).                                                                           |
| `keepArtefacts`      | Keep the volume's artefacts after release.                                                                                              |
| `backend`            | `'ebs'` today.                                                                                                                          |

### Mounting

* The first Job-tier step of a run must mount `rw` - the clone happens on the first rw mount, and an `ro` mount on an empty volume is refused.
* `mount: 'ro'` drops the `write`, `edit` and `git` tools from a coding turn.
* Each run works on its own branch, `lua/wf-<lineageId>`. When a turn completes (and at each checkpoint) the harness commits and pushes that branch; a diff that contains a secret is refused before the push (`secret_in_diff`).
* A child workflow started with `{ workspace: 'inherit' }` uses the parent's volume; the parent's volume is released while the child waits.
* `lua workflows workspace <runId>` shows the repo, branch, head, size and TTL; `--release` frees the volume early.

### Parallel worktree arms

Several coding turns can work on the same checkout at once. Each arm gets its own worktree and branch (`lua/wf-<lineageId>/<armId>`) and a merge row folds them back:

```typescript theme={null}
.parallel(['implement', 'writeTests', 'updateDocs'], { merge: { strategy: 'rebase', onConflict: 'agent' } })
.agentStep('implement', { agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 7200, prompt: template('...') })
.agentStep('writeTests', { agentId: 'swe-tester', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 5400, prompt: template('...') })
.agentStep('updateDocs', { agentId: 'swe-writer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 1800, jobResources: 'small', prompt: template('...') })
```

`merge.strategy` is `'rebase'` or `'merge'`; `onConflict: 'agent'` lets one resolver turn fix conflicts, `'fail'` fails the merge. At most 8 arms.

## Coding turns

An agent step on the Job tier is a coding session on the mounted checkout:

```typescript theme={null}
const jobTurn = () => ({
  agentId: '$self',
  tier: 'job' as const,
  harness: 'claude-code' as const,
  workspace: { mount: 'rw' as const },
  jobResources: 'medium' as const,
  timeoutSeconds: 3600,
  maxTurns: 200,
  retry: { maxAttempts: 2 },
  toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] },
});

createWorkflow({ /* ... */ })
  .then(admit)
  .agentStep('spec', {
    agentId: '$self', tier: 'job', harness: 'claude-code', workspace: { mount: 'rw' },
    jobResources: 'small', timeoutSeconds: 1800, maxTurns: 80,
    toolScope: { jobTools: ['read', 'glob', 'grep'] },      // read-only turn: no shell, no edit
    systemPrompt: ARCHITECT_ROLE.instructions,
    prompt: template(SPEC_PROMPT),
    outputSchema: Spec,
  })
  .agentStep('implement', { ...jobTurn(), prompt: template(IMPLEMENT_PROMPT), outputSchema: Result })
  .dowhile('reviewFix', and(eq(reviewRef.path('verdict'), lit('revise')), lt(reviewRef.path('round'), lit(2))), { maxIterations: 3 })
  .agentStep('reviewFix', { ...jobTurn(), prompt: template(REVIEW_FIX_PROMPT), outputSchema: Review })
  .then(openPr)
  .commit();
```

* **Harness.** `claude-code` runs the turn as a Claude Code session with the step's prompt, the agent's persona and the tool allowlist. `generic` is the other harness; it does not support the schema-repair pass a `claude-code` turn gets when its reply misses `outputSchema`.
* **Tool scope.** `toolScope.jobTools` picks from `shell`, `read`, `write`, `edit`, `glob`, `grep`, `git`, `gh` and `fetch`. Leave out `gh` when a code step opens the PR instead.
* **Output schema.** The turn's final reply is validated against `outputSchema`; a mismatch fails the attempt, so give the turn `retry: { maxAttempts: 2 }`. The workspace persists across attempts, so a retry continues rather than restarts.
* **Segments.** A long turn is split into 4-hour segments. At each boundary the harness commits, pushes and checkpoints; the next segment resumes from the checkpoint on the same attempt.
* **Model.** Leave `model` unset to use the organisation default for Job turns.

## Size classes

| `jobResources`    | CPU (request / limit) | Memory | Ephemeral storage |
| ----------------- | --------------------- | ------ | ----------------- |
| `small` (default) | 1 / 2                 | 2 GiB  | 4 GiB             |
| `medium`          | 2 / 4                 | 4 GiB  | 8 GiB             |
| `large`           | 4 / 8                 | 8 GiB  | 16 GiB            |

A container that exceeds its memory limit is killed and the step fails with `job_oom_killed`. Keep test suites inside the class (for example `--maxWorkers=2` on a memory-hungry suite) or pick a larger one.

## Credentials

The Job container never holds a credential.

* `workspace.credentialsRef` names a GitHub connection. At spawn the platform mints a **short-lived token scoped to that one repository** and the permissions the step needs, and hands it to a sidecar next to the container - not to the container itself.
* Inside the container the git remote is a local proxy. `git fetch`, `git pull` and `git push` work normally; the proxy adds the credential on the way out.
* A push is admitted only to the run's own branch (or the arm's branch): no other refs, no deletes, no force-push over a moved ref. A pod spawned without an exact ref refuses every push.
* `gh` (when granted in `jobTools` / `toolScope.jobTools`) goes through the same proxy and is limited to reading the pinned repository and three writes: create a pull request, edit a pull request's title/body/draft state, and comment on an issue or PR. Merging, other repositories and organisation-level calls are refused.
* Tokens are never written to a row, an event, a log or the journal. If the connection cannot mint a token the step fails with `credentials_revoked` (not retried).
* The model provider key is likewise held only by the sidecar; the container talks to the provider through a metered local proxy.

Steps that need other services use `requiredConnections` and the usual `Integrations.passthrough` from a worker-tier code step - the pattern in the shipped examples is to open the PR from a worker step under `ctx.once` after the coding turns finish.

## What the run page shows

On the desktop run page, select a Job-tier step to see:

* the Job's name, phase, size class and harness, with spawned / claimed / last-heartbeat times;
* elapsed time against the timeout, and the segment strip for a multi-segment turn;
* **What the agent is doing**: the turn's latest activity, newest first - every tool call with its input and, once it returns, whether it succeeded and its output; and the model's own notes between calls;
* the workspace panel: branch, head, size used and files changed.

The **Log** tab lists the same activity for the whole run with filters for **Tool calls**, **Agent notes** and **Step events**, and a **Follow** switch that keeps the newest line in view.

From the CLI:

```bash theme={null}
lua workflows jobs <runId>                              # every Job-tier step: status, size, pod phase, segment, heartbeat
lua workflows job-logs <runId> <stepId> --tail 500 --follow   # the container log, polled until the step ends
lua workflows workspace <runId>                          # the volume: repo, branch, head, size, arms
```

## Limits

| Limit                                    | Value                                                                                     |
| ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| Code step timeout                        | 1..14 400 s (default 3600)                                                                |
| Agent step timeout                       | 1..86 400 s (default 3600); above 14 400 s a workspace is required                        |
| Segment length                           | 4 h, then checkpoint and re-spawn on the same attempt                                     |
| `maxTurns`                               | 1..500                                                                                    |
| Worktree arms per `parallel`             | 8                                                                                         |
| Job-tier concurrency and live workspaces | Capped per organisation; a step past the cap waits (`step.throttled`) rather than failing |
| Job seconds per run                      | A run budget dimension (`jobSeconds`); exhausting it parks the run on a `budget` gate     |
| Container memory                         | The size class limit (2 / 4 / 8 GiB); exceeding it fails the step with `job_oom_killed`   |

## Related

* [Authoring](/workflows/authoring) - every step and container option
* [Runs and events](/workflows/runs-and-events) - parks, gates, retry-step and the run page
* [Workflows Command](/cli/workflows-command#lua-workflows-jobs) - `jobs`, `job-logs` and `workspace`


# Workflows Quick Start
Source: https://docs.heylua.ai/workflows/quick-start

Define a workflow, run it locally, push and deploy it, start a run, approve the card and read the result

## What you will build

A `ticket-plan` workflow that loads a ticket, asks your agent for an implementation plan, pauses for your approval, and records the outcome. By the end you will have started a run from the CLI, approved it, and read its output.

<Note>
  Workflows are a per-agent feature. If `lua workflows list` reports that workflows are not found on your agent, ask your organisation admin to enable them.
</Note>

<Steps>
  <Step title="Create the workflow file">
    Inside a lua-cli project (`lua init` if you do not have one), create `src/workflows/ticket-plan.ts`:

    ```typescript theme={null}
    import { z } from 'zod';
    import { createStep, createWorkflow, fromStep, template } from 'lua-cli';

    const Ticket = z.object({ id: z.string(), title: z.string(), body: z.string() });

    const loadTicket = createStep({
      id: 'loadTicket',
      inputSchema: z.object({ ticketId: z.string() }),
      outputSchema: Ticket,
      timeoutSeconds: 60,
      async execute({ inputData, log }) {
        // Replace with your tracker's API. Anything you return must match outputSchema.
        log(`loading ${inputData.ticketId}`);
        return { id: inputData.ticketId, title: 'Add CSV export', body: 'Users want to export the orders table.' };
      },
    });

    const Plan = z.object({
      summary: z.string(),
      files: z.array(z.string()),
      estimate: z.enum(['S', 'M', 'L']),
    });

    const record = createStep({
      id: 'record',
      inputSchema: z.any(),
      outputSchema: z.object({ approved: z.boolean(), summary: z.string() }),
      timeoutSeconds: 60,
      async execute({ getStepResult }) {
        const decision = getStepResult<{ approved: boolean }>('approvePlan');
        const plan = getStepResult<z.infer<typeof Plan>>('plan');
        return { approved: decision.approved, summary: plan.summary };
      },
    });

    export const ticketPlan = createWorkflow({
      name: 'ticket-plan',
      description: 'Load a ticket, draft a plan, ask for approval, record the decision.',
      inputSchema: z.object({ ticketId: z.string() }),
      outputSchema: z.object({ approved: z.boolean(), summary: z.string() }),
      budget: { maxCredits: 20 },
    })
      .then(loadTicket)
      .agentStep('plan', {
        agentId: '$self',
        // Ticket text is external content, so the turn runs with no tools.
        toolScope: {},
        prompt: template(
          'Ticket ${stepResults.loadTicket.id}: ${stepResults.loadTicket.title}\n\n${stepResults.loadTicket.body}\n\nWrite a short implementation plan.'
        ),
        outputSchema: Plan,
      })
      .approval('approvePlan', {
        title: 'Start work on this ticket?',
        details: template('${stepResults.plan.summary} (estimate ${stepResults.plan.estimate})'),
        approver: 'creator',
        timeoutHours: 72,
        onTimeout: 'deny',
      })
      .then(record)
      .commit();
    ```

    Names must match `^[a-z][a-z0-9-_]*$`; step ids must match `^[a-z][a-zA-Z0-9_-]{0,63}$`. The compiler finds every `createWorkflow(...).commit()` chain in your project - you can also list them on your `LuaAgent` under `workflows: [ticketPlan]`.
  </Step>

  <Step title="Run it locally">
    `lua test workflow` compiles the project and drives the graph offline. Agent steps are faked by default and approvals can be pre-answered:

    ```bash theme={null}
    lua test workflow --name ticket-plan --input '{"ticketId":"TP-12"}' --approve approvePlan
    ```

    Give the faked agent step a realistic output with `--step-output`:

    ```bash theme={null}
    lua test workflow --name ticket-plan \
      --input '{"ticketId":"TP-12"}' \
      --step-output 'plan={"summary":"Add an export button","files":["src/orders.ts"],"estimate":"S"}' \
      --approve approvePlan
    ```

    `lua workflows run ticket-plan ...` is the same command under the workflows verb. Pass `--agents live` to call the real agent instead of the fake.
  </Step>

  <Step title="Push it">
    ```bash theme={null}
    lua push workflow
    ```

    Pushing mints a new immutable version of the workflow on the server and records it in `lua.skill.yaml` under `workflows:`. Nothing is live yet.

    <Note>
      `lua push all` does not stage workflows - push them explicitly with `lua push workflow` (aliases: `workflows`, `wf`). Add `--auto-deploy` to publish the pushed version straight away.
    </Note>
  </Step>

  <Step title="Deploy it">
    ```bash theme={null}
    lua workflows deploy ticket-plan -v latest
    ```

    Deploying makes that version the active one and, on an agent under versioning, records a new agent version (the `agentVersion` the command prints). `lua workflows view ticket-plan` shows the versions and which one is active.
  </Step>

  <Step title="Start a run and watch it">
    ```bash theme={null}
    lua workflows start ticket-plan --input '{"ticketId":"TP-12"}' --follow
    ```

    `start` answers immediately with a run id (`wfr_...`) and `--follow` attaches the live event stream. The stream prints one line per event and stops at the approval:

    ```
    Run wfr_3f2... · queued
    [10:14:02] run.started
    [10:14:02] step.started · loadTicket
    [10:14:03] step.completed · loadTicket
    [10:14:03] step.started · plan
    [10:14:11] step.completed · plan
    [10:14:11] run.suspended · approvePlan {"stepId":"approvePlan","kind":"approval"}
    run waits for a person (approval · approvePlan) — lua workflows approve wfr_3f2... --approval <id> --decision approve|deny; then: lua workflows watch wfr_3f2...
    ```

    The command exits with code `8` (parked on a person). Pass `--input @file.json` to read the input from a file.
  </Step>

  <Step title="Approve the card">
    <Tabs>
      <Tab title="Desktop">
        Open **Runs** in the desktop, pick the run, and answer the card in the **Needs you** section of the run page. The same card also appears in your Inbox.
      </Tab>

      <Tab title="CLI">
        Approvals are resolved by their approval id (`wfa_...`). Read it off the run:

        ```bash theme={null}
        lua workflows status wfr_3f2... --json | jq -r '.data.suspensions[].suspend.approvalId'
        ```

        Then decide:

        ```bash theme={null}
        lua workflows approve wfr_3f2... --approval wfa_9c1... --decision approve --note "Go ahead"
        ```

        `--decision deny` completes the approval as denied; the run continues and `record` sees `approved: false`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Read the result">
    Re-attach and wait for the terminal event:

    ```bash theme={null}
    lua workflows watch wfr_3f2...
    ```

    Then read the run and its steps:

    ```bash theme={null}
    lua workflows status wfr_3f2... --steps
    ```

    ```
    Run wfr_3f2... · completed
       Workflow: ... @ ... (a1b2c3d4e5f6)
       Trigger:  api
       Output:   {"approved":true,"summary":"Add an export button"}

    Step         Kind      Status     Attempt  Error
    loadTicket   code      completed  1
    plan         agent     completed  1
    approvePlan  approval  completed  1
    record       code      completed  1
    ```

    `lua workflows status <runId> --json` returns the full run document, including each step's input and output preview.
  </Step>
</Steps>

## Start a run from a skill

A tool can start the same workflow on the user's behalf. The idempotency key makes a retried tool call return the original run instead of a second one:

```typescript theme={null}
import { Workflows } from 'lua-cli';

const { runId, status } = await Workflows.start(
  'ticket-plan',
  { ticketId: input.ticketId },
  { idempotencyKey: `ticket-plan:${input.ticketId}`, correlationKey: input.ticketId, tags: ['triage'] }
);
```

See [Authoring](/workflows/authoring#starting-runs-from-code) for the full `Workflows` API.

## Where to go next

<CardGroup>
  <Card title="Authoring" icon="code" href="/workflows/authoring">
    Every builder call, binding helper, retry and approval option
  </Card>

  <Card title="Job tier" icon="server" href="/workflows/job-tier">
    Give a step a repository checkout and a coding session
  </Card>

  <Card title="Runs and events" icon="timeline" href="/workflows/runs-and-events">
    Statuses, the ledger, SSE and the desktop Runs pages
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli/workflows-command">
    All `lua workflows` subcommands and flags
  </Card>
</CardGroup>


# Runs and Events
Source: https://docs.heylua.ai/workflows/runs-and-events

Run lifecycle and statuses, the events ledger, the SSE stream, approvals and signals, cancel and retry, and the desktop Runs pages

## Overview

Every start creates a **run** (`wfr_...`) with a status, a budget, step rows and an append-only **events ledger**. The ledger is what the CLI's `watch`, the desktop's live views and your own SSE clients read; it stays with the run after the run ends.

## Run lifecycle

```
queued ──▶ running ──▶ completed
   │          │  ▲
   │          ├──┼──▶ suspended  (waiting for a person: approval, input, signal)
   │          ├──┼──▶ waiting    (a timer: sleep, retry backoff, a child run)
   │          ├──┼──▶ gated      (holds no slot: consent, quota, billing, budget, exception)
   │          │
   │          └─▶ cancellation_requested ──▶ cancelled / abandoned
   └──▶ gated
                       failed · timed_out
```

| Group     | Statuses                                                     | Meaning                                                                                   |
| --------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| In flight | `queued`, `running`, `cancellation_requested`                | The run holds an execution slot.                                                          |
| Idle      | `gated`, `suspended`, `waiting`                              | The run holds no slot; nothing is executing until a person, a signal or a timer wakes it. |
| Terminal  | `completed`, `failed`, `cancelled`, `abandoned`, `timed_out` | Final. Late writes from a stale worker are fenced off.                                    |

`failing` is a flag, not a status: a step with `onError: 'fail'` failed and the run is unwinding to `failed`.

### Gates

A `gated` (or, for `exception`, `suspended`) run carries `gate.kind`:

| Kind                       | Why                                                                                                    | How it clears                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `start-consent`            | The start needs a person's consent                                                                     | Approve on the desktop (`lua workflows start` exits 6)          |
| `quota`                    | The organisation's concurrency or suspended-run cap is full (`code: concurrency_cap \| suspended_cap`) | Automatically when a slot frees                                 |
| `billing`                  | Credits ran out mid-run                                                                                | Top up, then `lua workflows retry-step <runId> --step <stepId>` |
| `budget`                   | The run's own `maxCredits` / `maxSteps` / `jobSeconds` ran out (`dimension`, `spent`, `cap`)           | Raise the budget (desktop, or `Workflows.raiseBudget`)          |
| `exception`                | A step parked for a person (`onError: 'park'`, or an external-effect step hit by a platform fault)     | Retry, skip, complete or fail the step                          |
| `org_archived`, `disabled` | The organisation is archived, or workflows were switched off                                           | Administrative                                                  |

### Triggers

`run.trigger` records how the run started: `chat`, `sdk`, `api` (CLI and HTTP starts), `schedule`, `webhook` (trigger primitives), `template`, `workflow` (a parent run), `device`.

## Step lifecycle

| Status                                     | Meaning                                                                         |
| ------------------------------------------ | ------------------------------------------------------------------------------- |
| `pending`                                  | Upstream steps have not finished.                                               |
| `ready`, `waiting`, `dispatched`           | Eligible; waiting for a slot, a timer, or a worker/Job to claim it.             |
| `claimed`, `running`                       | Executing under a lease.                                                        |
| `suspended`                                | Parked for a person: `suspend.kind` is `approval`, `input`, `signal` or `gate`. |
| `cancellation_requested`                   | Being cancelled.                                                                |
| `completed`, `skipped`                     | Done.                                                                           |
| `failed`, `cancelled`, `timeout`, `reaped` | Terminal failures (`reaped` = the lease expired and the attempt was reclaimed). |

Each row carries `attempt` / `maxAttempts`, `dependsOn`, timings, a 2 KB preview of input and output, `error { code, message, killReason? }`, `artefactIds`, and - for Job-tier rows - the `job` block described in [Job tier](/workflows/job-tier#what-the-run-page-shows). Step kinds are `code`, `agent`, `tool`, `map`, `branch`, `foreach`, `loop`, `sleep`, `sleepUntil`, `approval`, `signal`, `subrun` and `merge`.

## The events ledger

Every change to a run appends one event:

```json theme={null}
{
  "runId": "wfr_3f2...",
  "seq": 12,
  "ts": "2026-09-03T10:14:11.204Z",
  "type": "step.completed",
  "stepId": "plan",
  "attempt": 1,
  "actor": { "kind": "system" },
  "data": { "durationMs": 8120 }
}
```

`seq` is per run and strictly increasing - order by `seq`, never by `ts`. `stepId` is present on every `step.*`, `approval.*`, `signal.*` and `timer.*` event.

### Event types

| Family                     | Types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run lifecycle              | `run.created`, `run.gated`, `run.gate_cleared`, `run.started`, `run.claimed`, `run.phase`, `run.log`, `run.suspended`, `run.waiting`, `run.resumed`, `run.cancel_requested`, `run.completed`, `run.failed`, `run.cancelled`, `run.abandoned`, `run.timed_out`, `run.failing`, `run.bailing`, `run.repaired`, `run.reconciled`, `run.signal_parked`, `run.billing_hold`, `run.budget_parked`, `run.budget_raised`, `run.exported`, `run.reassigned`, `run.reply_delivered`, `run.reply_failed`, `run.workspace_provisioned`, `run.workspace_released`, `run.workspace_restored`, `run.migrated`, `run.migration_scheduled`, `run.migration_applied`, `run.migration_refused`, `run.callback_delivered`, `run.callback_failed`, `run.export_auto_queued`, `run.export_pushed`, `run.export_push_failed` |
| Step lifecycle             | `step.ready`, `step.dispatched`, `step.claimed`, `step.started`, `step.progress`, `step.completed`, `step.failed`, `step.skipped`, `step.cancelled`, `step.timeout`, `step.reaped`, `step.retried`, `step.retry_scheduled`, `step.throttled`, `step.suspended`, `step.resumed`, `step.parked`, `step.resolved`, `step.gated`, `step.signal_received`, `step.approval_item_decided`, `step.artefact`, `step.dataset`, `step.checkpointed`, `step.job_spawned`, `step.merged`, `step.mcp_call_denied`, `step.foreach_expanded`, `step.loop_iteration`                                                                                                                                                                                                                                                   |
| Approvals, signals, timers | `approval.requested`, `approval.edited`, `approval.escalated`, `approval.expired`, `approval.resolved`, `signal.received`, `signal.consumed`, `signal.rejected`, `timer.set`, `timer.fired`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Billing and other          | `billing.gate`, `billing.step_charged`, `billing.budget_exhausted`, `journal.divergence`, `goal.updated`, plus schedule and fleet events                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

`step.progress` carries `data.message` from `ctx.log(...)`. `run.suspended` carries `{ stepId, kind }`; `approval.requested` carries the `approvalId` you need to resolve it from the API or CLI.

### Retention

* A run and its events, steps, signals and artefacts are kept together. A run is stamped to expire 365 days after it was created; when it ends, the expiry is restamped to `completedAt` plus the organisation's workflow retention (7..90 days; the platform default is 90 and the ceiling is 90). Lowering the organisation's retention tightens existing runs; raising it never extends a run already stamped.
* Export before expiry with `lua workflows archive-runs --since 8d --out ./archive` (bundles are downloadable for 7 days after the export is requested), or delete a terminal run early with `lua workflows delete-run <runId>`.

## Streaming events (SSE)

```
GET /workflows/{agentId}/runs/{runId}/events
Accept: text/event-stream
Authorization: Bearer <token>
```

Requires the `workflows:read` scope on the agent. The response is a standard Server-Sent Events stream:

```
retry: 3000
: connected run=wfr_3f2... from=0 head=12

id: 11
event: step.started
data: {"runId":"wfr_3f2...","seq":11,"ts":"...","type":"step.started","stepId":"plan", ...}

id: 12
event: step.completed
data: {...}

event: heartbeat
data: {"ts":1756894451204,"head":12}

id: 13
event: run.completed
data: {...}

event: end
data: {"seq":13,"status":"completed"}
```

| Frame                                            | Meaning                                                                                                                                                |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id: <seq>` / `event: <type>` / `data: <event>`  | One ledger event. Missed history is replayed from your cursor before live events are tailed.                                                           |
| `heartbeat` (no id)                              | Every 15 s while the stream is idle.                                                                                                                   |
| `end { seq, status }`                            | Sent after the run's terminal event; the server closes the stream.                                                                                     |
| `reconnect { reason }`                           | Reconnect from your last id.                                                                                                                           |
| `error { code }`                                 | For example `run_gone` (the run was erased) or `forbidden` (your access was re-checked and revoked).                                                   |
| `workflow.output.acl_changed { restricted, ts }` | Output visibility flipped for you mid-stream; payloads are redacted or unredacted from here on. This control frame has no id and is not in the ledger. |

### Cursors

* `Last-Event-ID: <seq>` on reconnect resumes after that sequence. It **wins** over the query parameter.
* `?afterSeq=<seq>` does the same for a first connection.
* `?types=step.completed,run.failed` filters both the replay and the tail to those types.

### Polling form

The same URL without `Accept: text/event-stream` returns one JSON page:

```
GET /workflows/{agentId}/runs/{runId}/events?afterSeq=0&limit=500
→ { "events": [ ... ] }
```

`lua workflows logs` uses this form; `lua workflows watch` uses the stream and reconnects from `Last-Event-ID` when it drops.

### Redaction

Event payloads (`data`) carry step inputs and outputs. A viewer without the `workflows:read-outputs` grant (or outside a workflow's `outputVisibility`) receives the same frames with `data` redacted; the check is repeated every 60 s on a live stream.

## Approvals and signals

### Resolving an approval

```
POST /workflows/{agentId}/runs/{runId}/approvals/{approvalId}/resolve
{ "decision": "approve" | "deny", "note"?: "...", "editedPayload"?: {...}, "expectedFingerprint"?: "..." }
```

* Only a signed-in person can resolve an approval (`workflows:execute`); service principals get 403 `APPROVAL_REQUIRES_HUMAN`.
* Editing the payload requires the `expectedFingerprint` of the version you looked at; 409 `PAYLOAD_MISMATCH` means it changed - refetch and try again.
* Other refusals: `NOT_AN_APPROVER`, `FOUR_EYES_REQUIRED`, `STEP_UP_REQUIRED` (approve from the desktop with a fresh login), `EDIT_NOT_ALLOWED`.
* A second resolve is a 200 no-op `{ resolved: false, outcome: 'noop', reason }` naming who decided.

The `approvalId` (`wfa_...`) is on the run's `suspensions[].suspend.approvalId`, on the `approval.requested` event, and on the desktop card. CLI: `lua workflows approve <runId> --approval <id> --decision approve|deny [--note] [--edit @file --fingerprint <f>]`.

### Resuming an input suspend

A step that called `ctx.suspend(payload)` is resumed with data that must match its `resumeSchema`:

```
POST /workflows/{agentId}/runs/{runId}/steps/{stepId}/resume
{ "resumeData": {...} }
```

CLI: `lua workflows resume <runId> --step <id> --data '{...}'`. Resuming an approval step or a signal wait this way is refused with 409 `APPROVAL_REQUIRES_HUMAN` / `USE_SIGNAL_ROUTE`.

### Delivering a signal

```
POST /workflows/{agentId}/runs/{runId}/signals/{name}
{ "payload"?: {...}, "dedupeKey"?: "..." }
```

| Response                                                 | Meaning                                            |
| -------------------------------------------------------- | -------------------------------------------------- |
| 202 `{ accepted: true, consumed: true, stepId }`         | A waiting step took it.                            |
| 202 `{ accepted: true, consumed: false }`                | Parked until a step waits for it.                  |
| 200 `{ accepted: true, duplicate: true }`                | The `dedupeKey` was seen before.                   |
| 202 `{ accepted: false, reason: 'source_not_accepted' }` | The wait's `acceptedSources` excludes this caller. |
| 409 `RUN_TERMINAL`                                       | The run already ended.                             |

`POST /workflows/{agentId}/signals/by-key` with `{ correlationKey, name, payload?, dedupeKey?, allowMultiple? }` delivers to the live run(s) started with that `correlationKey` (409 `CORRELATION_KEY_AMBIGUOUS` when several match and `allowMultiple` is false). CLI: `lua workflows signal <runId> <name> --payload '{...}' [--dedupe-key <key>]`.

## Cancelling

```
POST /workflows/{agentId}/runs/{runId}/cancel   { "mode"?: "request" | "force", "reason"?: "..." }
```

A cancel is a request: running steps are asked to stop at their next boundary and the run moves to `cancellation_requested`. The verdict tells you what to do next - `nextAction: 'none'` (done), `'cancel_again'` (ask again to escalate) or `'force'` (a force cancel becomes available at `forceAvailableAt`). `lua workflows cancel <runId> [--reason <text>] [--force]` prints the same.

## Retrying and repairing

| Action                | When                                                                                              | How                                                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `retry-step`          | A step failed past its retries, parked on an exception gate, or is on a billing hold              | `lua workflows retry-step <runId> --step <id> [--note <text>]` - re-arms the same step; 409 `STEP_NOT_PARKED` if it is not parked, `RUN_TERMINAL` if the run ended |
| Resolve a parked step | You want to skip it, supply its output, or fail it                                                | The desktop's exception card, or `POST .../steps/{stepId}/resolve`                                                                                                 |
| Repair run            | The run is terminal and you want to continue from the failed step with the completed steps seeded | The desktop's **Repair** dialog, or `POST .../runs/{runId}/repair`; the new run shares the original's `lineageId`, so `ctx.once` keys still hold                   |
| Raise budget          | The run parked on a `budget` gate                                                                 | The desktop, or `POST .../runs/{runId}/budget`                                                                                                                     |

## Starting and listing runs over HTTP

| Route                                                                         | Scope                                | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /workflows/{agentId}/definitions`                                        | `workflows:read`                     | Workflow definitions on the agent (`items`, `nextCursor`).                                                                                                                                                                                                                                                                                                                                                                                              |
| `POST /workflows/{agentId}/runs`                                              | `workflows:execute`                  | Start a run: `{ workflowId, input, idempotencyKey?, budget?, correlationKey?, tags?, waitSeconds?, workflowVersionId? }`. 202 `{ runId, status: 'queued' \| 'gated', watchHint, idempotentReplay? }`; 200 with the run when `waitSeconds` (0..55) elapsed on a settled run. An `Idempotency-Key` header wins over the body field. 409 `RUNS_IN_FLIGHT` under `concurrencyPolicy: 'forbid'`; 429 `CONCURRENCY_CAP` / `SUSPENDED_CAP` with `Retry-After`. |
| `POST /workflows/{agentId}/runs/batch`                                        | `workflows:execute`                  | Many starts at once; each item needs its own `idempotencyKey`. Body at most 2 MB.                                                                                                                                                                                                                                                                                                                                                                       |
| `GET /workflows/{agentId}/runs`                                               | `workflows:read`                     | Filter by `workflowId`, `status`, `correlationKey`, `tag`, `since`; `sort` one of `-createdAt`, `createdAt`, `-durationMs`, `durationMs`; cursor paging.                                                                                                                                                                                                                                                                                                |
| `GET /workflows/{agentId}/runs/{runId}?fields=summary\|full`                  | `workflows:read`                     | `full` hydrates inputs and outputs for readers who may see them.                                                                                                                                                                                                                                                                                                                                                                                        |
| `GET /workflows/{agentId}/runs/{runId}/steps/{stepId}?attempt=n`              | `workflows:read`                     | One step with its attempts (input/output are `{__hidden}` without `read-outputs`).                                                                                                                                                                                                                                                                                                                                                                      |
| `DELETE /workflows/{agentId}/runs/{runId}`                                    | `workflows:execute`                  | Erase a terminal run (202 `{ purgeId }`; 409 `RUN_NOT_TERMINAL`). Creator or org admin, person only.                                                                                                                                                                                                                                                                                                                                                    |
| `POST /workflows/{agentId}/runs/{runId}/export` / `GET .../export/{exportId}` | `workflows:read` + `read-outputs`    | Request and download an evidence bundle of a terminal run.                                                                                                                                                                                                                                                                                                                                                                                              |
| `GET /workflows/{agentId}/runs/{runId}/artefacts/{artefactId}`                | `workflows:read` + `read-outputs`    | A presigned download of a run artefact.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET/POST/PATCH/DELETE /workflows/{agentId}/schedules[/{jobId}]`              | `workflows:read` / `workflows:write` | Schedules attached to a workflow; `PATCH` pauses/resumes and backfills.                                                                                                                                                                                                                                                                                                                                                                                 |

Run inputs are at most 256 KB; a run holds up to 10 tags.

## The desktop Runs pages

**Runs** lists every run on the agent with search by ticket, order or run id (the `correlationKey`), status filters, and a **waiting for you** section for runs suspended on your approval or input. Open a run for:

| Area              | What it shows                                                                                                                                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Header and status | Workflow, version, trigger, status pill, budget spent versus cap, and a gate banner when the run is parked (with the action that clears it).                                                                   |
| **Needs you**     | The approval card, resume-input form or exception card for every step waiting on a person. Approve, deny or edit here.                                                                                         |
| **Timeline** tab  | Every step in dispatch order with status, attempt, duration and - for live Job-tier steps - the current phase and activity. Select a step for its input, output, error, attempts, artefacts and Job panel.     |
| **Graph** tab     | The workflow graph with each node coloured by its status (script-form runs show a **Phases** tree instead).                                                                                                    |
| **Events** tab    | The events ledger, live.                                                                                                                                                                                       |
| **Log** tab       | Tool calls (with input and output), the agent's notes and step events in one stream, with **All / Tool calls / Agent notes / Step events** filters and a **Follow** switch that keeps the newest line in view. |
| Aside             | Run details (ids, correlation key, tags, timings, last activity), the workspace panel for Job-tier runs, and the actions rail: cancel, retry, repair, release workspace, export.                               |

## Related

* [Workflows Command](/cli/workflows-command) - `start`, `watch`, `status`, `approve`, `signal`, `cancel`, `retry-step`, `archive-runs`
* [Job tier](/workflows/job-tier) - what a Job-tier step's panel and log contain
* [Authoring](/workflows/authoring#approvals) - approval, signal and retry options on the definition