JSPM

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

Command-line interface for Lua AI platform - develop, test, and deploy LuaSkills with custom tools

Package Exports

  • lua-cli
  • lua-cli/cli

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

  1. Configure your authentication:

    lua auth configure

    Choose between API key or email authentication methods.

  2. Initialize a new skill project:

    lua skill init

    Choose between selecting an existing agent or creating a new one, then provide skill details.

  3. Develop your tools:

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

  4. Compile your skill:

    lua skill compile

    Bundles dependencies and creates deployable files.

  5. Test your tools:

    lua skill test

    Interactive testing interface for your tools.

  6. 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.heylua.ai/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

  1. Copy the template:

    cp -r template/ my-skill/
cd my-skill

  2. Install dependencies:

    npm install

  3. Read the documentation:

    # Start with the quick start guide
cat QUICKSTART.md

# Then read the full documentation
cat README.md

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

  1. Run lua auth configure
  2. Select "API Key"
  3. Enter your API key when prompted
  4. The key is validated and stored securely

Email Authentication

  1. Run lua auth configure
  2. Select "Email"
  3. Enter your email address
  4. Check your email for the OTP code
  5. Enter the 6-digit OTP code
  6. 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:

  1. Clone the repository
  2. Install dependencies: npm install
  3. Build the project: npm run build
  4. Make your changes
  5. Test your changes
  6. 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/user-data-api';

// 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/skill';
import { user } from 'lua-cli/user-data-api';
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:

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