| title | Changelog |
|---|---|
| description | Release notes and version history for lua-cli |
Released: April 23, 2026
Attach images and documents to any chat message using `@` syntax — in both interactive and non-interactive mode.```bash
# 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.
Released: April 22, 2026
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. 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.Released: April 22, 2026
`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
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.
Released: April 21, 2026
Added a reusable agent invocation surface callable from within a LuaSkill, LuaWebhook, LuaJob, or any other primitive:```typescript
await Agents.invoke(targetAgentId, prompt)
await Agents.invoke(targetAgentId, { messages, systemPrompt })
```
Released: April 16, 2026
Manage the LLM model for your agent directly from the CLI.```bash
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.
```bash
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.
```bash
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.
Released: April 15, 2026
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
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.
Released: April 13, 2026
`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
# 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>
Released: April 8, 2026
Subscribe your webhooks to WhatsApp message lifecycle events dispatched when Meta sends status callbacks.```bash
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`.
```bash
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.
Released: March 30, 2026
Agents can now have individual batching configuration for message debouncing. New `lua chat` flags for testing:```bash
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.
Released: March 27, 2026
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. `.env` parsing now correctly strips inline comments: `LUA_API_KEY=abc # my comment` resolves to `abc`.Released: March 24, 2026
Automatic retries with backoff for transient server failures (429, 500–504). Max 3 retries, never retries client errors. Improves reliability for flaky network conditions. Removed the `lua dev` web UI command and unused dependencies, significantly reducing install size. Chat sessions now have a 5-minute timeout instead of hanging indefinitely on unresponsive connections.Released: March 24, 2026
New `AI.generate` API for running text generation from within tools, aligned with Vercel AI SDK `generateText` semantics.**Simplified — returns plain text:**
```typescript
// 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
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.
```bash
export LUA_SKIP_KEYCHAIN=1
lua --version # Now works without keytar.node
```
Released: March 20, 2026
Use `lua chat -t` or `--thread ` for isolated sessions. `lua chat clear --thread ` clears one thread. Omit the thread ID with `-t` to auto-generate a UUID.```bash
lua chat --thread my-test
lua chat -t
lua chat clear --thread my-test --force
```
```bash
lua chat --clear
lua chat -t my-test --clear
```
Released: March 15, 2026
Connecting integrations defaults to exposing full MCP tool payloads (hide sensitive off). `defer_tools` is aligned with Unified.to expectations. Compiling skills resolves tool references more reliably for imports and dependencies.Released: March 11, 2026
Added `lua logs --type agent_error` to filter logs for execution errors in tools, webhooks, and jobs. Fixed timezone handling for cron schedules and improved error logging for failed cron jobs.Released: March 10, 2026
Extended base URLs for internal service discovery.Released: March 2, 2026
`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
// 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 * * *' }
```
Released: February 27, 2026
`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
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`.
```bash
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.
Released: February 20, 2026
The `User.get()` method now supports looking up users by email address or phone number, in addition to userId.```typescript
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.
```bash
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.
```bash
# 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`
```bash
# 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.
```bash
# 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.
```bash
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
```bash
lua agents # Formatted output
lua agents --json # JSON output for scripting
```
See the [Utility Commands](/cli/utility-commands#lua-agents) documentation.
```typescript
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.
```bash
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.
# New (correct)
lua push skill --name mySkill --set-version 1.0.5
```
**Reason:** Avoids confusion with the global `--version` flag that shows CLI version.
# 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.
**Benefit:** Prevents "Version already exists" errors during automated deployments.
- Job Creation: Fixed
__exportsnaming collision when primitives calledJobs.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_JOBSvia 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:
AuthenticationErrorproperly 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
- Added
UserLookupOptionsfor email/phone lookup - Added
EmailChannelMode,CreateGeneratedEmailChannelResponse,CreateExistingEmailChannelResponse - Added
MCPServerSourceenum for tracking MCP server origin - Updated
User.get()return type toUserDataInstance | null - Added
'mcp'and'mastra'to log type enums
Released: January 22, 2026
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.
```bash
# Delete a skill from the server
lua skills delete --skill-name 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
```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>
- Push: Fixed crash when pushing primitives without a version field. First push now defaults to version
0.0.1and shows "(none - first push)" in prompts.
- Added
MCPStreamableHttpServerConfiginterface for streamable-http transport - Updated
MCPTransporttype to'sse' | 'streamable-http' - Added
SkillSourcetype:'cli' | 'marketplace' | 'manual' - Removed
MCPStdioServerConfig(stdio not supported yet)
Released: January 20, 2026
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
# 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.
```bash
lua logs --type user_message --limit 20
lua logs --type agent_response --limit 20
```
- 💬 **User Messages**: View incoming user messages with channel and userId info
- 🤖 **Agent Responses**: View AI-generated responses with distinct coloring
```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.
```typescript
// 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
}
});
```
- Chat: Allow
lua chatto work without mandatory skills - agents can now have only webhooks, jobs, or processors - Commands: Normalized action handling for case-insensitive action comparisons
- 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
Released: January 13, 2026
New `lua sync` command to detect drift between server and local code:```bash
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
```bash
# 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.
```typescript
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'`
```typescript
import { Lua } from 'lua-cli';
// Access raw webhook payload when triggered by webhook
const webhookPayload = Lua.request.webhook;
```
- Simplified Agent Creation: Streamlined
lua initflow with cleaner prompts - Better TypeScript Support: Improved handling of path aliases and variable references in your code
- Fixed sync command occasionally showing false drift detection
- Fixed skill publishing issues
- Fixed compilation when skills are defined inline vs imported from separate files
Released: December 7, 2025
New `LuaMCPServer` class for integrating Model Context Protocol servers with your agent:```typescript
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`
```typescript
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.
```typescript
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);
```
```typescript
// Get all jobs
const jobs = await Jobs.getAll();
// Activate/deactivate job scheduling
await job.activate();
await job.deactivate();
// Manually trigger execution
await job.trigger();
```
```bash
lua evals
```
```typescript
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' } }
});
```
**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
```typescript
const userId = user._luaProfile.userId; // ✅ Recommended
const fullName = user._luaProfile.fullName;
const emails = user._luaProfile.emailAddresses;
// user.userId still works but is deprecated
```
```typescript
// Before
const schedule = job.schedule;
const id = job.jobId;
// After
const schedule = job.activeVersion.schedule;
const id = job.id;
await job.trigger(); // New method
```
```typescript
// Before
execute: async (query, headers, body) => {
// handle webhook
}
// After
execute: async (event) => {
const { query, headers, body, timestamp } = event;
// handle webhook
}
```
```typescript
// 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
- Data API Type Safety:
searchTextparameter added toData.create()andData.update(),dataparameter type changed toRecord<string, any> - PostProcessor Simplified: Return type now requires
modifiedResponse: string, removedasyncfield - Compilation: Handle
.jsextensions for Node16/NodeNext module resolution - Template: Minimal by default, use
--with-examplesflag for examples - Web UI: React Query, Sonner toasts, improved env panels, docs in toolbar
- Removed
contextfield from webhooks, jobs, and postprocessors - Removed
versionfield fromLuaSkill,LuaJob, and processor configurations - Improved push command: displays both
webhookIdandwebhook-nameURL formats - Rewritten
interfaces/jobs.tsto matchlua-apiDTOs exactly
Released: October 30, 2025
Enhanced User.get() method now accepts an optional userId parameter:
// 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
Released: October 30, 2025
This release brings comprehensive dependency bundling, debug mode, enhanced validation, and critical bug fixes.
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.
```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
**Critical Fix:** Relative imports now work correctly in Jobs, Webhooks, and Processors:
```typescript
// ✅ Now works perfectly
import { MyService } from "../services/MyService";
// ✅ Also works
import { MyService } from "@/services/MyService";
```
- 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
- 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
Released: October 2025
Version 3.0.0 focuses on developer experience, deployment automation, and real-time chat capabilities.
The flagship feature: a single, intuitive way to configure your entire agent.**Before (v2.x):**
```typescript
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
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
```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
```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
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
```
**On `lua init`:**
- Agent name, persona → YAML + `index.ts` LuaAgent
**On `lua compile`:**
- LuaAgent persona → YAML
No manual synchronization needed!
Bundling:
- Fixed
Cannot find module '../services/ApiService'in pre-bundled tools - Fixed
process.cwd is not a functionin sandbox execution - Fixed lua-cli API code being bundled into tools
Push & Deploy:
- Fixed webhooks and jobs not found during
push all - Fixed missing
toolsarray 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
**New Way:**
```typescript
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
No action needed - handled automatically by CLI.
```typescript
await Jobs.create({
metadata: { userId: input.userId },
execute: async (job) => {
const userId = job.metadata.userId;
}
});
```
| Metric | Before | After |
|---|---|---|
| Bundle overhead | ~500KB | 50-70% smaller |
| Compilation speed | - | 30% faster |
| Template examples | 5 | 30+ |
| CLI commands | - | 25+ |
npm install lua-cli@3.1.0Required changes:
- Update
JobInstanceaccess patterns (useactiveVersion.schedule,idinstead ofjobId) - Update webhook execute functions to use event object
- Update PreProcessor responses to use discriminated union
- Remove
welcomeMessagefrom LuaAgent (configure on channel/voice instead)
npm install lua-cli@3.0.0Required changes:
- Wrap skills in a
LuaAgentconfiguration - Update jobs to use
metadatafor data passing - Run
lua compileto sync with YAML
// src/index.ts
import { LuaAgent } from 'lua-cli';
export const agent = new LuaAgent({
name: 'my-agent',
persona: 'Your agent persona...',
skills: [/* your existing skills */],
});