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

# Non-Interactive Mode

> Automate CLI commands for AI IDEs, CI/CD pipelines, and scripting

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

<Note>
  Every command now has non-interactive options with consistent naming patterns.
</Note>

<Card title="AI Agent Building Guide" icon="robot" href="/ai-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.
</Card>

## Design Patterns

### Consistent Option Naming

All commands follow these patterns:

| Pattern              | Description                | Example                 |
| -------------------- | -------------------------- | ----------------------- |
| `--<entity>-name`    | Select entity by name      | `--skill-name mySkill`  |
| `--<entity>-version` | Specify version            | `--skill-version 1.0.5` |
| `--force`            | Skip confirmation prompts  | `--force`               |
| `--json`             | Output as JSON for parsing | `--json`                |
| `[action]`           | Positional action argument | `lua jobs view`         |

### Action Arguments

Many commands accept an action as the first argument:

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

<Note>
  The global `--ci` flag makes the CLI fail loudly on missing required arguments instead of silently prompting (which fails in non-TTY environments).
</Note>

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:

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

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

<Tabs>
  <Tab title="CI/CD Pipelines">
    **Always use `--ci` in automated environments:**

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

  <Tab title="Local Development">
    **Don't use `--ci` locally:**

    ```bash theme={null}
    # Local - interactive prompts are helpful
    lua push skill
    ? Select a skill: mySkill
    ? Enter version: 1.0.1

    # CI/CD - no prompts, just errors
    lua --ci push skill
    # Error: missing --name flag
    ```

    **Why**: Interactive prompts provide guidance and defaults.
  </Tab>

  <Tab title="Scripts & Automation">
    **Use `--ci` in bash scripts:**

    ```bash theme={null}
    #!/bin/bash
    set -e

    # Fail fast if required args missing
    lua --ci push skill \
      --name "$SKILL_NAME" \
      --set-version "$VERSION" \
      --force
    ```

    **Why**: Scripts should fail fast and clearly, not hang waiting for input.
  </Tab>
</Tabs>

### Behavior Differences

| Scenario              | Without --ci               | With --ci                      |
| --------------------- | -------------------------- | ------------------------------ |
| Missing required flag | Shows prompt (hangs in CI) | Throws error immediately       |
| Non-TTY environment   | Shows warning, continues   | Throws error if prompts needed |
| All flags provided    | Works normally             | Works normally                 |

### Auto-Detection

Even without `--ci`, the CLI automatically detects non-TTY environments and shows a warning:

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

<Tabs>
  <Tab title="init">
    Initialize a new project without prompts:

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

    # Create agent with a specific model
    lua init --agent-name "My Bot" --org-id org456 --model openai/gpt-4o

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

    # With example code
    lua init --agent-id abc123 --with-examples
    ```

    | Option                | Description                                    |
    | --------------------- | ---------------------------------------------- |
    | `--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                          |
    | `--model <model>`     | LLM model for the agent (e.g. `openai/gpt-4o`) |
    | `--force`             | Override existing `lua.skill.yaml`             |
    | `--with-examples`     | Include example code                           |
  </Tab>
</Tabs>

### Development & Testing

<Tabs>
  <Tab title="test">
    Test skills, webhooks, or jobs without prompts:

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

    | Option           | Description            |
    | ---------------- | ---------------------- |
    | `--name <name>`  | Entity name to test    |
    | `--input <json>` | JSON input for testing |
  </Tab>

  <Tab title="sync">
    Detect and resolve drift without prompts:

    ```bash theme={null}
    # Check for drift (exit code 1 if found)
    lua sync --check

    # Auto-accept server state (pull server → local)
    lua sync --accept

    # Push local state to server without prompting
    lua sync --push
    ```

    | Option     | Description                 |
    | ---------- | --------------------------- |
    | `--check`  | Check only, exit 1 if drift |
    | `--accept` | Pull server state to local  |
    | `--push`   | Push local state to server  |
  </Tab>

  <Tab title="chat">
    Send messages without interactive session:

    ```bash theme={null}
    # Send to sandbox
    lua chat -e sandbox -m "Hello, what can you do?"

    # Send to production
    lua chat -e production -m "Help me with my order"

    # Default: sandbox
    lua chat -m "Quick test message"

    # Scoped to an explicit thread
    lua chat -m "Run scenario A" --thread scenario-a

    # Auto-generated thread (UUID printed at start)
    lua chat -m "Isolated test" --thread

    # Isolated test with auto-clear after response
    lua chat -m "Run test" -t my-test --clear

    # Send multiple messages concurrently (load / batch testing)
    lua chat -b "Message 1" "Message 2" "Message 3"

    # Batch with delay between messages (ms)
    lua chat -b "Msg 1" "Msg 2" "Msg 3" -d 500
    ```

    **File attachments** — use `@<path>` inside the message string:

    ```bash theme={null}
    # Attach an image
    lua chat -m "@screenshot.png what's wrong with this UI?" -e sandbox

    # Attach a document
    lua chat -m "@report.pdf summarize this" -e production

    # Multiple attachments
    lua chat -m "compare @before.png and @after.png" -e sandbox
    ```

    | Option                      | Description                                               |
    | --------------------------- | --------------------------------------------------------- |
    | `-e, --env <env>`           | Environment: sandbox or production                        |
    | `-m, --message <text>`      | Message to send (supports `@<path>` file attachments)     |
    | `-t, --thread [id]`         | Scope to a thread (omit ID to auto-generate UUID)         |
    | `--clear`, `--clear-thread` | Clear thread history after response (requires `--thread`) |
    | `-b, --batch <messages...>` | Send multiple messages concurrently                       |
    | `-d, --delay <ms>`          | Delay between batch messages in ms (default: 100)         |
  </Tab>
