> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/connections.md).

# connections

Credentials and configuration for external systems. Build connections first — every export and import references one.

**REST API**: [Connections](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections)

```
celigo connections <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand                            | Purpose                                                                                                                                                                                                                                                                                          |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list`                                | List all connections.                                                                                                                                                                                                                                                                            |
| `applications`                        | List the external applications in use across the account, with resource references.                                                                                                                                                                                                              |
| `get <id>`                            | Fetch one connection (secrets are masked as `******`). Explains an empty `http._iClientId` on a connector OAuth connection.                                                                                                                                                                      |
| `create`                              | Create a connection from a JSON body (`--file <path>` or stdin) — connector-first: `--connector` scaffolds from a pre-built HTTP connector, `--tp-connector` links a trading partner connector, and a hand-written `type: http` body is checked against the connector catalog before it is sent. |
| `set <id> key=value …`                | Set whitelisted fields (e.g. `name`, `debugUntil`) via atomic PATCH. Supports `key=file://<path>`.                                                                                                                                                                                               |
| `update <id>`                         | Full-replace PUT from a JSON body (`--file <path>` or stdin). Refuses masked placeholders unless `--force`.                                                                                                                                                                                      |
| `delete <id>`                         | Delete a connection by ID.                                                                                                                                                                                                                                                                       |
| `dependencies <id>` (alias `used-by`) | List resources that depend on this connection.                                                                                                                                                                                                                                                   |
| `audit <id>`                          | Show the audit log (change history) for one connection.                                                                                                                                                                                                                                          |
| `ping <id>`                           | Test connectivity and auth against the remote system.                                                                                                                                                                                                                                            |
| `enable-debug <id>`                   | Turn on connection-level debug logging for a time window.                                                                                                                                                                                                                                        |
| `disable-debug <id>`                  | Turn off connection-level debug logging.                                                                                                                                                                                                                                                         |
| `debug-logs <id>`                     | Fetch captured debug logs for a connection.                                                                                                                                                                                                                                                      |
| `delete-debug-logs <id>`              | Delete the captured debug logs for a connection.                                                                                                                                                                                                                                                 |
| `authorize <id>`                      | Complete the OAuth2 authorization flow in a browser and poll to completion.                                                                                                                                                                                                                      |
| `purge-messages <id>`                 | Purge queued messages for a connection.                                                                                                                                                                                                                                                          |

> **`set` is PATCH-only for connections.** Because `GET /v1/connections/{id}` returns masked credential values (`******`), `set` applies only PATCH-whitelisted fields (e.g. `name`, `debugUntil`) atomically — it never round-trips other fields through GET → modify → PUT, which would overwrite the real credentials. To change non-whitelisted fields, use `update` with a hand-built payload that contains the actual secrets (or `""` to clear them).

***

## `celigo connections list`

List all connections in the current account.

**Signature**

```bash
celigo connections list [--integration <id>]
```

**Arguments**

None.

**Flags**

| Flag                 | Type   | Default | Description                                          |
| -------------------- | ------ | ------- | ---------------------------------------------------- |
| `--integration <id>` | string | —       | List only connections belonging to this integration. |

Default table columns: `_id`, `name`, `type`, `offline`, `lastModified`.

**Example**

```bash
celigo connections list --format table
```

