> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# connectors initiate

> Set up a single connector and start its OAuth flow

`connectors initiate` sets up or re-scopes one connector directly on an app through the API and starts its [authorization flow](#authorization-flow), without touching any local files or an app's [sandbox](/developers/app-code/local-development/bring-your-own-agent). It only needs a [target app](/developers/references/cli/commands/introduction#select-a-target-app), which you can set with `--app-id`, the `BASE44_APP_ID` environment variable, or a linked project.

Use it when you don't maintain connector definitions as local files in a project, for example on an app you built in the app editor, or from a script or AI agent that only knows the app's ID. Use [`connectors push`](/developers/references/cli/commands/connectors-push) instead when you do maintain connector definitions as local files, the same way you would for entities or functions.

`connectors initiate` also never removes a connector, where `push` runs a full sync that deletes any connector missing from your local files. The connector it creates persists on the app itself, not just for your current terminal session, until you re-scope or remove it.

<Warning>
  The scopes you pass replace the connector's existing scopes instead of merging with them, so pass the full set you want each time. Any scope you leave out is dropped, and you are asked to authorize the connector again. See [connector permissions and scopes](/Integrations/Connectors#connector-permissions) for the scopes each service supports.
</Warning>

If the connector is already authorized with the requested scopes, the command reports this and exits. If a different user already authorized it, the command fails with a `different_user` error naming their email address.

## Usage

```bash theme={null}
base44 connectors initiate
```

## Flags

| Flag                        | Description                                                                                                                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--integration-type <type>` | Required. The integration type to set up, for example `googlecalendar`, `gmail`, or `slack`. See [supported services](/developers/backend/resources/connectors#supported-services) for the full list of type identifiers. |
| `--scopes <scopes...>`      | OAuth scopes to request, separated by spaces or commas. See [connector permissions and scopes](/Integrations/Connectors#connector-permissions) for the scopes each service supports. Defaults to no scopes.               |
| `--json`                    | Output the result as JSON, including the authorization URL. See [JSON output](/developers/references/cli/commands/introduction#json-output).                                                                              |

## Authorization flow

Authorizing a connector means signing in to the third-party service at a URL the command provides, and granting the requested scopes. This step needs a human, since the CLI can't complete it on your behalf.

The command always prints this URL, but what happens next depends on how you run it:

* **Interactive terminal:** The command asks whether to open the URL in your browser. After you authorize, it waits up to two minutes and reports the result. Press `Esc` to stop waiting and finish authorizing later.
* **Non-interactive terminal, or with `--json`:** The command exits without opening a browser or waiting. Open the URL yourself to complete authorization.

Running [`connectors pull`](/developers/references/cli/commands/connectors-pull) afterwards is optional, since `connectors initiate` never touches any files itself and the connector stays authorized on the app either way. Pull it only if you also maintain a local project for this app and use [`connectors push`](/developers/references/cli/commands/connectors-push), because `push` deletes any connector missing from your local files.

## Example

Set up a Google Calendar connector on a specific app, without a local project:

```bash theme={null}
base44 connectors initiate --app-id app_123 --integration-type googlecalendar --scopes https://www.googleapis.com/auth/calendar
```

```
Authorize googlecalendar here: https://auth.base44.io/oauth/...

✓ googlecalendar authorized. Run 'base44 connectors pull' to fetch its config.
```

Request several scopes, separated by commas, for a connector that is already authorized with different scopes:

```bash theme={null}
base44 connectors initiate --integration-type gmail --scopes https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.send
```

## See also

* [`connectors list-available`](/developers/references/cli/commands/connectors-list-available): List the integration types you can set up
* [`connectors pull`](/developers/references/cli/commands/connectors-pull): Pull connector configurations from Base44 to local files
* [`connectors push`](/developers/references/cli/commands/connectors-push): Push all local connector configurations to Base44
* [Using Connectors](/Integrations/Connectors): Guide to using connectors in your app