Package Exports

lua-cli
lua-cli/skill
lua-cli/types
lua-cli/user-data-api

Readme

Lua CLI

A powerful command-line interface for the Lua AI platform that helps you develop, test, and deploy LuaSkills with custom tools.

Installation

npm install -g lua-cli

Usage

After installation, you can use the lua command:

lua --help

Features

🔐 Secure Authentication: Support for both API key and email-based OTP authentication
🏢 Organization Management: Select and manage multiple organizations
🤖 Agent Management: Choose from available agents within your organizations
🛠️ Skill Development: Initialize new Lua skills with proper configuration
🔧 Tool Development: Create custom tools with TypeScript and Zod validation
📦 Dependency Bundling: Automatic bundling of npm packages using esbuild
🧪 Interactive Testing: Test your tools with real-time execution
🚀 Deployment: Compile and deploy skills to the Lua platform
🔑 API Key Management: Securely store, view, and manage your API keys
💾 User Data API: Built-in API for persistent user data storage in your tools
📚 Comprehensive Documentation: Complete guides and examples

Quick Start

Configure your authentication:
```
lua auth configure
```
Choose between API key or email authentication methods.
Initialize a new skill project:
```
lua skill init
```
Choose between selecting an existing agent or creating a new one, then provide skill details.

Develop your tools:

# Create tools in the tools/ directory
# See template/README.md for examples

Compile your skill:
```
lua skill compile
```
Bundles dependencies and creates deployable files.
Test your tools:
```
lua skill test
```
Interactive testing interface for your tools.
Deploy your skill:
```
lua skill deploy
```
Deploy to the Lua platform.

Commands

Authentication Commands

`lua auth configure`

Set up your authentication credentials. You can choose between:

API Key: Direct API key input
Email: Email-based OTP authentication

lua auth configure

`lua auth key`

Display your stored API key (with confirmation prompt).

lua auth key

`lua auth logout`

Delete your stored API key and credentials.

lua auth logout

Skill Management Commands

`lua skill init`

Initialize a new Lua skill project in the current directory.

lua skill init

This command will:

Fetch your organizations and agents from the API
Let you select an organization by name
Choose between existing agents or creating a new one:
- Existing Agent: Select from your current agents
- New Agent: Create a custom agent with:
  - Agent type selection (Base Agent, Shopify, WooCommerce, etc.)
  - Required metadata collection (API keys, IDs, etc.)
  - Feature configuration (RAG, tickets, web search, etc.)
  - Business information (name, type, personality, traits)
  - Automatic persona generation and welcome message
Prompt for skill name and description
Create a lua.skill.yaml configuration file with agent details
Copy template files to the current directory

`lua skill compile`

Compile your LuaSkill and bundle all dependencies.

lua skill compile

This command will:

Scan your tools for imports and dependencies
Bundle external packages using esbuild
Compress the generated code for efficient storage
Create .lua/deploy.json with compiled skill data
Generate individual tool files in .lua/ directory

Options:

--watch - Watch for changes and recompile automatically
--minify - Minify the bundled code

`lua skill test`

Interactive testing interface for your tools.

lua skill test

Features:

Tool selection menu
Input validation with Zod schemas
Real-time execution in isolated VM context
Error reporting and debugging
Mock data support

`lua skill push`

Push your compiled skill version to the server.

lua skill push

This command will:

Compile your skill first
Confirm the version you want to push
Send the compiled skill data to the server
Store the skill ID in your YAML file

`lua skill dev`

Push your compiled skill version to the sandbox for development and testing with automatic file watching and web chat interface.

lua skill dev

This command will:

