lua-cli 3.5.0-alpha.3 → 3.5.0-beta.1

package/docs/CLI_REFERENCE.md

@@ -0,0 +1,924 @@
+# CLI Command Reference
+
+Complete reference for all lua-cli commands.
+
+---
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Project Setup](#project-setup)
+- [Development](#development)
+- [Deployment](#deployment)
+- [Management](#management)
+- [Marketplace](#marketplace)
+- [Utilities](#utilities)
+- [Global Flags](#global-flags)
+
+---
+
+## Authentication
+
+### `lua auth configure`
+
+Set up API authentication.
+
+**Usage:**
+```bash
+lua auth configure
+```
+
+**Description:**
+Prompts for your API key and stores it securely in the system keychain (macOS Keychain, Windows Credential Vault, Linux libsecret).
+
+**Example:**
+```bash
+$ lua auth configure
+? Enter your Lua API key: **********************
+✅ API key configured successfully
+```
+
+**Alternative Authentication:**
+- Environment variable: `export LUA_API_KEY=your-api-key`
+- `.env` file: `LUA_API_KEY=your-api-key`
+
+---
+
+## Project Setup
+
+### `lua init`
+
+Initialize a new Lua agent project.
+
+**Usage:**
+```bash
+lua init [options]
+```
+
+**Description:**
+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)
+❯ Create new agent
+  my-assistant (existing)
+
+? Agent name: customer-support-bot
+? Persona: You are a helpful customer support assistant...
+? Welcome message: Hello! How can I help you today?
+
+✅ Project initialized successfully
+```
+
+---
+
+## Development
+
+### `lua compile`
+
+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...
+✅ Compiled 5 tools, 2 skills, 1 webhook
+✅ Compilation complete
+
+$ lua compile --debug
+🔍 Scanning src/...
+🔍 Found: src/skills/tools/WeatherTool.ts (TOOL)
+🔍 Found: src/skills/general.skill.ts (SKILL)
+📦 Bundling...
+✅ Compilation complete
+```
+
+---
+
+### `lua test`
+
+Test tools, webhooks, and jobs interactively.
+
+**Usage:**
+```bash
+lua test [options]
+```
+
+**Description:**
+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
+? Select tool: get_weather
+? Input (JSON): { "city": "London" }
+
+⏳ Executing...
+✅ Result:
+{
+  "temperature": 15,
+  "condition": "cloudy",
+  "city": "London"
+}
+```
+
+---
+
+### `lua chat`
+
+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?
+
+You: What's the weather in Paris?
+🔄 Calling tool: get_weather...
+Agent: The current weather in Paris is 18°C and sunny.
+
+You: /exit
+👋 Goodbye!
+```
+
+---
+
+### `lua dev`
+
+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
+📂 Watching for changes...
+
+[10:30:15] File changed: src/skills/tools/WeatherTool.ts
+[10:30:15] Recompiling...
+✅ Compilation complete
+```
+
+---
+
+## Deployment
+
+### `lua push`
+
+Push primitives to the server.
+
+**Usage:**
+```bash
+lua push [type] [options]
+```
+
+**Arguments:**
+- `type` - Primitive type to push: `skill`, `webhook`, `job`, `preprocessor`, `postprocessor`, `mcp`, `all`
+
+**Options:**
+- `--name <name>` - Specific primitive name
+- `--force` - Skip confirmation prompts
+- `--auto-deploy` - Automatically deploy after push (only with `all`)
+
+**Description:**
+Uploads compiled artifacts to the server, creates new versions, and optionally deploys to production.
+
+**Interactive Mode:**
+```bash
+$ lua push
+? Select type: Skill
+? Select skill: general-skill
+? Confirm push? Yes
+
+⏳ Pushing general-skill...
+✅ Pushed v1.0.1
+? Deploy to production? Yes
+✅ Deployed to production
+```
+
+**Batch Mode (CI/CD):**
+```bash
+$ lua push all --force --auto-deploy
+⏳ Pushing all primitives...
+✅ Pushed 2 skills (v1.0.1)
+✅ Pushed 1 webhook (v1.0.1)
+✅ Pushed 1 job (v1.0.1)
+✅ Deployed to production
+```
+
+**Examples:**
+```bash
+# Push specific skill interactively
+lua push skill
+
+# Push specific skill by name without prompts
+lua push skill --name weather-skill --force
+
+# Push all and deploy to production (CI/CD)
+lua push all --force --auto-deploy
+```
+
+---
+
+### `lua 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)
+
+**Description:**
+Activates a specific version in production environment.
+
+**Example:**
+```bash
+$ lua deploy skill
+? Select skill: general-skill
+? Select version: v1.0.1
+✅ Deployed general-skill v1.0.1 to production
+```
+
+---
+
+## Management
+
+### `lua production`
+
+View production environment status.
+
+**Usage:**
+```bash
+lua production [options]
+```
+
+**Description:**
+Displays current production state for all primitives (skills, webhooks, jobs, processors).
+
+**Example:**
+```bash
+$ lua production
+📊 Production Status
+
+Skills:
+  ✅ general-skill v1.0.1
+  ✅ weather-skill v1.0.0
+
+Webhooks:
+  ✅ payment-webhook v1.0.0
+
+Jobs:
+  ✅ daily-cleanup v1.0.0
+```
+
+---
+
+### `lua env`
+
+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
+
+**Description:**
+Manage server-side environment variables (stored encrypted, available in tools/webhooks/jobs).
+
+**Example:**
+```bash
+$ lua env list
+🔑 Environment Variables:
+  OPENAI_API_KEY=sk-...
+  STRIPE_SECRET_KEY=sk_live_...
+
+$ lua env set WEATHER_API_KEY abc123
+✅ Set WEATHER_API_KEY
+
+$ lua env delete OLD_KEY
+✅ Deleted OLD_KEY
+```
+
+---
+
+### `lua persona`
+
+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...
+✅ Persona updated
+
+$ lua persona --set "You are a technical support specialist..."
+✅ Persona updated
+```
+
+---
+
+### `lua logs`
+
+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
+
+**Description:**
+Interactive log viewer with filtering, search, and real-time streaming.
+
+**Example:**
+```bash
+$ lua logs
+📋 Recent Logs (50)
+
+[2026-02-06 10:30:15] INFO  Tool execution: get_weather
+[2026-02-06 10:30:16] INFO  API call: weather.com
+[2026-02-06 10:30:17] INFO  Response sent
+
+? Filter by level: (Use arrow keys)
+  All
+❯ Info
+  Warning
+  Error
+```
+
+---
+
+### `lua skills`
+
+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:
+  - general-skill (v1.0.1)
+  - weather-skill (v1.0.0)
+
+$ lua skills versions general-skill
+📦 Versions for general-skill:
+  - v1.0.1 (production)
+  - v1.0.0
+  - v0.9.0
+```
+
+---
+
+### `lua webhooks`
+
+Manage webhooks.
+
+**Usage:**
+```bash
+lua webhooks [command]
+```
+
+**Commands:**
+- `list` - List all webhooks
+- `url <name>` - Get webhook URL
+
+**Example:**
+```bash
+$ lua webhooks list
+🪝 Webhooks:
+  - payment-webhook (v1.0.0)
+    URL: https://api.heylua.ai/webhooks/hook_123
+
+$ lua webhooks url payment-webhook
+🔗 Webhook URL:
+https://api.heylua.ai/webhooks/hook_123
+```
+
+---
+
+### `lua jobs`
+
+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:
+  - daily-cleanup (v1.0.0)
+    Schedule: 0 0 * * * (daily at midnight)
+    Status: Active
+
+$ lua jobs run daily-cleanup
+✅ Job daily-cleanup executed successfully
+```
+
+---
+
+### `lua integrations`
+
+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
+
+**Description:**
+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
+- Slack - Workspace integration
+- GitHub - Repository access
+- Notion - Workspace data
+- And more...
+
+**Example:**
+```bash
+$ lua integrations list
+🔌 Available Integrations:
+  - Linear
+  - Discord
+  - Google Calendar
+  - Slack
+
+$ lua integrations connect linear
+🔗 Opening browser for authentication...
+✅ Linear connected
+✅ MCP server created: linear-integration
+```
+
+---
+
+### `lua channels`
+
+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:
+  - WhatsApp (configured)
+  - Web Chat (configured)
+  - API (configured)
+```
+
+---
+
+## Marketplace
+
+### `lua marketplace`
+
+Access the skills marketplace.
+
+**Usage:**
+```bash
+lua marketplace [options]
+```
+
+**Description:**
+Interactive marketplace for discovering and installing community skills. Also allows publishing your own skills.
+
+**Features:**
+- 🔍 Browse verified skills
+- 📥 Install skills to your agent
+- 📤 Publish your own skills
+- ⭐ View ratings and reviews
+
+**Example:**
+```bash
+$ lua marketplace
+? What would you like to do?
+❯ Browse Skills (Installer)
+  Publish Skill (Creator)
+
+? Select category:
+  - E-commerce
+  - Productivity
+  - Data Analysis
+  - Communication
+
+? Install "Advanced Calculator"? Yes
+✅ Skill installed successfully
+```
+
+---
+
+## Utilities
+
+### `lua admin`
+
+Open the admin dashboard.
+
+**Usage:**
+```bash
+lua admin
+```
+
+**Description:**
+Opens https://admin.heylua.ai in your default browser.
+
+---
+
+### `lua docs`
+
+Open documentation.
+
+**Usage:**
+```bash
+lua docs
+```
+
+**Description:**
+Opens https://docs.heylua.ai in your default browser.
+
+---
+
+### `lua --version`
+
+Show CLI version.
+
+**Usage:**
+```bash
+lua --version
+```
+
+**Example:**
+```bash
+$ lua --version
+lua-cli v3.5.0-alpha.3
+```
+
+---
+
+### `lua --help`
+
+Show help information.
+
+**Usage:**
+```bash
+lua --help
+lua <command> --help
+```
+
+**Example:**
+```bash
+$ lua --help
+Usage: lua [command] [options]
+
+Commands:
+  auth         Authentication commands
+  init         Initialize new project
+  compile      Compile source code
+  ...
+
+$ lua push --help
+Usage: lua push [type] [options]
+
+Arguments:
+  type         Primitive type to push
+...
+```
+
+---
+
+## Global Flags
+
+These flags can be used with any command:
+
+### `--ci`
+
+Enable CI/CD mode (fail loudly on missing required flags).
+
+**Usage:**
+```bash
+lua <command> --ci
+```
+
+**Description:**
+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
+# Command cancels silently
+
+# With --ci flag (loud failure with clear message)
+$ lua push skill --ci
+❌ Error: Interactive prompt required but --ci flag is set.
+   Provide all required flags or arguments.
+   Missing: --name
+
+# Correct usage in CI
+$ lua push skill --ci --name weather-skill --force
+✅ Pushed weather-skill v1.0.1
+```
+
+**Best Practice:**
+Always use `--ci` in CI/CD pipelines:
+```yaml
+# .github/workflows/deploy.yml
+- name: Deploy
+  run: lua push all --ci --force --auto-deploy
+```
+
+---
+
+## Environment Variables
+
+### `LUA_API_KEY`
+
+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
+```
+
+---
+
+## Exit Codes
+
+- `0` - Success
+- `1` - Error (general failure)
+- `2` - Authentication error
+- `130` - User cancelled (Ctrl+C)
+
+---
+
+## Tips & Best Practices
+
+### Development Workflow
+```bash
+# 1. Make changes
+vim src/skills/tools/MyTool.ts
+
+# 2. Test locally
+lua test
+
+# 3. Test with chat
+lua chat
+
+# 4. Compile
+lua compile
+
+# 5. Push to server
+lua push skill --name my-skill
+
+# 6. Deploy to production
+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
+
+# Then deploy to production
+lua push all --force --auto-deploy
+```
+
+### Version Management
+```bash
+# View versions
+lua skills versions my-skill
+
+# Deploy specific version
+lua deploy skill --name my-skill --version 1.0.0
+
+# Rollback
+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
+
+# 2. Add to skill
+# src/skills/my.skill.ts
+
+# 3. Test
+lua test
+
+# 4. Deploy
+lua compile
+lua push skill --name my-skill --force
+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
+
+# Watch logs
+lua logs --follow
+
+# Check specific skill versions
+lua skills versions my-skill
+```
+
+### Environment Variables
+```bash
+# Set environment variables
+lua env set OPENAI_API_KEY sk-...
+lua env set STRIPE_SECRET_KEY sk_live_...
+
+# List all
+lua env list
+
+# Delete
+lua env delete OLD_KEY
+```
+
+---
+
+## Troubleshooting
+
+### "Authentication failed"
+```bash
+# Reconfigure API key
+lua auth configure
+
+# Or use environment variable
+export LUA_API_KEY=your-api-key
+```
+
+### "Compilation failed"
+```bash
+# Check for errors
+lua compile --debug
+
+# Common issues:
+# - TypeScript syntax errors
+# - Missing imports
+# - Invalid Zod schemas
+```
+
+### "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
+
+# Deploy specific version
+lua deploy skill --name my-skill --version 1.0.0
+```
+
+---
+
+## See Also
+
+- [Getting Started Guide](./GETTING_STARTED.md) - Step-by-step tutorial
+- [API Reference](./API_REFERENCE.md) - Platform APIs
+- [Main README](../README.md) - Project overview
+
+---
+
+**Version:** 3.5.0-alpha.3
+**Last Updated:** February 2026