> 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)

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

**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#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#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#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#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#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#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#get-v1-connections-_id) and a final [`POST /v1/connections/{_id}/ping`](https://developer.celigo.com/api/api-reference/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/connections.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
