Overview
Utility commands provide quick access to the Lua Admin interface, documentation, shell autocomplete setup, and telemetry settings.lua status
lua agents
lua completion
lua admin
lua evals
lua docs
lua telemetry
lua models
lua governance
lua update
lua status / lua describe
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.)
- API key source (env var / credentials file / .env)
- Authenticated email, user ID, and organization list
- Server reachability status
- Config path (
lua.skill.yaml) - Agent name and ID
- Compiled manifest β how many primitives were found in the last compile
- Local version (from YAML)
- Server version (active)
- Sync status:
synced,ahead,behind,not deployed, orserver only
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:
schemaVersion: 1) so consumers can detect breaking changes. All human-readable progress output is suppressed in JSON mode.
lua 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 ID
- Agent name
- Environment (production/staging/sandbox)
- Status (active/inactive)
Example Output
- Interactive
- JSON Output
Options
Use Cases
Discover Available Agents
Discover Available Agents
lua init or scripts:Team Management
Team Management
Automation & Scripting
Automation & Scripting
Environment Discovery
Environment Discovery
CI/CD Integration
CI/CD Integration
Multi-Agent Workflows
Multi-Agent Workflows
JSON Parsing Examples
Extract specific information:Requirements
- Must be authenticated (
lua auth configure) - API key must have valid permissions
Troubleshooting
No organizations found
No organizations found
- Verify authentication:
lua auth key --force - Ensure API key has permissions
- Check if youβre a member of any organizations
Missing expected agents
Missing expected agents
- 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)
JSON parsing errors
JSON parsing errors
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.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
Completion Features
Main Commands
Main Commands
Subcommands
Subcommands
Environment Options
Environment Options
Help Flags
Help Flags
Verification
After installation, verify autocomplete is working:- Test Basic Completion
- Test Subcommands
- Test Environment
Troubleshooting
Completions not working
Completions not working
-
Restart your terminal or reload shell config:
-
Verify script was added correctly:
-
Try explicit installation:
Completions incomplete
Completions incomplete
-
Regenerate completion script:
-
Check Lua CLI version:
Fish completions not loading
Fish completions not loading
-
Verify file location:
-
Regenerate if missing:
- Restart Fish shell
Conflict with existing completions
Conflict with existing completions
Benefits
Faster Workflow
Discover Commands
Fewer Typos
Better UX
Advanced Usage
Multiple Shells
Multiple Shells
Team Setup
Team Setup
Docker/Remote
Docker/Remote
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
- π₯ Add users to your agent
- βοΈ Edit user permissions
- ποΈ Remove users
- π View user activity
- π User analytics
- π Generate new API keys
- ποΈ View existing keys
- ποΈ Revoke keys
- π Copy keys for development
- π Manage key permissions
- π± WhatsApp integration
- πΈ Instagram messaging
- βοΈ Email integration
- π Facebook Messenger
- π¬ Slack integration
- π SMS/Twilio
- π Website chat widget
- π Custom integrations
- π³ 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.agentIdandagent.orgId
Use Cases
Monitor Conversations
Monitor Conversations
- View live conversations
- See how users interact with your agent
- Identify areas for improvement
- Take over conversations if needed
Manage Team Access
Manage Team Access
- Add team members
- Set permissions (admin, developer, viewer)
- Manage API keys per user
- Control who can deploy
Connect Channels
Connect Channels
- Connect WhatsApp Business
- Set up Instagram messaging
- Configure email integration
- Add Slack workspace
- Enable Facebook Messenger
Review Analytics
Review Analytics
- View conversation metrics
- Check response times
- Monitor user satisfaction
- Track tool usage
- Analyze peak times
Manage Billing
Manage Billing
- Review usage this month
- Check billing history
- Update payment method
- Upgrade subscription
- Download invoices
Troubleshooting
Dashboard doesn't open
Dashboard doesn't open
- Run
lua auth configureto authenticate - Ensure
lua.skill.yamlexists (lua init) - Verify agent ID is in config
Wrong agent displayed
Wrong agent displayed
- Verify youβre in correct project directory
- Check
agentIdinlua.skill.yaml - Switch to correct agent directory
Permission denied
Permission denied
- Verify you have admin access
- Check with organization owner
- 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
Test Agent Responses
Test Agent Responses
- Run predefined test scenarios
- Validate agent behavior
- Check response quality
- Ensure consistency
Track Performance
Track Performance
- Monitor evaluation scores
- Compare across versions
- Identify regressions
- Measure improvements
Quality Assurance
Quality Assurance
- Run evaluations before deployment
- Validate production readiness
- Document test results
- Share with team
Troubleshooting
Dashboard doesn't open
Dashboard doesn't open
- Run
lua auth configureto authenticate - Ensure
lua.skill.yamlexists (lua init) - Verify agent ID is in config
Wrong agent displayed
Wrong agent displayed
- Verify youβre in correct project directory
- Check
agentIdinlua.skill.yaml - 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 anywhereUse Cases
Quick Reference
Quick Reference
API Lookup
API Lookup
Find Examples
Find Examples
Keyboard Shortcut
Add to your shell profile for even faster access:lua telemetry
What Is Collected
lua-cli collects usage data to improve the developer experience:Opting Out
You can opt out at any time using either method:- CLI command
- Environment variable
~/.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:CI/CD Environments
In CI/CD pipelines, disable telemetry via environment variable β no config file needed:--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
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.lua sync detects drift on governance configuration the same way it does for other primitives.
lua update
Updateslua-cli to the latest published version using the same package manager you installed it with (npm, pnpm, or yarn).
lua status to see whether an update is available before running.
lua channels-phone
Phone-specific helper for thelua channels family. Used during phone-channel setup and diagnosis. Run lua channels-phone --help for the current subcommand set.
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.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.

