lua integrations

lua integrations connects a third-party service to the agent through Unified.to. A connected integration provisions an MCP server 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

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.

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 with an unknown --connection id (a missing --connection exits 2). Read the output, not only $?.

Custom MCP servers

A custom MCP server, added by URL from the Tools page or the admin dashboard, is a connection too. list shows it with the agent’s other connections, labelled (lua-cli 3.46.0 and later) Type: Custom MCP server (managed from Tools) (or personal · managed from Tools when it serves only you), with its host, its state, and how many of its tools are on. The state reads Active, Paused, Can't reach the server - check it on the Tools page, Signed out - sign in again on the Tools page, or Credentials rejected - update them on the Tools page. In lua-cli 3.46.0 and later, update and mcp activate|deactivate refuse a custom server with exit 2 before changing anything, the update menu doesn’t offer it, and mcp list leaves it out. disconnect, pause, and resume act on it like on any connection. Edit it or sign in again from the Tools page.

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. Refuses a custom MCP server
`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. Custom MCP servers show their host, state and tools on instead
`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; custom MCP servers are left out
`mcp activate` / `deactivate`	Show or hide the connection’s tools to the model; the connection stays. Refuses a custom MCP server

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.

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.

lua integrations connect --scope user --integration github --auth-method oauth --scopes all --ci

List the agent’s connections.

lua integrations list --ci

Output

============================================================
🔗 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.

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.

lua integrations update --connection-id 6aa3c41e… --scopes task_task_read,task_task_write --ci
lua integrations disconnect --connection-id 6aa3c41e… --ci

A custom MCP server in the list, and the refusal when you try to update it.

lua integrations list --ci

Output

…
🔴 Acme CRM
   Type: Custom MCP server (managed from Tools)
   Connection: mcp_8a0e1f2a-1b2c-4d3e-8f40-123456789abc
   Host: crm.example.com
   Status: Signed out - sign in again on the Tools page
   Tools: 4 of 6 on
   Connected: 05/10/2026
…

lua integrations update --connection-id mcp_8a0e1f2a-1b2c-4d3e-8f40-123456789abc --ci

Output

✖ usage: Connection mcp_8a0e1f2a-1b2c-4d3e-8f40-123456789abc is a custom MCP server, which 'lua integrations update' doesn't manage
💡 Edit it or sign in again from the Tools page in Lua.

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`; `update` or `mcp activate\|deactivate` on a custom MCP server
`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)

SDK

CLI

REST API

lua integrations

Synopsis

Description

Custom MCP servers

Arguments

Actions

Options

`connect`

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

`webhooks`

`mcp`

Examples

Exit codes

See also

​Synopsis

​Description

​Custom MCP servers

​Arguments

​Actions

​Options

​connect

​update, convert, disconnect, list, info

​webhooks

​mcp

​Examples

​Exit codes

​See also

Synopsis

Description

Custom MCP servers

Arguments

Actions

Options

`connect`

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

`webhooks`

`mcp`

Examples

Exit codes

See also