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

# Integrations Command

> Connect third-party integrations and set up event-driven triggers for your agent via Unified.to

## Overview

The `lua integrations` command enables you to connect your agent to third-party services like Linear, Discord, Google Calendar, HubSpot, and 250+ other integrations via [Unified.to](https://unified.to). When you connect an integration:

* An **MCP server** is automatically created to expose tools to your agent
* **Triggers** can be set up to wake up your agent when events occur in the connected service

```bash theme={null}
lua integrations              # Interactive mode
lua integrations connect      # Connect a new integration
lua integrations list         # List connected integrations
lua integrations available    # View available integrations
lua integrations info <type>  # View integration details (scopes, triggers)
lua integrations disconnect   # Disconnect an integration
lua integrations update       # Update connection scopes
lua integrations webhooks     # Manage triggers (webhook subscriptions)
lua integrations mcp          # Manage MCP servers for connections

# Triggers shortcut (alias for lua integrations webhooks)
lua triggers                  # Interactive trigger management
lua triggers list             # List all triggers
lua triggers create           # Create a new trigger
lua triggers pause            # Pause a trigger or all triggers for a connection
lua triggers resume           # Resume a trigger or all triggers for a connection
lua triggers delete           # Delete a trigger
```

<Note>
  **Limit**: Only 1 connection per integration type is allowed per agent. To change scopes, use `lua integrations update`.
</Note>

## How It Works

1. **Connect**: Authenticate with a third-party service via OAuth or API token
2. **Auto-MCP**: An MCP server is automatically created and activated for the connection
3. **Agent Access**: Your agent can now use tools from that integration (e.g., create Linear issues, send Discord messages)
4. **Triggers** (optional): Set up event-driven triggers to wake up your agent when things happen (e.g., a task is created, a message is received). Triggers are opt-in — you can skip them at connect and add them later.

## Commands

### lua integrations connect

Connect a new third-party integration with optional triggers.

```bash theme={null}
# Interactive mode (recommended for first-time setup)
lua integrations connect

# Non-interactive: connect Linear with OAuth and all scopes
lua integrations connect --integration linear --auth-method oauth --scopes all

# Connect with triggers enabled (agent wakes up on events)
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

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

# Specify specific scopes
lua integrations connect --integration linear --auth-method oauth --scopes "task_task_read,task_task_write"

# Use API token authentication
lua integrations connect --integration linear --auth-method token

# Control sensitive data visibility
lua integrations connect --integration discord --auth-method oauth --scopes all --hide-sensitive false
```

**What happens:**

1. CLI fetches available integrations
2. You select or specify an integration and auth method
3. Browser opens for OAuth authorization (or you enter API credentials)
4. Connection is established and stored
5. MCP server is automatically created and activated
6. In interactive mode, you're asked whether to configure triggers now (opt-in, default: skip). If triggers are specified via `--triggers`, they are created immediately.

<Note>
  **Triggers are opt-in**: The interactive flow asks "Do you want to configure triggers now?" and defaults to skip — add only what you actually need. You can always add triggers later with `lua triggers create`. When using `--triggers` non-interactively, triggers are created immediately.
</Note>

### lua integrations list

View all connected integrations and their status.

```bash theme={null}
lua integrations list
```

**Output:**

```
============================================================
🔗 Connected Integrations
============================================================

🟢 Linear
   ID: 6978e0294d9c2007ed5cb129
   Status: Active
   MCP Server: linear (✅ active)
   Connected: 1/27/2026

🟡 Discord
   ID: 6979e707ea702a223666bfd2
   Status: Connected (tools pending)
   MCP Server: discord (⏸️ inactive)
   Connected: 1/28/2026

============================================================
Total: 2 connection(s)
```

**Status Icons:**

* 🟢 Active - Connection healthy, tools available
* 🟡 Connected (tools pending) - Connection healthy, MCP server inactive
* 🔴 Unhealthy - Re-authorization required
* ⏸️ Paused - Connection paused

### lua integrations info

View detailed information about an integration type, including available OAuth scopes and triggers. This is useful for discovering what's available **before** connecting.

```bash theme={null}
# View integration details
lua integrations info linear

# Output as JSON (for scripting/AI agents)
lua integrations info linear --json
```

**Output:**

```
============================================================
📋 Integration Info: Linear
============================================================

🔑 OAuth Scopes:
   ✓ task_task_read
     Manage and view issues in Linear
   ✓ task_task_write
     Create and update issues in Linear
   ✓ task_project_read
     View projects in Linear
   ...

⚡ Available Triggers:
   • task_task.created [virtual, 60min interval]
     A new issue was created in Linear
   • task_task.updated [virtual, 60min interval]
     An issue was updated in Linear
   • task_task.deleted [virtual, 60min interval]
     An issue was deleted in Linear
   • task_comment.created [virtual, 60min interval]
     A new comment was added to an issue
   ...

============================================================
```

<Note>
  **Friendly Labels**: Scopes and triggers display user-friendly descriptions (e.g., "A new issue was created in Linear" instead of "task\_task.created") to help non-technical users understand what each option does.
</Note>

### lua integrations available

List all available integrations you can connect.

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

Shows integrations grouped by category (task, messaging, crm, etc.) with auth type indicators:

* 🔐 OAuth only
* 🔑 API Token only
* 🔐🔑 Both available

### lua integrations update

Update an existing connection's OAuth scopes. This re-authorizes the connection with new permissions.

```bash theme={null}
# Interactive mode
lua integrations update

# Non-interactive: update Linear with all scopes
lua integrations update --integration linear --scopes all

# Specific scopes
lua integrations update --integration linear --scopes "task_task_read,task_task_write,task_project_read"
```

<Note>
  Update deletes the old connection and creates a new one with updated scopes. You'll need to re-authorize in the browser.
</Note>

### lua integrations disconnect

Remove a connected account. This also deletes the associated MCP server and any webhook subscriptions.

```bash theme={null}
# Interactive mode
lua integrations disconnect

# Non-interactive
lua integrations disconnect --connection-id 6978e0294d9c2007ed5cb129
```

### lua integrations webhooks

Manage triggers (webhook subscriptions) for connected integrations. Triggers let your agent receive events when things happen in connected services (e.g., task created, message received).

<Tabs>
  <Tab title="list">
    List all triggers:

    ```bash theme={null}
    lua integrations webhooks list

    # Output as JSON for scripting
    lua integrations webhooks list --json
    ```

    **Output:**

    ```
    ────────────────────────────────────────────────────────────────────────────────
    ⚡ Triggers / Webhook Subscriptions
    ────────────────────────────────────────────────────────────────────────────────

    📦 linear
       ✅ task_task.created (poll, agent trigger)
          ID: 698304fa49d44978357b6435
       ⏸️  task_task.updated (paused by you) (poll, agent trigger)
          ID: 698304fb49d44978357b6436
       💳 task_comment.created (credit-suspended) (poll, agent trigger)
          ID: 698304fc49d44978357b6437

    ────────────────────────────────────────────────────────────────────────────────
    Total: 3 trigger(s)
    ```

    **Status Icons:**

    * ✅ Active — trigger is running
    * ⏸️ Paused by you — you paused this trigger; resume with `lua triggers resume`
    * 💳 Credit-suspended — paused due to credit depletion; add credits to re-enable
    * 🔴 Unhealthy — requires re-authorization
    * ⚪ Paused externally — paused from outside Lua (e.g., Unified.to dashboard)

    **JSON Output:**

    ```json theme={null}
    {
      "triggers": [
        {
          "id": "698304fa49d44978357b6435",
          "integrationType": "linear",
          "objectType": "task_task",
          "event": "created",
          "webhookType": "virtual",
          "hookUrl": "https://api.heylua.ai/webhook/unifiedto/data",
          "status": "active",
          "userPaused": false,
          "creditSuspended": false,
          "interval": 60,
          "connectionId": "698304f949d44978357b6425"
        }
      ],
      "total": 1
    }
    ```

    <Note>
      Webhook IDs are displayed for each trigger, making it easy to reference them for pause/resume/delete operations.
    </Note>
  </Tab>

  <Tab title="events">
    List available trigger events for an integration:

    ```bash theme={null}
    # By integration type (before connecting)
    lua integrations webhooks events --integration linear

    # By connection ID (after connecting)
    lua integrations webhooks events --connection abc123

    # As JSON for scripting
    lua integrations webhooks events --integration linear --json
    ```

    **Output:**

    ```
    ⚡ Available Trigger Events for linear
    ────────────────────────────────────────────────────────────────────────────────
      • task_task.created [virtual]
        A new issue was created in Linear
      • task_task.updated [virtual]
        An issue was updated in Linear
      • task_task.deleted [virtual]
        An issue was deleted in Linear
      • task_comment.created [virtual]
        A new comment was added to an issue
    ────────────────────────────────────────────────────────────────────────────────
    ```
  </Tab>

  <Tab title="create">
    Create a new trigger:

    ```bash theme={null}
    # Interactive mode
    lua integrations webhooks create

    # Non-interactive: Agent trigger mode (default - wakes up your agent)
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created

    # Custom webhook URL (your own endpoint)
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event created \
      --hook-url https://my-server.com/webhook

    # With custom polling interval for virtual webhooks
    lua integrations webhooks create \
      --connection abc123 \
      --object task_task \
      --event updated \
      --interval 120
    ```

    **Trigger Modes:**

    * **Agent Trigger** (default): Events wake up your agent with the payload in `runtimeContext`
    * **Custom URL**: Events are sent to your specified webhook URL

    **Webhook Types:**

    * **Native**: Real-time webhooks from the integration (when supported)
    * **Virtual**: Polling-based webhooks (Unified.to polls the API at intervals)

    **Interval options** (for virtual webhooks):

    * `60` - 1 hour (default)
    * `120` - 2 hours
    * `240` - 4 hours
    * `480` - 8 hours
    * `720` - 12 hours
    * `1440` - 24 hours
    * `2880` - 48 hours
  </Tab>

  <Tab title="delete">
    Delete a trigger:

    ```bash theme={null}
    lua integrations webhooks delete --webhook-id wh_abc123
    ```
  </Tab>

  <Tab title="pause">
    Pause a single trigger or all triggers for a connection. The connection and MCP server remain active — only event delivery is paused.

    ```bash theme={null}
    # Pause a single trigger (interactive: choose from list)
    lua integrations webhooks pause

    # Pause a specific trigger by ID
    lua integrations webhooks pause --webhook-id wh_abc123

    # Pause a specific trigger with a reason
    lua integrations webhooks pause --webhook-id wh_abc123 --reason "Maintenance window"

    # Pause ALL triggers for a connection
    lua integrations webhooks pause --connection-id 6978e0294d9c2007ed5cb129
    ```

    <Note>
      Pausing a trigger is different from deleting it. The subscription is preserved and can be resumed at any time. Credit-suspended triggers cannot be paused/resumed by users — add credits to re-enable them.
    </Note>
  </Tab>

  <Tab title="resume">
    Resume a paused trigger or all paused triggers for a connection.

    ```bash theme={null}
    # Resume a single trigger (interactive: choose from paused list)
    lua integrations webhooks resume

    # Resume a specific trigger by ID
    lua integrations webhooks resume --webhook-id wh_abc123

    # Resume ALL paused triggers for a connection
    lua integrations webhooks resume --connection-id 6978e0294d9c2007ed5cb129
    ```

    <Note>
      Credit-suspended triggers are skipped during resume — they require credits to be added to your account first.
    </Note>
  </Tab>
</Tabs>

### lua integrations mcp

Manage MCP servers for connections. MCP servers are automatically created when you connect an integration, but you can activate/deactivate them manually.

<Tabs>
  <Tab title="list">
    List connections with MCP server status:

    ```bash theme={null}
    lua integrations mcp list
    ```

    **Output:**

    ```
    ────────────────────────────────────────────────────────────────────────────────
    🔌 MCP Servers for Connections
    ────────────────────────────────────────────────────────────────────────────────

      Connection: 6978e0294d9c2007ed5cb129
      Integration: Linear
      MCP Server: linear
      Status: ✅ active
    ────────────────────────────────────────────────────────────────────────────────
    ```
  </Tab>

  <Tab title="activate">
    Activate MCP server for a connection:

    ```bash theme={null}
    lua integrations mcp activate --connection 6978e0294d9c2007ed5cb129
    ```

    Once activated, your agent can use tools from this integration.
  </Tab>

  <Tab title="deactivate">
    Deactivate MCP server for a connection:

    ```bash theme={null}
    lua integrations mcp deactivate --connection 6978e0294d9c2007ed5cb129
    ```

    The connection remains but tools are hidden from the agent.
  </Tab>
</Tabs>

## Non-Interactive Mode

All integrations commands support non-interactive mode for CI/CD, automation, and AI coding assistants.

### Discovery Commands

Use these to discover available options before connecting:

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

| Option                    | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| `--integration <type>`    | Integration type (e.g., `linear`, `discord`, `googlecalendar`)                  |
| `--auth-method <method>`  | Authentication method: `oauth` or `token`                                       |
| `--scopes <scopes>`       | Comma-separated OAuth scopes, or `all` for all available                        |
| `--hide-sensitive <bool>` | Hide sensitive data from MCP tools (default: `true`)                            |
| `--triggers <events>`     | Comma-separated triggers (e.g., `task_task.created,task_task.updated`) or `all` |
| `--custom-webhook`        | Use custom webhook URL instead of agent trigger                                 |
| `--hook-url <url>`        | Custom webhook URL (use with `--custom-webhook`)                                |

### Info Options

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

### Disconnect Options

| Option                 | Description                 |
| ---------------------- | --------------------------- |
| `--connection-id <id>` | Connection ID to disconnect |

### Trigger/Webhook Options

| Option                 | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `--connection <id>`    | Connection ID for the trigger                     |
| `--connection-id <id>` | Connection ID for pause/resume all triggers       |
| `--integration <type>` | Integration type (for events discovery)           |
| `--object <type>`      | Object type (e.g., `task_task`, `calendar_event`) |
| `--event <type>`       | Event type: `created`, `updated`, or `deleted`    |
| `--hook-url <url>`     | Custom webhook URL (default: agent trigger)       |
| `--interval <minutes>` | Polling interval for virtual webhooks             |
| `--webhook-id <id>`    | Trigger ID (for delete/pause/resume actions)      |
| `--reason <text>`      | Optional reason for pausing (informational)       |
| `--json`               | Output as JSON (for list/events commands)         |

### MCP Options

| Option              | Description                      |
| ------------------- | -------------------------------- |
| `--connection <id>` | Connection ID for MCP operations |

### Examples

```bash theme={null}
# Discover available integrations and their details
lua integrations available
lua integrations info linear --json

# Connect (interactive — triggers are opt-in, default: skip)
lua integrations connect --integration linear --auth-method oauth --scopes all

# Connect with specific triggers in one command (non-interactive)
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created,task_task.updated

# Add a trigger after connection (via alias)
lua triggers create \
  --connection 6978e0294d9c2007ed5cb129 \
  --object task_task \
  --event deleted

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

# Pause / resume a specific trigger
lua triggers pause --webhook-id 698304fa49d44978357b6435
lua triggers resume --webhook-id 698304fa49d44978357b6435

# Pause / resume ALL triggers for a connection
lua triggers pause --connection-id 6978e0294d9c2007ed5cb129
lua triggers resume --connection-id 6978e0294d9c2007ed5cb129

# List triggers with status icons
lua triggers list
lua triggers list --json

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

## Workflow Example

<Steps>
  <Step title="Discover Available Integrations">
    ```bash theme={null}
    # See what integrations are available
    lua integrations available

    # Get details about a specific integration
    lua integrations info linear
    ```

    View available integrations, their OAuth scopes, and trigger events.
  </Step>

  <Step title="Connect the Integration">
    ```bash theme={null}
    # Interactive — you'll be asked whether to add triggers now (opt-in, default: skip)
    lua integrations connect --integration linear --auth-method oauth --scopes all

    # Or specify triggers directly (non-interactive)
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created,task_task.updated
    ```

    Complete OAuth in the browser. MCP server is auto-created and activated. Add triggers now or skip and add them later with `lua triggers create`.
  </Step>

  <Step title="Verify Connection">
    ```bash theme={null}
    lua integrations list
    ```

    Confirm the connection shows as Active (🟢) and triggers are configured.
  </Step>

  <Step title="Test with Agent">
    ```bash theme={null}
    lua chat -e sandbox -m "Create a Linear issue titled 'Test from Lua'"
    ```

    Your agent should now have access to Linear tools.
  </Step>

  <Step title="Manage Triggers">
    ```bash theme={null}
    # List all triggers (with status icons)
    lua triggers list

    # Add more triggers post-connect
    lua triggers create --connection <id> --object task_task --event deleted

    # Pause a trigger temporarily
    lua triggers pause --webhook-id <id>

    # Resume it later
    lua triggers resume --webhook-id <id>
    ```

    When events occur in Linear, your agent will be notified automatically. Pause/resume any time without losing the subscription.
  </Step>
</Steps>

## Event-Driven Triggers

Triggers are a powerful way to make your agent **reactive** to external events. Instead of polling or manually checking for updates, your agent automatically wakes up when something happens.

### How Triggers Work

1. **You connect an integration** with triggers enabled
2. **Unified.to monitors** the connected service for events
3. **When an event occurs** (e.g., a task is created), Unified.to sends a webhook
4. **Your agent wakes up** with the event data in `runtimeContext`
5. **The agent can respond** based on what happened

### Example: React to New Linear Issues

```bash theme={null}
# Connect Linear with trigger for new issues
lua integrations connect --integration linear --auth-method oauth --scopes all \
  --triggers task_task.created
```

When a new issue is created in Linear, your agent receives the event data and can:

* Send a notification to Slack
* Update a dashboard
* Assign the issue to a team member
* Any other action your agent is configured to perform

### Trigger Types

| Type        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| **Native**  | Real-time webhooks (when the integration supports them)        |
| **Virtual** | Polling-based (Unified.to checks at intervals, default 1 hour) |

Most integrations use virtual webhooks. The polling interval can be configured:

```bash theme={null}
# Set a 2-hour polling interval
lua integrations webhooks create --connection abc123 --object task_task --event created --interval 120
```

## Authentication Types

### OAuth 2.0 (Recommended)

* Secure authorization flow via browser
* Scope selection for fine-grained permissions
* Automatic token refresh
* Requires OAuth to be configured for the integration in your Unified.to workspace

### API Token / Personal Access Token

* Direct credential entry
* Simpler setup
* Token fields vary by integration (e.g., API Key, Personal Access Token, Bot Token)
* Instructions shown during connection for where to obtain credentials

## Tips

<AccordionGroup>
  <Accordion title="Use Triggers for Event-Driven Workflows">
    Triggers make your agent reactive to external events. They are opt-in — add only what you actually need:

    ```bash theme={null}
    # Add triggers after connecting (recommended: start with what you need)
    lua triggers create --connection abc123 --object task_task --event created

    # Or specify triggers at connect time (non-interactive)
    lua integrations connect --integration linear --auth-method oauth --scopes all \
      --triggers task_task.created,task_task.updated

    # Pause a trigger temporarily (preserves subscription)
    lua triggers pause --webhook-id <id>
    lua triggers resume --webhook-id <id>
    ```

    Your agent automatically wakes up when events occur — no polling required!
  </Accordion>

  <Accordion title="Discover Before Connecting">
    Use discovery commands to understand what's available:

    ```bash theme={null}
    # See all integrations
    lua integrations available

    # Get detailed info about an integration
    lua integrations info linear

    # See available trigger events
    lua integrations webhooks events --integration linear
    ```

    This is especially useful for AI coding assistants building agents programmatically.
  </Accordion>

  <Accordion title="Hide Sensitive Data">
    By default, `--hide-sensitive true` is enabled, which hides sensitive fields from MCP tool responses. Disable only if your agent needs access to sensitive data:

    ```bash theme={null}
    lua integrations connect --integration discord --auth-method oauth --scopes all --hide-sensitive false
    ```
  </Accordion>

  <Accordion title="Scope Selection">
    When using OAuth, select only the scopes your agent needs. Use `all` during development, then restrict to specific scopes in production:

    ```bash theme={null}
    # Development
    lua integrations connect --integration linear --auth-method oauth --scopes all

    # Production
    lua integrations connect --integration linear --auth-method oauth --scopes "task_task_read,task_task_write"
    ```
  </Accordion>

  <Accordion title="One Connection Per Integration">
    Each agent can have only one connection per integration type. To change accounts or scopes, use `lua integrations update` or disconnect and reconnect.
  </Accordion>

  <Accordion title="JSON Output for Scripting">
    Use `--json` for machine-readable output:

    ```bash theme={null}
    lua integrations info linear --json
    lua integrations webhooks events --integration linear --json
    ```

    Perfect for CI/CD pipelines and AI coding assistants.
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={2}>
  <Card title="MCP Command" icon="plug" href="/cli/mcp-command">
    Manage all MCP servers (including non-integration servers)
  </Card>

  <Card title="Chat Command" icon="comments" href="/cli/chat-command">
    Test your agent with integration tools
  </Card>
</CardGroup>

## See Also

* [MCP Servers Overview](/overview/mcp-servers) - Understanding MCP servers
* [Webhooks Overview](/overview/webhooks) - Creating webhook handlers
* [LuaWebhook API](/api/luawebhook) - Webhook API reference