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 without --connection or with an unknown one. Read the output, not only $?.

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.

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

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)

SDK

CLI

REST API

lua integrations

Synopsis

Description

Arguments

Actions

Options

`connect`

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

`webhooks`

`mcp`

Examples

Exit codes

See also

​Synopsis

​Description

​Arguments

​Actions

​Options

​connect

​update, convert, disconnect, list, info

​webhooks

​mcp

​Examples

​Exit codes

​See also

Synopsis

Description

Arguments

Actions

Options

`connect`

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

`webhooks`

`mcp`

Examples

Exit codes

See also