JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 139
  • Score
    100M100P100Q79414F
  • License MIT

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

Package Exports

  • lua-cli

Readme

Lua CLI

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

npm version 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
  • 🛒 Marketplace - Publish and install verified skills from the community
  • 🛠️ 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

npm install -g lua-cli

Project Installation

npm install lua-cli

Verify Installation

lua --version

🚀 Quick Start

1. Authenticate

lua auth configure

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

2. Initialize Project

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

# Test individual tools
lua test

# Chat with your agent
lua chat

4. Deploy to Production

# Interactive deployment
lua push

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

🎯 Core Concepts

LuaAgent

The unified configuration for your AI agent:

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:

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:

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:

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:

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

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

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

import { Baskets } from 'lua-cli';

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

Orders API

import { Orders } from 'lua-cli';

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

Custom Data API

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

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

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

Marketplace

lua marketplace             # Access the skills marketplace (Creator & Installer)

Development

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

Deployment

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

Management

lua production              # View production status
lua env                     # Manage environment variables
lua persona                 # Update agent persona
lua logs                    # View and filter agent logs (interactive)
lua skills                  # Manage skills
lua webhooks                # Manage webhooks
lua jobs                    # Manage scheduled jobs

Utilities

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:

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:

# 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
# 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

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

# 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

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

🚀 Deployment

Development Workflow

# 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

# .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:

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

# 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

API Documentation

Advanced Topics

Examples

💻 Development

Prerequisites

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

Building from Source

# 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

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 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

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

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?

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 file for details.

🙏 Acknowledgments

Built with:

📈 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:

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

Made with ❤️ by the Lua team

Version: 3.0.0
Last Updated: October 2025