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

# Connect a Unified.to integration

> Connect a SaaS product to your agent with lua integrations connect, choose its scopes, and verify the tools it provisions

After this guide, your agent has a connection to one of the products in `lua integrations available`, an active [MCP server](/concepts/mcp-servers) 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](/integrations/overview) 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](/get-started/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.

<Steps>
  <Step title="Find the integration type">
    List every connectable type by category; `🔐` marks OAuth, `🔑` a token, and the value in parentheses is what `--integration` takes.

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

    ```text Output theme={null}
    ============================================================
    🔌 Available Integrations
    ============================================================

    …
    📁 COMMERCE
       🔐🔑 BigCommerce (bigcommerce)
       🔑 Akeneo (akeneo)
       🔐🔑 Salsify (salsify)
       🔐🔑 Shopify (shopify)
    …
    ============================================================
    Total: 256 integration(s) available
    🔐 = OAuth  🔑 = API Key/Token  🔐🔑 = Both
    ```

    `lua integrations info <type> --ci` shows one type's auth methods, scope names, token fields, and events; add `--json` to script it.
  </Step>

  <Step title="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.

    ```bash theme={null}
    lua integrations connect --scope agent --integration linear --auth-method oauth --scopes all \
      --account-label "Linear (ops)" --ci
    ```

    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    lua integrations info woocommerce --ci
    ```

    ```text Output theme={null}
    ============================================================
    📋 Integration: WooCommerce
    ============================================================

      Type: woocommerce
      Categories: commerce, accounting, metadata
      Auth Support: token
      OAuth Configured: No

      Token Fields:
        - Consumer Key
          💡 Found at WooCommerce > Settings > Advanced > REST API
        - Consumer Secret
        - Store URL
          💡 The domain of your WooCommerce store (e.g. store.com or store.example.com)
    …
    ```

    Shopify asks for an Admin API access token and the Store ID; connect with `--auth-method token` and paste the values in the browser.

    ```bash theme={null}
    lua integrations connect --scope agent --integration woocommerce --auth-method token --ci
    ```
  </Step>

  <Step title="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`.

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

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

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

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

    Then ask the agent something only the integration can answer, for example `lua chat -m "List my open Linear issues"`.
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="Authorization failed: Timeout waiting for OAuth callback">
    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.
  </Accordion>

  <Accordion title="Integration &#x22;linear&#x22; not found or already connected.">
    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`.
  </Accordion>

  <Accordion title="Connection created but MCP server pending activation.">
    The connection exists but its tools are off. Run `lua integrations mcp activate --connection <id>`; see [Manage integration MCP tools](/integrations/mcp).
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Subscribe to integration events" href="/integrations/events">Wake the agent or your webhook when something changes.</Card>
  <Card title="Manage integration MCP tools" href="/integrations/mcp">What the model sees, and how to switch it off.</Card>
  <Card title="Call an integration's API directly" href="/integrations/passthrough">`Integrations.passthrough` for endpoints the tools don't cover.</Card>
  <Card title="lua integrations reference" href="/reference/cli/integrations">Every action, flag, and exit code.</Card>
</Columns>