**Corresponds to**: [`GET /v1/connections`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#get-v1-connections)

***

## `celigo connections applications`

List the external applications (NetSuite, Shopify, an HTTP-connector ID, a trading-partner code, etc.) referenced by at least one resource in the account. Each entry carries an application slug (`_id`) and, when present, `refs` pointing to the connections, exports, imports, and connectors that use it.

The list is usage-driven — applications with no referencing resource are omitted.

**Signature**

```bash
celigo connections applications [--application <name>]
```

**Flags**

| Flag                   | Type   | Default | Meaning                                                                                                                                     |
| ---------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `--application <name>` | string | —       | Case-insensitive substring match against application slugs. Filtering happens client-side; the server returns the full response either way. |

**Examples**

```bash
# Find every Slack-related adaptor the account is using
celigo connections applications --application slack

# List all applications in use (no filter)
celigo connections applications --format table
```

**Corresponds to**: [`GET /v1/applications`](https://developer.celigo.com/api/api-reference/account-and-admin/account#get-v1-applications) (operationId: `listAccountApplications`)

***

## `celigo connections get <id>`

Fetch a single connection by ID. Encrypted fields are returned as `******`.

On a connector OAuth connection whose `http._iClientId` is empty, a stderr note says whether the connection authorizes through the connector's Celigo-managed (global) iClient — in which case the empty field is not a misconfiguration — or still needs your own iClient before `connections authorize`. Added in celigo-cli 2026.9.1.

**Signature**

```bash
celigo connections get <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo connections get 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/connections/{_id}`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#get-v1-connections-_id)

***

## `celigo connections create`

Create a connection from a JSON body. Read the body from a file with `-f, --file` (recommended), or pipe it on stdin.

Since celigo-cli 2026.9.1 the command is **connector-first**. A pre-built HTTP connector's definition carries the connection form every connection created from it inherits, and the CLI reads that form instead of leaving a `type: http` body to be hand-written:

* `--connector <id|name>` scaffolds what the connector's own form saves — `type`, `assistant`, `http.formType: assistant`, the connector, API, and version ids, its default `http.auth.type`, every applicable pre-configured field (media type, ping, headers, the Celigo-managed global iClient), and a base URI. Your body is merged over the scaffold (your fields win), and `--name` alone is body enough. The fields the form requires you to set — credentials, `settings.*`, OAuth scopes — are listed on stderr and never invented.
* `--tp-connector <id|name>` links an `as2`, `ftp`, or `s3` connection to a trading partner connector (`_tpConnectorId`), checks the transport type, and lists the fields the connector's form requires. The form's own connection values are template stand-ins (a placeholder partner id, a staging AS2 URI) and are never copied into your connection.
* A hand-written body is checked before it is sent (see the warning below). A hand-written `as2`/`ftp`/`s3`/`van` body whose name refers to a partner that has a trading partner connector gets a stderr note naming the connector — a note, never a refusal, because a name is evidence enough to say so but not to refuse.

Find HTTP connectors with [`http-connectors match <url|name>`](/cli/commands/http-connectors.md#celigo-http-connectors-match) and trading partner connectors with [`trading-partner-connectors list`](/cli/commands/trading-partner-connectors.md#celigo-trading-partner-connectors-list).

> ⚠️ **Two hand-written shapes are refused since celigo-cli 2026.9.1.** The API accepts both silently, and neither connection authorizes the way its connector expects. A raw `type: http` body whose base URI a pre-built connector serves is refused with `Refusing to create a raw HTTP connection to <host>: a pre-built connector serves it.`, naming the connector, its default auth type, and its global iClient — create it with `--connector <id>` instead, or pass `--allow-raw-http` to create the raw connection deliberately. A body that references a connector but sets an `http.auth.type` the connector's form does not offer is refused with `Refusing to create a <connector> connection with http.auth.type '<type>': the connector's form offers <types> …` — scaffold it with `--connector`, or pass `--auth-type <type>` equal to the body's value to confirm the choice. An auth type the form offers but does not preselect passes with a note.

**Signature**

```bash
celigo connections create [-f <path>] [--dry-run]
celigo connections create --connector <id|name> [--api <id|name>] [--version <id|name>] [--auth-type <type>] [--name <name>] [-f <path>] [--dry-run]
celigo connections create --tp-connector <id|name> [--name <name>] [-f <path>] [--dry-run]
celigo connections create --allow-raw-http -f <path>
```

**Arguments**

None.

**Flags**

| Flag                        | Type    | Default                       | Description                                                                                                                                                                                                                                                                                                                                          |
| --------------------------- | ------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --file <path>`         | string  | —                             | Read the JSON body from a file instead of stdin (`--file -` also means stdin). Added in celigo-cli 2026.6.1.                                                                                                                                                                                                                                         |
| `--connector <id\|name>`    | string  | —                             | Scaffold the connection from this pre-built HTTP connector (see `http-connectors match`). Your body's fields win over the scaffold; with `--name`, a body is optional. Mutually exclusive with `--tp-connector`. Added in celigo-cli 2026.9.1.                                                                                                       |
| `--api <id\|name>`          | string  | the connector's default group | API group of a grouped connector (the connection's `http._httpConnectorApiId`). Only with `--connector`. Added in celigo-cli 2026.9.1.                                                                                                                                                                                                               |
| `--version <id\|name>`      | string  | the first published version   | Connector version the connection references. Only with `--connector`. Added in celigo-cli 2026.9.1.                                                                                                                                                                                                                                                  |
| `--auth-type <type>`        | string  | the connector's default       | The auth type to configure with `--connector`, or — on a hand-written body that references a connector — the type to confirm when it departs from what the connector's form offers. A form that makes the user choose and gets no `--auth-type` is an error naming the offered types. Added in celigo-cli 2026.9.1.                                  |
| `--name <name>`             | string  | —                             | Connection name. With `--connector` or `--tp-connector` a body is then optional. Added in celigo-cli 2026.9.1.                                                                                                                                                                                                                                       |
| `--allow-raw-http`          | boolean | `false`                       | Create a raw `type: http` connection even though a pre-built connector serves its base URI. Added in celigo-cli 2026.9.1.                                                                                                                                                                                                                            |
| `--tp-connector <id\|name>` | string  | —                             | Link the connection to this trading partner connector via `_tpConnectorId` (the full connector name, or a base name that has one variant — a base name shared by a partner's AS2 and FTP variants must be given in full). Refuses a transport the connector does not provision. Mutually exclusive with `--connector`. Added in celigo-cli 2026.9.1. |
| `--dry-run`                 | boolean | `false`                       | Run the checks and print the body that would be sent (the scaffold, with `--connector`) without creating anything. Added in celigo-cli 2026.9.1.                                                                                                                                                                                                     |

**Request body**

A JSON object matching the `POST /v1/connections` request schema (one variant per connection type: `http`, `netsuite`, `salesforce`, `ftp`, `rdbms`, `s3`, `as2`, `wrapper`, …). See the [Connections API reference](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections). With `--connector` or `--tp-connector` the body is optional and is merged over the scaffold.

**Example**

```bash
# 1. Find the connector that serves the API, and what its form prescribes
celigo http-connectors match https://api.github.com

# 2. Create the connection from the connector; the fields you must set are listed on stderr
celigo connections create --connector github --name "GitHub - Prod"

# See the scaffold without creating anything
celigo connections create --connector github --name "GitHub - Prod" --dry-run

# A grouped connector: pick the API group and a non-default auth type
celigo connections create --connector 5f83a9b2c7d3e8f1a2b3c4d5 --api 6a1b2c3d4e5f6a7b8c9d0e1f \
  --auth-type basic --file ./creds.json

# Link an AS2 connection to a trading partner connector (by id, or by its full name)
celigo connections create --tp-connector 7b2c3d4e5f6a7b8c9d0e1f2a --name "Acme Retail AS2" --file ./as2.json

# From a checked-in JSON file (checked against the connector catalog before it is sent)
celigo connections create --file ./connection.json

# A raw HTTP connection to a host no connector serves
echo '{"name":"httpbin","type":"http","http":{"baseURI":"https://httpbin.org"}}' \
  | celigo connections create
```

**Corresponds to**: `POST /v1/connections` (operationId: `createConnection`), preceded by reads of the connector catalogs for the scaffold and the checks — `GET /v1/httpconnectors` and `GET /v1/httpconnectors/{_id}` for HTTP connectors, `GET /v1/tpconnectors` and `GET /v1/tpconnectors/{_id}` for trading partner connectors. `--dry-run` sends no `POST`.

***

## `celigo connections set <id>`

Set field(s) on a connection. Only PATCH-whitelisted fields (e.g. `name`, `debugUntil`, `schedule.*`) are accepted, applied via an atomic PATCH. Other fields must go through `update` because GET masks credential values. Accepts `key=value` pairs; values auto-parse as JSON (`=null` removes a field). Supports dot paths and array indexing. A `key=file://<path>` value loads that field's value from a file (a leading `~` and relative paths are supported). Added in celigo-cli 2026.6.1.

**Signature**

```bash
celigo connections set <id> [assignments...]
```

**Arguments**

| Argument           | Type              | Required | Description                                |
| ------------------ | ----------------- | -------- | ------------------------------------------ |
| `<id>`             | string            | Yes      | Connection ID.                             |
| `[assignments...]` | `key=value` pairs | Yes      | One or more whitelisted field assignments. |

**Example**

```bash
celigo connections set 5f83a9b2c7d3e8f1a2b3c4d5 name="Renamed connection"
```

**Corresponds to**: `PATCH /v1/connections/{_id}` (operationId: `patchConnection`)

***

## `celigo connections update <id>`

Full-replace a connection with a JSON body. Read the body from a file with `-f, --file`, or pipe it on stdin. Refuses to submit a payload containing masked placeholders (all-asterisk strings) unless `--force` is passed.

> ⚠️ **`update` erases omitted fields.** `PUT` is a full replace — any field missing from the body is cleared. `GET` the connection first, edit it, then send back the complete object — or use `set` for whitelisted fields.

**Signature**

```bash
celigo connections update <id> --file <path> [--force]
celigo connections update <id> [--force] < connection.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

| Flag                | Type    | Default | Description                                                                                                                                                     |
| ------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --file <path>` | string  | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin). Added in celigo-cli 2026.6.1.                                                    |
| `--force`           | boolean | `false` | Submit the payload even if it contains masked credential values (`***`). Without it, masked fields cause the command to abort with the list of offending paths. |

**Request body**

A complete connection object matching the `PUT /v1/connections/{_id}` request schema (`PUT` is a full replace). See the [Connections API reference](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections).

**Example**

```bash
celigo connections get 5f83... --format json \
  | jq '.name = "Renamed" | .http.unencrypted.apiKey = "real-key"' \
  | celigo connections update 5f83...
```

**Corresponds to**: [`PUT /v1/connections/{_id}`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#put-v1-connections-_id)

***

## `celigo connections delete <id>`

Delete a connection. Prompts for confirmation unless `-y` is passed.

> ⚠️ **`delete` is immediate.** Every export and import that references this connection stops working until you repoint it. Run `dependencies` first.

**Signature**

```bash
celigo connections delete <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

| Flag        | Type    | Default | Description                        |
| ----------- | ------- | ------- | ---------------------------------- |
| `-y, --yes` | boolean | `false` | Skip the interactive confirmation. |

**Example**

```bash
celigo connections delete 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: [`DELETE /v1/connections/{_id}`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#delete-v1-connections-_id)

***

## `celigo connections dependencies <id>`

List resources that depend on this connection (exports, imports, flows, …). Use it to check whether a connection is safe to delete — empty means no dependents. Aliased as `used-by`.

**Signature**

```bash
celigo connections dependencies <id>
celigo connections used-by <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo connections dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/connections/{_id}/dependencies` (operationId: `listConnectionDependencies`)

***

## `celigo connections audit <id>`

Show the audit log (change history) for one connection.

**Signature**

```bash
celigo connections audit <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo connections audit 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/connections/{_id}/audit`

***

## `celigo connections ping <id>`

Ping a connection — the API attempts the remote handshake (auth + basic request) and returns the outcome.

**Signature**

```bash
celigo connections ping <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo connections ping 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`POST /v1/connections/{_id}/ping`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#post-v1-connections-_id-ping)

***

## `celigo connections enable-debug <id>`

Turn on connection-level debug logging by PATCHing `debugDate` to a future timestamp. Logs are shared across every flow that uses this connection.

**Signature**

```bash
celigo connections enable-debug <id> [--duration <minutes>]
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

| Flag                   | Type    | Default | Description                                                  |
| ---------------------- | ------- | ------- | ------------------------------------------------------------ |
| `--duration <minutes>` | integer | `60`    | Minutes to keep debug on. Values above 60 are clamped to 60. |

**Example**

```bash
celigo connections enable-debug 5f83a9b2c7d3e8f1a2b3c4d5 --duration 30
```

**Corresponds to**: [`PATCH /v1/connections/{_id}`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#patch-v1-connections-_id) (JSON Patch: `replace /debugDate`)

***

## `celigo connections disable-debug <id>`

Turn off connection-level debug logging by PATCH-removing `debugDate`.

**Signature**

```bash
celigo connections disable-debug <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo connections disable-debug 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PATCH /v1/connections/{_id}`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#patch-v1-connections-_id) (JSON Patch: `remove /debugDate`)

***

## `celigo connections debug-logs <id>`

Fetch the debug logs captured while `debugDate` was set. Logs cover every flow that ran against this connection during the window.

**Signature**

```bash
celigo connections debug-logs <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo connections debug-logs 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/connections/{_id}/debug`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#get-v1-connections-_id-debug)

***

## `celigo connections delete-debug-logs <id>`

Delete the captured debug logs for a connection. Prompts for confirmation unless `-y` is passed.

**Signature**

```bash
celigo connections delete-debug-logs <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

| Flag        | Type    | Default | Description                        |
| ----------- | ------- | ------- | ---------------------------------- |
| `-y, --yes` | boolean | `false` | Skip the interactive confirmation. |

**Example**

```bash
celigo connections delete-debug-logs 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: `DELETE /v1/connections/{_id}/debug`

***

## `celigo connections authorize <id>`

Complete an OAuth2 authorization flow for a connection that has `needsAuthorization: true`. Fetches the provider's authorization URL, opens it in your browser (or prints it), then polls the connection until `needsAuthorization` clears, then pings to verify. Works for HTTP OAuth, Salesforce, and every other OAuth2-backed connection type.

**Signature**

```bash
celigo connections authorize <id> [--timeout <seconds>] [--print-url]
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

| Flag                  | Type    | Default | Description                                                                                  |
| --------------------- | ------- | ------- | -------------------------------------------------------------------------------------------- |
| `--timeout <seconds>` | integer | `180`   | How long to poll before giving up.                                                           |
| `--print-url`         | boolean | `false` | Print the authorization URL instead of opening a browser (useful for headless environments). |

**Example**

```bash
celigo connections authorize 5f83a9b2c7d3e8f1a2b3c4d5 --timeout 300
celigo connections authorize 5f83a9b2c7d3e8f1a2b3c4d5 --print-url
```

**Corresponds to**: `GET /v1/connection/{_id}/oauth2` (operationId: `getConnectionOAuth2AuthorizationUrl`) to obtain the authorization URL, followed by polling [`GET /v1/connections/{_id}`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#get-v1-connections-_id) and a final [`POST /v1/connections/{_id}/ping`](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections#post-v1-connections-_id-ping).

***

## `celigo connections purge-messages <id>`

Purge queued messages for a connection. Prompts for confirmation unless `-y` is passed.

> ⚠️ **`purge-messages` discards queued messages.** Queued messages for this connection are dropped and cannot be recovered. Any in-flight data waiting on the queue is lost.

**Signature**

```bash
celigo connections purge-messages <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | Connection ID. |

**Flags**

| Flag        | Type    | Default | Description                        |
| ----------- | ------- | ------- | ---------------------------------- |
| `-y, --yes` | boolean | `false` | Skip the interactive confirmation. |

**Example**

```bash
celigo connections purge-messages 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: `POST /v1/connections/{_id}/purgemessages` (operationId: `purgeConnectionMessages`)

***

## Gotchas

* **`type` is lowercase.** Connection `type` values (`http`, `netsuite`, `ftp`, `salesforce`, `rdbms`, `s3`, …) are lowercase. The `adaptorType` field on exports and imports is PascalCase (`NetSuiteDistributedImport`, `HTTPExport`). Mixing the two cases is the most common cause of `422 Unprocessable Entity` errors.
* **NetSuite connections need `distributed: true`** and `suiteAppInstalled: true`. Without them the SuiteApp bridge won't pick up the connection and every NetSuite flow will fail to submit.
* **Resources don't cross environments.** A flow can reference only connections that live in the same environment. The API rejects references to resources in another environment.
* **OAuth connections can share an iClient.** When several connections point at the same provider (Salesforce, NetSuite OAuth, HubSpot, …), register one [iclient](/cli/commands/iclients.md) and reference it from each connection so credentials rotate in one place.
* **`update` refuses masked payloads by default.** `GET /v1/connections/{id}` returns encrypted fields as `******`. Piping GET → update without editing will abort listing every masked path; fill them in with the real values (or `""` to clear) or pass `--force` to submit anyway.
* **`debug-logs` is shared.** Turning on debug collects traffic from every flow that uses the connection during the window — expect noise if the connection is hot.
* **HTTP connections are connector-first (celigo-cli 2026.9.1).** Run `http-connectors match <url|name>` first, then `connections create --connector <id>`. A hand-written `type: http` body whose base URI a pre-built connector serves is refused (`--allow-raw-http` overrides), and so is a connector connection whose `http.auth.type` the connector's form does not offer (`--auth-type <type>` confirms). The API accepts both shapes and neither authorizes the way the connector expects.
* **The connector's form is the source of the connection's defaults.** `--connector` copies the form's pre-configured fields and lists the fields you must set (credentials, `settings.*`, scopes) on stderr; nothing is guessed. A grouped connector is created from one API group (`--api`), and a connection uses the connector's `legacyId` as its `assistant` value.
* **An empty `http._iClientId` can be correct.** A connector that ships a Celigo-managed (global) iClient authorizes through it; `connections get` says so on stderr. Only when the connector expects your own iClient is the empty field something to fix before `connections authorize`.
* **Trading partner connectors are linked, not copied.** `--tp-connector` sets `_tpConnectorId` and checks the transport; the connector form's connection values (a placeholder partner id, a staging AS2 URI) are stand-ins, and the partner's host and identity are the fields you set. A hand-written `as2`/`ftp`/`s3`/`van` body named after a partner that has a connector gets a stderr note, never a refusal. The interchange identity (ISA/GS ids) lives on the [EDI profile](/cli/commands/edi-profiles.md), not on the connection.

## Related

* [exports](/cli/commands/exports.md) — every export references a connection via `_connectionId`.
* [imports](/cli/commands/imports.md) — every import references a connection via `_connectionId`.
* [iclients](/cli/commands/iclients.md) — shared OAuth credential stores that connections can point at.
* [http-connectors](/cli/commands/http-connectors.md) — `match` finds the pre-built connector for a URL or an application name before `create --connector`.
* [trading-partner-connectors](/cli/commands/trading-partner-connectors.md) — the connectors `create --tp-connector` links.
* [edi-profiles](/cli/commands/edi-profiles.md) — `edi-profiles create --tp-connector` scaffolds the partner's interchange envelope.
