Utility Commands

Overview

Utility commands provide quick access to the Lua Admin interface, documentation, shell autocomplete setup, and telemetry settings.

lua agents

List organizations and agents

lua completion

Generate shell autocomplete

lua admin

Open admin dashboard

lua evals

Open evaluations dashboard

lua docs

Open documentation

lua telemetry

Manage usage telemetry

New in v3.6.0: lua telemetry command to manage usage data collection.

New in v2.6.0: Shell autocomplete support for Bash, Zsh, and Fish!

New in v3.5.0: lua agents command to list all accessible organizations and agents with JSON output support.

lua agents

New in v3.5.0: List all organizations and agents you have access to for discovery and scripting.

View all organizations and agents accessible with your API key. Useful for automation, team management, and discovering available agents.

lua agents           # List all accessible agents
lua agents --json    # JSON output for scripting

What It Shows

The command displays all organizations you’re a member of and their associated agents: Organization Information:

Organization ID
Organization name
Your role (owner, admin, developer)

Agent Information:

Agent ID
Agent name
Environment (production/staging/sandbox)
Status (active/inactive)

Example Output

Interactive
JSON Output

$ lua agents

✅ Found 2 organizations with 4 agents

Organization: My Company (org_abc123)
Role: Owner
├── Customer Support Bot (agent_xyz789)
│   Environment: Production
│   Status: Active
├── Sales Assistant (agent_def456)
│   Environment: Production
│   Status: Active

Organization: Test Workspace (org_test999)
Role: Developer
├── Dev Bot (agent_dev111)
│   Environment: Staging
│   Status: Active
└── Experimental Agent (agent_exp222)
    Environment: Sandbox
    Status: Inactive

$ lua agents --json

{
  "success": true,
  "organizations": [
    {
      "orgId": "org_abc123",
      "orgName": "My Company",
      "role": "owner",
      "agents": [
        {
          "agentId": "agent_xyz789",
          "agentName": "Customer Support Bot",
          "environment": "production",
          "status": "active",
          "createdAt": "2025-01-15T10:30:00Z",
          "lastUpdated": "2025-01-20T14:22:00Z"
        },
        {
          "agentId": "agent_def456",
          "agentName": "Sales Assistant",
          "environment": "production",
          "status": "active",
          "createdAt": "2025-01-18T09:15:00Z",
          "lastUpdated": "2025-01-21T16:45:00Z"
        }
      ]
    },
    {
      "orgId": "org_test999",
      "orgName": "Test Workspace",
      "role": "developer",
      "agents": [
        {
          "agentId": "agent_dev111",
          "agentName": "Dev Bot",
          "environment": "staging",
          "status": "active",
          "createdAt": "2025-01-10T12:00:00Z",
          "lastUpdated": "2025-01-19T11:30:00Z"
        },
        {
          "agentId": "agent_exp222",
          "agentName": "Experimental Agent",
          "environment": "sandbox",
          "status": "inactive",
          "createdAt": "2025-01-12T15:20:00Z",
          "lastUpdated": "2025-01-14T10:10:00Z"
        }
      ]
    }
  ]
}

Options

Option	Description
`--json`	Output as JSON for programmatic parsing

Use Cases

Discover Available Agents

Find agent IDs for lua init or scripts:

$ lua agents
# Copy agent ID for initialization

$ lua init --agent-id agent_xyz789

Quickly find the correct agent ID without going to admin dashboard.

Team Management

See what agents team members have access to:

$ lua agents
# Review all accessible agents
# Verify permissions are correct
# Check which agents are active

Audit team access and agent organization.

Automation & Scripting

Parse JSON to automate agent operations:

# Get all production agents
lua agents --json | jq '.organizations[].agents[] | select(.environment == "production")'

# Count total agents
lua agents --json | jq '[.organizations[].agents[]] | length'

# Find agent by name
lua agents --json | jq '.organizations[].agents[] | select(.agentName == "Sales Assistant")'

# List all agent IDs
lua agents --json | jq -r '.organizations[].agents[].agentId'

Build automation tools and monitoring scripts.

Environment Discovery

Identify staging/sandbox agents for testing:

# Find all staging agents
lua agents --json | jq '.organizations[].agents[] | select(.environment == "staging")'

# Check for inactive agents
lua agents --json | jq '.organizations[].agents[] | select(.status == "inactive")'

Manage different environments effectively.

CI/CD Integration

Validate agent access in pipelines:

#!/bin/bash
# Verify agent exists before deployment

AGENT_ID="agent_xyz789"
AGENTS_JSON=$(lua agents --json)