Compile your skill first
Confirm the version you want to push to sandbox
Smart Sandbox Management:
- If you have a previous sandbox skill ID stored, it will try to update the existing sandbox
- If the update fails or no sandbox exists, it will create a new one
- The sandbox skill ID is securely stored on your machine for future use
Display the sandbox skill ID for testing
Web Chat Interface:
- Automatically opens a beautiful chat interface in your browser
- Test your sandbox skill in real-time with natural language
- Messages are sent to the sandbox environment via the chat API
- Available at http://localhost:3000 (opens automatically)
Live Log Panel:
- Real-time log feed showing execution details
- WebSocket connection to wss://api.lua.dev/feed
- Console-style interface with color-coded log levels
- Shows tool calls, errors, metrics, and execution metadata
- Displays detailed information in expandable sections
- Connection status indicator and automatic reconnection
- Supports log types: error, debug, warn, info
File Watching Mode:
- Watches for file changes in the current directory
- Automatically recompiles and pushes to sandbox when files change
- Ignores build artifacts (.lua/, node_modules/, .git/, etc.)
- Debounces rapid changes to prevent excessive builds
- Press Ctrl+C to stop watching and exit

`lua skill deploy`

Deploy a version to production.

lua skill deploy

This command will:

Fetch available versions from the server
Let you select which version to deploy
Show a warning about deploying to all users
Publish the selected version to production

Requirements:

Valid API key (configured with lua auth configure)
Compiled skill (run lua skill compile first)
Active internet connection

Template System

The Lua CLI includes a comprehensive template system with examples and documentation:

Template Structure

template/
├── README.md              # Complete user guide
├── DEVELOPER.md           # Technical documentation  
├── API.md                 # API reference
├── QUICKSTART.md          # Quick start guide
├── tools/                 # Example tools
│   ├── GetWeatherTool.ts
│   ├── GetUserDataTool.ts
│   ├── CreatePostTool.ts
│   ├── CalculatorTool.ts
│   └── AdvancedMathTool.ts
├── services/              # Example services
│   ├── ApiService.ts
│   ├── GetWeather.ts
│   └── MathService.ts
└── index.ts               # Main skill definition

Getting Started with Templates

Copy the template:
```
cp -r template/ my-skill/
cd my-skill
```
Install dependencies:
```
npm install
```

Read the documentation:

# Start with the quick start guide
cat QUICKSTART.md

# Then read the full documentation
cat README.md

Create your tools:

# Modify existing tools or create new ones
# See tools/ directory for examples

Configuration File

The lua.skill.yaml file is created when you run lua skill init:

agent:
  agentId: "your-agent-id"
  orgId: "your-organization-id"
  persona: "Generated persona description" # Only for newly created agents
  welcomeMessage: "Welcome message" # Only for newly created agents

skill:
  name: "Your Skill Name"
  version: "0.0.1"
  skillId: "your-skill-id"

Authentication Methods

API Key Authentication

Run lua auth configure
Select "API Key"
Enter your API key when prompted
The key is validated and stored securely

Email Authentication

Run lua auth configure
Select "Email"
Enter your email address
Check your email for the OTP code
Enter the 6-digit OTP code
An API key is automatically generated and stored

Security

All API keys are stored securely using your system's credential manager
Email authentication uses OTP (One-Time Password) for secure verification
Confirmation prompts prevent accidental exposure of sensitive information
No credentials are stored in plain text

Development Workflow

1. Project Setup

# Initialize a new skill project
lua skill init

# Or copy the template
cp -r template/ my-skill/
cd my-skill
npm install

2. Tool Development

# Create tools in tools/ directory
# Use TypeScript with Zod validation
# See template/tools/ for examples

3. Testing

# Compile your skill
lua skill compile

# Test your tools interactively
lua skill test

4. Deployment

# Push version to server
lua skill push

# Deploy to production
lua skill deploy

5. Iteration

# Make changes to your tools
# Recompile and test
lua skill compile && lua skill test

# Push updates
lua skill push

# Deploy updates
lua skill deploy

Requirements

Node.js 16.0.0 or higher
Valid Lua AI platform account
TypeScript knowledge (for tool development)
Basic understanding of Zod schemas

Development

To contribute to this project:

Clone the repository
Install dependencies: npm install
Build the project: npm run build
Make your changes
Test your changes
Submit a pull request

