lua-cli 3.32.2 → 3.32.3

package/docs/CLI_REFERENCE.md

@@ -27,6 +27,7 @@ Complete reference for all lua-cli commands.
 Set up API authentication.
 
 **Usage:**
+
 ```bash
 lua auth configure
 ```
@@ -35,6 +36,7 @@ lua auth configure
 Prompts for your API key and stores it in `~/.lua-cli/credentials` (file-based, works on all platforms including headless Linux and Docker).
 
 **Example:**
+
 ```bash
 $ lua auth configure
 ? Enter your Lua API key: **********************
@@ -42,6 +44,7 @@ $ lua auth configure
 ```
 
 **Alternative Authentication:**
+
 - Environment variable: `export LUA_API_KEY=your-api-key`
 - `.env` file: `LUA_API_KEY=your-api-key`
 
@@ -54,6 +57,7 @@ $ lua auth configure
 Initialize a new Lua agent project.
 
 **Usage:**
+
 ```bash
 lua init [options]
 ```
@@ -62,11 +66,13 @@ lua init [options]
 Creates project structure, configures agent, and sets up development environment.
 
 **Interactive Prompts:**
+
 - Select or create an agent
 - Configure persona and welcome message
 - Set up project directory structure
 
 **Example:**
+
 ```bash
 $ lua init
 ? Select an agent: (Use arrow keys)
@@ -89,21 +95,25 @@ $ lua init
 Compile TypeScript source code to deployable format.
 
 **Usage:**
+
 ```bash
 lua compile [options]
 ```
 
 **Options:**
+
 - `--debug` - Show detailed compilation output
 
 **Description:**
 Compiles TypeScript to JavaScript bundles, validates primitives (tools, skills, webhooks, jobs, processors), and generates manifest.
 
 **Output:**
+
 - `.lua/artifacts/` - Bundled JavaScript files
 - `.lua/manifest.json` - Compilation manifest
 
 **Example:**
+
 ```bash
 $ lua compile
 ⏳ Compiling agent...
@@ -125,6 +135,7 @@ $ lua compile --debug
 Test tools, webhooks, and jobs interactively.
 
 **Usage:**
+
 ```bash
 lua test [options]
 ```
@@ -133,12 +144,14 @@ lua test [options]
 Interactive testing environment for individual primitives. Runs code in local sandbox with full API access.
 
 **Interactive Flow:**
+
 1. Select primitive type (Tool / Webhook / Job)
 2. Select specific primitive to test
 3. Provide test input
 4. View execution results
 
 **Example:**
+
 ```bash
 $ lua test
 ? Select type: Tool
@@ -161,23 +174,27 @@ $ lua test
 Interactive chat interface with your agent.
 
 **Usage:**
+
 ```bash
 lua chat [options]
 ```
 
 **Options:**
+
 - `--production` - Chat with production environment (default: sandbox)
 
 **Description:**
 Real-time streaming chat interface for testing agent behavior.
 
 **Features:**
+
 - ✅ Animated typing indicator
 - ✅ Character-by-character streaming
 - ✅ Tool execution visibility
 - ✅ Environment selection (sandbox/production)
 
 **Example:**
+
 ```bash
 $ lua chat
 🤖 Welcome! How can I help you today?
@@ -197,17 +214,20 @@ You: /exit
 Start development server with live reload.
 
 **Usage:**
+
 ```bash
 lua dev [options]
 ```
 
 **Options:**
+
 - `--port <number>` - Server port (default: 3100)
 
 **Description:**
 Starts local development server with file watching and live reload. Includes chat UI and sandbox environment.
 
 **Example:**
+
 ```bash
 $ lua dev
 🚀 Dev server running on http://localhost:3100
@@ -227,14 +247,17 @@ $ lua dev
 Push primitives to the server.
 
 **Usage:**
+
 ```bash
 lua push [type] [options]
 ```
 
 **Arguments:**
+
 - `type` - Primitive type to push: `skill`, `webhook`, `job`, `preprocessor`, `postprocessor`, `mcp`, `device`, `all`
 
 **Options:**
+
 - `--name <name>` - Specific primitive name
 - `--force` - Skip confirmation prompts
 - `--auto-deploy` - Automatically deploy after push (only with `all`)
@@ -243,6 +266,7 @@ lua push [type] [options]
 Uploads compiled artifacts to the server, creates new versions, and optionally deploys to production.
 
 **Interactive Mode:**
+
 ```bash
 $ lua push
 ? Select type: Skill