if echo "$AGENTS_JSON" | jq -e ".organizations[].agents[] | select(.agentId == \"$AGENT_ID\")" > /dev/null; then
  echo "✅ Agent found - proceeding with deployment"
  lua push all --force --auto-deploy
else
  echo "❌ Agent not accessible - check API key permissions"
  exit 1
fi

Validate environment before deploying.

Multi-Agent Workflows

Deploy to multiple agents programmatically:

# Deploy to all production agents
for agent_id in $(lua agents --json | jq -r '.organizations[].agents[] | select(.environment == "production") | .agentId'); do
  echo "Deploying to $agent_id"
  cd "/path/to/project/$agent_id"
  lua push all --force --auto-deploy
done

Automate multi-agent deployments.

JSON Parsing Examples

Extract specific information:

# Get organization names
lua agents --json | jq -r '.organizations[].orgName'

# Get agents in specific org
lua agents --json | jq '.organizations[] | select(.orgName == "My Company") | .agents'

# Count agents per organization
lua agents --json | jq '.organizations[] | {org: .orgName, count: (.agents | length)}'

# Find your role in each organization
lua agents --json | jq '.organizations[] | {org: .orgName, role: .role}'

# List active production agents with details
lua agents --json | jq '.organizations[].agents[] | select(.status == "active" and .environment == "production") | {name: .agentName, id: .agentId}'

Requirements

Must be authenticated (lua auth configure)
API key must have valid permissions

Troubleshooting

No organizations found

Check:

Verify authentication: lua auth key --force
Ensure API key has permissions
Check if you’re a member of any organizations

Error: “No organizations accessible”

# Re-authenticate
$ lua auth configure
# Ask organization owner to add you

Missing expected agents

Check:

Verify agent exists in admin dashboard
Ensure you have access to the agent’s organization
Check if agent was recently created (may take a moment)

Solution:

# Refresh by re-running
$ lua agents

JSON parsing errors

Ensure jq is installed:

# macOS
brew install jq

# Ubuntu/Debian
apt-get install jq

# Test
echo '{"test": true}' | jq '.'

Integration with Other Commands

# Discover agent → Initialize project → Deploy
lua agents                              # Find agent ID
lua init --agent-id agent_xyz789        # Initialize
lua push all --force --auto-deploy      # Deploy

# List agents → Select one → Check production state
lua agents --json | jq -r '.organizations[].agents[].agentId'
lua production overview                 # Check specific agent

# Automate init for multiple agents
for agent_id in $(lua agents --json | jq -r '.organizations[0].agents[].agentId'); do
  mkdir "project-$agent_id"
  cd "project-$agent_id"
  lua init --agent-id "$agent_id"
  cd ..
done

Non-Interactive Mode for Auth Commands

The following commands support --force to skip confirmation prompts:

# View API key without confirmation
lua auth key --force

# Logout without confirmation
lua auth logout --force

# Clear chat history without confirmation
lua chat clear --force

# Clear specific user's history without confirmation
lua chat clear --user [email protected] --force

lua completion

Generate shell autocomplete scripts for faster command-line workflows.

lua completion [shell]       # Generate completion script
lua completion bash          # Generate for Bash
lua completion zsh           # Generate for Zsh
lua completion fish          # Generate for Fish

New in v2.6.0: Enable tab completion for all Lua CLI commands and arguments!

What It Does

Generates shell-specific completion scripts that enable:

✅ Tab completion for all commands
✅ Subcommand suggestions
✅ Environment option suggestions (sandbox, staging, production)
✅ Argument completion for push, env, persona, skills
✅ Context-aware completions

Supported Shells

Bash
Zsh
Fish

Installation

# Add to your ~/.bashrc
lua completion bash >> ~/.bashrc
source ~/.bashrc

# Or for one-time setup
echo 'eval "$(lua completion bash)"' >> ~/.bashrc
source ~/.bashrc

Test it

lua pu<TAB>           # Completes to: lua push
lua push <TAB>        # Shows: skill, persona
lua env <TAB>         # Shows: sandbox, staging, production
lua persona <TAB>     # Shows: sandbox, staging, production

Installation

# Add to your ~/.zshrc
lua completion zsh >> ~/.zshrc
source ~/.zshrc

# Or for one-time setup
echo 'eval "$(lua completion zsh)"' >> ~/.zshrc
source ~/.zshrc

Test it

lua <TAB>             # Shows all commands
lua skills <TAB>      # Shows: sandbox, staging, production
lua auth <TAB>        # Shows: configure, logout, key

