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

# flows

Manage flows, the pipelines that connect `pageGenerators` (exports) to `pageProcessors` (imports) or `routers` (branching), plus their run, error, test-run, and execution-log surface.

> ⚠️ **Response mapping shape.** `pageProcessors[].responseMapping.fields`/`.lists` are bare arrays — the same shape `get` returns. The API does not reject the object-wrapper shape (`{"fields": {"type": [...]}}`) that its generated schema docs described before 2026-08-22: it accepts it and silently corrupts the mapping to `fields: [null]`, erasing the step's mappings. Always send the bare-array shape; repair a corrupted flow by resending the full document with correct bare-array mappings via `update`.

**Abstract/instance (multi-instance) flows:** a flow with `isAbstract: true` is a reusable template that never runs directly; instances reference it via `_abstractFlowId` (immutable) and customize only through `overrides`. Structure belongs to the abstract — editing the abstract's graph propagates to every instance implicitly, and the server rejects structural fields on an instance write (`422 flow_instance_invalid_fields`), so the structural commands (`add-processor`, `remove-processor`, `add-generator`, `remove-generator`) refuse instance targets up front and point at the abstract. Use `list --abstract-flow-id` to enumerate an abstract's instances and `get --merge-instance` for an instance's effective config.

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

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

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

## Subcommands

