> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Utility Commands

> Quick access commands for admin interface and documentation

## Overview

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

<CardGroup cols={3}>
  <Card title="lua status" icon="circle-check">
    Full agent state at a glance
  </Card>

  <Card title="lua agents" icon="users">
    List organizations and agents
  </Card>

  <Card title="lua completion" icon="terminal">
    Generate shell autocomplete
  </Card>

  <Card title="lua admin" icon="gauge">
    Open admin dashboard
  </Card>

  <Card title="lua evals" icon="chart-bar">
    Open evaluations dashboard
  </Card>

  <Card title="lua docs" icon="book">
    Open documentation
  </Card>

  <Card title="lua telemetry" icon="chart-mixed">
    Manage usage telemetry
  </Card>

  <Card title="lua models" icon="brain">
    List and select the LLM your agent uses
  </Card>

  <Card title="lua governance" icon="shield-check">
    Manage governance policies for your agent
  </Card>

  <Card title="lua update" icon="arrow-rotate-right">
    Update lua-cli to the latest version
  </Card>
</CardGroup>

## lua status / lua describe

<Note>
  Inspect the full state of your agent project in a single command.
</Note>

`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.

```bash theme={null}
lua status           # human-readable table
lua describe         # identical output via alias
lua status --json    # machine-readable JSON for scripting
```

### 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:

```bash theme={null}
lua status --json | jq '.auth.email'
lua status --json | jq '.primitives[] | select(.kind == "skill") | .diffs'
```

The schema is versioned (`schemaVersion: 1`) so consumers can detect breaking changes. All human-readable progress output is suppressed in JSON mode.

## lua agents

<Note>
  List all organizations and agents you have access to for discovery and scripting.
</Note>

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

```bash theme={null}
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

<Tabs>
  <Tab title="Interactive">
    ```bash theme={null}
    $ 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
    ```
  </Tab>

  <Tab title="JSON Output">
    ```bash theme={null}
    $ lua agents --json
    ```

    ```json theme={null}
    {
      "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"
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### Options

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

### Use Cases

<AccordionGroup>
  <Accordion title="Discover Available Agents">
    **Find agent IDs for `lua init` or scripts:**

    ```bash theme={null}
    $ lua agents
    # Copy agent ID for initialization

    $ lua init --agent-id agent_xyz789
    ```

    Quickly find the correct agent ID without going to admin dashboard.
  </Accordion>

  <Accordion title="Team Management">
    **See what agents team members have access to:**

    ```bash theme={null}
    $ lua agents
    # Review all accessible agents
    # Verify permissions are correct
    # Check which agents are active
    ```

    Audit team access and agent organization.
  </Accordion>

  <Accordion title="Automation & Scripting">
    **Parse JSON to automate agent operations:**

    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="Environment Discovery">
    **Identify staging/sandbox agents for testing:**

    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="CI/CD Integration">
    **Validate agent access in pipelines:**

    ```bash theme={null}
    #!/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.
  </Accordion>

  <Accordion title="Multi-Agent Workflows">
    **Deploy to multiple agents programmatically:**

    ```bash theme={null}
    # 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.
  </Accordion>
</AccordionGroup>

### JSON Parsing Examples

**Extract specific information:**

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="No organizations found">
    **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"

    ```bash theme={null}
    # Re-authenticate
    $ lua auth configure
    # Ask organization owner to add you
    ```
  </Accordion>

  <Accordion title="Missing expected agents">
    **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:**

    ```bash theme={null}
    # Refresh by re-running
    $ lua agents
    ```
  </Accordion>

  <Accordion title="JSON parsing errors">
    **Ensure jq is installed:**

    ```bash theme={null}
    # macOS
    brew install jq

    # Ubuntu/Debian
    apt-get install jq

    # Test
    echo '{"test": true}' | jq '.'
    ```
  </Accordion>
</AccordionGroup>

### Integration with Other Commands

```bash theme={null}
# 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:

```bash theme={null}
# 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 user@email.com --force
```

## lua completion

Generate shell autocomplete scripts for faster command-line workflows.

```bash theme={null}
lua completion [shell]       # Generate completion script
lua completion bash          # Generate for Bash
lua completion zsh           # Generate for Zsh
lua completion fish          # Generate for Fish
```

<Note>
  Enable tab completion for all Lua CLI commands and arguments!
</Note>

### 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

