Skip to main content
After this guide, your agent has a connection to one of the products in lua integrations available, an active MCP server of that product’s tools, and you know how to re-authorize, disconnect, or convert it. For Shopify, WooCommerce, Square, or SimplyBook.me with a synced catalog and baskets, use the catalog app instead. Verified against lua-cli 3.33.0. Before you begin
  • A project created with lua init and signed in with lua auth configure (see Install).
  • An account on the provider that may authorize apps; for token types, the values lua integrations info <type> lists under Token Fields.
  • A browser on the machine running the CLI: authorization ends on a local callback.
1

Find the integration type

List every connectable type by category; 🔐 marks OAuth, 🔑 a token, and the value in parentheses is what --integration takes.
Output
lua integrations info <type> --ci shows one type’s auth methods, scope names, token fields, and events; add --json to script it.
2

Connect

Pass every choice as a flag: under --ci any prompt the CLI still needs fails the run, and it asks who owns the connection unless you pass --scope; the one prompt --ci skips is whether to add integration webhooks, which you can do later.
The CLI prints the authorization URL, opens it, and waits up to 5 minutes for the callback. Approve on the provider’s page; the summary then prints the connection ID, the MCP server’s name and state, and the permissions granted. Omitted flags are prompted: --auth-method when the type supports both methods, --scopes when the type has configurable scopes (an empty selection means all), and --account-label, which defaults to the type’s name.
3

Connect with a token (Shopify, WooCommerce)

Token types take their keys on the Unified.to authorization page, never in the terminal; info lists what to have ready.
Output
Shopify asks for an Admin API access token and the Store ID; connect with --auth-method token and paste the values in the browser.
4

Verify

List the agent’s connections; Active with MCP Server: <type> (active) means the model has the tools on its next turn. list has no --json, so a script reads the ID from the Connection: line; Status is Active, Connected (MCP pending), Paused, Unhealthy - run "lua integrations update" to re-authorize, or Inactive.
Output
Then ask the agent something only the integration can answer, for example lua chat -m "List my open Linear issues".
The admin dashboard (lua admin) connects integrations through the same Unified.to page; the connection then appears in lua integrations list.

​
Options you may need

​
Connect as yourself

--scope user makes a personal connection: no agent owns it, every private agent you own (including ones you create later) can use it, and publishing an agent removes its access. --triggers, --hook-url, --custom-webhook, --account-label, and --hide-sensitive are agent-only and are refused before anything runs (Agent-scoped options cannot be used with --scope user). lua integrations list --scope user shows your personal connections and how many agents each is mounted on. lua integrations convert --connection-id <id> --force turns an agent connection you created into a personal one; the agent keeps access, and there is no way back.

​
Re-authorize in place

lua integrations update --connection-id <id> --scopes <csv|all> --ci opens the browser again and rotates the credential into the same connection: the ID, MCP server, and integration webhooks are kept, and a failed or timed-out authorization leaves the connection unchanged but prints ❌ Authorization failed: <reason> and exits 0, so a script checks for that line, not the exit code. update --integration <type> works while the agent has one account of that type; with several it stops with Multiple <type> accounts are connected; rerun with --connection-id to choose the exact account. A type without configurable scopes can’t be updated: disconnect and connect again. --hide-sensitive true, on connect or update, hides PII fields from the tools; the default is false and non-interactive runs never ask.

​
Disconnect

lua integrations disconnect --connection-id <id> --ci deletes the connection with its MCP server and integration webhooks. With --scope user it removes the personal connection from every agent and always asks whether to also forget what it added to memory, so it can’t run headless.

​
If it isn’t working

The provider page wasn’t completed within 5 minutes, or the browser ran on another machine, so the callback never reached the CLI. Run connect again on the machine whose browser you use; if the browser didn’t open, paste the printed URL.
At agent scope, connect offers only types this agent doesn’t have yet. Re-authorize the existing connection with lua integrations update --connection-id <id>, disconnect it first, or add a second account of the type as a personal connection with --scope user.
The connection exists but its tools are off. Run lua integrations mcp activate --connection <id>; see Manage integration MCP tools.

​
Next steps

Subscribe to integration events

Wake the agent or your webhook when something changes.

Manage integration MCP tools

What the model sees, and how to switch it off.

Call an integration's API directly

Integrations.passthrough for endpoints the tools don’t cover.

lua integrations reference

Every action, flag, and exit code.