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

# lua integrations

> Unified.to integrations for an agent or for you: connect, update, list, info, disconnect, convert, integration webhooks and their MCP servers

`lua integrations` connects a third-party service to the agent through Unified.to. A connected [integration](/concepts/integrations) provisions an [MCP server](/concepts/mcp-servers) of tools the model can call at once, and can subscribe the agent to the service's events as integration webhooks.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua integrations [action] [subaction] [options]
lua integrations connect --scope <agent|user> --integration <type> [--auth-method <oauth|token>] [--scopes <csv|all>] [--account-label <label>] [--hide-sensitive <true|false>] [--triggers <csv>] [--custom-webhook --hook-url <url>]
lua integrations update --connection-id <id> [--scopes <csv|all>] [--scope user]
lua integrations list [--scope <agent|user|all>]
lua integrations available
lua integrations info <type> [--json]
lua integrations disconnect --connection-id <id> [--scope user]
lua integrations convert --connection-id <id> [--force]
lua integrations webhooks <list|events|create|delete|pause|resume> [options]
lua integrations mcp <list|activate|deactivate> [--connection <id>]
```

## Description

A connection belongs either to the agent (`--scope agent`, the default and the narrower grant: the credential lives on the agent and dies with it) or to you (`--scope user`: every private agent you own can use it, including ones you create later, and publishing an agent removes its access). Integration webhooks, `--account-label` and `--hide-sensitive` exist at agent scope only; `connect` refuses them with `--scope user` before anything else runs, and `update --scope user` ignores them. `convert` turns an agent connection into a personal one; there is no way back. At agent scope `connect` offers only types the agent doesn't have yet (`Integration "<type>" not found or already connected.`), so a second account of one type is added as a personal connection with `--scope user`.

`connect` and `update` always finish in the browser: the CLI opens the authorization URL (printing it when it cannot) and waits up to 5 minutes for the callback. `connect` prompts for every flag it needs when omitted, including `--scope`, so a `--ci` run must pass `--scope`, `--integration`, `--auth-method` (when the type supports both), `--scopes` (OAuth types with configurable scopes) and `--account-label`. `update` never asks for the scope: it acts on the agent unless you pass `--scope user`, and keeps the existing account label. Any other prompt under `--ci` fails with `✖ error: Interactive prompt required but --ci flag is set. Provide all required flags or arguments.` (exit 1); the one exception is the trigger step of `connect`, whose prompts and validation are reported as `ℹ️  Note: Could not fetch available triggers` and skipped.

`--hide-sensitive` hides PII fields from the MCP tools. Its default is `false`: fields are exposed unless you pass `--hide-sensitive true`, and non-interactive runs never ask. (The built-in `--help` text says the default is `true`; the command behaves as described here.) `--json` is honored by `info`, `webhooks list` and `webhooks events`; `list` prints text only.

<Note>
  Some failures print a `❌` line and still exit 0: an authorization that fails or times out, a failed `disconnect` or `convert`, an unknown id on `disconnect`, `convert`, `webhooks delete`, `pause` or `resume`, and `mcp activate` or `deactivate` without `--connection` or with an unknown one. Read the output, not only `$?`.
</Note>

## Arguments

| Argument    | Values                                                                                                      | Description                                                                                                                                                                                                                                                                    |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action`    | `connect`, `update`, `list`, `available`, `info`, `disconnect`, `convert`, `webhooks`, `mcp`                | Aliases: `add`, `link` → `connect`; `edit`, `modify` → `update`; `ls`, `l` → `list`; `show`, `view`, `status` → `info`; `remove`, `rm`, `delete`, `unlink` → `disconnect`; `claim` → `convert`; `triggers`, `hook`, `hooks` → `webhooks`; `mcps` → `mcp`. Omit it for the menu |
| `subaction` | `info <type>`; `webhooks <list\|events\|create\|delete\|pause\|resume>`; `mcp <list\|activate\|deactivate>` | Webhook aliases: `ls`, `l` → `list`; `new`, `add` → `create`; `rm`, `remove`, `del` → `delete`; `stop`, `off` → `pause`; `on`, `start` → `resume`; `list-events` → `events`. A bare `webhooks` or `mcp` opens its menu                                                         |