License

MIT License - see LICENSE file for details.

User Data API

The Lua CLI provides a built-in User Data API that allows your tools to interact with persistent user data stored in the Lua system.

Basic Usage

import { user } from 'lua-cli';

// Get user data
const userData = await user.data.get();
console.log('User data:', userData);

// Create or update user data
await user.data.create({
  name: 'John Doe',
  preferences: {
    theme: 'dark',
    language: 'en'
  }
});

// Update existing data
await user.data.update({
  name: 'Jane Doe',
  preferences: {
    theme: 'light',
    language: 'es'
  }
});

// Clear all user data
await user.data.clear();

Using in Tools

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

export class UserPreferencesTool extends LuaTool {
  constructor() {
    super('user-preferences', 'Manage user preferences');
  }

  async execute(input: { action: string; key?: string; value?: string }) {
    const { action, key, value } = input;

    switch (action) {
      case 'get':
        const userData = await user.data.get();
        return { preferences: userData.preferences || {} };
      
      case 'set':
        if (!key || !value) {
          throw new Error('Key and value are required for set action');
        }
        
        const currentData = await user.data.get();
        const updatedData = {
          ...currentData,
          preferences: {
            ...currentData.preferences,
            [key]: value
          }
        };
        
        await user.data.update(updatedData);
        return { success: true, message: `Set ${key} to ${value}` };
      
      case 'clear':
        await user.data.clear();
        return { success: true, message: 'All preferences cleared' };
      
      default:
        throw new Error('Invalid action. Use: get, set, or clear');
    }
  }

  getInputSchema() {
    return z.object({
      action: z.enum(['get', 'set', 'clear']).describe('Action to perform'),
      key: z.string().optional().describe('Preference key (required for set action)'),
      value: z.string().optional().describe('Preference value (required for set action)')
    });
  }
}

API Reference

user.data.get() - Retrieves current user data
user.data.create(data) - Creates or updates user data
user.data.update(data) - Updates existing user data (alias for create)
user.data.clear() - Clears all user data

For more details, see USER_DATA_API.md.

Support

For support and questions:

Create an issue on GitHub
Contact: stefan@lua.dev

Changelog

1.4.0

Agent Creation: Added ability to create new agents during lua skill init
Agent Type Selection: Choose from various agent types (Base Agent, Shopify, WooCommerce, etc.)
Metadata Collection: Automatic collection of required metadata for agent types
Feature Configuration: Enable/disable features like RAG, tickets, web search
Persona Generation: Automatic persona and welcome message generation for new agents
Enhanced YAML: Added persona and welcome message fields to configuration file

1.3.0

Command Restructure: Reorganized commands under lua auth and lua skill groups
New Push Command: Added lua skill push to push versions to server
New Deploy Command: Added lua skill deploy to deploy versions to production
Version Management: Added version field to YAML configuration
Improved UX: Better command organization and intuitive naming
Enhanced Workflow: Complete skill lifecycle from init to production deployment

1.2.0

Tool Development Framework: Complete LuaSkill and LuaTool framework
Dependency Bundling: Automatic bundling of npm packages using esbuild
Interactive Testing: Real-time tool testing with lua test command
Code Compression: Gzip compression for efficient storage
In-Memory Execution: VM-based execution without temporary files
Comprehensive Documentation: Complete guides, API reference, and examples
Template System: Rich template with 5 example tools and services
TypeScript Support: Full TypeScript integration with Zod validation
Error Handling: Robust error handling and validation
Performance Optimization: Optimized bundling and execution

1.1.0

Major Refactoring: Complete codebase reorganization into modular structure
Email Authentication: Added OTP-based email authentication
API Key Display: New lua apiKey command
TypeScript Types: Comprehensive type definitions
Improved Architecture: Separated commands, services, and utilities

1.0.0

Initial release
API key authentication
Organization and agent management
Skill project initialization
Secure credential storage