# 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/lua-ai-global/lua-cli/blob/main/LICENSE)

**lua-cli** is the official command-line tool for building intelligent AI agents on the Lua 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 in sandbox before deploying
- 🚀 **Batch Deployment** - Push all components with one command
- 🛒 **Marketplace** - Publish and install verified skills from the community
- 🌐 **CI/CD Ready** - Environment variable support for automated deployments

---

## Installation

### Global Installation (Recommended)

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

### Verify Installation

```bash
lua --version
```

---

## Quick Start

### 1. Authenticate

```bash
lua auth configure
```

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

### 2. Initialize Project

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

Follow the prompts to configure your agent.

### 3. Create a Tool

Create `src/skills/tools/WeatherTool.ts`:

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

export default class WeatherTool implements LuaTool {
  name = 'get_weather';
  description = 'Get current weather for any city';

  inputSchema = z.object({
    city: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    return { temperature: 72, condition: 'sunny' };
  }
}
```

### 4. Test Locally

```bash
lua test      # Test individual tools
lua chat      # Interactive chat with your agent
```

### 5. Deploy to Production

```bash
lua compile
lua push all --force --auto-deploy
```

Your agent is now live! 🎉

---

## Core Concepts

### LuaAgent - Unified Configuration

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

export const agent = new LuaAgent({
  name: 'my-assistant',
  persona: 'You are a helpful AI assistant...',
  skills: [customerSupportSkill, productSkill],
  webhooks: [paymentWebhook],
  jobs: [dailyReportJob]
});
```

### Skills - Tool Collections

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

export default new LuaSkill({
  name: 'weather-skill',
  description: 'Weather information tools',
  tools: [new GetWeatherTool(), new GetForecastTool()]
});
```

### Runtime APIs

Access powerful APIs in your tools:

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

// User data
const user = await User.get();
await user.send([{ type: 'text', text: 'Hello!' }]);

// Products
const products = await Products.get();
await Products.create({ name: 'Widget', price: 29.99 });

// Custom data storage
await Data.create('notes', { text: 'Hello' });
const results = await Data.search('notes', 'query');
```

---

## Key Commands

```bash
# Project Setup
lua init                    # Initialize new project
lua compile                 # Compile TypeScript

# Development
lua test                    # Test tools interactively
lua chat                    # Chat with your agent
lua dev                     # Dev server with live reload

# Deployment
lua push                    # Push to server (interactive)
lua push all --force        # Push all without prompts
lua deploy                  # Deploy to production

# Management
lua production              # View production status
lua env                     # Manage environment variables
lua logs                    # View agent logs
lua marketplace             # Browse and install skills
```

[**→ Full CLI Reference**](docs/CLI_REFERENCE.md)

---

## Documentation

### Getting Started
- [**Getting Started Guide**](docs/GETTING_STARTED.md) - Complete step-by-step tutorial
- [**CLI Reference**](docs/CLI_REFERENCE.md) - All available commands
- [**API Reference**](docs/API_REFERENCE.md) - Platform API overview

### API Documentation
- [LuaAgent](docs/api/LuaAgent.md) - Agent configuration
- [LuaSkill](docs/api/LuaSkill.md) - Tool collections
- [LuaTool](docs/api/LuaTool.md) - Creating tools
- [LuaWebhook](docs/api/LuaWebhook.md) - HTTP endpoints
- [LuaJob](docs/api/LuaJob.md) - Scheduled tasks
- [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
- [AI API](docs/api/AI.md) - AI text generation

[**→ Complete API Documentation**](docs/README.md)

---

## CI/CD Integration

Perfect for automated deployments:

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

**Global `--ci` flag**: Fails loudly on missing required flags instead of silently canceling in non-TTY environments.

---

## Example: E-commerce Agent

```typescript
import { LuaAgent, LuaSkill } from 'lua-cli';
import { Products, Baskets, Orders } from 'lua-cli';

const productSkill = new LuaSkill({
  name: 'product-skill',
  description: 'Product browsing and search',
  tools: [new SearchProductsTool(), new GetProductTool()]
});

const orderSkill = new LuaSkill({
  name: 'order-skill',
  description: 'Order management',
  tools: [new PlaceOrderTool(), new TrackOrderTool()]
});

export const agent = new LuaAgent({
  name: 'ecommerce-assistant',
  persona: 'You are an e-commerce assistant helping customers browse products and place orders.',
  skills: [productSkill, orderSkill],
  webhooks: [orderWebhook],
  jobs: [inventoryCheckJob]
});
```

---

## Contributing

We welcome contributions!

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/lua-ai-global/lua-cli.git
cd lua-cli
npm install
npm run build
npm link
npm test
```

---

## Architecture

lua-cli is part of a distributed platform:

- **lua-cli** - Developer tool (this repo)
- **lua-api** - API gateway
- **lua-agents** - Business logic service (CRUD, MongoDB)
- **lua-core** - Agent runtime (Mastra, VM sandbox, streaming)
- **lua-auth** - Authentication service

[**→ Architecture Details**](CLAUDE.md)

---

## Support

- **Documentation**: [docs.heylua.ai](https://docs.heylua.ai)
- **Email**: support@heylua.ai
- **GitHub Issues**: [github.com/lua-ai-global/lua-cli/issues](https://github.com/lua-ai-global/lua-cli/issues)
- **Admin Dashboard**: [admin.heylua.ai](https://admin.heylua.ai)

---

## License

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

---

## Links

- **Website**: [heylua.ai](https://heylua.ai)
- **Documentation**: [docs.heylua.ai](https://docs.heylua.ai)
- **npm Package**: [npmjs.com/package/lua-cli](https://www.npmjs.com/package/lua-cli)
- **GitHub**: [github.com/lua-ai-global/lua-cli](https://github.com/lua-ai-global/lua-cli)

---

*Made with ❤️ by the Lua team*

**Version:** 3.5.0-alpha.3
**Last Updated:** February 2026