Installation

# Create completions directory if it doesn't exist
mkdir -p ~/.config/fish/completions

# Generate completion file
lua completion fish > ~/.config/fish/completions/lua.fish

# Completions are automatically loaded

Test it

lua <TAB>             # Shows all commands with descriptions
lua push <TAB>        # Shows: skill, persona
lua env <TAB>         # Shows: sandbox, staging, production

Completion Features

Main Commands

Tab completion for all Lua CLI commands:

lua a<TAB>        # auth, admin
lua p<TAB>        # push, persona, production
lua s<TAB>        # skills
lua e<TAB>        # env
lua f<TAB>        # features
lua c<TAB>        # compile, completion, chat, channels

Subcommands

Context-aware subcommand completion:

lua auth <TAB>         # configure, logout, key
lua push <TAB>         # skill, persona
lua chat <TAB>         # clear
lua completion <TAB>   # bash, zsh, fish

Environment Options

Environment selection for applicable commands:

lua env <TAB>          # sandbox, staging, production
lua persona <TAB>      # sandbox, staging, production
lua skills <TAB>       # sandbox, staging, production

Help Flags

Common flags available for all commands:

lua --<TAB>            # --help, --version
lua push --<TAB>       # --help

Verification

After installation, verify autocomplete is working:

Test Basic Completion
Test Subcommands
Test Environment

# Type this and press TAB
lua pu

# Should complete to:
lua push

# Type this and press TAB
lua push 

# Should show options:
skill  persona

# Type this and press TAB
lua env 

# Should show:
sandbox  staging  production

Troubleshooting

Completions not working

Problem: Tab completion doesn’t work after installationSolutions:

Restart your terminal or reload shell config:

# Bash
source ~/.bashrc

# Zsh
source ~/.zshrc

# Fish (automatic)

Verify script was added correctly:

# Check if completion is in config
tail ~/.bashrc    # or ~/.zshrc

Try explicit installation:

eval "$(lua completion bash)"  # Or zsh

Completions incomplete

Problem: Some commands complete, others don’tSolutions:

Regenerate completion script:

lua completion bash > /tmp/lua_completions
cat /tmp/lua_completions >> ~/.bashrc
source ~/.bashrc

Check Lua CLI version:

lua --version
# Should be v2.6.0 or higher

Fish completions not loading

Problem: Completions don’t work in Fish shellSolutions:

Verify file location:
```
ls ~/.config/fish/completions/lua.fish
```

Regenerate if missing:

mkdir -p ~/.config/fish/completions
lua completion fish > ~/.config/fish/completions/lua.fish

Restart Fish shell

Conflict with existing completions

Problem: Completions conflict with other toolsSolution: Remove old completion and reinstall:

# Bash/Zsh: Remove old lines from config file
vim ~/.bashrc  # or ~/.zshrc
# Delete old lua completion lines

# Fish: Remove old file
rm ~/.config/fish/completions/lua.fish

# Reinstall
lua completion [your-shell]

Benefits

Faster Workflow

Type less, complete more with tab

Discover Commands

See available options without docs

Fewer Typos

Autocomplete prevents mistakes

Better UX

Professional CLI experience

Advanced Usage

Multiple Shells

If you use multiple shells, install for each:

# Bash
lua completion bash >> ~/.bashrc

# Zsh
lua completion zsh >> ~/.zshrc

# Fish
lua completion fish > ~/.config/fish/completions/lua.fish

Team Setup

Add to team onboarding:

# In your team's setup script
echo "Setting up Lua CLI autocomplete..."
lua completion bash >> ~/.bashrc
source ~/.bashrc
echo "✅ Autocomplete enabled"

Docker/Remote

Include in Docker images:

# In Dockerfile
RUN lua completion bash >> /root/.bashrc

lua admin

Launch the Lua Admin interface in your default browser.

lua admin

What It Opens

The Lua Admin Dashboard provides complete control over your agent: Conversations

💬 View conversations in real-time
📝 Reply to user messages
📊 Monitor conversation quality
🔍 Search conversation history
📈 Analyze user interactions

User Management

👥 Add users to your agent
✏️ Edit user permissions
🗑️ Remove users
👀 View user activity
📊 User analytics

API Keys

🔑 Generate new API keys
👁️ View existing keys
🗑️ Revoke keys
📋 Copy keys for development
🔒 Manage key permissions

Channel Connections

📱 WhatsApp integration
📸 Instagram messaging
✉️ Email integration
👍 Facebook Messenger
💬 Slack integration
📞 SMS/Twilio
🌐 Website chat widget
🔗 Custom integrations