### Actions

| Action                                 | Description                                                                                                                                                                                                     |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connect`                              | Connect a type the agent does not have yet (agent scope), or a personal connection. Prints `🎉 Connection Established!` with the connection id, MCP server name and state, permissions and integration webhooks |
| `update`                               | Re-authorize one connection in place with new scopes; its id, MCP server and integration webhooks are kept. A type without configurable scopes cannot be updated: disconnect and connect again                  |
| `list`                                 | Connections with id, status, MCP server and state, connected date; `--scope user` prints your personal connections and how many agents each is available on                                                     |
| `available`                            | Every connectable type by category, marked `🔐` (OAuth), `🔑` (token) or both                                                                                                                                   |
| `info <type>`                          | Type, categories, auth support, OAuth scopes, token fields, available trigger events                                                                                                                            |
| `disconnect`                           | Delete a connection with its MCP server and integration webhooks. `--scope user` removes it from every agent and asks whether to forget what it added to memory                                                 |
| `convert`                              | Make an agent connection yours; the agent keeps access, every private agent you own gains it                                                                                                                    |
| `webhooks list`                        | Every integration webhook with id, `<object>.<event>`, type (`poll` or `push`), destination and state                                                                                                           |
| `webhooks events`                      | The events a type or connection offers, with their filters                                                                                                                                                      |
| `webhooks create`                      | Subscribe a connection to one event                                                                                                                                                                             |
| `webhooks delete` / `pause` / `resume` | By `--webhook-id`, or `pause` / `resume` every webhook of a connection by `--connection-id`                                                                                                                     |
| `mcp list`                             | Each connection's MCP server and whether it is active                                                                                                                                                           |
| `mcp activate` / `deactivate`          | Show or hide the connection's tools to the model; the connection stays                                                                                                                                          |

## Options

### `connect`

| Option                                 | Description                                                                                                                                                                                                           | Default                               |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `--scope <agent\|user>`                | Who owns the connection. Prompted when omitted                                                                                                                                                                        | Prompt, pre-selecting `agent`         |
| `--integration <type>`                 | The type as `available` prints it (`linear`, `googlecalendar`)                                                                                                                                                        | Prompt                                |
| `--auth-method <oauth\|token>`         | Validated against what the type supports; prompted when it supports both                                                                                                                                              | The only method the type supports     |
| `--scopes <csv\|all>`                  | OAuth scopes by their unified name; an unknown scope is a usage error listing the valid ones                                                                                                                          | Prompt; empty selection means all     |
| `--account-label <label>`              | Distinguishes several accounts of one type. Agent scope only                                                                                                                                                          | Prompt, defaulting to the type's name |
| `--hide-sensitive <true\|false>`       | Hide PII fields from the MCP tools. Agent scope only                                                                                                                                                                  | `false`                               |
| `--triggers <csv>`                     | Integration webhooks to create, each `<object>.<event>` from `info`. An unknown name is reported as `Could not fetch available triggers`, the names before it are kept, and the connection proceeds. Agent scope only | None                                  |
| `--custom-webhook`, `--hook-url <url>` | Send the `--triggers` events to your URL instead of waking the agent; the URL is prompted when `--custom-webhook` comes alone                                                                                         | Wake the agent                        |

### `update`, `convert`, `disconnect`, `list`, `info`

| Option                           | Description                                                                                                                                                        | Default |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `--connection-id <id>`           | The exact connection. Required for `disconnect` and `convert`; `update` accepts `--integration <type>` instead when the agent has exactly one account of that type | —       |
| `--scopes <csv\|all>`            | `update`: the new scopes                                                                                                                                           | Prompt  |
| `--hide-sensitive <true\|false>` | `update`: as for `connect`                                                                                                                                         | `false` |
| `--scope <agent\|user\|all>`     | `list`: which connections; `update`, `disconnect`: act on a personal connection                                                                                    | `agent` |
| `--force`                        | `convert`: skip the confirmation                                                                                                                                   | Prompt  |
| `--json`                         | `info`: the full record as JSON                                                                                                                                    | Text    |

### `webhooks`

| Option                                                   | Description                                                                                                                     | Default |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `--integration <type>`                                   | `events`: by type, before connecting                                                                                            | —       |
| `--connection <id>`                                      | `events`: by connection; `create`: the connection to subscribe. Required for a non-interactive `create`                         | Prompt  |
| `--object <type>`, `--event <created\|updated\|deleted>` | `create`: the event; an unsupported pair is a usage error listing the available ones                                            | Prompt  |
| `--hook-url <url>`                                       | `create`: destination. Without it the CLI asks; the agent-trigger destination is `https://api.heylua.ai/webhook/unifiedto/data` | Prompt  |
| `--interval <minutes>`                                   | `create`: polling interval of a `virtual` event; the menu offers 1, 5, 10, 15, 30, 60, 120, 240, 480, 720, 1440 and 2880        | Prompt  |
| `--webhook-id <id>`                                      | `delete`, `pause`, `resume`: one webhook                                                                                        | —       |
| `--connection-id <id>`                                   | `pause`, `resume`: every webhook of the connection                                                                              | —       |
| `--reason <text>`                                        | `pause --webhook-id`: recorded with the pause                                                                                   | —       |
| `--json`                                                 | `list`, `events`: JSON (`{ triggers, total }` or `{ source, events, defaults }`)                                                | Text    |

