Package Exports

lua-cli

Readme

Lua CLI

Build AI agents with custom capabilities using TypeScript.

🎯 What is Lua CLI?

Lua CLI is a powerful command-line tool for building, testing, and deploying AI skills. A skill is a collection of tools (functions) that your AI agent can use to accomplish tasks.

Think of it like:

🤖 AI Agent = Your assistant (like ChatGPT)
🎯 Skills = What it can do (your custom capabilities)
🛠️ Tools = Specific functions (e.g., "get weather", "create order")

⚡ Quick Start

# Install
npm install -g lua-cli

# Authenticate
lua auth configure

# Create a project
mkdir my-skill && cd my-skill
lua init

# Test locally
lua test

# Start dev mode
lua dev

Done! Your AI skill is running at http://localhost:3000 🎉

📦 Installation

Global Installation (Recommended)

npm install -g lua-cli

Using npx (No Installation)

npx lua-cli [command]

Requirements

Node.js 16.0.0 or higher
npm 7.0.0 or higher
TypeScript knowledge (for development)

🚀 Features

For Developers

🔨 TypeScript-first - Full type safety and autocomplete
🎨 Template System - 30+ example tools to learn from
🧪 Interactive Testing - Test tools before deployment
🔄 Live Reload - Dev mode with automatic recompilation
📦 Auto Bundling - Dependencies bundled automatically with esbuild
✅ Input Validation - Zod schema validation built-in

For Operations

🔐 Secure Auth - API key or email OTP authentication
🌐 Multi-Skill - Multiple skills in one project
📊 Version Management - Push, test, and deploy versions
🎯 Sandbox Testing - Test in isolation before production
📝 Environment Variables - Secure configuration management

For Users

💬 Chat Interface - Test your AI in real conversations
🔍 Tool Explorer - Browse and test individual tools
📊 Real-time Logs - WebSocket log streaming
🎨 Beautiful UI - Modern, intuitive interface

📖 Documentation

📘 For Beginners

Getting Started Guide - Zero to deployed skill in one hour

Installation and setup
Your first skill
Step-by-step tutorial
Complete restaurant skill example

🔧 For Developers

API Reference - Complete API documentation

All exported APIs (User, Data, Products, Baskets, Orders)
Type definitions
Code examples
Best practices

Template Guide - Understanding the example project

Template structure explained
30+ tool examples
Building your first skill
Common patterns and recipes

💻 For CLI Users

CLI Reference - All command documentation

Complete command reference
Flags and options
Workflow examples
Troubleshooting

🏗️ For Contributors

Developer Guide - Architecture and internals

Codebase structure
Module organization
Contributing guidelines

🎓 Core Concepts

Skills

A skill is a collection of related tools:

import { LuaSkill } from 'lua-cli';

const weatherSkill = new LuaSkill({
  name: "weather-skill",
  version: "1.0.0",
  description: "Provides weather information",
  context: "Use get_weather when users ask about weather...",
  tools: [
    new GetWeatherTool(),
    new GetForecastTool()
  ]
});

Tools

A tool is a single function the AI can call:

import { LuaTool } from 'lua-cli';
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: any) {
    // Call weather API
    return {
      temperature: 72,
      condition: "sunny",
      city: input.city
    };
  }
}

Platform APIs

Built-in APIs for common operations:

import { User, Data, Products, Baskets, Orders } from 'lua-cli';

// User data
const user = await User.get();

// Custom data with vector search
await Data.create('movies', movieData, searchText);
const results = await Data.search('movies', 'sci-fi thriller');

// Products
const products = await Products.search('laptop');

// Shopping baskets
const basket = await Baskets.create({ currency: 'USD' });
await Baskets.addItem(basketId, { id, price, quantity });

// Orders
const order = await Baskets.placeOrder(orderData, basketId);

💡 Examples

Example 1: Simple Weather Tool

import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class WeatherTool implements LuaTool {
  name = "get_weather";
  description = "Get weather for any city";
  inputSchema = z.object({ city: z.string() });

  async execute(input: any) {
    const response = await fetch(
      `https://api.open-meteo.com/v1/forecast?city=${input.city}`
    );
    const data = await response.json();
    return { temperature: data.temp, condition: data.condition };
  }
}

Example 2: E-commerce Tool

import { LuaTool, Products, Baskets } from 'lua-cli';
import { z } from 'zod';

export default class AddToCartTool implements LuaTool {
  name = "add_to_cart";
  description = "Add product to shopping cart";
  
  inputSchema = z.object({
    productId: z.string(),
    quantity: z.number().min(1)
  });

  async execute(input: any) {
    const product = await Products.getById(input.productId);
    const basket = await Baskets.create({ currency: 'USD' });
    
    await Baskets.addItem(basket.id, {
      id: input.productId,
      price: product.price,
      quantity: input.quantity
    });
    
    return {
      basketId: basket.id,
      message: `Added ${input.quantity}x ${product.name} to cart`
    };
  }
}

Example 3: Custom Data with Search

import { LuaTool, Data } from 'lua-cli';
import { z } from 'zod';