| Subcommand                                                      | Purpose                                                                                                                        |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `list`                                                          | List all flows.                                                                                                                |
| `get <id>`                                                      | Fetch one flow.                                                                                                                |
| `create`                                                        | Create a flow from a JSON body (stdin, or `--file`).                                                                           |
| `update <id>`                                                   | Full replace from a JSON body (PUT). Omitted fields are erased.                                                                |
| `set <id> key=value …`                                          | Safe field edit: GET, modify, PUT.                                                                                             |
| `delete <id>`                                                   | Delete a flow.                                                                                                                 |
| `dependencies <id>` (alias `used-by`)                           | List resources that depend on this flow.                                                                                       |
| `audit <id>`                                                    | Show the audit log (change history) for one flow.                                                                              |
| `run <id>`                                                      | Trigger a one-off flow run.                                                                                                    |
| `clone <id> <integrationId> <environmentId>`                    | Clone a flow into another integration/environment.                                                                             |
| `errors <id> <exportOrImportId>`                                | List open errors for one step.                                                                                                 |
| `resolved-errors <id> <exportOrImportId>`                       | List errors already resolved.                                                                                                  |
| `resolve-errors <id> <exportOrImportId> [errorIds]`             | Resolve errors (or all if omitted).                                                                                            |
| `error <id> <exportOrImportId> <errorId>`                       | One open error by id. `--request-detail` adds the captured HTTP request/response; `--retry-data` adds the editable retry data. |
| `delete-debug-requests <id> <exportOrImportId> [reqAndResKeys]` | Delete stored request/response traces (specific keys, or all the step's).                                                      |
| `retry-errors <id> <exportOrImportId> [retryDataKeys]`          | Retry errors (or all if omitted).                                                                                              |
| `assign-errors <id> <exportOrImportId> <email> [errorIds]`      | Assign errors to a user.                                                                                                       |
| `unassign-errors <id> <exportOrImportId> [errorIds]`            | Unassign errors (or all if omitted).                                                                                           |
| `delete-resolved-errors <id> <exportOrImportId> [errorIds]`     | Purge resolved errors.                                                                                                         |
| `update-error-data <id> <exportOrImportId> <errorId>`           | Update an error's retry data before re-running (resolves its retryDataKey internally).                                         |
| `tag-errors <id> <exportOrImportId>`                            | Set or clear tags on a batch of errors.                                                                                        |
| `error-summary <id>`                                            | Per-step open-error counts and last-error times for a flow.                                                                    |
| `error-analysis <id> <exportOrImportId>`                        | Group errors by message/code.                                                                                                  |
| `add-processor <id> <exportOrImportId>`                         | Add a page processor to a flow.                                                                                                |
| `remove-processor <id> <exportOrImportId>`                      | Remove a page processor.                                                                                                       |
| `add-generator <id> <exportId>`                                 | Add a page generator (export).                                                                                                 |
| `remove-generator <id> <exportId>`                              | Remove a page generator.                                                                                                       |
| `replace-connection <id> <oldConnId> <newConnId>`               | Swap a connection across every step.                                                                                           |
| `set-group <flowGroupingId> <flowIds...>`                       | Assign flows to a flow group.                                                                                                  |
| `unset-group <flowIds...>`                                      | Remove flows from their flow group.                                                                                            |
| `debug-requests <id> <exportOrImportId>`                        | List debug HTTP request log entries.                                                                                           |
| `debug-request-detail <id> <exportOrImportId> <key>`            | Full request/response for one debug entry.                                                                                     |
| `test-run <id>`                                                 | Start a test run and return stage-by-stage results.                                                                            |
| `test-run-step-results <id> <runId> <exportOrImportId>`         | Step results for a test run.                                                                                                   |
| `test-run-step-logs <id> <runId> <exportOrImportId>`            | HTTP logs for a test run step.                                                                                                 |
| `enable-execution-logs <id>`                                    | Arm debug execution logging on a flow.                                                                                         |
| `disable-execution-logs <id>`                                   | Disarm debug execution logging.                                                                                                |
| `execution-logs <id> <jobId>`                                   | List execution log entries for a run.                                                                                          |
| `query-execution-logs <id> <jobId>`                             | Search execution log metadata for a step.                                                                                      |
| `execution-log-detail <id> <jobId>`                             | Get per-stage data for an execution log step.                                                                                  |
| `last-export-date <id>`                                         | Flow-level delta checkpoint.                                                                                                   |
| `delete-execution-logs <id>`                                    | Delete a flow's execution logs within a time range.                                                                            |
| `cancel-jobs <id>`                                              | Cancel a flow's jobs.                                                                                                          |

***

## `celigo flows list`

List all flows in the account, with optional server-side filters.

**Signature**

```bash
celigo flows list [flags]
```

**Flags**

| Flag                      | Type             | Default   | Description                                                                                                                                                                                                                               |
| ------------------------- | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--integration <id>`      | string           | —         | List only flows belonging to this integration.                                                                                                                                                                                            |
| `--name <substring>`      | string           | —         | Filter by name — a server-side substring match, not exact. Added in celigo-cli 2026.8.7.                                                                                                                                                  |
| `--disabled`              | boolean          | `false`   | Only flows with `disabled: true`. Added in celigo-cli 2026.8.7.                                                                                                                                                                           |
| `--sort-by <field>`       | `lastExecutedAt` | —         | Sort by last execution — most recently executed first, never-run flows last. Added in celigo-cli 2026.8.7.                                                                                                                                |
| `--include-instances`     | boolean          | `false`   | Include instance flows generated from abstract (multi-instance) flows, otherwise excluded from the results. Added in celigo-cli 2026.8.7.                                                                                                 |
| `--abstract-flow-id <id>` | string           | —         | List the instance flows generated from this abstract flow (the API's `_abstractFlowId` filter). Implies `--include-instances`: the filter alone returns the instances even though plain lists exclude them. Added in celigo-cli 2026.8.7. |
| `--fields <spec>`         | string           | `default` | Fields to request per row. `default` returns `_id`, `name`, and the table columns; `all` returns complete documents; a comma-separated list requests specific fields. See [field projection](/cli/getting-started/global-flags.md).       |
| `--limit <n>`             | integer          | —         | Return at most `<n>` rows, fetching a single page.                                                                                                                                                                                        |

`--include-instances` also applies to the `--integration` form; `--name`, `--disabled`, `--sort-by`, and `--abstract-flow-id` are main-list only — the integration-scoped endpoint ignores them, so the CLI rejects the combination.

Default table columns: `_id`, `name`, `_integrationId`, `disabled`, `lastModified`, `lastExecutedAt`.

**Example**

```bash
celigo flows list --format table
celigo flows list --integration 5f83a9b2c7d3e8f1a2b3c4d5

# Disabled flows whose name mentions "orders", most recently run first
celigo flows list --name orders --disabled --sort-by lastExecutedAt

# Every instance generated from one abstract flow
celigo flows list --abstract-flow-id 5f83a9b2c7d3e8f1a2b3c4d5

# Complete flow documents, including every step
celigo flows list --fields all

# Find flows that have never run
celigo flows list --jq '.[] | select(.lastExecutedAt == null) | .name'
```

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

***

## `celigo flows get`

Fetch one flow by ID.

**Signature**

```bash
celigo flows get <id> [--merge-instance]
```

**Arguments**

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

**Flags**

| Flag               | Type    | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--merge-instance` | boolean | `false` | For an instance flow: return its effective config — the abstract flow's structure (`pageGenerators`/`routers`) merged with this instance's `overrides` (the API's `mergeInstance` param). The merged document keeps `_abstractFlowId` but absorbs the overrides into the structure (the `overrides` key disappears). Without it an instance returns its sparse document: `_abstractFlowId`, `overrides`, and instance-level fields only. Non-instance flows are returned unchanged (the server ignores the param). Added in celigo-cli 2026.8.7. |

**Example**

```bash
celigo flows get 5f83a9b2c7d3e8f1a2b3c4d5

# An instance flow's effective config, structure and overrides merged
celigo flows get 6a1b2c3d4e5f6a7b8c9d0e1f --merge-instance
```

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

***

## `celigo flows create`

Create a flow from a JSON body (stdin, or `--file`).

**Signature**

```bash
celigo flows create [flags]
```

**Flags**

| Flag                | Type   | Default | Description                                                             |
| ------------------- | ------ | ------- | ----------------------------------------------------------------------- |
| `-f, --file <path>` | string | stdin   | Read the JSON body from a file instead of stdin (`-` also means stdin). |

**Request body**

Reads JSON on stdin (or from `--file`). See the `POST /v1/flows` schema for the full payload shape.

**Example**

```bash
cat flow.json | celigo flows create
celigo flows create --file flow.json
```

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

***

## `celigo flows update`

Full replace of a flow from a JSON body (stdin, or `--file`). Omitted fields are erased.

> ⚠️ **`PUT` fully replaces the flow.** Any field omitted from the body is erased. `GET` the flow first, edit, then send the complete object back — or use `set` for targeted edits.

**Signature**

```bash
celigo flows update <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                | Type    | Default | Description                                                                          |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------ |
| `-f, --file <path>` | string  | stdin   | Read the JSON body from a file instead of stdin (`-` also means stdin).              |
| `--force`           | boolean | `false` | Submit even if the body contains masked credential values (`***`) copied from a GET. |

**Request body**

Reads JSON on stdin (or from `--file`). See the `PUT /v1/flows/{_id}` schema for the full payload shape.

**Example**

```bash
celigo flows get 5f83a9b2c7d3e8f1a2b3c4d5 --format json > flow.json
# edit flow.json
cat flow.json | celigo flows update 5f83a9b2c7d3e8f1a2b3c4d5
celigo flows update 5f83a9b2c7d3e8f1a2b3c4d5 --file flow.json
```

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

***

## `celigo flows set`

Safe field edit. Whitelisted fields (e.g. `name`, `debugUntil`, `schedule.*`) are applied via an atomic PATCH; other fields go through GET, modify, PUT. Accepts `key=value` pairs; values auto-parse as JSON (`disabled=false` is a boolean; `=null` removes a field). Supports dot paths and array indexing. A value can also be loaded from a file with `key=file://<path>` (avoids hand-escaping multi-line content like script source or SQL; `~` and relative paths are supported).

**Signature**

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

**Arguments**

| Argument           | Type              | Required | Description                                                                         |
| ------------------ | ----------------- | -------- | ----------------------------------------------------------------------------------- |
| `<id>`             | string            | Yes      | Flow ID.                                                                            |
| `[assignments...]` | `key=value` pairs | Yes      | One or more field assignments. Use `key=file://<path>` to load a value from a file. |

**Example**

```bash
celigo flows set 5f83a9b2c7d3e8f1a2b3c4d5 disabled=false
celigo flows set 5f83a9b2c7d3e8f1a2b3c4d5 'schedule=? */15 * * * *'
celigo flows set 5f83a9b2c7d3e8f1a2b3c4d5 pageGenerators[0]._exportId=6a1b2c3d4e5f6a7b8c9d0e1f
celigo flows set 5f83a9b2c7d3e8f1a2b3c4d5 routers[0].branches[0].pageProcessors[0].script.content=file://./hook.js
```

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

***

## `celigo flows delete`

Delete a flow.

> ⚠️ **Deleting a flow is destructive.** The flow and its step wiring are removed. Run `dependencies` first to confirm nothing references it.

**Signature**

```bash
celigo flows delete <id> [flags]
```

**Arguments**

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

**Flags**

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

**Example**

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

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

***

## `celigo flows audit`

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

**Signature**

```bash
celigo flows audit <id>
```

**Arguments**

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

**Example**

```bash
celigo flows audit 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/flows/{_id}/audit` (per-resource audit log; returns entries for the flow and its descendants).

***

## `celigo flows run`

Trigger a one-off flow run. Use `--start-time` / `--end-time` to override the delta window, or `--export-ids` to run a subset of a multi-generator flow.

> **The delta override flags were renamed in celigo-cli 2026.8.1.** They were `--start-date` and `--end-date`, which read as calendar dates but accept full timestamps. Use `--start-time` and `--end-time`.

**Signature**

```bash
celigo flows run <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                 | Type         | Default        | Description                                               |
| -------------------- | ------------ | -------------- | --------------------------------------------------------- |
| `--start-time <iso>` | ISO 8601     | —              | Start of the delta window. Maps to `lastExportDateTime`.  |
| `--end-time <iso>`   | ISO 8601     | —              | End of the delta window. Maps to `currentExportDateTime`. |
| `--export-ids <ids>` | string (csv) | all generators | Comma-separated export IDs to run.                        |
| `-y, --yes`          | boolean      | `false`        | Skip confirmation.                                        |

**Example**

```bash
celigo flows run 5f83a9b2c7d3e8f1a2b3c4d5 -y

# Backfill one day
celigo flows run 5f83a9b2c7d3e8f1a2b3c4d5 \
  --start-time 2026-04-01T00:00:00Z --end-time 2026-04-02T00:00:00Z -y
```

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

***

## `celigo flows clone`

Clone a flow into a target integration and environment. Same-env clones auto-build a self-map from the source flow's connections; cross-env clones require a `connectionMap` piped via stdin.

**Signature**

```bash
celigo flows clone <id> <integrationId> <environmentId> [flags]
```

**Arguments**

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

**Flags**

| Flag                | Type   | Default                 | Description                                  |
| ------------------- | ------ | ----------------------- | -------------------------------------------- |
| `--flow-group <id>` | string | —                       | Target flow group ID within the integration. |
| `--name <name>`     | string | `Clone - <source name>` | Name for the cloned flow.                    |

**Request body** (cross-env clones only)

Reads optional JSON on stdin:

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

**Example**

```bash
celigo flows clone 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f 7b2c3d4e5f6a7b8c9d0e1f2a
```

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

***

## `celigo flows errors`

Get open errors for a flow export or import step.

**Signature**

```bash
celigo flows errors <id> <exportOrImportId>
```

**Arguments**

| Argument             | Type   | Required | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `<id>`               | string | Yes      | Flow ID.                             |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow. |

**Example**

```bash
celigo flows errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f --format json | jq length
```

**Corresponds to**: [`GET /v1/flows/{_id}/{_exportOrImportId}/errors`](https://developer.celigo.com/api/api-reference/flows) (operationId: `listFlowStepErrors`)

***

## `celigo flows resolved-errors`

Get errors already marked resolved on a flow step.

**Signature**

```bash
celigo flows resolved-errors <id> <exportOrImportId>
```

**Arguments**

| Argument             | Type   | Required | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `<id>`               | string | Yes      | Flow ID.                             |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow. |

**Example**

```bash
celigo flows resolved-errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/flows/{_id}/{_exportOrImportId}/resolved`](https://developer.celigo.com/api/api-reference/flows) (operationId: `listFlowStepResolvedErrors`)

***

## `celigo flows resolve-errors`

Mark errors resolved. Pass a comma-separated `[errorIds]` list, or omit to resolve every open error on the step.

**Signature**

```bash
celigo flows resolve-errors <id> <exportOrImportId> [errorIds] [flags]
```

**Arguments**

| Argument             | Type         | Required | Description                                            |
| -------------------- | ------------ | -------- | ------------------------------------------------------ |
| `<id>`               | string       | Yes      | Flow ID.                                               |
| `<exportOrImportId>` | string       | Yes      | Export or import ID within the flow.                   |
| `[errorIds]`         | string (csv) | No       | Error IDs to resolve. Omit to resolve all open errors. |

**Flags**

| Flag        | Type    | Default | Description                           |
| ----------- | ------- | ------- | ------------------------------------- |
| `-y, --yes` | boolean | `false` | Skip confirmation when resolving all. |

**Example**

```bash
celigo flows resolve-errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`PUT /v1/flows/{_id}/{_exportOrImportId}/resolved`](https://developer.celigo.com/api/api-reference/flows) (operationId: `resolveFlowStepErrors`)

***

## `celigo flows error`

Get one open error on a flow step **by its error id**. With no flags it prints the error record. Two flags enrich it, each resolving a derived key off the error record so you only ever need the `errorId`:

* `--request-detail` — also fetch the captured HTTP request/response trace (via the error's `reqAndResKey`). If you already hold a `reqAndResKey` — e.g. from `debug-requests` — use `debug-request-detail` instead.
* `--retry-data` — also fetch the editable retry data (via the error's `retryDataKey`), the same payload you edit and pipe into `update-error-data`.

With either flag the output is a composite `{ error, requestResponse?, retryData? }`.

**Signature**

```bash
celigo flows error <id> <exportOrImportId> <errorId> [--request-detail] [--retry-data]
```

**Arguments**

| Argument             | Type   | Required | Description                                                                                                                                                                              |
| -------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`               | string | Yes      | Flow ID.                                                                                                                                                                                 |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow.                                                                                                                                                     |
| `<errorId>`          | string | Yes      | `errorId` from a `flows errors` entry. Record-level errors from non-HTTP adaptors have no stored trace (`--request-detail`) and only retryable errors carry retry data (`--retry-data`). |

**Example**

```bash
celigo flows error 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f 4694681992 --request-detail --retry-data
```

**Corresponds to**: [`GET /v1/flows/{_id}/{_exportOrImportId}/errors`](https://developer.celigo.com/api/api-reference/flows) (operationId: `listFlowStepErrors`), plus [`GET .../requests/{key}`](https://developer.celigo.com/api/api-reference/flows) (`getFlowStepRequestDetail`) with `--request-detail` and [`GET .../{retryDataKey}/data`](https://developer.celigo.com/api/api-reference/flows) (`getFlowStepErrorData`) with `--retry-data`.

***

## `celigo flows retry-errors`

Retry errors by `retryDataKey`. Pass a comma-separated `[retryDataKeys]` list, or omit to retry every open error.

**Signature**

```bash
celigo flows retry-errors <id> <exportOrImportId> [retryDataKeys] [flags]
```

**Arguments**

| Argument             | Type         | Required | Description                                         |
| -------------------- | ------------ | -------- | --------------------------------------------------- |
| `<id>`               | string       | Yes      | Flow ID.                                            |
| `<exportOrImportId>` | string       | Yes      | Export or import ID within the flow.                |
| `[retryDataKeys]`    | string (csv) | No       | Retry keys to retry. Omit to retry all open errors. |

**Flags**

| Flag        | Type    | Default | Description                          |
| ----------- | ------- | ------- | ------------------------------------ |
| `-y, --yes` | boolean | `false` | Skip confirmation when retrying all. |

**Example**

```bash
celigo flows retry-errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`POST /v1/flows/{_id}/{_exportOrImportId}/retry`](https://developer.celigo.com/api/api-reference/flows) (operationId: `retryFlowStepErrors`)

***

## `celigo flows assign-errors`

Assign errors to a user by email. Pass a comma-separated `[errorIds]` list, or omit to assign every open error.

**Signature**

```bash
celigo flows assign-errors <id> <exportOrImportId> <email> [errorIds] [flags]
```

**Arguments**

| Argument             | Type         | Required | Description                                          |
| -------------------- | ------------ | -------- | ---------------------------------------------------- |
| `<id>`               | string       | Yes      | Flow ID.                                             |
| `<exportOrImportId>` | string       | Yes      | Export or import ID within the flow.                 |
| `<email>`            | string       | Yes      | Assignee email address.                              |
| `[errorIds]`         | string (csv) | No       | Error IDs to assign. Omit to assign all open errors. |

**Flags**

| Flag        | Type    | Default | Description                           |
| ----------- | ------- | ------- | ------------------------------------- |
| `-y, --yes` | boolean | `false` | Skip confirmation when assigning all. |

**Example**

```bash
celigo flows assign-errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f ops@example.com -y
```

**Corresponds to**: [`PUT /v1/flows/{_id}/{_exportOrImportId}/errors/assign`](https://developer.celigo.com/api/api-reference/flows) (operationId: `assignFlowStepErrors`)

***

## `celigo flows unassign-errors`

Unassign errors on a flow step. Pass a comma-separated `[errorIds]` list, or omit to unassign every open error on the step.

**Signature**

```bash
celigo flows unassign-errors <id> <exportOrImportId> [errorIds] [flags]
```

**Arguments**

| Argument             | Type         | Required | Description                                              |
| -------------------- | ------------ | -------- | -------------------------------------------------------- |
| `<id>`               | string       | Yes      | Flow ID.                                                 |
| `<exportOrImportId>` | string       | Yes      | Export or import ID within the flow.                     |
| `[errorIds]`         | string (csv) | No       | Error IDs to unassign. Omit to unassign all open errors. |

**Flags**

| Flag        | Type    | Default | Description                             |
| ----------- | ------- | ------- | --------------------------------------- |
| `-y, --yes` | boolean | `false` | Skip confirmation when unassigning all. |

**Example**

```bash
celigo flows unassign-errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`PUT /v1/flows/{_id}/{_exportOrImportId}/errors/unassign`](https://developer.celigo.com/api/api-reference/flows) (operationId: `unassignFlowStepErrors`)

***

## `celigo flows delete-resolved-errors`

Delete resolved errors. Pass a comma-separated `[errorIds]` list, or omit to delete every resolved error on the step.

> ⚠️ **Deleting resolved errors is permanent.** Purged error records cannot be recovered. Omitting `[errorIds]` deletes every resolved error on the step.

**Signature**

```bash
celigo flows delete-resolved-errors <id> <exportOrImportId> [errorIds] [flags]
```

**Arguments**

| Argument             | Type         | Required | Description                                              |
| -------------------- | ------------ | -------- | -------------------------------------------------------- |
| `<id>`               | string       | Yes      | Flow ID.                                                 |
| `<exportOrImportId>` | string       | Yes      | Export or import ID within the flow.                     |
| `[errorIds]`         | string (csv) | No       | Error IDs to delete. Omit to delete all resolved errors. |

**Flags**

| Flag        | Type    | Default | Description                          |
| ----------- | ------- | ------- | ------------------------------------ |
| `-y, --yes` | boolean | `false` | Skip confirmation when deleting all. |

**Example**

```bash
celigo flows delete-resolved-errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`DELETE /v1/flows/{_id}/{_exportOrImportId}/resolved`](https://developer.celigo.com/api/api-reference/flows) (operationId: `deleteFlowStepResolvedErrors`)

***

## `celigo flows update-error-data`

Update an error's retry data before retrying. Pass the **error id** — the CLI resolves the error's `retryDataKey` internally — and pipe the modified data object via stdin (typically from `flows error --retry-data` output).

**Signature**

```bash
celigo flows update-error-data <id> <exportOrImportId> <errorId>
```

**Arguments**

| Argument             | Type   | Required | Description                                                        |
| -------------------- | ------ | -------- | ------------------------------------------------------------------ |
| `<id>`               | string | Yes      | Flow ID.                                                           |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow.                               |
| `<errorId>`          | string | Yes      | `errorId` from a `flows errors` entry (same key as `flows error`). |

**Request body**

Reads JSON on stdin. See the `PUT /v1/flows/{_id}/{_exportOrImportId}/{retryDataKey}/data` schema for the full payload shape.

**Example**

```bash
celigo flows error 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f 4694681992 --retry-data --format json \
  | jq '.retryData.data.quantity = 5' \
  | celigo flows update-error-data 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f 4694681992
```

**Corresponds to**: [`PUT /v1/flows/{_id}/{_exportOrImportId}/{retryDataKey}/data`](https://developer.celigo.com/api/api-reference/flows) (operationId: `updateFlowStepErrorData`)

***

## `celigo flows tag-errors`

Update tags on a batch of errors. `tagIds` uses the short tag code from `tags list` (the `tagId` field, e.g. `F3ZBQ`), not the Mongo `_id`. An empty `tagIds` array clears all tags.

**Signature**

```bash
celigo flows tag-errors <id> <exportOrImportId>
```

**Arguments**

| Argument             | Type   | Required | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `<id>`               | string | Yes      | Flow ID.                             |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow. |

**Request body**

Reads JSON on stdin:

```json
{"errors":[{"id":"<errorId>","rdk":"<retryDataKey>"}],"tagIds":["F3ZBQ"]}
```

See the `PUT /v1/flows/{_id}/{_exportOrImportId}/tags` schema for the full payload shape.

**Example**

```bash
echo '{"errors":[{"id":"abc","rdk":"xyz"}],"tagIds":["F3ZBQ"]}' \
  | celigo flows tag-errors 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`PUT /v1/flows/{_id}/{_exportOrImportId}/tags`](https://developer.celigo.com/api/api-reference/flows) (operationId: `updateFlowStepErrorTags`)

***

## `celigo flows error-summary`

Summarize a flow's open errors, with a count and the last error time per step. One request returns the flow-level rollup, and the command reports only steps with at least one open error.

Output columns: `stepId`, `openErrors`, `lastErrorAt`. In `table` format, a flow with no open errors prints a confirmation message. In `json` format it prints `[]`, so downstream parsing stays valid.

**Signature**

```bash
celigo flows error-summary <id>
```

**Arguments**

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

**Example**

```bash
celigo flows error-summary 5f83a9b2c7d3e8f1a2b3c4d5

# The step that failed most recently
celigo flows error-summary 5f83a9b2c7d3e8f1a2b3c4d5 --jq 'max_by(.lastErrorAt)'
```

**Corresponds to**: [`GET /v1/flows/{_id}/errors`](https://developer.celigo.com/api/api-reference/flows), the flow-level error rollup. One request covers every step.

***

## `celigo flows error-analysis`

Fetch a sample of errors on a step and group by `code` + `message`, counting occurrences. Client-side analysis over `listFlowStepErrors`.

**Signature**

```bash
celigo flows error-analysis <id> <exportOrImportId> [flags]
```

**Arguments**

| Argument             | Type   | Required | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `<id>`               | string | Yes      | Flow ID.                             |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow. |

**Flags**

| Flag          | Type    | Default | Description            |
| ------------- | ------- | ------- | ---------------------- |
| `--limit <n>` | integer | `100`   | Max errors to analyze. |

**Example**

```bash
celigo flows error-analysis 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f --limit 500
```

**Corresponds to**: [`GET /v1/flows/{_id}/{_exportOrImportId}/errors`](https://developer.celigo.com/api/api-reference/flows) (operationId: `listFlowStepErrors`)

***

## `celigo flows add-processor`

Add a page processor to a flow (auto-detects whether the ID is an export or import). For router-based flows, `--router` and optionally `--branch` are required.

> **Instance flows are refused.** All four structural commands (`add-processor`, `remove-processor`, `add-generator`, `remove-generator`) reject an instance-flow target up front, before the confirmation prompt and the PUT: an instance inherits its whole graph from its abstract flow, and the server rejects structural fields on an instance write (`422 flow_instance_invalid_fields`). The error names the abstract flow to edit instead — structural changes there propagate to every instance automatically; per-instance customization goes through `overrides`.

**Signature**

```bash
celigo flows add-processor <id> <exportOrImportId> [flags]
```

**Arguments**

| Argument             | Type   | Required | Description                                |
| -------------------- | ------ | -------- | ------------------------------------------ |
| `<id>`               | string | Yes      | Flow ID.                                   |
| `<exportOrImportId>` | string | Yes      | Export or import ID to add as a processor. |

**Flags**

| Flag                    | Type    | Default | Description                                                |
| ----------------------- | ------- | ------- | ---------------------------------------------------------- |
| `--router <routerId>`   | string  | —       | Target a specific router. Required for router-based flows. |
| `--branch <branchName>` | string  | —       | Target a specific branch within the router.                |
| `-y, --yes`             | boolean | `false` | Skip confirmation.                                         |

**Example**

```bash
celigo flows add-processor 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`GET /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#get-v1-flows-_id) (operationId: `getFlowById`) → [`PUT /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#put-v1-flows-_id) (operationId: `updateFlow`)

***

## `celigo flows remove-processor`

Remove a page processor from a flow by its export or import ID.

**Signature**

```bash
celigo flows remove-processor <id> <exportOrImportId> [flags]
```

**Arguments**

| Argument             | Type   | Required | Description                                     |
| -------------------- | ------ | -------- | ----------------------------------------------- |
| `<id>`               | string | Yes      | Flow ID.                                        |
| `<exportOrImportId>` | string | Yes      | Export or import ID of the processor to remove. |

**Flags**

| Flag                    | Type    | Default | Description                                 |
| ----------------------- | ------- | ------- | ------------------------------------------- |
| `--router <routerId>`   | string  | —       | Target a specific router.                   |
| `--branch <branchName>` | string  | —       | Target a specific branch within the router. |
| `-y, --yes`             | boolean | `false` | Skip confirmation.                          |

**Example**

```bash
celigo flows remove-processor 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`GET /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#get-v1-flows-_id) (operationId: `getFlowById`) → [`PUT /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#put-v1-flows-_id) (operationId: `updateFlow`)

***

## `celigo flows add-generator`

Add a page generator (export) to a flow. Appends to the end of `pageGenerators` by default; `--index` inserts at a specific 0-based position. `--schedule` sets a per-generator cron override.

**Signature**

```bash
celigo flows add-generator <id> <exportId> [flags]
```

**Arguments**

| Argument     | Type   | Required | Description                      |
| ------------ | ------ | -------- | -------------------------------- |
| `<id>`       | string | Yes      | Flow ID.                         |
| `<exportId>` | string | Yes      | Export ID to add as a generator. |

**Flags**

| Flag                 | Type         | Default | Description                      |
| -------------------- | ------------ | ------- | -------------------------------- |
| `--index <position>` | integer      | append  | 0-based insert position.         |
| `--schedule <cron>`  | 6-field cron | —       | Per-generator schedule override. |
| `-y, --yes`          | boolean      | `false` | Skip confirmation.               |

**Example**

```bash
celigo flows add-generator 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f --schedule '? */5 * * * *' -y
```

**Corresponds to**: [`GET /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#get-v1-flows-_id) (operationId: `getFlowById`) → [`PUT /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#put-v1-flows-_id) (operationId: `updateFlow`)

***

## `celigo flows remove-generator`

Remove a page generator from a flow by export ID.

**Signature**

```bash
celigo flows remove-generator <id> <exportId> [flags]
```

**Arguments**

| Argument     | Type   | Required | Description                           |
| ------------ | ------ | -------- | ------------------------------------- |
| `<id>`       | string | Yes      | Flow ID.                              |
| `<exportId>` | string | Yes      | Export ID of the generator to remove. |

**Flags**

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

**Example**

```bash
celigo flows remove-generator 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`GET /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#get-v1-flows-_id) (operationId: `getFlowById`) → [`PUT /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#put-v1-flows-_id) (operationId: `updateFlow`)

***

## `celigo flows replace-connection`

Swap a connection across every export and import in a flow.

**Signature**

```bash
celigo flows replace-connection <id> <oldConnectionId> <newConnectionId>
```

**Arguments**

| Argument            | Type   | Required | Description                                             |
| ------------------- | ------ | -------- | ------------------------------------------------------- |
| `<id>`              | string | Yes      | Flow ID.                                                |
| `<oldConnectionId>` | string | Yes      | Connection ID currently referenced by the flow's steps. |
| `<newConnectionId>` | string | Yes      | Connection ID to swap in.                               |

**Example**

```bash
celigo flows replace-connection 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f 7b2c3d4e5f6a7b8c9d0e1f2a
```

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

***

## `celigo flows set-group`

Assign one or more flows to a flow group (a section defined on the integration via [`integrations create-flow-group`](/cli/commands/integrations.md#celigo-integrations-create-flow-group)). Group *membership* is a property of the flows, not the integration — which is why this lives under `flows`.

**Signature**

```bash
celigo flows set-group <flowGroupingId> <flowIds...>
```

**Arguments**

| Argument           | Type              | Required | Description                                                                                                                |
| ------------------ | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `<flowGroupingId>` | string            | Yes      | Flow group ID (must be non-empty). To remove flows from their group, use [`flows unset-group`](#celigo-flows-unset-group). |
| `<flowIds...>`     | string (variadic) | Yes      | One or more flow IDs to set.                                                                                               |

**Flags**

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

**Example**

```bash
celigo flows set-group grp123 flow1 flow2
```

**Corresponds to**: [`PUT /v1/flows/updateFlowGrouping`](https://developer.celigo.com/api/api-reference/flows#put-v1-flows-updateflowgrouping)

***

## `celigo flows unset-group`

Remove one or more flows from their flow group, leaving them ungrouped. (Calls the same endpoint as `set-group` with an empty group id.)

**Signature**

```bash
celigo flows unset-group <flowIds...>
```

**Arguments**

| Argument       | Type              | Required | Description                                      |
| -------------- | ----------------- | -------- | ------------------------------------------------ |
| `<flowIds...>` | string (variadic) | Yes      | One or more flow IDs to remove from their group. |

**Example**

```bash
celigo flows unset-group flow1 flow2
```

**Corresponds to**: [`PUT /v1/flows/updateFlowGrouping`](https://developer.celigo.com/api/api-reference/flows#put-v1-flows-updateflowgrouping) (empty `_flowGroupingId`)

***

## `celigo flows debug-requests`

List debug HTTP request log entries for an export or import step. Requires `debugUntil` to be set on the export or import (run `celigo exports enable-debug` / `celigo imports enable-debug` first).

**Signature**

```bash
celigo flows debug-requests <id> <exportOrImportId> [flags]
```

**Arguments**

| Argument             | Type   | Required | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `<id>`               | string | Yes      | Flow ID.                             |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow. |

**Flags**

| Flag                | Type    | Default | Description                            |
| ------------------- | ------- | ------- | -------------------------------------- |
| `--since <minutes>` | integer | `60`    | Show requests from the last N minutes. |

**Example**

```bash
celigo flows debug-requests 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f --since 30
```

**Corresponds to**: [`GET /v1/flows/{_id}/{_exportOrImportId}/requests?time_gt=<ms>`](https://developer.celigo.com/api/api-reference/flows)

***

## `celigo flows debug-request-detail`

Full request/response payload for one debug log entry.

**Signature**

```bash
celigo flows debug-request-detail <id> <exportOrImportId> <key>
```

**Arguments**

| Argument             | Type   | Required | Description                              |
| -------------------- | ------ | -------- | ---------------------------------------- |
| `<id>`               | string | Yes      | Flow ID.                                 |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow.     |
| `<key>`              | string | Yes      | Request key from `flows debug-requests`. |

**Example**

```bash
celigo flows debug-request-detail 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f abcd1234
```

**Corresponds to**: [`GET /v1/flows/{_id}/{_exportOrImportId}/requests/{key}`](https://developer.celigo.com/api/api-reference/flows) (operationId: `getFlowStepRequestDetail`)

***

## `celigo flows delete-debug-requests`

Delete stored HTTP request/response traces for a flow step. Pass `reqAndResKeys` (comma-separated) to delete specific traces, or omit them to clear every trace referenced by the step's current errors. The error records themselves remain (their `reqAndResKey` pointers dangle). Prompts for confirmation unless `-y`.

> ⚠️ **Deleting request traces is permanent.** The stored request/response captures are removed and cannot be recovered; the error records keep dangling `reqAndResKey` pointers.

**Signature**

```bash
celigo flows delete-debug-requests <id> <exportOrImportId> [reqAndResKeys] [-y]
```

**Arguments**

| Argument             | Type   | Required | Description                                                                                  |
| -------------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `<id>`               | string | Yes      | Flow ID.                                                                                     |
| `<exportOrImportId>` | string | Yes      | Export or import ID within the flow.                                                         |
| `[reqAndResKeys]`    | string | No       | Comma-separated `reqAndResKey` values. Omit to clear all of the step's current error traces. |

**Example**

```bash
celigo flows delete-debug-requests 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`DELETE /v1/flows/{_id}/{_stepId}/requests`](https://developer.celigo.com/api/api-reference/flows) (operationId: `deleteFlowStepRequests`) — body `{ "keys": [...] }`; the CLI enumerates the step's error traces when keys are omitted.

***

## `celigo flows test-run`

Start a test run and return stage-by-stage results. The flow must be `disabled: true` (the API returns `403 Forbidden` for enabled flows) and `--export` (a page generator export ID) is required.

**Signature**

```bash
celigo flows test-run <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                  | Type   | Default | Description                                     |
| --------------------- | ------ | ------- | ----------------------------------------------- |
| `--export <exportId>` | string | —       | Export ID (page generator). Required for flows. |

**Example**

```bash
celigo flows test-run 5f83a9b2c7d3e8f1a2b3c4d5 --export 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`POST /v1/flows/{_id}/test/run`](https://developer.celigo.com/api/api-reference/flows)

***

## `celigo flows test-run-step-results`

Get stage-by-stage results for one step in a test run. Base64-encoded responses are auto-decoded.

**Signature**

```bash
celigo flows test-run-step-results <id> <runId> <exportOrImportId>
```

**Arguments**

| Argument             | Type   | Required | Description                             |
| -------------------- | ------ | -------- | --------------------------------------- |
| `<id>`               | string | Yes      | Flow ID.                                |
| `<runId>`            | string | Yes      | Test run ID (from `test-run` response). |
| `<exportOrImportId>` | string | Yes      | Step ID (from test-run metadata).       |

**Example**

```bash
celigo flows test-run-step-results 5f83a9b2c7d3e8f1a2b3c4d5 run_abc123 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/flows/{_id}/test/run/{runId}/{_stepId}`](https://developer.celigo.com/api/api-reference/flows)

***

## `celigo flows test-run-step-logs`

HTTP request/response logs for a test-run step. Only steps that issued outbound HTTP calls (exports, imports, lookups) produce logs — others return `404 Not Found`.

**Signature**

```bash
celigo flows test-run-step-logs <id> <runId> <exportOrImportId>
```

**Arguments**

| Argument             | Type   | Required | Description                             |
| -------------------- | ------ | -------- | --------------------------------------- |
| `<id>`               | string | Yes      | Flow ID.                                |
| `<runId>`            | string | Yes      | Test run ID (from `test-run` response). |
| `<exportOrImportId>` | string | Yes      | Step ID (from test-run metadata).       |

**Example**

```bash
celigo flows test-run-step-logs 5f83a9b2c7d3e8f1a2b3c4d5 run_abc123 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/flows/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse`](https://developer.celigo.com/api/api-reference/flows#get-v1-flows-_id-test-run-runid-_stepid-logs-requestandresponse) (operationId: `getFlowTestRunStepLogs`)

***

## `celigo flows enable-execution-logs`

Arm debug execution logging on a flow. Sets `logging.debugUntil` via JSON-patch. Subsequent runs capture detailed per-stage logs viewable via `execution-logs`, `query-execution-logs`, and `execution-log-detail`.

**Signature**

```bash
celigo flows enable-execution-logs <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                   | Type          | Default | Description                        |
| ---------------------- | ------------- | ------- | ---------------------------------- |
| `--duration <minutes>` | integer (≤60) | `60`    | Debug window length. Capped at 60. |

**Example**

```bash
celigo flows enable-execution-logs 5f83a9b2c7d3e8f1a2b3c4d5 --duration 30
```

**Corresponds to**: [`PATCH /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#patch-v1-flows-_id) with `[{op:"replace", path:"/logging/debugUntil", value:<iso>}]`

***

## `celigo flows disable-execution-logs`

Disarm debug execution logging on a flow (removes `logging.debugUntil`).

**Signature**

```bash
celigo flows disable-execution-logs <id>
```

**Arguments**

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

**Example**

```bash
celigo flows disable-execution-logs 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PATCH /v1/flows/{_id}`](https://developer.celigo.com/api/api-reference/flows#patch-v1-flows-_id) with `[{op:"remove", path:"/logging/debugUntil"}]`

***

## `celigo flows execution-logs`

List execution log entries for a flow run. Each entry has `recordId`, `groupId`, `traceKey`, and `_expOrImpId` — feed these to `query-execution-logs` and `execution-log-detail` to drill into per-step traces.

**Signature**

```bash
celigo flows execution-logs <id> <jobId>
```

**Arguments**

| Argument  | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| `<id>`    | string | Yes      | Flow ID.                                 |
| `<jobId>` | string | Yes      | Job ID from `jobs list` / `jobs latest`. |

**Example**

```bash
celigo flows execution-logs 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/flows/{_id}/jobs/{jobId}/logs`](https://developer.celigo.com/api/api-reference/flows) (operationId: `listFlowExecutionLogs`)

***

## `celigo flows query-execution-logs`

Search execution log metadata for a step. Pass `--trace-key` to widen results to every step sharing that trace (both the export side and the import side).

**Signature**

```bash
celigo flows query-execution-logs <id> <jobId> --export-or-import-id <id> --group-id <id> --record-id <id> [flags]
```

**Arguments**

| Argument  | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `<id>`    | string | Yes      | Flow ID.    |
| `<jobId>` | string | Yes      | Job ID.     |

**Flags**

| Flag                         | Type   | Default | Description                                        |
| ---------------------------- | ------ | ------- | -------------------------------------------------- |
| `--export-or-import-id <id>` | string | —       | **Required.** Export or import ID.                 |
| `--group-id <id>`            | string | —       | **Required.** Group ID from `execution-logs`.      |
| `--record-id <id>`           | string | —       | **Required.** Record ID from `execution-logs`.     |
| `--trace-key <key>`          | string | —       | Trace key — enables traceView across paired steps. |

**Example**

```bash
celigo flows query-execution-logs 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f \
  --export-or-import-id 7b2c3d4e5f6a7b8c9d0e1f2a \
  --group-id g_abc --record-id r_xyz
```

**Corresponds to**: [`POST /v1/flows/{_id}/jobs/{jobId}/logs/metadata/query`](https://developer.celigo.com/api/api-reference/flows) (operationId: `queryFlowExecutionLogMetadata`)

***

## `celigo flows execution-log-detail`

Get per-stage execution log data for a step in a flow run. Use `--stage apiCall` to get HTTP request/response traces on `HTTPExport` / `HTTPImport` steps; other stages (`preMap`, `postMap`, `postSubmit`, `postResponseMap`) are populated only when the script hook calls `options.logs.push(...)`.

**Signature**

```bash
celigo flows execution-log-detail <id> <jobId> --export-or-import-id <id> --stage <stage> --group-id <id> --record-id <id>
```

**Arguments**

| Argument  | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `<id>`    | string | Yes      | Flow ID.    |
| `<jobId>` | string | Yes      | Job ID.     |

**Flags**

| Flag                         | Type   | Default | Description                                                                                           |
| ---------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `--export-or-import-id <id>` | string | —       | **Required.** Export or import ID.                                                                    |
| `--stage <stage>`            | string | —       | **Required.** Execution stage (e.g. `apiCall`, `preMap`, `postMap`, `postSubmit`, `postResponseMap`). |
| `--group-id <id>`            | string | —       | **Required.** Group ID from `execution-logs`.                                                         |
| `--record-id <id>`           | string | —       | **Required.** Record ID from `execution-logs`.                                                        |

**Example**

```bash
celigo flows execution-log-detail 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f \
  --export-or-import-id 7b2c3d4e5f6a7b8c9d0e1f2a \
  --stage apiCall --group-id g_abc --record-id r_xyz
```

**Corresponds to**: [`POST /v1/flows/{_id}/jobs/{jobId}/logs/data/query`](https://developer.celigo.com/api/api-reference/flows) (operationId: `queryFlowExecutionLogData`)

***

## `celigo flows last-export-date`

Get the flow-level delta checkpoint, the most recent export timestamp across all generators in the flow.

**Signature**

```bash
celigo flows last-export-date <id>
```

**Arguments**

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

**Example**

```bash
celigo flows last-export-date 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo flows dependencies`

List resources that depend on this flow (alias: `used-by`). Use it to check whether a flow is safe to delete; an empty result means nothing references it.

**Signature**

```bash
celigo flows dependencies <id>
```

**Arguments**

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

**Example**

```bash
celigo flows dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/flows/{_id}/dependencies`](https://developer.celigo.com/api/api-reference/flows) (operationId: `listFlowDependencies`)

***

## `celigo flows delete-execution-logs`

Delete a flow's execution logs within a time range. `--started-gte` and `--started-lte` are required ISO 8601 timestamps, and `--started-gte` must be before `--started-lte`. The command prompts for confirmation unless you pass `-y`.

> **These flags were renamed in celigo-cli 2026.8.1.** They were `--started-at` and `--end-at`. The new names match the `--*-gte` / `--*-lte` pattern used for every date bound in the CLI.

> ⚠️ **Deleting execution logs is permanent.** Logs in the given time range are removed and cannot be recovered.

**Signature**

```bash
celigo flows delete-execution-logs <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                  | Type     | Default | Description                                                                                            |
| --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `--started-gte <iso>` | ISO 8601 | —       | **Required.** Delete logs with `startedAt` at or after this timestamp.                                 |
| `--started-lte <iso>` | ISO 8601 | —       | **Required.** Delete logs with `startedAt` at or before this timestamp. Must be after `--started-gte`. |
| `-y, --yes`           | boolean  | `false` | Skip confirmation.                                                                                     |

**Example**

```bash
celigo flows delete-execution-logs 5f83a9b2c7d3e8f1a2b3c4d5 \
  --started-gte 2026-06-01T00:00:00Z --started-lte 2026-06-02T00:00:00Z -y
```

**Corresponds to**: [`DELETE /v1/flows/{_id}/logs`](https://developer.celigo.com/api/api-reference/flows) (operationId: `deleteFlowLogs`)

***

## `celigo flows cancel-jobs`

Cancel a flow's jobs. Optionally scope the cancellation with a JSON body (piped via stdin, or `--file`). Prompts for confirmation unless `-y`.

> ⚠️ **Canceling a flow's jobs is irreversible.** In-progress and queued jobs are stopped and cannot be resumed. Records already processed are not rolled back.

**Signature**

```bash
celigo flows cancel-jobs <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                | Type    | Default | Description                         |
| ------------------- | ------- | ------- | ----------------------------------- |
| `-y, --yes`         | boolean | `false` | Skip confirmation.                  |
| `-f, --file <path>` | string  | stdin   | JSON body file (or pipe via stdin). |

**Example**

```bash
celigo flows cancel-jobs 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: [`POST /v1/flows/{_id}/jobs/cancel`](https://developer.celigo.com/api/api-reference/flows) (operationId: `cancelFlowJobs`)

## Gotchas

* **Create flows with `disabled: true`.** Enable only after mappings and connections are verified — `test-run` also requires the flow to be disabled (the API returns `403 Forbidden` on enabled flows).
* **`responseMapping` lives on the flow**, under the `pageProcessors[]` entry — not on the import. Its `fields`/`lists` are **bare arrays**: the API accepts the old object-wrapper shape without an error and silently corrupts the step's mappings (see the warning at the top of this page).
* **Instance flows are structural no-go zones.** The structural commands refuse them client-side, and any other path to a structural write (e.g. a structural `flows set`) hits the server's `422 flow_instance_invalid_fields`. Edit the abstract flow instead; customize an instance only through `overrides`.
* **Plain lists exclude instance flows.** `flows list` omits instances unless you pass `--include-instances` (or `--abstract-flow-id`, which implies it). If a flow id from a job or the UI is missing from your list, it is probably an instance.
* **`schedule` is a 6-field cron** (seconds first): `"? */5 * * * *"` runs every five minutes.
* **Router IDs must be unique within a flow**, and `nextRouterId` must match a real router `id`.
* **`update` is a full replace** (PUT). Use `set` for field edits unless you're supplying the complete resource body.
* **`debug-requests` vs. `execution-logs` are different surfaces.** `debug-requests` reads per-export/per-import debug captures (armed by `exports enable-debug` / `imports enable-debug`). `execution-logs` reads flow-level per-record execution traces (armed by `flows enable-execution-logs`).
* **`test-run-step-logs` returns `404 Not Found` for non-HTTP steps by design.** Routers and steps that did not issue outbound HTTP traffic have no request/response logs.
* **`tag-errors` uses the short `tagId` code** from `tags list` (e.g. `F3ZBQ`), not the Mongo `_id`.

## Related

* [exports](/cli/commands/exports.md) — page generators that feed the flow.
* [imports](/cli/commands/imports.md) — page processors that consume flow records.
* [integrations](/cli/commands/integrations.md) — the container that owns flows.
* [jobs](/cli/commands/jobs.md) — execution history for flow runs.


---

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