### `mcp`

| Option              | Description                              | Default  |
| ------------------- | ---------------------------------------- | -------- |
| `--connection <id>` | `activate`, `deactivate`: the connection | Required |

## Examples

Discover a type, then connect it to the agent with every scope and two integration webhooks.

```bash theme={null}
lua integrations info linear --json --ci
lua integrations connect --scope agent --integration linear --auth-method oauth --scopes all \
  --account-label "Linear (ops)" --triggers task_task.created,task_task.updated --ci
```

Connect as yourself so every private agent you own can use it.

```bash theme={null}
lua integrations connect --scope user --integration github --auth-method oauth --scopes all --ci
```

List the agent's connections.

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

```text Output theme={null}
============================================================
🔗 Connected Integrations
============================================================

🟢 GitHub
   Connection: 6aa54baa…
   Status: Active
   MCP Server: github (active)
   Connected: 12/09/2026

🟢 Linear
   Connection: 6aa3c41e…
   Status: Active
   MCP Server: linear (active)
   Connected: 11/09/2026

…
============================================================
Total: 3 integration(s)
```

Subscribe an existing connection to an event, polling hourly, and later pause every webhook on it.

```bash theme={null}
lua integrations webhooks create --connection 6aa3c41e… --object task_comment --event created \
  --hook-url https://api.heylua.ai/webhook/unifiedto/data --interval 60 --ci
lua integrations webhooks pause --connection-id 6aa3c41e… --ci
```

Re-authorize one account with new scopes, then remove it.

```bash theme={null}
lua integrations update --connection-id 6aa3c41e… --scopes task_task_read,task_task_write --ci
lua integrations disconnect --connection-id 6aa3c41e… --ci
```

## Exit codes

| Code | Meaning                                                                                                                                                  |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Success, and the `❌` cases named in the note                                                                                                             |
| `1`  | A refused flag combination (`Agent-scoped options cannot be used with --scope user`), `update --connection-id` with an unknown id, a prompt under `--ci` |
| `2`  | Usage: unknown action or webhook sub-action, missing `--connection-id`, invalid `--scope` (`connect` only), `--auth-method` or `--scopes`                |
| `3`  | Not found: an unknown type for `info`, `webhooks create --connection` with an unknown id, `update --integration` with no such connection                 |
| `9`  | Not signed in (401)                                                                                                                                      |
| `10` | Forbidden (403 or another 4xx)                                                                                                                           |
| `11` | Unavailable: 5xx, connection refused, timeout                                                                                                            |
| `12` | The model provider refused the request (424)                                                                                                             |

## See also

* [Connect an integration](/integrations/connect) — the how-to, scope by scope
* [Integration events](/integrations/events) — what an integration webhook delivers to the agent
* [Integration MCP servers](/integrations/mcp) — the tools a connection provisions
* [`Integrations`](/reference/sdk/integrations) — `Integrations.passthrough` from code
* [`lua triggers`](/reference/cli/triggers) — the agent's own paste-anywhere triggers, a different command