export class CreateMovieTool implements LuaTool {
  name = "create_movie";
  description = "Add a movie to the database";
  
  inputSchema = z.object({
    title: z.string(),
    director: z.string(),
    year: z.number()
  });

  async execute(input: any) {
    const searchText = `${input.title} ${input.director} ${input.year}`;
    const movie = await Data.create('movies', input, searchText);
    return { id: movie.id, message: 'Movie added' };
  }
}

export class SearchMoviesTool implements LuaTool {
  name = "search_movies";
  description = "Search movies by title, director, or year";
  inputSchema = z.object({ query: z.string() });

  async execute(input: any) {
    const results = await Data.search('movies', input.query, 10, 0.7);
    return { movies: results.data, count: results.count };
  }
}

🎯 Commands

Authentication

lua auth configure    # Set up API key
lua auth key          # Display API key
lua auth logout       # Delete API key

Skill Management

lua init              # Create new skill project
lua compile           # Compile TypeScript to deployable format
lua test              # Test tools interactively
lua push              # Upload version to server
lua deploy            # Deploy version to production
lua dev               # Development mode with live reload

Utilities

lua admin             # Open Lua Admin Dashboard in browser
lua docs              # Open documentation in browser

See CLI_REFERENCE.md for complete command documentation.

🛠️ Development Workflow

Local Development

# Start dev mode
lua dev

# Make changes to src/tools/*.ts
# Save → Auto-recompiles → Auto-pushes to sandbox
# Test in browser at http://localhost:3000

Testing

# Test individual tools
lua test

# Test conversationally
lua dev
# Use chat interface

Deployment

# Upload new version
lua push

# Deploy to production
lua deploy

📚 Built-in APIs

User API

import { User } from 'lua-cli';

const user = await User.get();

Custom Data API (with Vector Search)

import { Data } from 'lua-cli';

await Data.create('collection', data, searchText);
const results = await Data.search('collection', 'query', limit, threshold);

Products API

import { Products } from 'lua-cli';

const products = await Products.search('laptop');
await Products.create({ name, price });

Baskets API

import { Baskets, BasketStatus } from 'lua-cli';

const basket = await Baskets.create({ currency: 'USD' });
await Baskets.addItem(basketId, { id, price, quantity });

Orders API

import { Orders, OrderStatus } from 'lua-cli';

const order = await Baskets.placeOrder(orderData, basketId);
await Orders.updateStatus(OrderStatus.FULFILLED, orderId);

See API_REFERENCE.md for complete API documentation.

🎨 Template Project

The template includes 30+ working examples:

🌤️ Weather Tool - External API integration
👤 User Data Tools - User management
🛍️ Product Tools - E-commerce catalog
🛒 Basket Tools - Shopping cart
📦 Order Tools - Order processing
🎬 Custom Data Tools - Vector search
💳 Payment Tool - Payment integration

See TEMPLATE_GUIDE.md for complete template documentation.

🔒 Security

✅ API keys stored in system keychain
✅ Environment variables for secrets
✅ Secure VM sandbox for tool execution
✅ No hardcoded credentials
✅ HTTPS for all API calls

Best Practices:

import { env } from 'lua-cli';

// ✅ Good - Use environment variables
const apiKey = env('EXTERNAL_API_KEY');

// ❌ Bad - Hardcoded secrets
const apiKey = 'sk_abc123';

🧪 Testing

Unit Testing

import { describe, it, expect } from '@jest/globals';
import MyTool from './tools/MyTool';

describe('MyTool', () => {
  it('should return expected result', async () => {
    const tool = new MyTool();
    const result = await tool.execute({ input: 'test' });
    expect(result).toHaveProperty('success');
  });
});

Interactive Testing

lua test
# Select tool → Enter inputs → See results

Conversational Testing

lua dev
# Chat with AI at http://localhost:3000

🎯 Use Cases

Customer Service

Answer FAQs from knowledge base
Look up order status
Create support tickets
Search documentation

E-commerce

Product search and recommendations
Shopping cart management
Order creation and tracking
Inventory checks

Booking & Scheduling

Check availability
Create appointments
Send confirmations
Manage reservations

Data Management

CRUD operations on custom data
Vector search for semantic queries
Data aggregation and reporting
Integration with external systems

📊 Architecture

┌─────────────────┐
│   AI Agent      │
│   (Lua Platform)│
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│   Your Skills   │ ← Built with Lua CLI
│   (TypeScript)  │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│   Your Tools    │
│   (Functions)   │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  Platform APIs  │ ← User, Products, Data, etc.
│  External APIs  │ ← Weather, Stripe, SendGrid, etc.
│  Databases      │ ← Your own systems
└─────────────────┘

🌟 Key Features

Type-Safe Development

// Full TypeScript support
import { LuaTool, Products } from 'lua-cli';
import { z } from 'zod';

// Autocomplete, type checking, and validation
export default class MyTool implements LuaTool {
  inputSchema = z.object({
    query: z.string()  // Validated at runtime
  });
  