<Tabs>
  <Tab title="Bash">
    **Installation**

    ```bash theme={null}
    # 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**

    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Zsh">
    **Installation**

    ```bash theme={null}
    # 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**

    ```bash theme={null}
    lua <TAB>             # Shows all commands
    lua skills <TAB>      # Shows: sandbox, staging, production
    lua auth <TAB>        # Shows: configure, logout, key
    ```
  </Tab>

  <Tab title="Fish">
    **Installation**

    ```bash theme={null}
    # 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**

    ```bash theme={null}
    lua <TAB>             # Shows all commands with descriptions
    lua push <TAB>        # Shows: skill, persona
    lua env <TAB>         # Shows: sandbox, staging, production
    ```
  </Tab>
</Tabs>

### Completion Features

<AccordionGroup>
  <Accordion title="Main Commands">
    Tab completion for all Lua CLI commands:

    ```bash theme={null}
    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
    ```
  </Accordion>

  <Accordion title="Subcommands">
    Context-aware subcommand completion:

    ```bash theme={null}
    lua auth <TAB>         # configure, logout, key
    lua push <TAB>         # skill, persona
    lua chat <TAB>         # clear
    lua completion <TAB>   # bash, zsh, fish
    ```
  </Accordion>

  <Accordion title="Environment Options">
    Environment selection for applicable commands:

    ```bash theme={null}
    lua env <TAB>          # sandbox, staging, production
    lua persona <TAB>      # sandbox, staging, production
    lua skills <TAB>       # sandbox, staging, production
    ```
  </Accordion>

  <Accordion title="Help Flags">
    Common flags available for all commands:

    ```bash theme={null}
    lua --<TAB>            # --help, --version
    lua push --<TAB>       # --help
    ```
  </Accordion>
</AccordionGroup>

### Verification

After installation, verify autocomplete is working:

<Tabs>
  <Tab title="Test Basic Completion">
    ```bash theme={null}
    # Type this and press TAB
    lua pu

    # Should complete to:
    lua push
    ```
  </Tab>

  <Tab title="Test Subcommands">
    ```bash theme={null}
    # Type this and press TAB
    lua push 

    # Should show options:
    skill  persona
    ```
  </Tab>

  <Tab title="Test Environment">
    ```bash theme={null}
    # Type this and press TAB
    lua env 

    # Should show:
    sandbox  staging  production
    ```
  </Tab>
</Tabs>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Completions not working">
    **Problem**: Tab completion doesn't work after installation

    **Solutions:**

    1. Restart your terminal or reload shell config:
       ```bash theme={null}
       # Bash
       source ~/.bashrc

       # Zsh
       source ~/.zshrc

       # Fish (automatic)
       ```

    2. Verify script was added correctly:
       ```bash theme={null}
       # Check if completion is in config
       tail ~/.bashrc    # or ~/.zshrc
       ```

    3. Try explicit installation:
       ```bash theme={null}
       eval "$(lua completion bash)"  # Or zsh
       ```
  </Accordion>

  <Accordion title="Completions incomplete">
    **Problem**: Some commands complete, others don't

    **Solutions:**

    1. Regenerate completion script:
       ```bash theme={null}
       lua completion bash > /tmp/lua_completions
       cat /tmp/lua_completions >> ~/.bashrc
       source ~/.bashrc
       ```

    2. Check Lua CLI version:
       ```bash theme={null}
       lua --version
       # Should be v2.6.0 or higher
       ```
  </Accordion>

  <Accordion title="Fish completions not loading">
    **Problem**: Completions don't work in Fish shell

    **Solutions:**

    1. Verify file location:
       ```bash theme={null}
       ls ~/.config/fish/completions/lua.fish
       ```

    2. Regenerate if missing:
       ```bash theme={null}
       mkdir -p ~/.config/fish/completions
       lua completion fish > ~/.config/fish/completions/lua.fish
       ```

    3. Restart Fish shell
  </Accordion>

  <Accordion title="Conflict with existing completions">
    **Problem**: Completions conflict with other tools

    **Solution:**
    Remove old completion and reinstall:

    ```bash theme={null}
    # 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]
    ```
  </Accordion>
</AccordionGroup>

### Benefits

<CardGroup cols={2}>
  <Card title="Faster Workflow" icon="bolt">
    Type less, complete more with tab
  </Card>

  <Card title="Discover Commands" icon="compass">
    See available options without docs
  </Card>

  <Card title="Fewer Typos" icon="check">
    Autocomplete prevents mistakes
  </Card>

  <Card title="Better UX" icon="heart">
    Professional CLI experience
  </Card>
</CardGroup>

### Advanced Usage

<AccordionGroup>
  <Accordion title="Multiple Shells">
    If you use multiple shells, install for each:

    ```bash theme={null}
    # Bash
    lua completion bash >> ~/.bashrc

    # Zsh
    lua completion zsh >> ~/.zshrc

    # Fish
    lua completion fish > ~/.config/fish/completions/lua.fish
    ```
  </Accordion>

  <Accordion title="Team Setup">
    Add to team onboarding:

    ```bash theme={null}
    # In your team's setup script
    echo "Setting up Lua CLI autocomplete..."
    lua completion bash >> ~/.bashrc
    source ~/.bashrc
    echo "✅ Autocomplete enabled"
    ```
  </Accordion>

  <Accordion title="Docker/Remote">
    Include in Docker images:

    ```dockerfile theme={null}
    # In Dockerfile
    RUN lua completion bash >> /root/.bashrc
    ```
  </Accordion>
</AccordionGroup>

## lua admin

Launch the Lua Admin interface in your default browser.

```bash theme={null}
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

