Skip to main content

Overview

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

lua status

Full agent state at a glance

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

lua models

List and select the LLM your agent uses

lua governance

Manage governance policies for your agent

lua update

Update lua-cli to the latest version

lua status / lua describe

Inspect the full state of your agent project in a single command.
lua status (alias: lua describe) shows a comprehensive snapshot of your agent: environment info, authentication, project config, per-primitive sync state, persona drift, backup status, telemetry, and actionable next steps.

What It Shows

Environment
  • CLI version and update availability
  • Node.js version, OS, install method (npm, pnpm, nvm, npx, local)
  • API base URL and any overriding env vars (LUA_API_URL, LUA_API_KEY, LUA_NO_HINTS, etc.)
Auth
  • API key source (env var / credentials file / .env)
  • Authenticated email, user ID, and organization list
  • Server reachability status
Project
  • Config path (lua.skill.yaml)
  • Agent name and ID
  • Compiled manifest β€” how many primitives were found in the last compile
Primitives Sync Table For each primitive type (skills, webhooks, jobs, preprocessors, postprocessors, MCP servers, devices, device triggers), shows:
  • Local version (from YAML)
  • Server version (active)
  • Sync status: synced, ahead, behind, not deployed, or server only
Persona / Backup / Telemetry Quick status indicators with a hint if action is needed. Next Steps Actionable hints based on current state (e.g. lua push backup if backup is out of sync).

JSON Output

The --json flag emits a stable JSON document intended for LLM agents, CI dashboards, and scripting:
The schema is versioned (schemaVersion: 1) so consumers can detect breaking changes. All human-readable progress output is suppressed in JSON mode.

lua agents

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.

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

Options

Use Cases

Find agent IDs for lua init or scripts:
Quickly find the correct agent ID without going to admin dashboard.
See what agents team members have access to:
Audit team access and agent organization.
Parse JSON to automate agent operations:
Build automation tools and monitoring scripts.
Identify staging/sandbox agents for testing:
Manage different environments effectively.
Validate agent access in pipelines:
Validate environment before deploying.
Deploy to multiple agents programmatically:
Automate multi-agent deployments.

JSON Parsing Examples

Extract specific information:

Requirements

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

Troubleshooting

Check:
  1. Verify authentication: lua auth key --force
  2. Ensure API key has permissions
  3. Check if you’re a member of any organizations
Error: β€œNo organizations accessible”
Check:
  1. Verify agent exists in admin dashboard
  2. Ensure you have access to the agent’s organization
  3. Check if agent was recently created (may take a moment)
Solution:
Ensure jq is installed:

Integration with Other Commands

Non-Interactive Mode for Auth Commands

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

lua completion

Generate shell autocomplete scripts for faster command-line workflows.
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

Installation
Test it

Completion Features

Tab completion for all Lua CLI commands:
Context-aware subcommand completion:
Environment selection for applicable commands:
Common flags available for all commands:

Verification

After installation, verify autocomplete is working:

Troubleshooting

Problem: Tab completion doesn’t work after installationSolutions:
  1. Restart your terminal or reload shell config:
  2. Verify script was added correctly:
  3. Try explicit installation:
Problem: Some commands complete, others don’tSolutions:
  1. Regenerate completion script:
  2. Check Lua CLI version:
Problem: Completions don’t work in Fish shellSolutions:
  1. Verify file location:
  2. Regenerate if missing:
  3. Restart Fish shell
Problem: Completions conflict with other toolsSolution: Remove old completion and reinstall:

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

If you use multiple shells, install for each:
Add to team onboarding:
Include in Docker images:

lua admin

Launch the Lua Admin interface in your default browser.

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

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

  • View live conversations
  • See how users interact with your agent
  • Identify areas for improvement
  • Take over conversations if needed
  • Add team members
  • Set permissions (admin, developer, viewer)
  • Manage API keys per user
  • Control who can deploy
  • Connect WhatsApp Business
  • Set up Instagram messaging
  • Configure email integration
  • Add Slack workspace
  • Enable Facebook Messenger
  • View conversation metrics
  • Check response times
  • Monitor user satisfaction
  • Track tool usage
  • Analyze peak times
  • Review usage this month
  • Check billing history
  • Update payment method
  • Upgrade subscription
  • Download invoices

Troubleshooting

Check:
  1. Run lua auth configure to authenticate
  2. Ensure lua.skill.yaml exists (lua init)
  3. Verify agent ID is in config
Error: β€œNo API key found”
Check:
  1. Verify you’re in correct project directory
  2. Check agentId in lua.skill.yaml
  3. Switch to correct agent directory
Check:
  1. Verify you have admin access
  2. Check with organization owner
  3. Request proper permissions

lua evals

Launch the Lua Evaluations Dashboard in your default browser.

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

Requirements

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

Use Cases

  • Run predefined test scenarios
  • Validate agent behavior
  • Check response quality
  • Ensure consistency
  • Monitor evaluation scores
  • Compare across versions
  • Identify regressions
  • Measure improvements
  • Run evaluations before deployment
  • Validate production readiness
  • Document test results
  • Share with team

Troubleshooting

Check:
  1. Run lua auth configure to authenticate
  2. Ensure lua.skill.yaml exists (lua init)
  3. Verify agent ID is in config
Error: β€œNo API key found”
Check:
  1. Verify you’re in correct project directory
  2. Check agentId in lua.skill.yaml
  3. Switch to correct agent directory

lua docs

Launch this documentation in your default browser.

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

Requirements

None - works from anywhere

Use Cases

Keyboard Shortcut

Add to your shell profile for even faster access:

lua telemetry

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

What Is Collected

lua-cli collects usage data to improve the developer experience: Your data is handled in accordance with our Privacy Policy.

Opting Out

You can opt out at any time using either method:
Persists your preference in ~/.lua-cli/telemetry.json. Re-enable with lua telemetry on.

Check Current Status

First-Run Notice

On first use, lua-cli prints a one-time notice:
This notice is shown once and never again.

CI/CD Environments

In CI/CD pipelines, disable telemetry via environment variable β€” no config file needed:
Or use the --ci flag which automatically adjusts CLI behavior for non-interactive environments.

lua models

Manage the LLM model for your agent. The current model is resolved server-first (authoritative) with a fallback to your local compiled artifact.

Actions

You can also set the model at agent creation time: lua init --model openai/gpt-4o.

lua governance

Manage governance policies for your agent project. Governance wraps tool calls, preprocessors, and postprocessors with runtime enforcement using the governance SDK.
After adding governance, lua sync detects drift on governance configuration the same way it does for other primitives.

lua update

Updates lua-cli to the latest published version using the same package manager you installed it with (npm, pnpm, or yarn).
No options β€” this is a one-shot command. Pair it with lua status to see whether an update is available before running.

lua channels-phone

Phone-specific helper for the lua channels family. Used during phone-channel setup and diagnosis. Run lua channels-phone --help for the current subcommand set.
For the general channel management command, see lua channels.

lua chat-log-probe

Inspect raw chat log records for a session. Useful when debugging an issue reported with a specific thread ID or user β€” it shows the underlying log entries the platform recorded, in execution order.
Pair this with lua logs --type user_message and --type agent_response for the high-level view; use chat-log-probe when you need the raw underlying records.

Quick Comparison

Integration with Workflow

During Development

During Deployment

When Troubleshooting

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