</Tabs>

### Deployment

<Tabs>
  <Tab title="push">
    Push components without prompts:

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

    | Option                | Description         |
    | --------------------- | ------------------- |
    | `--name <name>`       | Entity name to push |
    | `--set-version <ver>` | Version to set      |
    | `--force`             | Skip confirmations  |
    | `--auto-deploy`       | Deploy after push   |
  </Tab>

  <Tab title="deploy">
    Deploy to production without prompts:

    ```bash theme={null}
    # Deploy specific version
    lua deploy --skill-name mySkill --skill-version 1.0.5 --force

    # Deploy latest version
    lua deploy --skill-name mySkill --skill-version latest --force
    ```

    | Option                  | Description         |
    | ----------------------- | ------------------- |
    | `--skill-name <name>`   | Skill to deploy     |
    | `--skill-version <ver>` | Version or 'latest' |
    | `--force`               | Skip confirmation   |
  </Tab>
</Tabs>

### Entity Management

<Tabs>
  <Tab title="skills">
    Manage skills without prompts:

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

    | Action     | Options Required                  |
    | ---------- | --------------------------------- |
    | `view`     | None                              |
    | `versions` | `--skill-name`                    |
    | `deploy`   | `--skill-name`, `--skill-version` |
  </Tab>

  <Tab title="webhooks">
    Manage webhooks without prompts:

    ```bash theme={null}
    lua webhooks view
    lua webhooks activate --webhook-name myWebhook
    lua webhooks deactivate --webhook-name myWebhook
    lua webhooks versions --webhook-name myWebhook
    lua webhooks deploy --webhook-name myWebhook --webhook-version 1.0.3

    # Event subscriptions
    lua webhooks list-events
    lua webhooks subscribe --webhook-name myWebhook --event message.delivered
    lua webhooks unsubscribe --webhook-name myWebhook --event message.delivered
    ```

    | Action        | Options Required                      |
    | ------------- | ------------------------------------- |
    | `view`        | None                                  |
    | `activate`    | `--webhook-name`                      |
    | `deactivate`  | `--webhook-name`                      |
    | `versions`    | `--webhook-name`                      |
    | `deploy`      | `--webhook-name`, `--webhook-version` |
    | `list-events` | None                                  |
    | `subscribe`   | `--webhook-name`, `--event`           |
    | `unsubscribe` | `--webhook-name`, `--event`           |

    **Available event types (WhatsApp):**

    | Event               | Description                                     |
    | ------------------- | ----------------------------------------------- |
    | `message.sent`      | Message was sent to the recipient               |
    | `message.delivered` | Message was delivered to the recipient's device |
    | `message.read`      | Recipient read the message                      |
    | `message.failed`    | Message failed to send                          |
    | `message.played`    | Recipient played a voice/video message          |
  </Tab>

  <Tab title="jobs">
    Manage scheduled jobs without prompts:

    ```bash theme={null}
    lua jobs view
    lua jobs trigger -i healthCheck
    lua jobs activate -i myJob
    lua jobs deactivate -i myJob
    lua jobs versions -i myJob
    lua jobs deploy -i myJob -v 1.0.3
    lua jobs deploy -i myJob -v latest
    lua jobs history -i myJob
    lua jobs delete -i oldJob
    ```

    | Option                        | Description                       |
    | ----------------------------- | --------------------------------- |
    | `-i, --job-name <name>`       | Job name                          |
    | `-v, --job-version <version>` | Version or 'latest' (deploy only) |

    | Action       | Options Required              |
    | ------------ | ----------------------------- |
    | `view`       | None                          |
    | `trigger`    | `--job-name`                  |
    | `activate`   | `--job-name`                  |
    | `deactivate` | `--job-name`                  |
    | `versions`   | `--job-name`                  |
    | `deploy`     | `--job-name`, `--job-version` |
    | `history`    | `--job-name`                  |
    | `delete`     | `--job-name`                  |
  </Tab>

  <Tab title="preprocessors">
    Manage preprocessors without prompts:

    ```bash theme={null}
    lua preprocessors view
    lua preprocessors activate --preprocessor-name myPre
    lua preprocessors deactivate --preprocessor-name myPre
    lua preprocessors versions --preprocessor-name myPre
    lua preprocessors deploy --preprocessor-name myPre --preprocessor-version 1.0.3
    lua preprocessors delete --preprocessor-name oldPre
    ```
  </Tab>

  <Tab title="postprocessors">
    Manage postprocessors without prompts:

    ```bash theme={null}
    lua postprocessors view
    lua postprocessors activate --postprocessor-name myPost
    lua postprocessors deactivate --postprocessor-name myPost
    lua postprocessors versions --postprocessor-name myPost
    lua postprocessors deploy --postprocessor-name myPost --postprocessor-version 1.0.3
    lua postprocessors delete --postprocessor-name oldPost
    ```
  </Tab>