@@ -256,6 +280,7 @@ $ lua push
 ```
 
 **Batch Mode (CI/CD):**
+
 ```bash
 $ lua push all --force --auto-deploy
 ⏳ Pushing all primitives...
@@ -266,6 +291,7 @@ $ lua push all --force --auto-deploy
 ```
 
 **Examples:**
+
 ```bash
 # Push specific skill interactively
 lua push skill
@@ -284,14 +310,17 @@ lua push all --force --auto-deploy
 Deploy a primitive version to production.
 
 **Usage:**
+
 ```bash
 lua deploy [type] [options]
 ```
 
 **Arguments:**
+
 - `type` - Primitive type: `skill`, `webhook`, `job`, `preprocessor`, `postprocessor`, `mcp`
 
 **Options:**
+
 - `--name <name>` - Specific primitive name
 - `--version <version>` - Specific version (default: latest)
 
@@ -299,6 +328,7 @@ lua deploy [type] [options]
 Activates a specific version in production environment.
 
 **Example:**
+
 ```bash
 $ lua deploy skill
 ? Select skill: general-skill
@@ -315,6 +345,7 @@ $ lua deploy skill
 View production environment status.
 
 **Usage:**
+
 ```bash
 lua production [options]
 ```
@@ -323,6 +354,7 @@ lua production [options]
 Displays current production state for all primitives (skills, webhooks, jobs, processors).
 
 **Example:**
+
 ```bash
 $ lua production
 📊 Production Status
@@ -345,11 +377,13 @@ Jobs:
 Manage environment variables.
 
 **Usage:**
+
 ```bash
 lua env [command]
 ```
 
 **Commands:**
+
 - `list` - List all environment variables
 - `set <key> <value>` - Set environment variable
 - `delete <key>` - Delete environment variable
@@ -358,6 +392,7 @@ lua env [command]
 Manage server-side environment variables (stored encrypted, available in tools/webhooks/jobs).
 
 **Example:**
+
 ```bash
 $ lua env list
 🔑 Environment Variables:
@@ -378,17 +413,20 @@ $ lua env delete OLD_KEY
 Update agent persona.
 
 **Usage:**
+
 ```bash
 lua persona [options]
 ```
 
 **Options:**
+
 - `--set <text>` - Set persona text directly
 
 **Description:**
 Updates agent personality/instructions.
 
 **Example:**
+
 ```bash
 $ lua persona
 ? Agent persona: You are a friendly customer support agent specialized in e-commerce...
@@ -405,11 +443,13 @@ $ lua persona --set "You are a technical support specialist..."
 View and filter agent logs.
 
 **Usage:**
+
 ```bash
 lua logs [options]
 ```
 
 **Options:**
+
 - `--limit <number>` - Number of logs to fetch (default: 50)
 - `--follow` - Follow logs in real-time
 
@@ -417,6 +457,7 @@ lua logs [options]
 Interactive log viewer with filtering, search, and real-time streaming.
 
 **Example:**
+
 ```bash
 $ lua logs
 📋 Recent Logs (50)
@@ -439,16 +480,19 @@ $ lua logs
 Manage skills.
 
 **Usage:**
+
 ```bash
 lua skills [command]
 ```
 
 **Commands:**
+
 - `list` - List all skills
 - `versions <name>` - View skill versions
 - `delete <name>` - Delete a skill
 
 **Example:**
+
 ```bash
 $ lua skills list
 📚 Skills:
@@ -469,15 +513,18 @@ $ lua skills versions general-skill
 Manage webhooks.
 
 **Usage:**
+
 ```bash
 lua webhooks [command]
 ```
 
 **Commands:**
+
 - `list` - List all webhooks
 - `url <name>` - Get webhook URL
 
 **Example:**
+
 ```bash
 $ lua webhooks list
 🪝 Webhooks:
@@ -496,15 +543,18 @@ https://api.heylua.ai/webhooks/hook_123
 Manage scheduled jobs.
 
 **Usage:**
+
 ```bash
 lua jobs [command]
 ```
 
 **Commands:**
+
 - `list` - List all jobs
 - `run <name>` - Manually trigger a job
 
 **Example:**
+
 ```bash
 $ lua jobs list
 ⏰ Scheduled Jobs:
@@ -523,11 +573,13 @@ $ lua jobs run daily-cleanup
 Connect third-party accounts and services.
 
 **Usage:**
+
 ```bash
 lua integrations [command]
 ```
 
 **Commands:**
+
 - `list` - List available integrations
 - `connect <name>` - Connect an integration
 - `disconnect <name>` - Disconnect an integration
@@ -536,6 +588,7 @@ lua integrations [command]
 Authenticate and connect third-party services (Linear, Discord, Google Calendar, etc.). Automatically creates MCP servers for connected integrations.
 
 **Supported Integrations:**
+
 - Linear - Project management
 - Discord - Bot integration
 - Google Calendar - Calendar access
@@ -545,6 +598,7 @@ Authenticate and connect third-party services (Linear, Discord, Google Calendar,
 - And more...
 
 **Example:**
+
 ```bash
 $ lua integrations list
 🔌 Available Integrations:
@@ -566,15 +620,18 @@ $ lua integrations connect linear
 Manage chat channels (WhatsApp, Web, etc.).
 
 **Usage:**
+
 ```bash
 lua channels [command]
 ```
 
 **Commands:**
+
 - `list` - List all channels
 - `configure <channel>` - Configure channel settings
 
 **Example:**
+
 ```bash
 $ lua channels list
 💬 Active Channels:
@@ -592,6 +649,7 @@ $ lua channels list
 Browse, install, and manage marketplace skills and agent templates.
 
 **Usage:**
+
 ```bash
 lua marketplace [noun] [action] [options]
 ```
@@ -600,15 +658,18 @@ lua marketplace [noun] [action] [options]
 With no arguments, prompts for a domain — **Skills** or **Agent templates** — then hands off to that domain's own interactive picker. Pass `noun` (`skill` or `template`) to skip straight to a domain, and `action` for non-interactive mode.
 
 **Skill actions** (`lua marketplace skill <action>`):
+
 - `list`, `publish`, `edit`, `unlist`, `unpublish`, `transfer`, `org` — manage listings owned by the configured agent's organization
 - `mine` — list skills originally authored by the caller; ownership is still shown separately through `creatorOrgId`
 - `search`, `view`, `install`, `update`, `uninstall`, `installed` — browse and manage skills on this agent
 
 **Template actions** (`lua marketplace template <action>`):
+
 - `create`, `publish`, `view`, `versions` — manage a versioned snapshot of an agent's deployable manifest
 - `install`, `apply`, `status`, `installed`, `uninstall` — install onto one agent, or fleet-apply across many
 
 **Example:**
+
 ```bash
 $ lua marketplace
 ? What would you like to browse?
@@ -638,6 +699,7 @@ $ lua marketplace template apply --template-id xyz --all-installed --force
 Open the admin dashboard.
 
 **Usage:**
+
 ```bash
 lua admin
 ```
@@ -652,6 +714,7 @@ Opens https://admin.heylua.ai in your default browser.
 Open documentation.
 
 **Usage:**
+
 ```bash
 lua docs
 ```
@@ -666,11 +729,13 @@ Opens https://docs.heylua.ai in your default browser.
 Show CLI version.
 
 **Usage:**
+
 ```bash
 lua --version
 ```
 
 **Example:**
+
 ```bash
 $ lua --version
 lua-cli vX.Y.Z
@@ -683,12 +748,14 @@ lua-cli vX.Y.Z
 Show help information.
 
 **Usage:**
+
 ```bash
 lua --help
 lua <command> --help
 ```
 
 **Example:**
+
 ```bash
 $ lua --help
 Usage: lua [command] [options]
@@ -718,6 +785,7 @@ These flags can be used with any command:
 Enable CI/CD mode (fail loudly on missing required flags).
 
 **Usage:**
+
 ```bash
 lua <command> --ci
 ```
@@ -726,6 +794,7 @@ lua <command> --ci
 In CI/CD environments (non-TTY), interactive prompts fail silently. The `--ci` flag makes the CLI fail loudly with clear error messages when required flags are missing.
 
 **Example:**
+
 ```bash
 # Without --ci flag (silent failure in CI)
 $ lua push skill
@@ -744,6 +813,7 @@ $ lua push skill --ci --name weather-skill --force
 
 **Best Practice:**
 Always use `--ci` in CI/CD pipelines:
+
 ```yaml
 # .github/workflows/deploy.yml
 - name: Deploy
@@ -759,11 +829,13 @@ Always use `--ci` in CI/CD pipelines:
 API authentication key.
 
 **Priority:**
+
 1. System keychain (set via `lua auth configure`)
 2. `LUA_API_KEY` environment variable
 3. `LUA_API_KEY` in `.env` file
 
 **Example:**
+
 ```bash
 export LUA_API_KEY=your-api-key
 lua push all --force
@@ -773,16 +845,43 @@ lua push all --force
 
 ## Exit Codes
 
-- `0` - Success
-- `1` - Error (general failure)
-- `2` - Authentication error
-- `130` - User cancelled (Ctrl+C)
+Every `lua` command exits with one of the classes below; `lua --help` prints the same table. An error is one line on stderr — `✖ <code>: <message>` — plus a `💡` hint when there is one; `LUA_DEBUG=1` (or `--debug`) prints the stack under it. `--help` / `--version` and a prompt cancelled with Ctrl+C exit `0`.
+
+| Exit | Code          | When                                                                                           |
+| ---- | ------------- | ---------------------------------------------------------------------------------------------- |
+| `0`  | `ok`          | Success                                                                                        |
+| `1`  | `error`       | An unclassified failure — the message says what (a compile failure is `compile_failed`)        |
+| `2`  | `usage`       | Bad arguments — an unknown option or command, an unknown action, no project / agent configured |
+| `3`  | `not_found`   | The named thing does not exist (HTTP 404)                                                      |
+| `9`  | `auth`        | No credential, or the server refused it (HTTP 401)                                             |
+| `10` | `forbidden`   | The credential is fine but may not do this (HTTP 403 — any other 4xx as `http_<status>`)       |
+| `11` | `unavailable` | The server or the network failed (HTTP 5xx, connection refused, request timeout)               |
+
+`lua workflows` adds its run outcomes — which is why the classes above skip 4–8 — and keeps `1` for the server's refusal of a verb (a 4xx other than 404):
+
+| Exit | Code            | When                                                                                   |
+| ---- | --------------- | -------------------------------------------------------------------------------------- |
+| `4`  | `run_failed`    | The run ended `failed` / `timed_out`                                                   |
+| `5`  | `run_cancelled` | The run ended `cancelled` / `abandoned`                                                |
+| `6`  | `run_gated`     | A consent gate — `start --follow` / `watch` exit here unless `--wait-for-human`        |
+| `7`  | `timeout`       | `--timeout <s>` reached (the run is still live)                                        |
+| `8`  | `run_parked`    | The run waits for a human — approval, input, signal, billing / budget / exception park |
+
+As printed by `lua --help` (`CLI_EXIT_CODE_HELP` in `src/errors/cli.error.ts`; `tests/__tests__/docs.exit-codes.test.ts` keeps this section and the constants in step):
+
+```text
+Exit codes: 0 ok · 1 error · 2 usage · 3 not found · 9 auth (401) · 10 forbidden (403 / other 4xx) ·
+            11 unavailable (5xx / network). lua workflows adds 4 run failed · 5 run cancelled · 6 run gated ·
+            7 --timeout reached · 8 run parked waiting for a human.
+Errors:     one line — ✖ <code>: <message> — plus a 💡 hint; LUA_DEBUG=1 prints the stack.
+```
 
 ---
 
 ## Tips & Best Practices
 
 ### Development Workflow
+
 ```bash
 # 1. Make changes
 vim src/skills/tools/MyTool.ts
@@ -804,12 +903,14 @@ lua deploy skill --name my-skill
 ```
 
 ### CI/CD Workflow
+
 ```bash
 # Single command deployment
 lua push all --ci --force --auto-deploy
 ```
 
 ### Testing Before Deploy
+
 ```bash
 # Always test in sandbox first
 lua chat  # Sandbox mode
@@ -819,6 +920,7 @@ lua push all --force --auto-deploy
 ```
 
 ### Version Management
+
 ```bash
 # View versions
 lua skills versions my-skill
@@ -835,6 +937,7 @@ lua deploy skill --name my-skill --version 0.9.0
 ## Common Patterns
 
 ### Create and Deploy New Skill
+
 ```bash
 # 1. Create tool file
 # src/skills/tools/MyTool.ts
@@ -852,11 +955,13 @@ lua deploy skill --name my-skill
 ```
 
 ### Update Agent Persona
+
 ```bash
 lua persona --set "You are a helpful assistant specializing in..."
 ```
 
 ### Monitor Production
+
 ```bash
 # View status
 lua production
@@ -869,6 +974,7 @@ lua skills versions my-skill
 ```
 
 ### Environment Variables
+
 ```bash
 # Set environment variables
 lua env set OPENAI_API_KEY sk-...
@@ -886,6 +992,7 @@ lua env delete OLD_KEY
 ## Troubleshooting
 
 ### "Authentication failed"
+
 ```bash
 # Reconfigure API key
 lua auth configure
@@ -895,6 +1002,7 @@ export LUA_API_KEY=your-api-key
 ```
 
 ### "Compilation failed"
+
 ```bash
 # Check for errors
 lua compile --debug
@@ -906,12 +1014,14 @@ lua compile --debug
 ```
 
 ### "Command hangs in CI"
+
 ```bash
 # Use --ci flag to fail loudly
 lua push all --ci --force --auto-deploy
 ```
 
 ### "Version conflict"
+
 ```bash
 # View current versions
 lua production
@@ -929,20 +1039,24 @@ lua deploy skill --name my-skill --version 1.0.0
 Manage the LLM model for your agent.
 
 **Usage:**
+
 ```bash
 lua models [action] [options]
 ```
 
 **Actions:**
+
 - `list` (default) — list all approved models grouped by provider, highlighting the current model
 - `set` — interactively select or non-interactively specify a model; writes it to `src/index.ts` and pushes to server
 - `unset` — remove the model from source and clear it on the server (reverts to platform default)
 
 **Options:**
+
 - `--model <code>` - Model code to set non-interactively (e.g. `openai/gpt-4o`)
 - `--json` - Output model list as JSON
 
 **Examples:**
+
 ```bash
 # List all available models
 lua models
@@ -971,11 +1085,13 @@ lua models list --json
 Manage bidirectional agent-device communication.
 
 **Usage:**
+
 ```bash
 lua devices [action] [options]
 ```
 
 **Actions:**
+
 - `list` — list all registered devices
 - `status` — check if a device is online, offline, or disabled
 - `enable` — re-enable a disabled device
@@ -985,6 +1101,7 @@ lua devices [action] [options]
 - `test-trigger` — simulate an inbound trigger from a device
 
 **Options:**
+
 - `--device-name <name>` - Target device name (interactive picker shown when omitted)
 - `--group <name>` - Filter devices by group (for `list`)
 - `--payload <json>` - JSON payload to send with the command (default: `{}`)
@@ -992,6 +1109,7 @@ lua devices [action] [options]
 - `--force` - Skip confirmation prompt (for `remove`)
 
 **Examples:**
+
 ```bash
 # List all devices
 lua devices list
@@ -1019,6 +1137,7 @@ lua devices test-trigger --device-name my-sensor
 ```
 
 **Pushing device definitions:**
+
 ```bash
 lua push device               # push device configurations to the server
 lua push all                  # includes devices in full push
@@ -1033,11 +1152,13 @@ lua push all                  # includes devices in full push
 Detect and resolve drift between local and server state.
 
 **Usage:**
+
 ```bash
 lua sync [options]
 ```
 
 **Options:**
+
 - `--check` - Report drift and exit 1 if any drift is found (CI/CD use)
 - `--accept` - Auto-pull all server state to local (non-interactive)
 - `--push` - Auto-push all local changes to server (non-interactive)
@@ -1050,6 +1171,7 @@ Compares your local YAML config and source files against the server state. Detec
 `lua sync --pull` (and `--accept`) guards against overwriting local changes made since the last `lua push backup`. If modified files are detected, the pull is refused with a list of conflicted files. Use `--force` to bypass.
 
 **Examples:**
+
 ```bash
 # Interactive drift resolution
 lua sync

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.32.2
+# lua-cli v3.32.3
 
-Welcome to the comprehensive API documentation for lua-cli v3.32.2. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.32.3. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index