lua-cli 2.2.8-alpha.1 → 2.3.0-alpha.1

package/CLI_REFERENCE.md

@@ -0,0 +1,818 @@
+# Lua CLI - Command Reference
+
+Complete reference guide for all Lua CLI commands.
+
+---
+
+## 📋 Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication Commands](#authentication-commands)
+- [Skill Management Commands](#skill-management-commands)
+- [Command Reference](#command-reference)
+
+---
+
+## Installation
+
+```bash
+npm install -g lua-cli
+```
+
+Or use with npx (no installation required):
+```bash
+npx lua-cli [command]
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+lua auth configure
+
+# 2. Initialize a new skill project
+mkdir my-skill && cd my-skill
+lua init
+
+# 3. Test your skill locally
+lua test
+
+# 4. Push to development environment
+lua push
+
+# 5. Start development mode with live reload
+lua dev
+
+# 6. Deploy to production
+lua deploy
+```
+
+---
+
+## Authentication Commands
+
+### `lua auth configure`
+
+Sets up your Lua CLI authentication credentials.
+
+**Usage:**
+```bash
+lua auth configure
+```
+
+**Interactive Prompts:**
+1. Choose authentication method:
+   - **API Key**: Enter an existing API key
+   - **Email**: Get API key via email OTP
+
+**For API Key Method:**
+- Prompts for your API key
+- Validates the key with the server
+- Stores securely in system keychain
+
+**For Email Method:**
+- Prompts for email address
+- Sends 6-digit OTP code to your email
+- Allows 3 attempts to enter correct OTP
+- Automatically generates and saves API key
+
+**Storage:**
+- Credentials stored in system keychain
+- macOS: Keychain
+- Windows: Credential Vault
+- Linux: libsecret
+
+**Example:**
+```bash
+$ lua auth configure
+? Choose authentication method: Email
+? Enter your email address: you@example.com
+📧 Sending OTP to your email...
+✅ OTP sent successfully!
+? Enter the OTP code: 123456
+🔐 Verifying OTP...
+✅ OTP verified successfully!
+🔑 Generating API key...
+✅ API key generated and saved securely.
+```
+
+---
+
+### `lua auth key`
+
+Displays your stored API key.
+
+**Usage:**
+```bash
+lua auth key
+```
+
+**Interactive Prompts:**
+- Confirmation prompt before displaying (security)
+
+**Output:**
+```bash
+$ lua auth key
+? This will display your API key. Are you sure you want to continue? Yes
+🔑 Your API key:
+lsk_abc123def456...
+```
+
+**Security Note:** Only displays after explicit confirmation to prevent accidental exposure.
+
+---
+
+### `lua auth logout`
+
+Deletes your stored API key from the system.
+
+**Usage:**
+```bash
+lua auth logout
+```
+
+**Interactive Prompts:**
+- Confirmation prompt (action cannot be undone)
+
+**What it does:**
+- Removes API key from system keychain
+- Does NOT invalidate the key on the server
+- You'll need to run `lua auth configure` again to use the CLI
+
+**Example:**
+```bash
+$ lua auth logout
+? Are you sure you want to delete your API key? This action cannot be undone. Yes
+✅ API key deleted successfully.
+```
+
+---
+
+## Skill Management Commands
+
+### `lua init`
+
+Initializes a new Lua skill project in the current directory.
+
+**Usage:**
+```bash
+mkdir my-skill && cd my-skill
+lua init
+```
+
+**Interactive Prompts:**
+
+**Step 1: Choose Agent**
+- **Select existing agent**: Choose from your organizations and agents
+- **Create new agent**: Create a new AI agent
+
+**Step 2a: For Existing Agent**
+- Select organization
+- Select agent from organization
+
+**Step 2b: For New Agent**
+- Enter business name (default: "Private")
+- Enter agent name (required)
+- Select business type from list
+- Select brand personality
+- Enter brand traits (optional)
+- Configure features (enable/disable)
+
+**What it creates:**
+```
+my-skill/
+├── src/
+│   ├── index.ts              # Skill entry point
+│   ├── tools/                # Tool implementations
+│   │   ├── GetWeatherTool.ts
+│   │   ├── UserDataTool.ts
+│   │   ├── ProductsTool.ts
+│   │   └── ... (more examples)
+│   └── services/             # Helper services
+├── lua.skill.yaml            # Skill configuration
+├── package.json              # Dependencies
+├── tsconfig.json             # TypeScript config
+├── .env.example              # Environment variables template
+└── README.md                 # Project documentation
+```
+
+**Configuration File (`lua.skill.yaml`):**
+```yaml
+agent:
+  agentId: agent_abc123
+  orgId: org_xyz789
+  persona: "..."
+  welcomeMessage: "..."
+
+skills: []  # Auto-populated during compilation
+```
+
+**Example:**
+```bash
+$ lua init
+? What would you like to do? Create new agent
+? Enter business name: My Coffee Shop
+? Enter agent name: CoffeeBot
+? Select business type: Food & Beverage (e.g. restaurant, bakery)
+? Select brand personality: Friendly
+? Enter brand traits: Warm, welcoming, knowledgeable about coffee
+🔄 Creating agent...
+✅ Agent created successfully!
+⏳ Waiting for agent to be ready...
+✅ Created lua.skill.yaml
+✅ Copied template files
+📦 Installing dependencies...
+✅ Lua skill project initialized successfully!
+```
+
+---
+
+### `lua compile`
+
+Compiles your TypeScript skill into deployable JavaScript bundles.
+
+**Usage:**
+```bash
+lua compile
+```
+
+**What it does:**
+1. Analyzes your TypeScript code to detect tools
+2. Bundles each tool individually with esbuild
+3. Bundles the main index file
+4. Extracts tool metadata and schemas
+5. Creates deployment artifacts
+6. Automatically creates skills via API if needed
+
+**Output:**
+```
+dist/
+├── deployment.json           # Deployment metadata
+├── index.js                  # Main skill bundle
+└── tools/                    # Individual tool bundles
+    ├── GetWeatherTool.js
+    ├── UserDataTool.js
+    └── ...
+
+.lua/
+├── deploy.json               # Legacy format
+├── get_weather.js            # Uncompressed (for debugging)
+└── ...
+```
+
+**Example:**
+```bash
+$ lua compile
+🔨 Compiling Lua skill...
+📦 Found 15 tools to bundle...
+📦 Bundling GetWeatherTool...
+📦 Bundling UserDataTool...
+... (more tools)
+📦 Bundling main index...
+✅ Skill compiled successfully - 15 tools bundled
+```
+
+**Notes:**
+- Automatically detects tools from `new LuaSkill({ tools: [...] })`
+- Automatically detects tools from `skill.addTools([...])`
+- Creates skills in `lua.skill.yaml` if they don't exist
+- Updates existing skills with new tools
+
+---
+
+### `lua test`
+
+Tests individual tools locally in a sandboxed environment.
+
+**Usage:**
+```bash
+lua test
+```
+
+**Interactive Prompts:**
+1. Select a tool from the list
+2. Enter input values based on the tool's schema
+3. View execution results
+
+**What it does:**
+1. Compiles the skill
+2. Lists all available tools
+3. Prompts for tool selection
+4. Dynamically generates input prompts based on tool's input schema
+5. Executes tool in secure VM sandbox
+6. Displays results or errors
+
+**Features:**
+- Supports nested object inputs
+- Validates required vs optional fields
+- Loads environment variables from `.env` and `lua.skill.yaml`
+- Secure sandbox execution (isolated from host system)
+- Detailed error reporting
+
+**Example:**
+```bash
+$ lua test
+🧪 Testing Lua skill...
+📦 Compiling code first...
+✅ Skill compiled successfully
+📄 Loaded environment variables from .env file
+
+? 🔧 Select a tool to test:
+❯ get_weather - Get the weather for a given city
+  create_product - Create a new product
+  get_user_data - Get user data
+  
+✅ Selected tool: get_weather
+
+📝 Enter input values:
+? city (required): London
+
+🚀 Executing tool...
+Input: {
+  "city": "London"
+}
+✅ Tool execution successful!
+Output: {
+  "weather": "3",
+  "city": "London",
+  "temperature": 15.2,
+  "description": "Windspeed 12.3 km/h"
+}
+```
+
+---
+
+### `lua push`
+
+Pushes your compiled skill version to the Lua server.
+
+**Usage:**
+```bash
+lua push
+```
+
+**Interactive Prompts:**
+- Confirmation to push version
+
+**What it does:**
+1. Reads version from `lua.skill.yaml`
+2. Prompts for confirmation
+3. Authenticates with API key
+4. Compiles the skill
+5. Validates deploy.json matches config
+6. Uploads version to server
+
+**Requirements:**
+- Must be in a skill directory (has `lua.skill.yaml`)
+- Must have run `lua init`
+- Must have valid API key
+
+**Example:**
+```bash
+$ lua push
+? Are you sure you want to push version 1.0.0? Yes
+✅ Authenticated
+🔄 Compiling skill...
+✅ Skill compiled successfully - 10 tools bundled
+🔄 Pushing version to server...
+✅ Version 1.0.0 pushed successfully
+```
+
+**Note:** This uploads to the server but does NOT deploy to production. Use `lua deploy` for production deployment.
+
+---
+
+### `lua deploy`
+
+Deploys a specific version to production (all users).
+
+**Usage:**
+```bash
+lua deploy
+```
+
+**Interactive Prompts:**
+1. Select version to deploy from list
+2. Confirm deployment with warning
+
+**What it does:**
+1. Fetches all available versions from server
+2. Displays versions with metadata:
+   - Version number
+   - Current status (if currently deployed)
+   - Created date
+   - Creator email
+3. Prompts for version selection
+4. Shows warning about production deployment
+5. Publishes selected version
+
+**Features:**
+- Lists all pushed versions
+- Shows which version is currently active
+- Sorts by date (newest first)
+- Requires explicit confirmation
+
+**Example:**
+```bash
+$ lua deploy
+✅ Authenticated
+🔄 Fetching available versions...
+
+? Select a version to deploy:
+  1.0.2 - Created: Oct 3, 2025 by you@example.com
+  1.0.1 - Created: Oct 2, 2025 by you@example.com
+❯ 1.0.0 (CURRENT) - Created: Oct 1, 2025 by you@example.com
+
+? ⚠️  Warning: This version will be deployed to all users. Do you want to proceed? Yes
+🔄 Publishing version...
+✅ Version 1.0.0 deployed successfully
+```
+
+**⚠️ WARNING:** This immediately deploys to ALL users. Test thoroughly with `lua dev` first!
+
+---
+
+### `lua dev`
+
+Starts development mode with live reloading and chat interface.
+
+**Usage:**
+```bash
+lua dev
+```
+
+**What it does:**
+1. Compiles the skill
+2. Pushes all skills to sandbox environment
+3. Starts local web server on port 3000
+4. Opens chat interface in your browser
+5. Watches for file changes
+6. Auto-recompiles and pushes on changes
+
+**Features:**
+- **Live Chat Interface**: Test your skill with conversational AI
+- **Tool Testing**: Test individual tools with custom inputs
+- **WebSocket Logging**: Real-time log streaming
+- **Auto-Reload**: Automatic recompilation on file changes
+- **Environment Management**: Edit `.env` variables in UI
+- **Persona Configuration**: Customize agent behavior
+- **Multi-Skill Support**: Works with multiple skills in one project
+
+**Chat Interface Features:**
+```
+http://localhost:3000
+
+Tabs:
+├── Chat        # Chat with your AI agent using sandbox skills
+├── Tools       # Test individual tools with custom inputs
+├── User Data   # View and modify user data
+├── Environment # Manage environment variables
+├── Persona     # Configure agent personality
+└── Skills      # View all skills and their tools
+```
+
+**File Watching:**
+- Watches: `.ts` files in `src/`
+- Ignores: `node_modules/`, `dist/`, `.lua/`, `.git/`
+- Debounce: 500ms (prevents multiple compilations)
+
+**Example:**
+```bash
+$ lua dev
+✅ Authenticated
+🔄 Compiling skill...
+✅ Skill compiled successfully - 10 tools bundled
+🔄 Pushing skills to sandbox...
+✅ Pushed 3 skills to sandbox
+🌐 Chat interface opened in your browser
+🔍 Watching for file changes... (Press Ctrl+C to stop)
+
+# Edit a file...
+🔄 File changed: src/tools/MyTool.ts - Compiling and pushing...
+✅ Compilation completed
+✅ Successfully pushed 3 skills to sandbox
+```
+
+**Stopping Dev Mode:**
+Press `Ctrl+C` to stop the file watcher and server.
+
+---
+
+## Command Reference
+
+### Global Flags
+
+All commands support:
+- `--help` - Show command help
+- `--version` - Show CLI version
+
+### Error Handling
+
+All commands include:
+- Descriptive error messages
+- Exit codes (0 = success, 1 = error)
+- Helpful troubleshooting hints
+
+### Common Errors
+
+**"No API key found"**
+```bash
+❌ No API key found. Run `lua auth configure` first.
+```
+**Solution:** Run `lua auth configure` to set up authentication.
+
+**"No lua.skill.yaml found"**
+```bash
+❌ No lua.skill.yaml found. Please run this command from a skill directory.
+```
+**Solution:** Run command from a skill directory or run `lua init` first.
+
+**"Missing agentId or skillId"**
+```bash
+❌ Missing agentId or skillId in skill configuration
+```
+**Solution:** Run `lua init` to set up your skill properly.
+
+---
+
+## Workflow Examples
+
+### **Complete Workflow: New Project**
+
+```bash
+# 1. Set up authentication
+lua auth configure
+
+# 2. Create new project
+mkdir my-weather-skill
+cd my-weather-skill
+lua init
+
+# 3. Customize your tools (edit src/tools/*.ts)
+# 4. Test locally
+lua test
+
+# 5. Push to server
+lua push
+
+# 6. Start development mode
+lua dev
+# Test in chat interface at http://localhost:3000
+
+# 7. When ready, deploy to production
+lua deploy
+```
+
+---
+
+### **Development Workflow**
+
+```bash
+# Start dev mode
+lua dev
+
+# Edit files - auto-reloads
+# Test in chat interface
+# When satisfied, push new version
+
+# Stop dev mode (Ctrl+C)
+
+# Push production version
+lua push
+
+# Deploy to all users
+lua deploy
+```
+
+---
+
+### **Testing Workflow**
+
+```bash
+# Test individual tools
+lua test
+# Select tool, enter inputs, see results
+
+# Test in conversational context
+lua dev
+# Use chat interface to test natural language interaction
+```
+
+---
+
+## Environment Variables
+
+### Loading Priority
+
+Environment variables are loaded in this order (later overrides earlier):
+
+1. System environment (`process.env`)
+2. `.env` file in project root
+3. `lua.skill.yaml` under `skill.env`
+
+### Using in Tools
+
+```typescript
+import { env } from 'lua-cli';
+
+export class MyTool implements LuaTool {
+  async execute(input: any) {
+    const apiKey = env('EXTERNAL_API_KEY');
+    const baseUrl = env('API_BASE_URL') || 'https://default.com';
+    
+    // Use environment variables...
+  }
+}
+```
+
+### Setting Variables
+
+**Option 1: `.env` file**
+```bash
+# .env
+EXTERNAL_API_KEY=your_key_here
+API_BASE_URL=https://api.example.com
+```
+
+**Option 2: `lua.skill.yaml`**
+```yaml
+skill:
+  name: my-skill
+  version: 1.0.0
+  env:
+    EXTERNAL_API_KEY: your_key_here
+    API_BASE_URL: https://api.example.com
+```
+
+**Option 3: Dev Mode UI**
+- Go to http://localhost:3000 during `lua dev`
+- Click "Environment" tab
+- Edit variables in UI
+- Changes saved to `.env` file
+
+---
+
+## Configuration File
+
+### `lua.skill.yaml`
+
+Created by `lua init`, updated by compilation.
+
+**Structure:**
+```yaml
+# Agent Configuration
+agent:
+  agentId: agent_abc123        # Your agent ID
+  orgId: org_xyz789            # Organization ID
+  persona: "..."               # Agent personality (optional)
+  welcomeMessage: "..."        # Welcome message (optional)
+
+# Legacy single skill format (deprecated)
+skill:
+  name: my-skill
+  version: 1.0.0
+  skillId: skill_legacy123
+
+# New multi-skill format (recommended)
+skills:
+  - name: general-skill
+    version: 1.0.0
+    skillId: skill_abc123
+  - name: product-skill
+    version: 1.0.0
+    skillId: skill_def456
+
+# Environment Variables (optional)
+skill:
+  env:
+    API_KEY: your_key_here
+    BASE_URL: https://api.example.com
+```
+
+**Auto-managed Fields:**
+- `skillId` - Automatically created during compilation
+- `skills` array - Auto-populated from your code
+
+**Manual Fields:**
+- `agentId` - Set during `lua init`
+- `orgId` - Set during `lua init`
+- `version` - Update manually when releasing new versions
+- `env` - Set your environment variables here
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Skill not found during dev**
+```bash
+💡 The skill doesn't exist on the server.
+   Please run "lua push" first to deploy your skill, then try "lua dev" again.
+```
+**Solution:** Run `lua push` before `lua dev`.
+
+**Compilation fails**
+```bash
+❌ No index.ts found in current directory or src/ directory
+```
+**Solution:** Create `index.ts` or `src/index.ts` with your skill definition.
+
+**Version mismatch**
+```bash
+❌ Version mismatch: config has 1.0.1, deploy.json has 1.0.0
+```
+**Solution:** Recompile after changing version in `lua.skill.yaml`.
+
+### Getting Help
+
+- Check command help: `lua [command] --help`
+- Visit documentation: https://docs.lua.ai
+- View examples in template: Check `template/` directory after install
+
+---
+
+## Best Practices
+
+### Versioning
+- Use semantic versioning: `MAJOR.MINOR.PATCH`
+- Increment PATCH for bug fixes
+- Increment MINOR for new features
+- Increment MAJOR for breaking changes
+
+### Development
+- Always test with `lua test` before pushing
+- Use `lua dev` for iterative development
+- Test thoroughly before deploying to production
+- Keep `.env` file in `.gitignore`
+
+### Deployment
+- Push new versions frequently for testing
+- Only deploy stable versions to production
+- Document changes between versions
+- Test in sandbox (dev mode) before deploying
+
+---
+
+## Advanced Usage
+
+### Multiple Skills in One Project
+
+You can define multiple skills in `index.ts`:
+
+```typescript
+const skill1 = new LuaSkill({
+  name: 'general-skill',
+  description: '...',
+  context: '...',
+  tools: [tool1, tool2]
+});
+
+const skill2 = new LuaSkill({
+  name: 'ecommerce-skill',
+  description: '...',
+  context: '...',
+  tools: [tool3, tool4]
+});
+```
+
+The CLI automatically:
+- Detects all skills
+- Creates separate skill IDs
+- Bundles all tools
+- Manages multi-skill deployments
+
+### Custom Build Configuration
+
+Modify `tsconfig.json` for TypeScript settings.
+
+The CLI uses:
+- **esbuild** for fast bundling
+- **ts-morph** for AST analysis
+- **VM sandboxing** for secure execution
+
+---
+
+## Command Summary
+
+| Command | Purpose | Requires |
+|---------|---------|----------|
+| `lua auth configure` | Set up API key | Nothing |
+| `lua auth key` | Show API key | API key |
+| `lua auth logout` | Delete API key | API key |
+| `lua init` | Initialize project | API key |
+| `lua compile` | Compile skill | Skill directory |
+| `lua test` | Test tools | Compiled skill |
+| `lua push` | Upload version | Compiled skill, API key |
+| `lua deploy` | Deploy to prod | Pushed versions |
+| `lua dev` | Dev mode | Compiled skill, pushed version |
+
+---
+
+**For detailed API documentation, see `API_REFERENCE.md`**  
+**For template documentation, see `TEMPLATE_GUIDE.md`**  
+**For development guide, see `DEVELOPER_GUIDE.md`**
+