</Tabs>

### Configuration

<Tabs>
  <Tab title="env">
    Manage environment variables without prompts:

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

    | Option              | Description         |
    | ------------------- | ------------------- |
    | `--list`            | List all variables  |
    | `-k, --key <name>`  | Variable name       |
    | `-v, --value <val>` | Variable value      |
    | `-d, --delete`      | Delete the variable |
  </Tab>

  <Tab title="persona">
    Manage persona without prompts:

    ```bash theme={null}
    # View current persona
    lua persona production view

    # List versions
    lua persona production versions

    # Deploy specific version
    lua persona production deploy --persona-version 5

    # Deploy latest
    lua persona production deploy --persona-version latest --force
    ```

    | Action     | Options                        |
    | ---------- | ------------------------------ |
    | `view`     | None                           |
    | `versions` | None                           |
    | `deploy`   | `--persona-version`, `--force` |
  </Tab>

  <Tab title="features">
    Manage features without prompts:

    ```bash theme={null}
    lua features list
    lua features enable --feature-name rag
    lua features disable --feature-name rag
    lua features view --feature-name webSearch
    ```

    | Action    | Options Required |
    | --------- | ---------------- |
    | `list`    | None             |
    | `enable`  | `--feature-name` |
    | `disable` | `--feature-name` |
    | `view`    | `--feature-name` |
  </Tab>

  <Tab title="resources">
    Manage knowledge base without prompts:

    ```bash theme={null}
    lua resources list
    lua resources view --resource-name "FAQ Document"
    lua resources delete --resource-name "Old Document"
    ```

    | Action   | Options Required  |
    | -------- | ----------------- |
    | `list`   | None              |
    | `view`   | `--resource-name` |
    | `delete` | `--resource-name` |
  </Tab>

  <Tab title="mcp">
    Manage MCP servers without prompts:

    ```bash theme={null}
    lua mcp list
    lua mcp activate --server-name filesystem
    lua mcp deactivate --server-name api-server
    lua mcp delete --server-name old-server

    # Positional style also works
    lua mcp activate filesystem
    ```

    | Action       | Options Required |
    | ------------ | ---------------- |
    | `list`       | None             |
    | `activate`   | `--server-name`  |
    | `deactivate` | `--server-name`  |
    | `delete`     | `--server-name`  |
  </Tab>

  <Tab title="integrations">
    Connect and manage third-party integrations without prompts:

    **Discovery Commands (for AI agents and scripting):**

    ```bash theme={null}
    # View available integrations
    lua integrations available

    # Get integration details (scopes and triggers)
    lua integrations info linear
    lua integrations info linear --json

    # List available trigger events
    lua integrations webhooks events --integration linear
    lua integrations webhooks events --integration linear --json
    ```

    **Connect with Triggers:**

    ```bash theme={null}
    # Connect with triggers enabled (recommended)
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created,task_task.updated

    # Connect with all available triggers
    lua integrations connect --integration linear --auth-method oauth --scopes all --triggers all

    # Connect without triggers
    lua integrations connect --integration linear --auth-method oauth --scopes all

    # Connect with custom webhook URL instead of agent trigger
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created --custom-webhook --hook-url https://my-server.com/webhook

    # List connections
    lua integrations list

    # Update connection scopes
    lua integrations update --integration linear --scopes "task_task_read,task_task_write"

    # Disconnect
    lua integrations disconnect --connection-id 6978e0294d9c2007ed5cb129
    ```

    **Connect Options:**

    | Option                    | Description                              |
    | ------------------------- | ---------------------------------------- |
    | `--integration <type>`    | Integration type (linear, discord, etc.) |
    | `--auth-method <method>`  | `oauth` or `token`                       |
    | `--scopes <scopes>`       | Comma-separated scopes or `all`          |
    | `--hide-sensitive <bool>` | Hide sensitive data (default: true)      |
    | `--triggers <events>`     | Comma-separated triggers or `all`        |
    | `--custom-webhook`        | Use custom URL instead of agent trigger  |
    | `--hook-url <url>`        | Custom webhook URL                       |
    | `--connection-id <id>`    | Connection ID (for disconnect)           |

    **Info Options:**

    | Option   | Description                  |
    | -------- | ---------------------------- |
    | `--json` | Output as JSON for scripting |

    **Trigger Management:**

    ```bash theme={null}
    # List triggers
    lua integrations webhooks list

    # List available trigger events
    lua integrations webhooks events --integration linear --json

    # Create trigger (agent wake-up mode - default)
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created

    # Create trigger with custom webhook URL
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created \
      --hook-url https://my-server.com/webhook

    # Create trigger with custom polling interval
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event updated \
      --interval 120

    # Delete trigger
    lua integrations webhooks delete --webhook-id wh_xyz789
    ```

    **Trigger Options:**

    | Option                 | Description                                           |
    | ---------------------- | ----------------------------------------------------- |
    | `--connection <id>`    | Connection ID                                         |
    | `--integration <type>` | Integration type (for events discovery)               |
    | `--object <type>`      | Object type (task\_task, calendar\_event, etc.)       |
    | `--event <type>`       | Event: created, updated, deleted                      |
    | `--hook-url <url>`     | Custom webhook URL (default: agent trigger)           |
    | `--interval <mins>`    | Polling interval (60, 120, 240, 480, 720, 1440, 2880) |
    | `--webhook-id <id>`    | Trigger ID (for delete)                               |
    | `--json`               | Output as JSON (for events command)                   |

    **MCP Server Management:**

    ```bash theme={null}
    lua integrations mcp list
    lua integrations mcp activate --connection abc123
    lua integrations mcp deactivate --connection abc123
    ```
  </Tab>