```bash theme={null}
$ 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

<AccordionGroup>
  <Accordion title="Monitor Conversations">
    ```bash theme={null}
    $ lua admin
    ```

    * View live conversations
    * See how users interact with your agent
    * Identify areas for improvement
    * Take over conversations if needed
  </Accordion>

  <Accordion title="Manage Team Access">
    ```bash theme={null}
    $ lua admin
    ```

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

  <Accordion title="Connect Channels">
    ```bash theme={null}
    $ lua admin
    ```

    * Connect WhatsApp Business
    * Set up Instagram messaging
    * Configure email integration
    * Add Slack workspace
    * Enable Facebook Messenger
  </Accordion>

  <Accordion title="Review Analytics">
    ```bash theme={null}
    $ lua admin
    ```

    * View conversation metrics
    * Check response times
    * Monitor user satisfaction
    * Track tool usage
    * Analyze peak times
  </Accordion>

  <Accordion title="Manage Billing">
    ```bash theme={null}
    $ lua admin
    ```

    * Review usage this month
    * Check billing history
    * Update payment method
    * Upgrade subscription
    * Download invoices
  </Accordion>
</AccordionGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Dashboard doesn't open">
    **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"

    ```bash theme={null}
    $ lua auth configure
    ```
  </Accordion>

  <Accordion title="Wrong agent displayed">
    **Check:**

    1. Verify you're in correct project directory
    2. Check `agentId` in `lua.skill.yaml`
    3. Switch to correct agent directory
  </Accordion>

  <Accordion title="Permission denied">
    **Check:**

    1. Verify you have admin access
    2. Check with organization owner
    3. Request proper permissions
  </Accordion>
</AccordionGroup>

## lua evals

Launch the Lua Evaluations Dashboard in your default browser.

```bash theme={null}
lua evals
```

### What It Opens

The Lua Evaluations Dashboard at [https://evals.heylua.ai](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

```bash theme={null}
$ 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

<AccordionGroup>
  <Accordion title="Test Agent Responses">
    ```bash theme={null}
    $ lua evals
    ```

    * Run predefined test scenarios
    * Validate agent behavior
    * Check response quality
    * Ensure consistency
  </Accordion>

  <Accordion title="Track Performance">
    ```bash theme={null}
    $ lua evals
    ```

    * Monitor evaluation scores
    * Compare across versions
    * Identify regressions
    * Measure improvements
  </Accordion>

  <Accordion title="Quality Assurance">
    ```bash theme={null}
    $ lua evals
    ```

    * Run evaluations before deployment
    * Validate production readiness
    * Document test results
    * Share with team
  </Accordion>
</AccordionGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Dashboard doesn't open">
    **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"

    ```bash theme={null}
    $ lua auth configure
    ```
  </Accordion>

  <Accordion title="Wrong agent displayed">
    **Check:**

    1. Verify you're in correct project directory
    2. Check `agentId` in `lua.skill.yaml`
    3. Switch to correct agent directory
  </Accordion>
</AccordionGroup>

## lua docs

Launch this documentation in your default browser.

```bash theme={null}
lua docs
```

### What It Opens

