Skip to main content

​
Overview

All Lua CLI commands now support non-interactive mode, enabling seamless automation for:
  • AI IDEs (Cursor, GitHub Copilot, Windsurf, etc.)
  • CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
  • Shell scripting and automation
  • Programmatic agent management
Non-interactive mode bypasses all prompts by providing arguments and flags directly on the command line.
New in v3.3.0: Every command now has non-interactive options with consistent naming patterns.

AI Agent Building Guide

Building with Cursor, Windsurf, or GitHub Copilot? See the complete AI Agent Building Guide for the full end-to-end workflow including authentication, testing strategies, sandbox vs production, common gotchas, and debugging.

​
Design Patterns

​
Consistent Option Naming

All commands follow these patterns:
PatternDescriptionExample
--<entity>-nameSelect entity by name--skill-name mySkill
--<entity>-versionSpecify version--skill-version 1.0.5
--forceSkip confirmation prompts--force
--jsonOutput as JSON for parsing--json
[action]Positional action argumentlua jobs view

​
Action Arguments

Many commands accept an action as the first argument: 
lua skills view                    # View all skills
lua skills versions --skill-name x # View versions for skill x
lua skills deploy --skill-name x   # Deploy skill x

​
CI/CD Mode (—ci flag)

New in v3.5.0: The global --ci flag makes the CLI fail loudly on missing required arguments instead of silently prompting (which fails in non-TTY environments).
In CI/CD pipelines and non-TTY environments (piped input, background jobs), interactive prompts silently fail, causing commands to cancel without clear error messages. The --ci flag prevents this by throwing errors when required arguments are missing: 
# Without --ci (fails silently in CI/CD)
lua push skill
# Silently cancels - no clear error

# With --ci (fails loudly with helpful error)
lua --ci push skill
# Error: Interactive prompt required but --ci flag is set. Provide all required flags or arguments.

​
Usage

The --ci flag is a global flag that must come before the command: 
# Correct
lua --ci push skill --name mySkill --set-version 1.0.0 --force

# Incorrect
lua push skill --ci  # Won't work - must be global

​
When to Use

Always use --ci in automated environments:
# GitHub Actions
- name: Push skill
  run: lua --ci push skill --name mySkill --set-version ${{ github.sha }} --force

# GitLab CI
script:
  - lua --ci push all --force --auto-deploy
Why: Ensures missing flags cause immediate, clear failures instead of silent hangs.

​
Behavior Differences

ScenarioWithout —ciWith —ci
Missing required flagShows prompt (hangs in CI)Throws error immediately
Non-TTY environmentShows warning, continuesThrows error if prompts needed
All flags providedWorks normallyWorks normally

​
Auto-Detection

Even without --ci, the CLI automatically detects non-TTY environments and shows a warning: 
echo "" | lua push skill
# Warning: stdin is not a TTY. Interactive prompts may not work correctly.
# Tip: Use --ci flag in CI/CD environments to fail loudly on missing required flags.
However, this still allows the command to continue (and likely fail silently). Using --ci prevents this by failing immediately.

​
Complete Command Reference

​
Project Setup

Initialize a new project without prompts:
# Use existing agent
lua init --agent-id abc123

# Create agent in existing organization
lua init --agent-name "My Bot" --org-id org456

# Create agent + new organization
lua init --agent-name "My Bot" --org-name "Acme Corp"

# Override existing project
lua init --agent-id abc123 --force

# With example code
lua init --agent-id abc123 --with-examples
OptionDescription
--agent-id <id>Use existing agent by ID
--agent-name <name>Name for new agent
--org-id <id>Existing organization ID
--org-name <name>New organization name
--forceOverride existing lua.skill.yaml
--with-examplesInclude example code

​
Development & Testing

Test skills, webhooks, or jobs without prompts:
# Test a skill/tool
lua test skill --name get_weather --input '{"city": "London"}'

# Test a webhook
lua test webhook --name payment-hook --input '{"query": {}, "headers": {}, "body": {"type": "payment"}}'

# Test a job
lua test job --name daily-report

# Test preprocessor
lua test preprocessor --name filter --input '{"message": "hello", "channel": "web"}'

# Test postprocessor
lua test postprocessor --name formatter --input '{"message": "hi", "response": "hello", "channel": "web"}'
OptionDescription
--name <name>Entity name to test
--input <json>JSON input for testing

​
Deployment

Push components without prompts:
# Push specific skill with version
lua push skill --name mySkill --set-version 1.0.5

# Push all components
lua push all --force

# Push and auto-deploy to production
lua push all --force --auto-deploy

# Push webhook
lua push webhook --name payment-hook --set-version 2.0.0

# Push job
lua push job --name daily-report --set-version 1.0.0
OptionDescription
--name <name>Entity name to push
--set-version <ver>Version to set
--forceSkip confirmations
--auto-deployDeploy after push

​
Entity Management

Manage skills without prompts:
# View all production skills
lua skills view

# View skill versions
lua skills versions --skill-name mySkill

# Deploy specific version
lua skills deploy --skill-name mySkill --skill-version 1.0.3

# Deploy latest
lua skills deploy --skill-name mySkill --skill-version latest
ActionOptions Required
viewNone
versions--skill-name
deploy--skill-name, --skill-version

​
Configuration

Manage environment variables without prompts:
# List variables
lua env sandbox --list
lua env production --list

# Set variable
lua env sandbox -k DATABASE_URL -v "postgres://localhost/db"
lua env production -k API_KEY -v "sk_live_xxx"

