Changelog

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()],
});

await Templates.send({
  to: { phoneNumber: "+15551234567" },
  templateName: "spring_promo",
  values: { header: { image_id: "1234567890" } },
});

lua marketplace template apply --template-id my-template-123 --agents agent-a,agent-b,agent-c --force

lua version status

await Channels.whatsapp.sendReaction({
  to: { phoneNumber: '+15551234567' },
  messageId: 'wamid.HBgL...',
  emoji: '👍',
});

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" }
  }'

import { LuaAgent } from 'lua-cli';

export const agent = new LuaAgent({
  name: 'support-triage',
  persona: '...',
  modelSettings: {
    reasoning: { effort: 'low', show: false },
  },
  skills: [triageSkill],
});

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!'
  });
}

import { LuaAgent } from 'lua-cli';

export const agent = new LuaAgent({
  name: 'research-assistant',
  persona: '...',
  browser: true,
});

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: '[email protected]' },
  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'
});

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}`
});

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

lua features configure --feature-name outboundChannels --recipient-scope anyone

// Exclude a tool from the voice agent
excludeTools: ['place_order']

// Hand the live call to another agent
await ctx.voice?.handoff('billing-agent');

// 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' }
  }
});

lua git auth github
# Open https://github.com/login/device and enter the code: WDJB-MJHT
# ✓ Logged in to GitHub as @your-username.

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

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],
});

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);

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);

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 };
}

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?",
});

lua channels
# → ☎️ Manage phone numbers
# → Search available numbers / Purchase / Bind / List / Release

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');
});

lua voice terminal   # CLI mode
lua voice browser    # Opens an embedded UI in your browser

lua logs --type calls

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' }),
});

// 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';
}

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

npm install -g lua-cli@latest

lua source list                # most recent 50 versions
lua source list --all          # full history
lua source list --limit 100    # custom cap

lua source rollback --version 12          # confirms before applying
lua source rollback --version 12 --force  # skip the confirmation

lua push backup --fresh

lua init --from-agent-id <existing-agent-id>

lua init --from-agent-id <id> \
  --include-resources \
  --include-custom-data \
  --include-inquiry-form \
  --include-devices \
  --include-ecommerce-catalog

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'
  },
});

lua status           # human-readable table
lua describe         # same output via alias
lua status --json    # machine-readable JSON (schemaVersion: 1)

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?)

Tool returned: Object — fields: success, message, data
Tool returned: Array[3] of UserDataInstance — fields: id, name, email

lua test skill --name myTool --input '{"userId":"123"}' --json | jq '.data'

// 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()] });

⚠️  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

# 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

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"

await Agents.invoke(targetAgentId, prompt)
await Agents.invoke(targetAgentId, { messages, systemPrompt })

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 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>]

lua sync --accept          # guarded pull — fails if local changes detected
lua sync --accept --force  # bypass the guard and overwrite local changes

lua init --model openai/gpt-4o
lua init --agent-name "My Bot" --org-id org123 --model anthropic/claude-3-5-sonnet

# 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

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

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

lua chat --batch           # Enable message batching in chat session
lua chat --delay 2000      # Set first-message delay (ms)

// 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?' }]
);

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)

export LUA_SKIP_KEYCHAIN=1
lua --version    # Now works without keytar.node

lua chat --thread my-test
lua chat -t
lua chat clear --thread my-test --force

lua chat --clear
lua chat -t my-test --clear

Push Error: Interval seconds must be at least 60

// 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 * * *' }

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';
  },
});

lua telemetry          # Show current status
lua telemetry on       # Enable telemetry
lua telemetry off      # Disable telemetry

import { User } from 'lua-cli';

// Look up by email
const user = await User.get({ email: '[email protected]' });

// 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' };
}

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

# 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

# Backup project sources
lua push backup

# Restore on new machine
lua init --agent-id abc123 --restore-sources

# 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

lua update   # Force-fetch latest version and install

lua agents            # Formatted output
lua agents --json     # JSON output for scripting

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 () => { ... }
});

lua push all --force                # All primitives + persona + backup
lua push all --force --auto-deploy  # Also deploys persona to production

# 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

# 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

# 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

// 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
  }
});

lua sync

# Clear all conversation history
lua chat clear

# Clear history for a specific user
lua chat clear --user [email protected]

import { Lua } from 'lua-cli';

// Access channel information
const channel = Lua.request.channel; // 'dev', 'webchat', 'whatsapp', etc.

import { Lua } from 'lua-cli';

// Access raw webhook payload when triggered by webhook
const webhookPayload = Lua.request.webhook;

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]
});

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'; }
});

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);

// Get all jobs
const jobs = await Jobs.getAll();

// Activate/deactivate job scheduling
await job.activate();
await job.deactivate();

// Manually trigger execution
await job.trigger();

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' } }
});

const userId = user._luaProfile.userId;        // ✅ Recommended
const fullName = user._luaProfile.fullName;
const emails = user._luaProfile.emailAddresses;

// user.userId still works but is deprecated

// Before
const schedule = job.schedule;
const id = job.jobId;

// After
const schedule = job.activeVersion.schedule;
const id = job.id;
await job.trigger(); // New method

// Before
execute: async (query, headers, body) => {
  // handle webhook
}

// After
execute: async (event) => {
  const { query, headers, body, timestamp } = event;
  // handle webhook
}

// Block response
return { action: 'block', response: 'Blocked' };

// Proceed response
return {
  action: 'proceed',
  modifiedMessage: [{ type: 'text', text: '...' }]
};