Opens the complete Lua documentation at [https://docs.heylua.ai](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

```bash theme={null}
$ lua docs
✓ Lua Documentation opened in your browser

  Documentation: https://docs.heylua.ai
```

### Requirements

None - works from anywhere

### Use Cases

<AccordionGroup>
  <Accordion title="Quick Reference">
    ```bash theme={null}
    # Forgot a command syntax?
    $ lua docs
    # Navigate to CLI Commands
    ```
  </Accordion>

  <Accordion title="API Lookup">
    ```bash theme={null}
    # Need API method signature?
    $ lua docs
    # Go to API Reference
    ```
  </Accordion>

  <Accordion title="Find Examples">
    ```bash theme={null}
    # Need an example for your use case?
    $ lua docs
    # Check Demos section
    ```
  </Accordion>

  <Accordion title="Share with Team">
    ```bash theme={null}
    # Onboarding new developer?
    $ lua docs
    # Share the URL
    ```
  </Accordion>
</AccordionGroup>

### Keyboard Shortcut

Add to your shell profile for even faster access:

```bash theme={null}
# Add to ~/.zshrc or ~/.bashrc
alias ld='lua docs'

# Usage
$ ld
# Opens documentation instantly
```

## lua telemetry

<Note>
  Manage whether lua-cli sends usage data.
</Note>

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

```bash theme={null}
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](https://heylua.ai/privacy).

### Opting Out

You can opt out at any time using either method:

<Tabs>
  <Tab title="CLI command">
    ```bash theme={null}
    lua telemetry off
    ```

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

  <Tab title="Environment variable">
    ```bash theme={null}
    # 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.
  </Tab>
</Tabs>

### Check Current Status

```bash theme={null}
$ 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:

```bash theme={null}
# In your CI environment variables
LUA_TELEMETRY=false
```

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.

```bash theme={null}
lua models                              # List all approved models, highlight the one in use
lua models list                         # Same as above
lua models list --json                  # Machine-readable JSON output
lua models set                          # Interactive picker (searchable, provider-grouped)
lua models set --model openai/gpt-4o    # Non-interactive
lua models unset                        # Remove model — revert to platform default
```

| Option           | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `--model <code>` | Model code for the `set` action (e.g. `openai/gpt-4o`). |
| `--json`         | Output `list` as JSON for scripting.                    |

### Actions

| Action           | What it does                                                                                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `list` (default) | Print all approved models grouped by provider. Highlights the currently configured model.                                                      |
| `set`            | Select a model interactively, or pass `--model` for non-interactive. Writes the model into your local `src/index.ts` and pushes to the server. |
| `unset`          | Remove the model from source and clear it on the server. Your agent reverts to the platform default.                                           |

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

## lua governance

Manage governance policies for your agent project. Governance wraps tool calls, preprocessors, and postprocessors with runtime enforcement using the governance SDK.

```bash theme={null}
lua governance              # Interactive governance setup
lua governance add          # Add governance (SDK or API mode)
lua governance remove       # Remove governance from agent (local + server)
```

| Action    | What it does                                                                      |
| --------- | --------------------------------------------------------------------------------- |
| (default) | Interactive setup — prompts for SDK or API mode and required configuration.       |
| `add`     | Add governance to the agent in either SDK mode (in-process) or API mode (remote). |
| `remove`  | Strip governance enforcement from both local source and the server.               |

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).

```bash theme={null}
lua update
```

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.

```bash theme={null}
lua channels-phone --help
```

For the general channel management command, see [`lua channels`](/cli/channels-command).

## 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.

```bash theme={null}
lua chat-log-probe --help
```

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

| 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

```bash theme={null}
# Need API reference?
$ lua docs
# Check API section

# Continue coding
```

### During Deployment

```bash theme={null}
# Deploy skills
$ lua push
$ lua deploy

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

### When Troubleshooting

```bash theme={null}
# Issue with command
$ lua docs
# Search troubleshooting section

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

## Next Steps

<CardGroup cols={2}>
  <Card title="All CLI Commands" icon="terminal" href="/cli/overview">
    Complete command reference
  </Card>

  <Card title="Admin Features" icon="gauge" href="https://admin.heylua.ai">
    Explore the admin dashboard
  </Card>

  <Card title="Getting Started" icon="rocket" href="/getting-started/quick-start">
    New to Lua? Start here
  </Card>

  <Card title="Demos" icon="layer-group" href="/demos/overview">
    11 production-ready solutions
  </Card>
</CardGroup>
