lua-cli/README.md

Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.

# Lua CLI

> Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs

[![npm version](https://img.shields.io/npm/v/lua-cli.svg)](https://www.npmjs.com/package/lua-cli)
[![License](https://img.shields.io/npm/l/lua-cli.svg)](https://github.com/heylua/lua-cli/blob/main/LICENSE)

**Lua CLI** is a command-line interface for building intelligent AI agents on the Lua AI platform. Create custom tools, integrate with external APIs, schedule automated tasks, and deploy to production—all from your terminal.

---

## ✨ Features

- 🤖 **LuaAgent** - Unified agent configuration with persona, skills, webhooks, and jobs
- 🛠️ **Custom Tools** - Build TypeScript tools with full type safety and Zod validation
- 🪝 **Webhooks** - HTTP endpoints for external integrations (Stripe, Shopify, etc.)
- ⏰ **Scheduled Jobs** - Cron-based and one-time background tasks
- 📥 **Preprocessors** - Filter and route messages before they reach your agent
- 📤 **Postprocessors** - Transform and format agent responses
- 💬 **Streaming Chat** - Real-time chat interface with typing indicators
- 🧪 **Local Testing** - Test tools, webhooks, and jobs before deploying
- 🚀 **Batch Deployment** - Push all components with one command
- 🔄 **Auto-Sync** - YAML and code stay synchronized automatically
- 🌐 **CI/CD Ready** - Environment variable support for automated deployments

---

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g lua-cli
```

### Project Installation

```bash
npm install lua-cli
```

### Verify Installation

```bash
lua --version
```

---

## 🚀 Quick Start

### 1. Authenticate

```bash
lua auth configure
```

Enter your API key when prompted (get one at https://admin.heylua.ai).

### 2. Initialize Project

```bash
mkdir my-agent
cd my-agent
lua init
```

Follow the prompts to:
- Select or create an agent
- Configure persona and welcome message
- Set up your project

### 3. Test Your Agent

```bash
# Test individual tools
lua test

# Chat with your agent
lua chat
```

### 4. Deploy to Production

```bash
# Interactive deployment
lua push

# Or batch deployment
lua push all --force --auto-deploy
```

---

## 🎯 Core Concepts

### LuaAgent

The unified configuration for your AI agent:

```typescript
import { LuaAgent, LuaSkill, LuaWebhook, LuaJob } from 'lua-cli';

export const agent = new LuaAgent({
  name: 'my-assistant',
  persona: 'You are a helpful AI assistant...',
  welcomeMessage: 'Hello! How can I help you today?',
  
  skills: [customerSupportSkill, productSkill],
  webhooks: [paymentWebhook],
  jobs: [dailyReportJob],
  preProcessors: [messageFilter],
  postProcessors: [responseFormatter]
});
```

### Skills

Group related tools together:

```typescript
import { LuaSkill } from 'lua-cli';

const weatherSkill = new LuaSkill({
  name: 'weather-skill',
  description: 'Weather information tools',
  context: 'Use these tools to get weather data for any location',
  tools: [
    new GetWeatherTool(),
    new GetForecastTool()
  ]
});
```

### Tools

Individual functions your agent can use:

```typescript
import { LuaTool } from 'lua-cli/skill';
import { z } from 'zod';

export default class GetWeatherTool implements LuaTool {
  name = 'get_weather';
  description = 'Get current weather for a city';
  
  inputSchema = z.object({
    city: z.string()
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    // Your logic here
    return { temperature: 72, condition: 'sunny' };
  }
}
```

### Webhooks

Receive HTTP requests from external systems:

```typescript
import { LuaWebhook } from 'lua-cli';
import { z } from 'zod';

export default new LuaWebhook({
  name: 'payment-webhook',
  version: '1.0.0',
  description: 'Handle payment notifications',
  
  bodySchema: z.object({
    orderId: z.string(),
    amount: z.number(),
    status: z.string()
  }),
  
  execute: async ({ body, headers, query }) => {
    // Process payment event
    return {
      status: 200,
      body: { received: true }
    };
  }
});
```

### Jobs

Schedule automated tasks:

```typescript
import { LuaJob } from 'lua-cli';

export default new LuaJob({
  name: 'daily-cleanup',
  version: '1.0.0',
  description: 'Clean up old data daily',
  
  schedule: {
    type: 'cron',
    pattern: '0 0 * * *'  // Midnight every day
  },
  
  execute: async (job) => {
    // Cleanup logic
    return { success: true, deleted: 42 };
  }
});
```

---

## 📚 Available APIs

Access powerful APIs in your tools and jobs:

### User API
```typescript
import { User } from 'lua-cli';

const user = await User.get();
await user.update({ preferences: 'dark-mode' });
await user.send([{ type: 'text', text: 'Hello!' }]);
```

### Products API
```typescript
import { Products } from 'lua-cli';

const products = await Products.get();
const product = await Products.create({ name: 'Widget', price: 29.99 });
await product.update({ price: 24.99 });
await product.delete();
```

### Baskets API
```typescript
import { Baskets } from 'lua-cli';

const basket = await Baskets.create();
await basket.addItem({ productId: '123', quantity: 2 });
await basket.placeOrder();
```

### Orders API
```typescript
import { Orders } from 'lua-cli';

const orders = await Orders.get();
await Orders.updateStatus('confirmed', orderId);
```

### Custom Data API
```typescript
import { Data } from 'lua-cli';

const movies = await Data.get('movies');
await Data.create('movies', { title: 'Inception', year: 2010 });
const results = await Data.search('movies', 'action thriller');
```

### Jobs API
```typescript
import { Jobs } from 'lua-cli';

const job = await Jobs.create({
  name: 'remind-user',
  metadata: { message: 'Meeting in 1 hour' },
  schedule: {
    type: 'once',
    executeAt: new Date(Date.now() + 3600000)
  },
  execute: async (job) => {
    const user = await job.user();
    await user.send([{ type: 'text', text: job.metadata.message }]);
    return { success: true };
  }
});
```

---

## 🛠️ CLI Commands

### Project Setup

```bash
lua auth configure          # Set up API key
lua init                    # Initialize new project
```

### Development

```bash
lua compile                 # Compile TypeScript to deployable format
lua test                    # Test tools/webhooks/jobs interactively
lua chat                    # Interactive chat with your agent
```

### Deployment

```bash
lua push                    # Push new version (interactive)
lua push all --force        # Push all components without prompts
lua deploy                  # Deploy version to production
```

### Management

```bash
lua production              # View production status
lua env                     # Manage environment variables
lua persona                 # Update agent persona
lua logs                    # View agent logs
lua skills                  # Manage skills
lua webhooks                # Manage webhooks
lua jobs                    # Manage scheduled jobs
```

### Utilities

```bash
lua admin                   # Open admin dashboard
lua docs                    # Open documentation
lua channels                # Manage chat channels
```

---

## 🔧 Advanced Features

### Streaming Chat

Real-time chat responses with typing indicators:

```bash
lua chat
```

- ✅ Animated typing indicator while waiting
- ✅ Text streams character-by-character as AI generates
- ✅ Custom welcome message from `lua.skill.yaml`
- ✅ Sandbox and production environments

### Batch Deployment

Deploy all components at once:

```bash
# Push everything without prompts
lua push all --force

# Push and deploy to production
lua push all --force --auto-deploy
```

Perfect for CI/CD pipelines:
- ✅ Auto-bumps patch versions
- ✅ No user interaction required
- ✅ Handles all component types
- ✅ Comprehensive error handling

### API Key Fallback

Flexible authentication for different environments:

**Priority:**
1. System keychain (macOS Keychain, Windows Credential Vault, Linux libsecret)
2. `LUA_API_KEY` environment variable
3. `LUA_API_KEY` in `.env` file

```bash
# CI/CD usage
export LUA_API_KEY=your-api-key
lua push all --force --auto-deploy
```

### Auto-Sync Configuration

Your `lua.skill.yaml` and `LuaAgent` stay synchronized:

- Run `lua init` → Syncs agent metadata to both YAML and code
- Run `lua compile` → Syncs LuaAgent changes back to YAML
- Edit either file → Changes propagate automatically

---

## 📖 Example Tool

```typescript
import { LuaTool, User } from 'lua-cli/skill';
import { z } from 'zod';
import axios from 'axios';

export default class WeatherTool implements LuaTool {
  name = 'get_weather';
  description = 'Get current weather for any city';
  
  inputSchema = z.object({
    city: z.string().describe('City name'),
    units: z.enum(['metric', 'imperial']).optional()
  });
  
  outputSchema = z.object({
    temperature: z.number(),
    condition: z.string(),
    city: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const response = await axios.get('https://api.weather.com/current', {
      params: {
        city: input.city,
        units: input.units || 'metric',
        apiKey: process.env.WEATHER_API_KEY
      }
    });
    
    return {
      temperature: response.data.temp,
      condition: response.data.condition,
      city: input.city
    };
  }
}
```

---

## 🏗️ Project Structure

```
your-project/
├── src/
│   ├── index.ts              # LuaAgent configuration
│   ├── skills/               # Tool collections
│   │   ├── tools/           # Individual tools
│   │   └── *.skill.ts       # Skill definitions
│   ├── webhooks/            # HTTP endpoints
│   ├── jobs/                # Scheduled tasks
│   ├── preprocessors/       # Message filters
│   ├── postprocessors/      # Response formatters
│   └── services/            # Shared utilities
├── lua.skill.yaml           # Agent metadata
├── .env                     # Environment variables
├── package.json
└── tsconfig.json
```

---

## 🔐 Security

### API Keys

- ✅ Stored securely in system keychain
- ✅ Never committed to version control
- ✅ Environment variable fallback for CI/CD
- ✅ Per-environment configuration

### Webhooks

- ✅ Signature validation support
- ✅ Request body validation with Zod
- ✅ HTTPS endpoints only
- ✅ Rate limiting ready

### User Data

- ✅ Encrypted at rest
- ✅ Scoped to authenticated users
- ✅ GDPR-compliant deletion
- ✅ Privacy-first design

---

## 🧪 Testing

### Test Individual Components

```bash
# Test a tool
lua test
# Select: Tool → get_weather
# Input: { city: "London" }
# Output: { temperature: 15, condition: "cloudy" }

# Test a webhook
lua test
# Select: Webhook → payment-webhook
# Input body, headers, query
# See response

# Test a job
lua test
# Select: Job → daily-cleanup
# Execute immediately
# See results
```

### Interactive Chat Testing

```bash
lua chat
# Select environment: Sandbox or Production
# Chat with your agent
# See tools in action
```

---

## 🚀 Deployment

### Development Workflow

```bash
# 1. Make changes to your code
vim src/skills/tools/MyTool.ts

# 2. Test locally
lua test

# 3. Test with chat
lua chat  # Sandbox mode

# 4. Compile
lua compile

# 5. Push to server
lua push

# 6. Deploy to production
lua deploy
```

### CI/CD Workflow

```yaml
# .github/workflows/deploy.yml
- name: Deploy Agent
  run: lua push all --force --auto-deploy
  env:
    LUA_API_KEY: ${{ secrets.LUA_API_KEY }}
```

---

## 📝 Configuration

### lua.skill.yaml

Central configuration file:

```yaml
agent:
  agentId: your-agent-id
  orgId: your-org-id
  persona: |
    You are a helpful AI assistant...
  welcomeMessage: Hello! How can I help you today?

skills:
  - name: general-skill
    version: 1.0.0
    skillId: skill-id-123

webhooks:
  - name: payment-webhook
    version: 1.0.0
    webhookId: webhook-id-456

jobs:
  - name: daily-cleanup
    version: 1.0.0
    jobId: job-id-789
    schedule:
      type: cron
      pattern: "0 0 * * *"
```

### Environment Variables

```.env
# Lua Platform
LUA_API_KEY=your-lua-api-key    # Optional: for CI/CD

# External Services
OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_live_...
PINECONE_API_KEY=...

# Custom Configuration
BASE_URL=https://api.example.com
```

---

## 🎓 Documentation

### Getting Started
- **[Quick Start Guide](template/QUICKSTART.md)** - Complete step-by-step tutorial
- **[Template README](template/README.md)** - Comprehensive project guide
- **[CLI Reference](#cli-commands)** - All available commands

### API Documentation
- **[Complete API Reference](docs/README.md)** - Full API documentation
- **[API Index](docs/API_INDEX.md)** - Quick reference table
- **Core APIs:**
  - [LuaAgent](docs/api/LuaAgent.md) - Agent configuration
  - [LuaSkill](docs/api/LuaSkill.md) - Tool collections
  - [LuaTool](docs/api/LuaTool.md) - Creating tools
- **Runtime APIs:**
  - [AI API](docs/api/AI.md) - AI text generation and analysis
  - [User API](docs/api/User.md) - User data management
  - [Products API](docs/api/Products.md) - Product catalog
  - [Data API](docs/api/Data.md) - Custom data storage
  - [Jobs API](docs/api/Jobs.md) - Dynamic job creation

### Advanced Topics
- [Webhooks & Jobs Guide](WEBHOOKS_JOBS_USAGE_GUIDE.md) - External integrations
- [Processors Guide](PROCESSORS_GUIDE.md) - Message processing
- [Dynamic Jobs](DYNAMIC_JOB_CREATION_API.md) - Creating jobs programmatically
- [Agent Configuration](LUAAGENT_IMPLEMENTATION.md) - LuaAgent deep dive

### Examples
- [Template Project](template/) - Full working example with 30+ tools
- [Example Skills](template/src/skills/) - Organized skill examples
- [Example Webhooks](template/src/webhooks/) - Webhook patterns
- [Example Jobs](template/src/jobs/) - Scheduled task examples

---

## 💻 Development

### Prerequisites

- Node.js 16+
- npm or yarn
- TypeScript 5+

### Building from Source

```bash
# Clone repository
git clone https://github.com/heylua/lua-cli.git
cd lua-cli

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

# Run tests
npm test
```

### Project Scripts

```bash
npm run build          # Compile TypeScript
npm run build:react    # Build web interface
npm run clean          # Clean dist folder
npm test               # Run test suite
```

---

## 🌟 What's New in v3.0.0

### Major Features

#### LuaAgent - Unified Configuration
- ✅ Single source of truth for all agent components
- ✅ Cleaner, more intuitive API
- ✅ Automatic sync with `lua.skill.yaml`

#### Streaming Chat Interface
- ✅ Real-time text streaming as AI generates responses
- ✅ Animated typing indicators
- ✅ Custom welcome messages from YAML
- ✅ Improved user experience

#### Batch Deployment
- ✅ `lua push all --force` - Deploy everything at once
- ✅ Auto-bump patch versions
- ✅ `--auto-deploy` flag for production
- ✅ Perfect for CI/CD pipelines

#### Enhanced Bundling
- ✅ Optimized bundle sizes (excludes lua-cli internals)
- ✅ Better import resolution
- ✅ Faster compilation
- ✅ Reduced deployment size

#### Improved Authentication
- ✅ Multi-source API key loading
- ✅ Environment variable support
- ✅ `.env` file fallback
- ✅ CI/CD friendly

### Breaking Changes from v2.x

- **LuaAgent required** - Use `new LuaAgent()` instead of exporting individual skills
- **Streaming endpoints** - Chat uses `/chat/stream` instead of `/chat/generate`
- **Jobs.create signature** - Metadata field recommended for passing data

See [CHANGELOG.md](CHANGELOG.md) for complete list of changes.

---

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

### Development Setup

```bash
git clone https://github.com/heylua/lua-cli.git
cd lua-cli
npm install
npm run build
npm link
```

---

## 📊 Use Cases

### Customer Support
- Handle product queries
- Process returns and refunds
- Escalate complex issues
- Track support tickets

### E-commerce
- Product recommendations
- Shopping cart management
- Order processing
- Payment integration

### Data Analysis
- Query databases
- Generate reports
- Visualize data
- Schedule analytics jobs

### Automation
- Scheduled reminders
- Data synchronization
- Health monitoring
- Batch processing

---

## 🆘 Support

### Getting Help

- **Documentation:** https://docs.heylua.ai
- **Email:** support@heylua.ai
- **GitHub Issues:** https://github.com/heylua/lua-cli/issues
- **Community:** https://community.heylua.ai

### Common Issues

**Q: How do I get an API key?**
Visit https://admin.heylua.ai and create an account.

**Q: Can I use this in production?**
Yes! v3.0.0 is production-ready with comprehensive testing and error handling.

**Q: How do I update to the latest version?**
```bash
npm install -g lua-cli@latest
```

**Q: Does this work with TypeScript?**
Yes! Full TypeScript support with type definitions included.

**Q: Can I deploy from CI/CD?**
Yes! Use environment variables and `lua push all --force --auto-deploy`.

---

## 📜 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

Built with:
- [TypeScript](https://www.typescriptlang.org/)
- [Zod](https://zod.dev/) - Schema validation
- [esbuild](https://esbuild.github.io/) - Fast bundling
- [Commander.js](https://github.com/tj/commander.js/) - CLI framework
- [Inquirer](https://github.com/SBoudrias/Inquirer.js/) - Interactive prompts

---

## 🔗 Links

- **Website:** https://heylua.ai
- **Documentation:** https://docs.heylua.ai
- **Admin Dashboard:** https://admin.heylua.ai
- **npm Package:** https://www.npmjs.com/package/lua-cli
- **GitHub:** https://github.com/heylua/lua-cli

---

## 📈 Roadmap

### Coming Soon
- 🔄 Real-time collaboration tools
- 📊 Built-in analytics dashboard
- 🎨 Visual skill builder
- 🔌 More integration templates
- 📱 Mobile SDK

### In Progress
- ✅ Enhanced error reporting
- ✅ Performance optimizations
- ✅ More example templates
- ✅ Improved documentation

---

## 💬 Community

Join the Lua community:

- **Discord:** Coming soon
- **Twitter:** @heylua_ai
- **Blog:** https://heylua.ai/blog

Share your agents, get help, and learn from others!

---

*Made with ❤️ by the Lua team*

**Version:** 3.0.0  
**Last Updated:** October 2025

---

## Quick Links

- [Quick Start →](template/QUICKSTART.md)
- [API Documentation →](API_REFERENCE.md)
- [Template Examples →](template/)
- [Changelog →](CHANGELOG.md)