Billing & Subscription

💳 View current plan
📊 Usage metrics
💰 Billing history
🔄 Update payment method
📈 Upgrade/downgrade plan

Example

$ lua admin
✓ Lua Admin Dashboard opened in your browser

  Dashboard URL: https://admin.heylua.ai
  Agent ID: agent-abc123
  Organization ID: org-xyz789

Requirements

Must be authenticated (lua auth configure)
Must be in a skill directory (has lua.skill.yaml)
Configuration must contain agent.agentId and agent.orgId

Use Cases

Monitor Conversations

$ lua admin

View live conversations
See how users interact with your agent
Identify areas for improvement
Take over conversations if needed

Manage Team Access

$ lua admin

Add team members
Set permissions (admin, developer, viewer)
Manage API keys per user
Control who can deploy

Connect Channels

$ lua admin

Connect WhatsApp Business
Set up Instagram messaging
Configure email integration
Add Slack workspace
Enable Facebook Messenger

Review Analytics

$ lua admin

View conversation metrics
Check response times
Monitor user satisfaction
Track tool usage
Analyze peak times

Manage Billing

$ lua admin

Review usage this month
Check billing history
Update payment method
Upgrade subscription
Download invoices

Troubleshooting

Dashboard doesn't open

Check:

Run lua auth configure to authenticate
Ensure lua.skill.yaml exists (lua init)
Verify agent ID is in config

Error: “No API key found”

$ lua auth configure

Wrong agent displayed

Check:

Verify you’re in correct project directory
Check agentId in lua.skill.yaml
Switch to correct agent directory

Permission denied

Check:

Verify you have admin access
Check with organization owner
Request proper permissions

lua evals

Launch the Lua Evaluations Dashboard in your default browser.

lua evals

What It Opens

The Lua Evaluations Dashboard at https://evals.heylua.ai provides tools to test and evaluate your agent: Evaluation Features

🧪 Test your agent with predefined scenarios
📊 View evaluation results and metrics
📈 Track agent performance over time
🔍 Identify areas for improvement
✅ Validate agent responses

Example

$ lua evals
✓ Lua Evaluations Dashboard opened in your browser

  Dashboard URL: https://evals.heylua.ai
  Agent ID: agent-abc123

Requirements

Must be authenticated (lua auth configure)
Must be in a skill directory (has lua.skill.yaml)
Configuration must contain agent.agentId

Use Cases

Test Agent Responses

$ lua evals

Run predefined test scenarios
Validate agent behavior
Check response quality
Ensure consistency

Track Performance

$ lua evals

Monitor evaluation scores
Compare across versions
Identify regressions
Measure improvements

Quality Assurance

$ lua evals

Run evaluations before deployment
Validate production readiness
Document test results
Share with team

Troubleshooting

Dashboard doesn't open

Check:

Run lua auth configure to authenticate
Ensure lua.skill.yaml exists (lua init)
Verify agent ID is in config

Error: “No API key found”

$ lua auth configure

Wrong agent displayed

Check:

Verify you’re in correct project directory
Check agentId in lua.skill.yaml
Switch to correct agent directory

lua docs

Launch this documentation in your default browser.

lua docs

What It Opens

Opens the complete Lua documentation at https://docs.heylua.ai Sections:

🏠 Overview and getting started
📖 Key concepts (Persona, Skills, Tools, Resources)
⌨️ All CLI commands
📚 Complete API reference
💼 11 production-ready demos
💬 LuaPop chat widget guide

Example

$ lua docs
✓ Lua Documentation opened in your browser

  Documentation: https://docs.heylua.ai

Requirements

None - works from anywhere

Use Cases

Quick Reference

# Forgot a command syntax?
$ lua docs
# Navigate to CLI Commands

API Lookup

# Need API method signature?
$ lua docs
# Go to API Reference

Find Examples

# Need an example for your use case?
$ lua docs
# Check Demos section

Share with Team

Keyboard Shortcut

Add to your shell profile for even faster access:

# Add to ~/.zshrc or ~/.bashrc
alias ld='lua docs'

# Usage
$ ld
# Opens documentation instantly

lua telemetry

New in v3.6.0: Manage whether lua-cli sends usage data.

Control whether lua-cli collects usage data to help improve the developer experience.

lua telemetry           # Show current status
lua telemetry on        # Enable telemetry
lua telemetry off       # Disable telemetry
lua telemetry status    # Show status (same as no argument)

What Is Collected

lua-cli collects usage data to improve the developer experience:

Collected	Not Collected
Command name (e.g. `push`, `compile`)	Your code or file contents
Success or failure	Command arguments or flag values
Command duration	API keys or secrets
CLI version, OS, Node.js version	Agent names or custom data
Account email (for person identification)

Your data is handled in accordance with our Privacy Policy.

Opting Out

You can opt out at any time using either method:

CLI command
Environment variable

lua telemetry off

Persists your preference in ~/.lua-cli/telemetry.json. Re-enable with lua telemetry on.

# Disable for this session
LUA_TELEMETRY=false lua push

# Or add to your shell profile to disable permanently
echo 'export LUA_TELEMETRY=false' >> ~/.zshrc

The environment variable takes highest priority and overrides the saved preference.

Check Current Status

$ lua telemetry
Telemetry: enabled

Usage:
  lua telemetry on      Enable telemetry
  lua telemetry off     Disable telemetry
  lua telemetry status  Show current setting

Or set LUA_TELEMETRY=false in your environment.

First-Run Notice

On first use, lua-cli prints a one-time notice:

  Lua CLI collects usage data to improve the developer experience.
  To opt out, run: lua telemetry off
  Or set: LUA_TELEMETRY=false

This notice is shown once and never again.

CI/CD Environments

In CI/CD pipelines, disable telemetry via environment variable — no config file needed:

# In your CI environment variables
LUA_TELEMETRY=false

Or use the --ci flag which automatically adjusts CLI behavior for non-interactive environments.

Quick Comparison

Command	Opens/Generates	Requires Auth	Use For
`lua agents`	List of organizations/agents	✅ Yes	Discovery, automation, team management
`lua completion`	Shell completion script	❌ No	Tab completion, faster workflows
`lua admin`	Admin dashboard	✅ Yes	Managing agent, conversations, billing
`lua evals`	Evaluations dashboard	✅ Yes	Testing agent, tracking performance
`lua docs`	Documentation	❌ No	Reference, examples, learning
`lua telemetry`	Telemetry settings	❌ No	Opt in/out of usage data collection

Integration with Workflow

During Development

# Need API reference?
$ lua docs
# Check API section

# Continue coding

During Deployment

# Deploy skills
$ lua push
$ lua deploy

# Check admin dashboard
$ lua admin
# Monitor conversations
# Verify deployment working

When Troubleshooting

# Issue with command
$ lua docs
# Search troubleshooting section

# Check production state
$ lua admin
# View live conversations
# Check for errors

Next Steps

All CLI Commands

Complete command reference

Admin Features

Explore the admin dashboard

Getting Started

New to Lua? Start here

Demos

11 production-ready solutions

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

​Overview

lua agents

lua completion

lua admin

lua evals

lua docs

lua telemetry

​lua agents

​What It Shows

​Example Output

​Options

​Use Cases

​JSON Parsing Examples

​Requirements

​Troubleshooting

​Integration with Other Commands

​Non-Interactive Mode for Auth Commands

​lua completion

​What It Does

​Supported Shells

​Completion Features

​Verification

​Troubleshooting

​Benefits

Faster Workflow

Discover Commands

Fewer Typos

Better UX

​Advanced Usage

​lua admin

​What It Opens

​Example

​Requirements

​Use Cases

​Troubleshooting

​lua evals

​What It Opens

​Example

​Requirements

​Use Cases

​Troubleshooting

​lua docs

​What It Opens

​Example

​Requirements

​Use Cases

​Keyboard Shortcut

​lua telemetry

​What Is Collected

​Opting Out

​Check Current Status

​First-Run Notice

​CI/CD Environments

​Quick Comparison

​Integration with Workflow

​During Development

​During Deployment

​When Troubleshooting

​Next Steps

All CLI Commands

Admin Features

Getting Started

Demos

Overview

lua agents

What It Shows

Example Output

Options

Use Cases

JSON Parsing Examples

Requirements

Troubleshooting

Integration with Other Commands

Non-Interactive Mode for Auth Commands

lua completion

What It Does

Supported Shells

Completion Features

Verification

Troubleshooting

Benefits

Advanced Usage

lua admin

What It Opens

Example

Requirements

Use Cases

Troubleshooting

lua evals

What It Opens

Example

Requirements

Use Cases

Troubleshooting

lua docs

What It Opens

Example

Requirements

Use Cases

Keyboard Shortcut

lua telemetry

What Is Collected

Opting Out

Check Current Status

First-Run Notice

CI/CD Environments

Quick Comparison

Integration with Workflow

During Development

During Deployment

When Troubleshooting

Next Steps