> 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/integrations.md).

# integrations

Containers that group flows, connections, and settings together. Reach for `integrations` when you need to create, clone, snapshot, or triage errors at the integration level.

**REST API**: [Integrations](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations)

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

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

***

## Subcommands

| Subcommand                                          | Purpose                                                                                                               |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `list`                                              | List every integration.                                                                                               |
| `get <id>`                                          | Fetch one integration by ID.                                                                                          |
| `create`                                            | Create from a JSON body (`--file <path>` or stdin).                                                                   |
| `update <id>`                                       | Full PUT replace from a JSON body (`--file <path>` or stdin).                                                         |
| `set <id> <key=value>...`                           | Safe field edit: whitelisted fields via PATCH, others via GET + modify + PUT. Supports `key=file://<path>`.           |
| `delete <id>`                                       | Delete an integration.                                                                                                |
| `clone <id> <environmentId>`                        | Clone the integration (and children) into an environment.                                                             |
| `dependencies <id>` (alias `used-by`)               | List resources that depend on this integration.                                                                       |
| `audit <id>`                                        | Show the audit log (change history) for one integration.                                                              |
| `flow-groups <id>`                                  | List flow groups (sections) within an integration.                                                                    |
| `create-flow-group <id> <name>`                     | Create a flow group.                                                                                                  |
| `delete-flow-group <id> <flowGroupingId>`           | Remove a flow group (flows in it become ungrouped).                                                                   |
| `api-groups <id>`                                   | List API groups (sections) within an integration.                                                                     |
| `create-api-group <id> <name>`                      | Create an API group.                                                                                                  |
| `delete-api-group <id> <apiGroupingId>`             | Remove an API group (APIs in it become ungrouped).                                                                    |
| `register-connections <id> <connectionIds...>`      | Register one or more connections.                                                                                     |
| `deregister-connections <id> <connectionIds...>`    | Deregister one or more connections.                                                                                   |
| `register-lookup-caches <id> <lookupCacheIds...>`   | Register one or more lookup caches.                                                                                   |
| `deregister-lookup-caches <id> <lookupCacheIds...>` | Deregister one or more lookup caches.                                                                                 |
| `download <id>`                                     | Download the integration as a ZIP.                                                                                    |
| `errors <id>`                                       | List all open errors across every flow.                                                                               |
| `settings <id>`                                     | List an Integration App's settings-form fields, flat. Added in celigo-cli 2026.9.1.                                   |
| `refresh-settings-metadata <id>`                    | Refresh the options behind an Integration App settings field (the UI's Refresh button). Added in celigo-cli 2026.9.1. |
| `persist-settings <id> <fieldName>=<value>…`        | Save Integration App settings through the app's connector code (the UI's Save button). Added in celigo-cli 2026.9.1.  |
| `revisions <id>`                                    | List revisions (snapshots, pulls, pushes).                                                                            |
| `revision <id> <revisionId>`                        | Fetch a single revision.                                                                                              |
| `create-snapshot <id>`                              | Create a snapshot revision.                                                                                           |
| `revision-diff <id> <revisionId>`                   | Show the before/after diff for a pending revision.                                                                    |

***

## `celigo integrations list`

List every integration in the account.

**Signature**

```bash
celigo integrations list [flags]
```

**Arguments**

*None.*

**Flags**

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

**Example**

```bash
celigo integrations list --format table
```

**Corresponds to**: [`GET /v1/integrations`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations) (operationId: `listIntegrations`).

***

## `celigo integrations get`

Fetch a single integration by ID.

**Signature**

```bash
celigo integrations get <id>
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo integrations get 5f83a9b2c7d3e8f1a2b3c4d5 --format json | jq '{name,mode}'
```

**Corresponds to**: [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) (operationId: `getIntegration`).

***

## `celigo integrations create`

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

**Signature**

```bash
celigo integrations create --file <path>
celigo integrations create < integration.json     # or pipe on stdin
```

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

**Request body**

A JSON object matching the `POST /v1/integrations` request schema.

**Example**

```bash
celigo integrations create --file ./integration.json
cat integration.json | celigo integrations create
```