# Delete variable
lua env production -k OLD_KEY --delete
OptionDescription
--listList all variables
-k, --key <name>Variable name
-v, --value <val>Variable value
-d, --deleteDelete the variable

​
Viewing & Debugging

View logs without prompts:
# View all logs
lua logs --type all --limit 50

# Filter by type
lua logs --type skill --limit 20
lua logs --type webhook --limit 20
lua logs --type job --limit 20

# Filter by specific entity
lua logs --type skill --name mySkill --limit 10

# Pagination
lua logs --type all --limit 20 --page 2

# JSON output for scripting
lua logs --type all --json
OptionDescription
--type <type>all, skill, job, webhook, preprocessor, postprocessor, user_message, agent_response
--name <name>Entity name (requires —type, not for message types)
--limit <n>Number of logs (default: 20)
--page <n>Page number
--jsonJSON output

​
Authentication & Utilities

Authentication commands with —force:
# View API key without confirmation
lua auth key --force

# Logout without confirmation
lua auth logout --force

​
Marketplace

Publish and manage skills:
# List a skill
lua marketplace create list --skill-name mySkill --display-name "My Skill"

# Publish a version
lua marketplace create publish --marketplace-id xyz --version-id v1 --changelog "Bug fixes"

# Update metadata
lua marketplace create update --marketplace-id xyz --display-name "New Name"

# Unlist
lua marketplace create unlist --marketplace-id xyz --force

# Unpublish version
lua marketplace create unpublish --marketplace-id xyz --version-id v1 --force

# View my listings
lua marketplace create view --json

​
Example Workflows

​
AI IDE Workflow (Cursor, Copilot)

When an AI assistant needs to manage your agent: 
# Initialize project for existing agent
lua init --agent-id agent_abc123

# Set environment variables
lua env sandbox -k OPENAI_KEY -v "sk-xxx"
lua env production -k OPENAI_KEY -v "sk-yyy"

# Discover and connect third-party integrations
lua integrations available
lua integrations info linear --json                    # Get scopes and triggers as JSON
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated       # Connect with triggers

# Verify integration
lua integrations list
lua integrations webhooks list

# Test a specific tool
lua test skill --name get_order --input '{"orderId": "123"}'

# Push and deploy
lua push skill --name order-service --set-version 1.0.0 --force
lua deploy --skill-name order-service --skill-version latest --force

# Check logs
lua logs --type skill --name order-service --limit 10 --json

​
GitHub Actions CI/CD

name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Lua CLI
        run: npm install -g lua-cli
      
      - name: Configure auth
        run: lua auth configure
        env:
          LUA_API_KEY: ${{ secrets.LUA_API_KEY }}
      
      - name: Check for drift
        run: lua sync --check
      
      - name: Compile
        run: lua compile
      
      - name: Push version
        run: lua push skill --name ${{ github.event.repository.name }} --set-version ${{ github.sha }} --force
      
      - name: Deploy to production
        run: lua deploy --skill-name ${{ github.event.repository.name }} --skill-version latest --force
      
      - name: Verify deployment
        run: lua logs --type skill --name ${{ github.event.repository.name }} --limit 5 --json

​
Bash Scripting

#!/bin/bash
set -e

SKILL_NAME="my-skill"
VERSION=$(date +%Y%m%d%H%M%S)

echo "Deploying $SKILL_NAME version $VERSION"

# Check drift
if ! lua sync --check; then
  echo "Drift detected! Run 'lua sync' manually to resolve."
  exit 1
fi

# Compile and push
lua compile
lua push skill --name "$SKILL_NAME" --set-version "$VERSION" --force

# Deploy
lua deploy --skill-name "$SKILL_NAME" --skill-version latest --force

# Verify
lua logs --type skill --name "$SKILL_NAME" --limit 5

echo "Deployment complete!"

​
Multi-Component Deployment

#!/bin/bash
# Deploy all components at once

VERSION="2.0.0"

# Push everything
lua push all --force

# Or push individually with versions
lua push skill --name order-service --set-version $VERSION --force
lua push webhook --name payment-hook --set-version $VERSION --force
lua push job --name daily-report --set-version $VERSION --force

# Deploy skills
lua deploy --skill-name order-service --skill-version latest --force

# Activate webhooks and jobs
lua webhooks activate --webhook-name payment-hook
lua jobs activate --job-name daily-report

# Verify
lua production overview

​
Exit Codes

All commands return consistent exit codes:
CodeMeaning
0Success
1Error (missing args, not found, API error)
Use exit codes in scripts: 
if lua sync --check; then
  echo "No drift"
else
  echo "Drift detected"
  exit 1
fi

​
JSON Output

Commands with --json output machine-readable JSON: 
# Get logs as JSON
logs=$(lua logs --type all --limit 5 --json)

# Parse with jq
echo "$logs" | jq '.logs[].message'

# Get installed skills
skills=$(lua marketplace install installed --json)

​
Best Practices

In automated pipelines, always use --force to skip confirmations:
lua push all --force
lua deploy --skill-name x --skill-version latest --force
Use lua sync --check in CI to fail builds on drift:
lua sync --check || { echo "Drift detected"; exit 1; }
When processing output programmatically, use --json:
lua logs --json | jq '.logs | length'
Use dynamic versions in CI:
lua push skill --name x --set-version $(git rev-parse --short HEAD) --force

CLI Overview

All available commands

Skill Management

init, test, push, deploy details

Sync Command

Drift detection details

Environment Variables

Managing configuration