</Tabs>

### Viewing & Debugging

<Tabs>
  <Tab title="logs">
    View logs without prompts:

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

    # Inspect logs for another agent you own
    lua logs --agent-id agent-abc123 --type skill --limit 10
    ```

    | Option                 | Description                                                                           |
    | ---------------------- | ------------------------------------------------------------------------------------- |
    | `--type <type>`        | all, skill, job, webhook, preprocessor, postprocessor, user\_message, agent\_response |
    | `--name <name>`        | Entity name (requires --type, not for message types)                                  |
    | `--user-id <userId>`   | Filter logs by user ID                                                                |
    | `--agent-id <agentId>` | Target a specific agent (admin access required)                                       |
    | `--limit <n>`          | Number of logs (default: 20)                                                          |
    | `--page <n>`           | Page number                                                                           |
    | `--json`               | JSON output                                                                           |
  </Tab>

  <Tab title="production">
    View production state without prompts:

    ```bash theme={null}
    lua production overview    # Production summary
    lua production persona     # Current persona
    lua production skills      # Deployed skills
    lua production env         # Environment variables
    ```
  </Tab>

  <Tab title="channels">
    View channels without prompts:

    ```bash theme={null}
    lua channels list    # List all channels
    ```
  </Tab>
</Tabs>

### Authentication & Utilities

<Tabs>
  <Tab title="auth">
    Authentication commands with --force:

    ```bash theme={null}
    # View API key without confirmation
    lua auth key --force

    # Logout without confirmation
    lua auth logout --force
    ```
  </Tab>

  <Tab title="chat clear">
    Clear history without confirmation:

    ```bash theme={null}
    # Clear all history
    lua chat clear --force

    # Clear specific user's history
    lua chat clear --user user@email.com --force
    lua chat clear --user +1234567890 --force

    # Clear a specific thread's history
    lua chat clear --thread my-test-scenario --force
    ```
  </Tab>
</Tabs>

### Marketplace

<Tabs>
  <Tab title="Creator Actions">
    Publish and manage skills:

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

  <Tab title="Installer Actions">
    Browse and install skills:

    ```bash theme={null}
    # Search marketplace
    lua marketplace install search --query "CRM" --limit 10 --json

    # View skill details
    lua marketplace install view --marketplace-id xyz --json

    # Install skill
    lua marketplace install install --marketplace-id xyz --version-id v1 --force

    # With environment variables
    lua marketplace install install --marketplace-id xyz --version-id v1 --env-vars "API_KEY=xxx,SECRET=yyy" --force

    # Update installed skill
    lua marketplace install update --skill-name mySkill --version-id v2

    # Uninstall
    lua marketplace install uninstall --skill-name mySkill --force

    # List installed
    lua marketplace install installed --json
    ```
  </Tab>
</Tabs>

## Example Workflows

### AI IDE Workflow (Cursor, Copilot)

When an AI assistant needs to manage your agent:

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

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

### Post-deploy verification (CI-friendly)

After any production deploy, run a 3-line probe to confirm the new version is healthy. This is the CI version of the canonical [post-deploy debug loop](/cli/debugging):

```bash theme={null}
# Push and auto-deploy in one shot
lua --ci push all --force --auto-deploy