**Corresponds to**: [`POST /v1/integrations`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#post-v1-integrations) (operationId: `createIntegration`).

***

## `celigo integrations update`

Full PUT replace of an integration from a JSON body (`--file <path>` or stdin). Omitted fields are erased.

> ⚠️ **`PUT` fully replaces the integration.** Any field omitted from the body is erased. Prefer `set` for targeted edits, or round-trip via `get` + `jq` before `update`.

**Signature**

```bash
celigo integrations update <id> --file <path>
celigo integrations update <id> < body.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `<id>`   | string | Yes      | Integration 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`           | bool   | `false` | Submit even if the body contains masked credential values (`***`) copied from a `get`.                       |

**Request body**

A JSON object matching the `PUT /v1/integrations/{_id}` request schema.

**Example**

```bash
celigo integrations get 5f83a9b2c7d3e8f1a2b3c4d5 --format json \
  | jq '.name = "renamed"' \
  | celigo integrations update 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PUT /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#put-v1-integrations-_id) (operationId: `updateIntegration`).

***

## `celigo integrations set`

Safe field edit. Whitelisted fields (e.g. `name`, `debugUntil`, `schedule.*`) are applied via an atomic `PATCH`; other fields go through GET + in-memory mutation + PUT. Values are auto-parsed as JSON (`disabled=false` is a boolean, `debugUntil=null` removes the field), with a fallback to the literal string when the value isn't valid JSON. Dot notation and array indexing are supported.

A `key=file://<path>` value loads that field's value from a file instead of the command line. A JSON file parses to an object; anything else is read as a literal string. A leading `~` and paths relative to the current directory are supported. Added in celigo-cli 2026.6.1.

**Signature**

```bash
celigo integrations set <id> key=value [key2=value2 ...]
```

**Arguments**

| Argument                 | Type              | Required | Description                                                                                                                            |
| ------------------------ | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`                   | string            | Yes      | Integration ID.                                                                                                                        |
| `key=value` (repeatable) | string (variadic) | Yes      | One or more assignments, e.g. `name=Prod` or `settings.general.notifyEmail=null`. Use `key=file://<path>` to load a value from a file. |

**Flags**

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

**Example**

```bash
celigo integrations set 5f83a9b2c7d3e8f1a2b3c4d5 'name=Shopify -> NetSuite (v2)'
```

**Corresponds to**: [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) + [`PUT /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#put-v1-integrations-_id) (operationIds: `getIntegration`, `updateIntegration`), or `PATCH /v1/integrations/{_id}` for whitelisted fields.

***

## `celigo integrations delete`

Delete an integration by ID.

> ⚠️ **Deleting an integration is destructive.** The integration and the flows it contains are removed. Run `dependencies` first to confirm nothing relies on it.

**Signature**

```bash
celigo integrations delete <id> [--yes]
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo integrations delete 5f83a9b2c7d3e8f1a2b3c4d5 --yes
```

**Corresponds to**: [`DELETE /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#delete-v1-integrations-_id) (operationId: `deleteIntegration`).

***

## `celigo integrations clone`

Clone an integration (and all child resources) into a target environment.

Same-environment clones auto-build a self-map from the source integration's `_registeredConnectionIds`. For cross-environment clones, pipe an explicit `connectionMap` via stdin so source connections are remapped to target-environment connections.

**Signature**

```bash
celigo integrations clone <id> <environmentId> [--name <name>]
```

**Arguments**

| Argument          | Type   | Required | Description            |
| ----------------- | ------ | -------- | ---------------------- |
| `<id>`            | string | Yes      | Source integration ID. |
| `<environmentId>` | string | Yes      | Target environment ID. |

**Flags**

| Flag            | Type   | Default                 | Description                      |
| --------------- | ------ | ----------------------- | -------------------------------- |
| `--name <name>` | string | `Clone - <source name>` | Name for the cloned integration. |

**Request body**

Stdin JSON is optional and only needed for cross-environment remapping:

```json
{"connectionMap":{"sourceConnId":"targetConnId"}}
```

**Example**

```bash
celigo integrations clone 5f83a9b2c7d3e8f1a2b3c4d5 envABC --name "Prod clone"
```

**Corresponds to**: [`POST /v1/integrations/{_id}/clone`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#post-v1-integrations-_id-clone) (operationId: `cloneIntegration`).

***

## `celigo integrations flow-groups`

List flow groups (sections) defined inside an integration. Reads from the integration's `flowGroupings` array.

**Signature**

```bash
celigo integrations flow-groups <id>
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo integrations flow-groups 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) (operationId: `getIntegration`) — reads the `flowGroupings` field.

***

## `celigo integrations create-flow-group`

Create a new flow group inside an integration. Implemented as a GET + PUT that appends to `flowGroupings`.

**Signature**

```bash
celigo integrations create-flow-group <id> <name>
```

**Arguments**

| Argument | Type   | Required | Description                          |
| -------- | ------ | -------- | ------------------------------------ |
| `<id>`   | string | Yes      | Integration ID.                      |
| `<name>` | string | Yes      | Display name for the new flow group. |

**Flags**

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

**Example**

```bash
celigo integrations create-flow-group 5f83a9b2c7d3e8f1a2b3c4d5 "Inbound orders"
```

**Corresponds to**: [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) + [`PUT /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#put-v1-integrations-_id) (operationIds: `getIntegration`, `updateIntegration`).

***

## `celigo integrations delete-flow-group`

Remove a flow group from an integration. Implemented as a GET + PUT that drops the matching entry from `flowGroupings`. The flows that were in the group are **not** deleted — they become ungrouped.

**Signature**

```bash
celigo integrations delete-flow-group <id> <flowGroupingId> [--yes]
```

**Arguments**

| Argument           | Type   | Required | Description                            |
| ------------------ | ------ | -------- | -------------------------------------- |
| `<id>`             | string | Yes      | Integration ID.                        |
| `<flowGroupingId>` | string | Yes      | Flow group `_id` (from `flow-groups`). |

**Flags**

| Flag          | Type | Default | Description                   |
| ------------- | ---- | ------- | ----------------------------- |
| `-y`, `--yes` | bool | `false` | Skip the confirmation prompt. |

**Example**

```bash
celigo integrations delete-flow-group 5f83a9b2c7d3e8f1a2b3c4d5 fg_abc123 --yes
```

**Corresponds to**: [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) + [`PUT /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#put-v1-integrations-_id) (operationIds: `getIntegration`, `updateIntegration`).

***

> **Assigning flows to a group** is a flows operation, not an integration one — see [`flows set-group`](/cli/commands/flows.md#celigo-flows-set-group). `create-flow-group`/`delete-flow-group` define groups on the integration; `flows set-group` sets which flows belong to one.

***

## `celigo integrations api-groups` / `create-api-group` / `delete-api-group`

The API-grouping equivalents of the flow-group commands above. `apiGroupings` is a separate array on the integration that works identically to `flowGroupings`, but for API resources. All three use the same GET → mutate → PUT pattern on the integration.

**Signatures**

```bash
celigo integrations api-groups <id>
celigo integrations create-api-group <id> <name>
celigo integrations delete-api-group <id> <apiGroupingId> [--yes]
```

**Arguments**

| Argument          | Type   | Required                 | Description                          |
| ----------------- | ------ | ------------------------ | ------------------------------------ |
| `<id>`            | string | Yes                      | Integration ID.                      |
| `<name>`          | string | Yes (`create-api-group`) | Display name for the new API group.  |
| `<apiGroupingId>` | string | Yes (`delete-api-group`) | API group `_id` (from `api-groups`). |

**Example**

```bash
celigo integrations api-groups 5f83a9b2c7d3e8f1a2b3c4d5
celigo integrations create-api-group 5f83a9b2c7d3e8f1a2b3c4d5 "Public endpoints"
celigo integrations delete-api-group 5f83a9b2c7d3e8f1a2b3c4d5 ag_abc123 --yes
```

**Corresponds to**: `api-groups` reads [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id); `create`/`delete` GET then [`PUT /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#put-v1-integrations-_id) (operationIds: `getIntegration`, `updateIntegration`).

> **Assigning APIs to a group** is an apis operation — see [`apis set-group`](/cli/commands/apis.md#celigo-apis-set-group-unset-group). `create-api-group`/`delete-api-group` define groups on the integration; `apis set-group` sets which APIs belong to one.

***

## `celigo integrations register-connections`

Register one or more connections to an integration via the dedicated registration endpoint.

**Signature**

```bash
celigo integrations register-connections <id> <connectionIds...>
```

**Arguments**

| Argument             | Type              | Required | Description                 |
| -------------------- | ----------------- | -------- | --------------------------- |
| `<id>`               | string            | Yes      | Integration ID.             |
| `<connectionIds...>` | string (variadic) | Yes      | One or more connection IDs. |

**Flags**

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

**Example**

```bash
celigo integrations register-connections 5f83a9b2c7d3e8f1a2b3c4d5 connA connB
```

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

***

## `celigo integrations deregister-connections`

Deregister one or more connections from an integration. Iterates a `DELETE` per connection ID.

**Signature**

```bash
celigo integrations deregister-connections <id> <connectionIds...> [--yes]
```

**Arguments**

| Argument             | Type              | Required | Description                 |
| -------------------- | ----------------- | -------- | --------------------------- |
| `<id>`               | string            | Yes      | Integration ID.             |
| `<connectionIds...>` | string (variadic) | Yes      | One or more connection IDs. |

**Flags**

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

**Example**

```bash
celigo integrations deregister-connections 5f83a9b2c7d3e8f1a2b3c4d5 connA connB --yes
```

**Corresponds to**: [`DELETE /v1/integrations/{_id}/connections/{_connectionId}/register`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#delete-v1-integrations-_id-connections-_connectionid-register) (one call per connection).

***

## `celigo integrations register-lookup-caches`

Register one or more lookup caches to an integration via the dedicated registration endpoint — the exact mirror of `register-connections`. Requires `full` mode. Added in celigo-cli 2026.8.7.

Registration also adds an entry to the integration's `aliases[]` for each cache (a slug of its name) — the handle the integration's steps reference the cache by.

**Signature**

```bash
celigo integrations register-lookup-caches <id> <lookupCacheIds...>
```

**Arguments**

| Argument              | Type              | Required | Description                   |
| --------------------- | ----------------- | -------- | ----------------------------- |
| `<id>`                | string            | Yes      | Integration ID.               |
| `<lookupCacheIds...>` | string (variadic) | Yes      | One or more lookup cache IDs. |

**Flags**

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

**Example**

```bash
celigo integrations register-lookup-caches 5f83a9b2c7d3e8f1a2b3c4d5 cacheA cacheB
```

**Corresponds to**: [`PUT /v1/integrations/{_id}/lookupcaches/register`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations) — a batch `PUT` with the raw id-array body.

***

## `celigo integrations deregister-lookup-caches`

Deregister one or more lookup caches from an integration; the caches themselves and their data are untouched. Iterates a `DELETE` per cache ID, like `deregister-connections`. Requires `full` mode. Added in celigo-cli 2026.8.7.

Deregistering fails with `400` while an alias still references a cache — **including the alias that `register-lookup-caches` itself creates**. Remove the alias first: edit the integration's `aliases[]` via `integrations set`.

**Signature**

```bash
celigo integrations deregister-lookup-caches <id> <lookupCacheIds...> [--yes]
```

**Arguments**

| Argument              | Type              | Required | Description                   |
| --------------------- | ----------------- | -------- | ----------------------------- |
| `<id>`                | string            | Yes      | Integration ID.               |
| `<lookupCacheIds...>` | string (variadic) | Yes      | One or more lookup cache IDs. |

**Flags**

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

**Example**

```bash
# Remove the alias register-lookup-caches created, then deregister
celigo integrations get 5f83a9b2c7d3e8f1a2b3c4d5 --jq '.aliases'
celigo integrations set 5f83a9b2c7d3e8f1a2b3c4d5 'aliases[0]=null'
celigo integrations deregister-lookup-caches 5f83a9b2c7d3e8f1a2b3c4d5 cacheA --yes
```

**Corresponds to**: [`DELETE /v1/integrations/{_id}/lookupcaches/{_lookupCacheId}/register`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations) (one call per cache).

***

## `celigo integrations download`

Download the integration as a ZIP. Resolves the signed URL from the template endpoint and writes the file locally. Rejects Integration App installations (non-standalone integrations).

**Signature**

```bash
celigo integrations download <id> [-o <path>]
```

**Arguments**

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

**Flags**

| Flag                    | Type   | Default             | Description            |
| ----------------------- | ------ | ------------------- | ---------------------- |
| `-o`, `--output <path>` | string | `<name>.zip` in CWD | Destination file path. |

**Example**

```bash
celigo integrations download 5f83a9b2c7d3e8f1a2b3c4d5 -o ./backup.zip
```

**Corresponds to**: [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) + [`GET /v1/integrations/{_id}/template`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations) (operationId for the first: `getIntegration`).

***

## `celigo integrations errors`

List every open error across all flows in an integration (paginated via `nextPageURL` in the body).

**Signature**

```bash
celigo integrations errors <id>
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo integrations errors 5f83a9b2c7d3e8f1a2b3c4d5 --format json
```

**Corresponds to**: [`GET /v1/integrations/{_id}/errors`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id-errors) (operationId: `listIntegrationErrors`).

***

## Integration App settings

An Integration App's settings form is driven by the app's connector code: the form is read from the integration document, and every save goes through the connector, which validates the values, rewrites the integration's settings, and may reconfigure the app's flows. Three commands, added in celigo-cli 2026.9.1, cover that form end to end — `settings` reads it, `refresh-settings-metadata` refreshes one field's options, and `persist-settings` saves values — through the UI's own routes.

> ⚠️ **A plain `set` or `update` on `settings` bypasses the connector.** Writing an Integration App's `settings` with `integrations set` or `integrations update` skips the app's validation and the flow reconfiguration its connector performs. Use `persist-settings` instead. For the same reason `celigo push` never writes an Integration App's `integration.json` — its documents are withheld — and these commands are the write path for its settings. See [push](/cli/local-tree/push.md).

***

## `celigo integrations settings`

List an Integration App's settings-form fields, flat, from the integration document. Each row carries `name` (the handle `refresh-settings-metadata` and `persist-settings` take), `label`, `type`, the current `value` in the shape `persist-settings` takes (a static map's `{map, default, allowFailures}`), the `section` path, `store` and `storeLabel` on a multi-store app, `flowId` for a flow's own settings, `refresh` — `[]` (no Refresh button), `["options"]` (refresh without `--type`), or a static map's `["extracts", "generates"]` or column ids (the `--type` values) — and the stored `options` as `[value, label]` pairs (usually only the current value; refresh for the full list).

The command refuses a standalone integration: its settings are plain document fields, so use `get` and `set` there. Works in `read` mode.

**Signature**

```bash
celigo integrations settings <id> [--store <id>] [--section <text>] [--field-name <name>] [--refreshable]
```

**Arguments**

| Argument | Type   | Required | Description                                        |
| -------- | ------ | -------- | -------------------------------------------------- |
| `<id>`   | string | Yes      | Integration ID of an Integration App installation. |

**Flags**

| Flag                  | Type    | Default | Description                                                                                                                                                                |
| --------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--store <id>`        | string  | —       | Only fields of this store (multi-store apps).                                                                                                                              |
| `--section <text>`    | string  | —       | Only fields whose section path contains this text.                                                                                                                         |
| `--field-name <name>` | string  | —       | Print one field's full definition (options, extracts, …). On a multi-store app a name several stores repeat must be scoped with `--store`; without it the name is refused. |
| `--refreshable`       | boolean | `false` | Only fields whose options can be refreshed.                                                                                                                                |

**Example**

```bash
# Every field of the form, as a table
celigo integrations settings 5f83a9b2c7d3e8f1a2b3c4d5 --format table

# One store's fields in one section
celigo integrations settings 5f83a9b2c7d3e8f1a2b3c4d5 --store 6a1b2c3d4e5f6a7b8c9d0e1f --section "Refund"

# The full definition of one field
celigo integrations settings 5f83a9b2c7d3e8f1a2b3c4d5 --field-name exports_7b2c3d4e5f6a7b8c9d0e1f2a_savedSearch_listSavedSearches
```

**Corresponds to**: [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) (operationId: `getIntegration`) — the form is read from the document; no other request is made.

***

## `celigo integrations refresh-settings-metadata`

Refresh the options behind an Integration App settings field — the UI's Refresh button. The connector re-pulls the field's list (saved searches, locations, accounts, price levels, …) from the connected app and the command prints the refreshed field: a select's `options` as `[value, label]` pairs, a static map's `extracts`/`generates` as `{id, text}` rows.

`--field-name` is checked against the form first: the field must exist (a typo gets suggestions) and be refreshable, and a static map needs `--type extracts` or `--type generates` (an n-column map: a column id) — see the field's `refresh` list in `settings`. Without the check the platform answers `[]` or `422 Unprocessable Entity`. The connector may write the refreshed list back into the integration document (a static map's `extracts` are rewritten; a select that yields value and label is not written). A raw JSON body via `--file`/stdin is sent unchecked, for connector-specific shapes — add-ons send `{"sectionId", "addOnId", "shopId", "fieldName", "pending"}`. Stdin is optional: with no flags and nothing piped the command prints the flag hint and exits `1` instead of waiting on an idle pipe.

**Required:** `operate` or `full` mode — the refresh is an operational write through the connector.

**Signature**

```bash
celigo integrations refresh-settings-metadata <id> --field-name <name> [--type <type>]
celigo integrations refresh-settings-metadata <id> -f <path>
```

**Arguments**

| Argument | Type   | Required | Description                                        |
| -------- | ------ | -------- | -------------------------------------------------- |
| `<id>`   | string | Yes      | Integration ID of an Integration App installation. |

**Flags**

| Flag                  | Type   | Default | Description                                                                                                                                                                    |
| --------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--field-name <name>` | string | —       | The settings field's `name` (for example `exports_<id>_savedSearch_listSavedSearches`), from `settings`.                                                                       |
| `--type <type>`       | string | —       | Which list to refresh on a static map: `extracts`, `generates`, or a column id. Required for a static map; the field's `refresh` list in `settings` names the accepted values. |
| `-f, --file <path>`   | string | —       | Raw JSON body file (or pipe via stdin) instead of the flags. Sent unchecked.                                                                                                   |

**Example**

```bash
# Refresh a select's options
celigo integrations refresh-settings-metadata 5f83a9b2c7d3e8f1a2b3c4d5 \
  --field-name exports_7b2c3d4e5f6a7b8c9d0e1f2a_savedSearch_listSavedSearches

# One side of a static map
celigo integrations refresh-settings-metadata 5f83a9b2c7d3e8f1a2b3c4d5 \
  --field-name imports_7b2c3d4e5f6a7b8c9d0e1f2a_staticMap --type generates
```

**Corresponds to**: `PUT /v1/integrations/{_id}/settings/refreshMetadata` — the UI's own route, not yet in the published API reference — after [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) to check the field against the form.

***

## `celigo integrations persist-settings`

Save Integration App settings through the app's connector code — the UI's Save button. Give `<fieldName>=<value>` assignments; values parse as JSON (`…=true`, `…=3`, `…="text"`). A select that yields value and label takes `{"id": …, "label": …}`; a static map takes `{"map": {…}, "default": …, "allowFailures": …}`. Every name is resolved against the form before anything is sent (an unknown name is an error with suggestions), and a multi-store app's values are nested under the store id — `--store`, else the store the fields belong to. One store per call: a name several stores repeat is resolved within `--store` and refused without it.

After the save the document is re-read and each field is reported `saved`, `unchanged` (it already held that value), or `not-saved`. The platform answers `{"success": true}` and echoes the body even when it saved nothing — for an unknown field name, or a multi-store body not nested under the store id — so the exit code follows the fields, not the response: any `not-saved`, or a connector refusal (`success: false`), exits `1`. The output is `{success, store?, fields: [{name, status, before, after, store?, flowId?}], response}`.

A raw body via `--file`/stdin (`{"pending": {…}}`, plus `sectionId`/`addOnId`/`shopId` for add-ons) is sent as given and verified the same way, store by store: a name the form knows is reported as above; a name it does not know is looked up after the `PUT` where the body addressed it (present with the sent value → `saved`, absent → `not-saved`, exit `1`); the UI's flow toggle `{"flowId", "disabled"}` is checked against the flow document. A body with nothing the form can locate — an add-on body (`addOnId`), a store key holding no field values — is `unverified`, which exits `1` unless `--allow-unverified`; the flag never excuses a `not-saved`. Stdin is optional: with no assignments and nothing piped the command prints the assignment hint and exits `1` without fetching the integration.

**Required:** `full` mode — the save is a configuration write that rewrites the integration's settings and may reconfigure its flows.

**Signature**

```bash
celigo integrations persist-settings <id> <fieldName>=<value> [<fieldName>=<value> ...] [--store <id>]
celigo integrations persist-settings <id> -f <path> [--allow-unverified]
```

**Arguments**

| Argument                           | Type              | Required             | Description                                                                                             |
| ---------------------------------- | ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| `<id>`                             | string            | Yes                  | Integration ID of an Integration App installation.                                                      |
| `<fieldName>=<value>` (repeatable) | string (variadic) | Yes, unless `--file` | One or more assignments. `<fieldName>` is the field's `name` from `settings`; `<value>` parses as JSON. |

**Flags**

| Flag                 | Type    | Default               | Description                                                                                                           |
| -------------------- | ------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--store <id>`       | string  | the fields' own store | The store whose settings to save (multi-store apps). Required when a field name is repeated across stores.            |
| `-f, --file <path>`  | string  | —                     | Raw JSON body file (or pipe via stdin) instead of assignments.                                                        |
| `--allow-unverified` | boolean | `false`               | Exit `0` when the body's fields cannot be located on the form to verify (add-on bodies). Never excuses a `not-saved`. |

**Example**

```bash
# A checkbox and a number
celigo integrations persist-settings 5f83a9b2c7d3e8f1a2b3c4d5 \
  imports_7b2c3d4e5f6a7b8c9d0e1f2a_syncTaxes=true \
  imports_7b2c3d4e5f6a7b8c9d0e1f2a_batchSize=3

# A select that yields value and label
celigo integrations persist-settings 5f83a9b2c7d3e8f1a2b3c4d5 \
  'exports_7b2c3d4e5f6a7b8c9d0e1f2a_savedSearch_listSavedSearches={"id":"5082","label":"Fulfillments"}'

# A static map, in one store of a multi-store app
celigo integrations persist-settings 5f83a9b2c7d3e8f1a2b3c4d5 --store 6a1b2c3d4e5f6a7b8c9d0e1f \
  'imports_7b2c3d4e5f6a7b8c9d0e1f2a_staticMap={"map":{"US":"1","CA":"2"},"default":"","allowFailures":true}'

# Only the fields that did not land
celigo integrations persist-settings 5f83a9b2c7d3e8f1a2b3c4d5 imports_7b2c3d4e5f6a7b8c9d0e1f2a_syncTaxes=true \
  --jq '[.fields[] | select(.status == "not-saved")]'
```

**Corresponds to**: `PUT /v1/integrations/{_id}/settings/persistSettings` — the UI's own route, not yet in the published API reference — after [`GET /v1/integrations/{_id}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id) to resolve the names against the form, and again after the save to verify each field (plus `GET /v1/flows/{_id}` before and after for a flow toggle).

***

## `celigo integrations revisions`

List all revisions (snapshots, pulls, pushes) for an integration.

**Signature**

```bash
celigo integrations revisions <id>
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo integrations revisions 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/integrations/{_id}/revisions`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id-revisions) (operationId: `listIntegrationRevisions`).

***

## `celigo integrations revision`

Get details of a single revision.

**Signature**

```bash
celigo integrations revision <id> <revisionId>
```

**Arguments**

| Argument       | Type   | Required | Description     |
| -------------- | ------ | -------- | --------------- |
| `<id>`         | string | Yes      | Integration ID. |
| `<revisionId>` | string | Yes      | Revision ID.    |

**Flags**

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

**Example**

```bash
celigo integrations revision 5f83a9b2c7d3e8f1a2b3c4d5 rev987
```

**Corresponds to**: [`GET /v1/integrations/{_id}/revisions/{_revisionId}`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id-revisions-_revisionid) (operationId: `getIntegrationRevision`).

***

## `celigo integrations create-snapshot`

Create a snapshot revision of the current integration state. Handy to run before a risky deploy.

**Signature**

```bash
celigo integrations create-snapshot <id> --description <text>
```

**Arguments**

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

**Flags**

| Flag                   | Type   | Default      | Description                          |
| ---------------------- | ------ | ------------ | ------------------------------------ |
| `--description <text>` | string | — (required) | Human-readable snapshot description. |

**Example**

```bash
celigo integrations create-snapshot 5f83a9b2c7d3e8f1a2b3c4d5 --description 'before deploy'
```

**Corresponds to**: [`POST /v1/integrations/{_id}/revisions/create`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#post-v1-integrations-_id-revisions-create) (operationId: `createIntegrationRevision`).

***

## `celigo integrations revision-diff`

Show the before/after diff for a revision. Only revisions in a pending state (e.g. `pull` or `revert`) can be diffed; completed snapshots cannot.

**Signature**

```bash
celigo integrations revision-diff <id> <revisionId>
```

**Arguments**

| Argument       | Type   | Required | Description     |
| -------------- | ------ | -------- | --------------- |
| `<id>`         | string | Yes      | Integration ID. |
| `<revisionId>` | string | Yes      | Revision ID.    |

**Flags**

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

**Example**

```bash
celigo integrations revision-diff 5f83a9b2c7d3e8f1a2b3c4d5 rev987
```

**Corresponds to**: [`GET /v1/integrations/{_id}/revisions/{_revisionId}/diff`](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations#get-v1-integrations-_id-revisions-_revisionid-diff) (operationId: `getIntegrationRevisionDiff`).

***

## `celigo integrations dependencies`

List resources that depend on this integration. Use this to check whether the integration is safe to delete — an empty result means no dependents. Aliased as `used-by`.

**Signature**

```bash
celigo integrations dependencies <id>
celigo integrations used-by <id>     # alias
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo integrations dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/integrations/{_id}/dependencies`.

***

## `celigo integrations audit`

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

**Signature**

```bash
celigo integrations audit <id>
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo integrations audit 5f83a9b2c7d3e8f1a2b3c4d5 --format table
```

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

***

## Gotchas

* **`update` is a full PUT replace.** Omitted fields are erased. Prefer `set` for targeted edits, or always round-trip via `get` + `jq` before `update`.
* **Cross-env clones require a `connectionMap`.** Same-env clones auto-build a self-map from `_registeredConnectionIds`. Only pipe stdin JSON when the target environment is different.
* **`download` rejects Integration App installations.** The template endpoint only works for standalone integrations — anything with `_connectorId` or `mode: install` errors out.
* **`revision-diff` fails on completed snapshots.** Only pending revisions (pulls, reverts) expose a diff; snapshot revisions are point-in-time captures with nothing to compare.
* **`create-snapshot` requires `--description`.** The flag is enforced by the CLI even though the REST payload accepts an empty description.
* **ILM commands are UI-only.** `revision-apply`, `revision-cancel`, `revert-*`, `pull-*`, `clonefamily`, and `ilm-ignore*` are session-auth only and are intentionally not exposed as CLI commands. Use the UI for those.
* **Lookup-cache registration leaves an alias behind.** `register-lookup-caches` adds an `aliases[]` entry per cache, and `deregister-lookup-caches` fails with `400` until every alias referencing the cache is removed (edit `aliases[]` via `integrations set`).
* **Integration App settings go through the connector.** `settings`, `refresh-settings-metadata`, and `persist-settings` (celigo-cli 2026.9.1) drive the app's settings form through its connector code; a plain `set`/`update` on `settings` bypasses it, and `celigo push` withholds an Integration App's documents. `settings` refuses a standalone integration — its settings are plain document fields.
* **`persist-settings` trusts the document, not the response.** The platform answers `{"success": true}` even when it saved nothing, so the command re-reads the integration and exits `1` when any field is `not-saved`. On a multi-store app, values nest under the store id: pass `--store` when a field name repeats across stores.

## Related

* [flows](/cli/commands/flows.md) — integrations contain flows; use `flows` for flow-level CRUD, runs, and errors.
* [connections](/cli/commands/connections.md) — `register-connections` / `deregister-connections` operate on connections already created via `celigo connections`.
* [lookup-caches](/cli/commands/lookup-caches.md) — `register-lookup-caches` / `deregister-lookup-caches` attach caches created via `celigo lookup-caches`.
* [flows](/cli/commands/flows.md) — assign errors at the step level with `flows assign-errors`; assign flows to a group with `flows set-group`.
* [account](/cli/commands/account.md) — `account snapshot` indexes every integration for search, dependency, and lint workflows.
* [push](/cli/local-tree/push.md) — `celigo push` writes a pulled tree back to the account, but never an Integration App's `integration.json`; `persist-settings` is that app's write path.