> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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] ``` Looking for what's new? See the [changelog](/changelog) for release notes. ### 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 marketplace` | 🛒 Ecosystem | Discover, install, and publish skills | ✅ 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 any primitive version to production (skill, webhook, job, processor, persona) | ✅ 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 | Browse, install, and publish skills on the marketplace | ✅ 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 | **For AI IDEs**: Complete workflow for Cursor, Windsurf, GitHub Copilot Command reference for automation, CI/CD, and scripting ### Quick Examples ```bash theme={null} # Authentication & Setup lua auth configure # 🔑 Set up your API key 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 skills marketplace # 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 deploy # 🚀 Deploy to production # 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 ``` **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) ## Quick Command Reference Initialize new skill project View and manage skills Manage environment variables Configure agent personality Manage agent capabilities Manage MCP servers Connect third-party accounts Detect and resolve drift Test tools interactively Interactive chat with your agent Upload version to server Deploy to production Shell autocomplete setup ## Shell Autocomplete Enable tab completion for all Lua CLI commands and arguments: ```bash theme={null} # One-time setup lua completion bash >> ~/.bashrc source ~/.bashrc # Now try: lua pu # Completes to: lua push lua push # Shows: skill, persona lua env # Shows: sandbox, staging, production ``` ```bash theme={null} # One-time setup lua completion zsh >> ~/.zshrc source ~/.zshrc # Now try: lua # Shows all commands lua persona # Shows: sandbox, staging, production ``` ```bash theme={null} # One-time setup lua completion fish > ~/.config/fish/completions/lua.fish # Now try: lua # Shows all commands with descriptions ``` ## Direct Mode Skip interactive prompts by specifying your target directly: ```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 ``` ```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 ``` ```bash theme={null} # Interactive lua persona ? Select environment: › Sandbox Production # Direct lua persona sandbox # Edit sandbox persona lua persona production # Deploy persona version ``` ```bash theme={null} # Interactive lua skills ? Select environment: › Sandbox Production # Direct lua skills sandbox # View local skills lua skills production # Manage production skills ``` ## Command Categories ### Authentication Set up API key authentication ```bash theme={null} lua auth configure ``` Choose between: * **Email**: OTP verification * **API Key**: Existing key Display stored API key ```bash theme={null} lua auth key ``` Shows key after confirmation prompt Delete stored credentials ```bash theme={null} lua auth logout ``` Removes key from system keychain ### Skill Management 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 Compile TypeScript to JavaScript ```bash theme={null} lua compile ``` Automatically: * Detects all tools * Bundles with esbuild * Creates deployment artifacts * Updates skill IDs Test tools interactively ```bash theme={null} lua test ``` Features: * Select tool from list * Dynamic input prompts * Secure sandbox execution * Detailed error reporting Upload version to server ```bash theme={null} lua push ``` * Compiles code * Validates configuration * Uploads to server * Creates new version Deploy to production ```bash theme={null} lua deploy ``` * Lists available versions * Shows current version * Requires confirmation * Immediate deployment Interactive chat ```bash theme={null} lua chat ``` Features: * Sandbox or production mode * Test conversational flows * Skill overrides * Persona customization ## Common Workflows ### New Project Workflow ```bash theme={null} lua auth configure ``` ```bash theme={null} mkdir my-skill && cd my-skill lua init # Minimal project (recommended) # OR lua init --with-examples # Include example code ``` ```bash theme={null} lua env sandbox ``` Add API keys and configuration to .env file ```bash theme={null} lua persona sandbox ``` Define your agent's personality in local file ```bash theme={null} lua chat ``` Interactive chat in sandbox mode **Optional**: Use `lua test` to test individual tools with specific inputs ```bash theme={null} lua push lua deploy ``` ### Development Workflow ```bash theme={null} lua env sandbox # Update local .env lua env production # Update production env vars ``` Add any new API keys or configuration needed ```bash theme={null} lua persona sandbox # Edit and test locally ``` Refine agent personality based on feedback Edit your tools in `src/tools/*.ts` ```bash theme={null} lua chat ``` Select sandbox mode to test with local changes **Pro tip**: Use `lua test` to debug specific tool logic if needed ```bash theme={null} lua persona production # Deploy persona version ``` Or use: `lua push persona` ```bash theme={null} lua push skill ``` Upload new skill version ```bash theme={null} lua deploy ``` Make available to all users ### 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: Variables from your shell Variables from project `.env` Variables from skill config ## Error Handling All commands include: * ✅ Descriptive error messages * ✅ Exit codes (0 = success, 1 = error) * ✅ Troubleshooting hints ### Common Errors ``` ❌ No API key found. Run `lua auth configure` first. ``` **Solution**: Run `lua auth configure` ``` ❌ No lua.skill.yaml found. Please run this command from a skill directory. ``` **Solution**: Run command from skill directory or run `lua init` first ``` ❌ 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) ``` ❌ No index.ts found in current directory or src/ directory ``` **Solution**: Create `index.ts` or `src/index.ts` with skill definition ## 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 Version 16.0.0 or higher Version 7.0.0 or higher Included in template (knowledge helpful) Optional but recommended ## Storage Locations **System Keychain** * macOS: Keychain * Windows: Credential Vault * Linux: libsecret **Your Project Directory** ``` your-skill/ ├── src/ # Your code ├── dist/ # Compiled output ├── .lua/ # CLI cache ├── node_modules/ # Dependencies └── lua.skill.yaml ``` **Build Artifacts** * `dist/` - Deployment bundles * `.lua/` - Compilation cache Safe to delete, will be regenerated ## Next Steps Set up API key authentication Learn all skill management commands Detect and resolve drift Manage sandbox and production variables Configure agent personality Manage agent capabilities Manage MCP servers for external tools Connect third-party accounts Interactive chat with your agent Shell autocomplete and more