# Send a probe message to production
lua --ci chat -m "verify production" -e production -t prod-verify --clear

# Confirm zero agent errors fired during the probe
lua logs --type agent_error --limit 5 --json | jq '.logs | length'
```

Wire the third line into your pipeline's exit code so a non-zero error count fails the build:

```bash theme={null}
errors=$(lua logs --type agent_error --limit 5 --json | jq '.logs | length')
if [ "$errors" -gt 0 ]; then
  echo "Production has $errors agent errors after deploy — failing build."
  exit 1
fi
```

<Note>
  **Silencing post-action hints in CI.** The CLI prints `✨ Tip:` / `💡 Diagnose:` lines and a quiet `agent_error` probe summary after each command. They're useful interactively but noisy when CI captures only command output. Set `LUA_NO_HINTS=1` to silence all of them:

  ```bash theme={null}
  export LUA_NO_HINTS=1
  lua --ci push all --force --auto-deploy
  lua --ci chat -m "verify production" -e production
  ```
</Note>

### Bash Scripting

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

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

# Subscribe webhook to delivery events
lua webhooks subscribe --webhook-name payment-hook --event message.delivered
lua webhooks subscribe --webhook-name payment-hook --event message.failed

# Verify
lua production overview
```

## Exit Codes

All commands return consistent exit codes:

| Code | Meaning                                    |
| ---- | ------------------------------------------ |
| `0`  | Success                                    |
| `1`  | Error (missing args, not found, API error) |

Use exit codes in scripts:

```bash theme={null}
if lua sync --check; then
  echo "No drift"
else
  echo "Drift detected"
  exit 1
fi
```

## JSON Output

Commands with `--json` output machine-readable JSON:

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

<AccordionGroup>
  <Accordion title="Always use --force in CI/CD">
    In automated pipelines, always use `--force` to skip confirmations:

    ```bash theme={null}
    lua push all --force
    lua deploy --skill-name x --skill-version latest --force
    ```
  </Accordion>

  <Accordion title="Use --check for validation">
    Use `lua sync --check` in CI to fail builds on drift:

    ```bash theme={null}
    lua sync --check || { echo "Drift detected"; exit 1; }
    ```
  </Accordion>

  <Accordion title="Use --json for parsing">
    When processing output programmatically, use `--json`:

    ```bash theme={null}
    lua logs --json | jq '.logs | length'
    ```
  </Accordion>

  <Accordion title="Version with timestamps or git SHAs">
    Use dynamic versions in CI:

    ```bash theme={null}
    lua push skill --name x --set-version $(git rev-parse --short HEAD) --force
    ```
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    All available commands
  </Card>

  <Card title="Skill Management" icon="wrench" href="/cli/skill-management">
    init, test, push, deploy details
  </Card>

  <Card title="Sync Command" icon="rotate" href="/cli/sync-command">
    Drift detection details
  </Card>

  <Card title="Environment Variables" icon="key" href="/cli/env-command">
    Managing configuration
  </Card>
</CardGroup>