# 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