  async execute(input: z.infer<typeof this.inputSchema>) {
    // input is fully typed!
    return await Products.search(input.query);
  }
}

Instant Feedback

lua dev
# Edit file → Save → Auto-reload → Test immediately

Production Ready

lua push    # Upload to server
lua deploy  # Deploy to all users

📖 Learning Resources

🟢 New to Lua?

Start here: GETTING_STARTED.md

Installation
First skill in 1 hour
Complete tutorial
Common patterns

🟡 Building Skills?

Read: API_REFERENCE.md

All exported APIs
Type definitions
Code examples
Best practices

🟠 Understanding Examples?

Read: TEMPLATE_GUIDE.md

Template structure
30+ tool examples
Common recipes
Migration guide

🔵 Using the CLI?

Read: CLI_REFERENCE.md

All commands
Flags and options
Workflows
Troubleshooting

🟣 Contributing?

Read: DEVELOPER_GUIDE.md

Architecture
Module structure
Contribution guidelines

🔧 Common Tasks

Create a New Tool

# Create file
touch src/tools/MyTool.ts

import { LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class MyTool implements LuaTool {
  name = "my_tool";
  description = "What it does";
  inputSchema = z.object({ param: z.string() });

  async execute(input: any) {
    // Your logic here
    return { success: true };
  }
}

Add to skill in src/index.ts:

import MyTool from './tools/MyTool';

const skill = new LuaSkill({
  tools: [new MyTool()]
});

Call External APIs

import { LuaTool, env } from 'lua-cli';

export default class ExternalApiTool implements LuaTool {
  async execute(input: any) {
    const apiKey = env('EXTERNAL_API_KEY');
    
    const response = await fetch('https://api.example.com/data', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    
    return await response.json();
  }
}

Use Platform APIs

import { LuaTool, Products, Baskets } from 'lua-cli';

export default class ShoppingTool implements LuaTool {
  async execute(input: any) {
    // Search products
    const products = await Products.search(input.query);
    
    // Create basket
    const basket = await Baskets.create({ currency: 'USD' });
    
    // Add item
    await Baskets.addItem(basket.id, {
      id: products.data[0].id,
      price: products.data[0].price,
      quantity: 1
    });
    
    return { basketId: basket.id };
  }
}

Store Custom Data

import { LuaTool, Data } from 'lua-cli';

export default class SaveNoteTool implements LuaTool {
  async execute(input: any) {
    // Create
    const note = await Data.create('notes', {
      title: input.title,
      content: input.content,
      tags: input.tags
    }, `${input.title} ${input.content}`);
    
    // Search later
    const results = await Data.search('notes', 'meeting notes', 10);
    
    return { noteId: note.id };
  }
}

🎯 Example Projects

Knowledge Base Assistant

Tools: search_kb, create_article, update_article
APIs: Data (vector search)
Use Case: Company documentation, FAQ

E-commerce Bot

Tools: search_products, add_to_cart, checkout
APIs: Products, Baskets, Orders
Use Case: Online shopping assistant

Booking System

Tools: check_availability, make_reservation, cancel_booking
APIs: Data (custom collections)
Use Case: Restaurant/hotel reservations

CRM Assistant

Tools: find_customer, create_lead, update_contact
APIs: Data, User
Use Case: Customer relationship management

🚀 Deployment

Development → Production Flow

# 1. Develop locally
lua dev
# Edit, test, iterate

# 2. Push to server
lua push

# 3. Test in sandbox
lua dev
# Final testing

# 4. Deploy to production
lua deploy
# Available to all users!

Version Management

Update version in lua.skill.yaml:

skills:
  - name: my-skill
    version: 1.0.1  # ← Increment this

Then push and deploy:

lua push    # Uploads v1.0.1
lua deploy  # Deploys v1.0.1

⚙️ Configuration

Environment Variables

.env file:

STRIPE_API_KEY=sk_test_abc123
SENDGRID_KEY=SG.xyz789
CUSTOM_API_URL=https://api.example.com

lua.skill.yaml:

skill:
  env:
    PRODUCTION_API_KEY: sk_live_abc123
    BASE_URL: https://prod.example.com

Access in code:

import { env } from 'lua-cli';

const key = env('STRIPE_API_KEY');

🤝 Contributing

We welcome contributions!

Fork the repository
Create a feature branch
Make your changes
Write tests
Submit a pull request

See DEVELOPER_GUIDE.md for architecture details.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

Documentation: https://docs.heylua.ai
Platform: https://heylua.ai
GitHub: https://github.com/lua-ai/lua-cli
npm: https://www.npmjs.com/package/lua-cli

💬 Support

Issues: GitHub Issues
Email: support@lua.ai
Docs: https://docs.heylua.ai

🎉 Quick Links

I want to...	Read this...
Get started	GETTING_STARTED.md
Learn the API	API_REFERENCE.md
Use CLI commands	CLI_REFERENCE.md
Understand examples	TEMPLATE_GUIDE.md
Contribute code	DEVELOPER_GUIDE.md
See changelog	CHANGELOG.md

Happy building! 🚀

Made with ❤️ by the Lua team