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

# syncs

Replicate data continuously from a source application into a data warehouse. Syncs are Celigo Data Ingestion pipelines. A sync belongs to an integration and pairs a source connection with a destination database and schema. Which tables or objects it replicates is configured with [datasets](/cli/commands/datasets.md).

This group builds, runs, and monitors syncs. To inspect or cancel the individual runs a sync produces, use [sync-jobs](/cli/commands/sync-jobs.md). For editions, entitlements, and how syncs compare to flows, see [What is Celigo sync?](https://docs.celigo.com/hc/en-us/articles/49523952843035-What-is-Celigo-sync) in the Help Center.

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

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

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

## Subcommands

| Subcommand             | Purpose                                                         |
| ---------------------- | --------------------------------------------------------------- |
| `list`                 | List the syncs in the account.                                  |
| `get <id>`             | Fetch one sync by ID.                                           |
| `create`               | Create a sync from a JSON body (`--file <path>` or stdin).      |
| `update <id>`          | Full replace from a JSON body. Omitted fields are erased.       |
| `set <id> key=value …` | Targeted field edit.                                            |
| `delete <id>`          | Delete a sync.                                                  |
| `run <syncId>`         | Trigger a run of a sync.                                        |
| `cancel-jobs <syncId>` | Cancel all running jobs for a sync.                             |
| `audit <syncId>`       | Show the audit log (change history) for a sync.                 |
| `events <syncId>`      | List schema drift and data catalog events across a sync's runs. |
| `usage`                | Report records loaded, per sync, per month, or per environment. |
| `sources`              | List the applications supported as a sync source.               |
| `destinations`         | List the applications supported as a sync destination.          |

***

## `celigo syncs list`

List the syncs in the account.

**Signature**

```bash
celigo syncs list [flags]
```

**Arguments**

None.

**Flags**

| Flag                 | Type    | Default   | Description                                                                                                                                                                                                                         |
| -------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--integration <id>` | string  | —         | List only syncs belonging to this integration.                                                                                                                                                                                      |
| `--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.                                                                                                                                                                                  |

**Example**

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

# Complete sync documents, including schedule and destination settings
celigo syncs list --fields all
```

Default table columns: `_id`, `name`, `_integrationId`, `disabled`. A `lastExecutedAt` column was removed in celigo-cli 2026.9.1 because the sync document carries no such field — run timing lives on [`sync-jobs list`](/cli/commands/sync-jobs.md).

**Corresponds to**: [`GET /v1/syncs`](https://developer.celigo.com/api/api-reference/syncs)

***

## `celigo syncs get`

Fetch one sync by ID, with its complete configuration.

**Signature**

```bash
celigo syncs get <id>
```

**Arguments**

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

**Example**

```bash
celigo syncs get 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo syncs create`

Create a sync from a JSON body. Read the body from a file with `-f, --file`, or pipe it on stdin.

**Signature**

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

**Flags**

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

**Request body**

A JSON object matching the `POST /v1/syncs` request schema. The sync names its parent integration, its source connection, and its destination database and schema.

**Example**

```bash
celigo syncs create --file ./sync.json
```

**Corresponds to**: [`POST /v1/syncs`](https://developer.celigo.com/api/api-reference/syncs)

***

## `celigo syncs update`

Replace a sync from a JSON body.

> ⚠️ **`update` replaces the entire sync.** `PUT` erases any field you omit, including the schedule and destination settings. Run `celigo syncs get <id>` first, edit the result, then send the complete object back. For a single field, use `set`.

**Signature**

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

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo syncs update 5f83a9b2c7d3e8f1a2b3c4d5 --file ./sync.json
```

**Corresponds to**: [`PUT /v1/syncs/{_id}`](https://developer.celigo.com/api/api-reference/syncs)

***

## `celigo syncs set`

Edit named fields on a sync without sending the whole document. Whitelisted fields such as `name`, `debugUntil`, and `schedule.*` apply through an atomic `PATCH`. Other fields round-trip `GET`, modify, then `PUT`, so omitted fields survive.

**Signature**

```bash
celigo syncs set <id> <key=value> [key=value ...]
```

**Arguments**

| Argument      | Type   | Required | Description                                                                                                                                                          |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`        | string | Yes      | Sync ID.                                                                                                                                                             |
| `<key=value>` | string | Yes (≥1) | Field assignments. Values are JSON-parsed first, so `disabled=false` becomes a boolean. `key=null` removes the field. Dot notation and array indexing are supported. |

**Example**

```bash
celigo syncs set 5f83a9b2c7d3e8f1a2b3c4d5 name="Salesforce to Snowflake"
celigo syncs set 5f83a9b2c7d3e8f1a2b3c4d5 debugUntil=null
```

**Corresponds to**: `PATCH /v1/syncs/{_id}` for whitelisted fields, otherwise [`GET`](https://developer.celigo.com/api/api-reference/syncs) followed by `PUT /v1/syncs/{_id}`.

***

## `celigo syncs delete`

Delete a sync. The command prompts for confirmation unless you pass `-y`.

> ⚠️ **Deleting a sync removes its datasets and run history.** The data already written to the destination warehouse stays there. Recover a deleted sync from the [Recycle Bin](/cli/commands/recycle-bin.md) if the retention window has not passed.

**Signature**

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

**Arguments**

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

**Flags**

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

**Example**

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

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

***

## `celigo syncs run`

Trigger a run of a sync.

**Signature**

```bash
celigo syncs run <syncId>
```

**Arguments**

| Argument   | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `<syncId>` | string | Yes      | Sync ID.    |

**Example**

```bash
celigo syncs run 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`POST /v1/syncs/{_syncId}/run`](https://developer.celigo.com/api/api-reference/syncs) (operationId: `runSync`)

The response carries a `flowExecutionGroupId`. Pass it to `syncs events --run` to see what that run produced.

***

## `celigo syncs cancel-jobs`

Cancel every running job for a sync. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Cancelling all jobs cannot be undone.** Every running job for the sync stops immediately, which can leave data partially synced. Re-run the sync to finish.

**Signature**

```bash
celigo syncs cancel-jobs <syncId> [flags]
```

**Arguments**

| Argument   | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `<syncId>` | string | Yes      | Sync ID.    |

**Flags**

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

**Example**

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

**Corresponds to**: [`PUT /v1/syncs/{_syncId}/syncJobs/cancel`](https://developer.celigo.com/api/api-reference/syncs) (operationId: `cancelSyncJobs`)

***

## `celigo syncs audit`

Show the audit log (change history) for a sync.

**Signature**

```bash
celigo syncs audit <syncId>
```

**Arguments**

| Argument   | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `<syncId>` | string | Yes      | Sync ID.    |

**Example**

```bash
celigo syncs audit 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/syncs/{_syncId}/audit`](https://developer.celigo.com/api/api-reference/syncs) (operationId: `getSyncAudit`)

***

## `celigo syncs events`

List a sync's events across all of its runs, newest first. Events fall into two categories:

| Category       | What it records                                                                |
| -------------- | ------------------------------------------------------------------------------ |
| `Schema Drift` | Schema changes detected in the source, and changes applied to the destination. |
| `Data Catalog` | Dataset metadata activity while the source is being cataloged.                 |

Use this to answer why a destination table changed shape, or why a dataset stopped replicating a column.

**Signature**

```bash
celigo syncs events <syncId> [flags]
```

**Arguments**

| Argument   | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `<syncId>` | string | Yes      | Sync ID.    |

**Flags**

| Flag                     | Type     | Default   | Description                                                                                           |
| ------------------------ | -------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `--type <type>`          | string   | —         | Filter to one category: `"Schema Drift"` or `"Data Catalog"`. Quote the value — both contain a space. |
| `--resource-name <name>` | string   | —         | Filter to one source table or object, for example `Account`.                                          |
| `--run <runId>`          | string   | —         | Filter to one run. Use the `flowExecutionGroupId` that `syncs run` returns.                           |
| `--time-gte <iso>`       | ISO 8601 | —         | Return events after this timestamp. Must not be in the future.                                        |
| `--time-lte <iso>`       | ISO 8601 | —         | Return events at or before this timestamp.                                                            |
| `--limit <n>`            | integer  | all pages | Max events to return, from 1 to 1000, in a single request. Without it, the CLI collects every page.   |

**Example**

```bash
# Every event for a sync, newest first
celigo syncs events 5f83a9b2c7d3e8f1a2b3c4d5 --format table

# Schema changes on one object
celigo syncs events 5f83a9b2c7d3e8f1a2b3c4d5 \
  --type "Schema Drift" --resource-name Account

# Everything one run produced
celigo syncs events 5f83a9b2c7d3e8f1a2b3c4d5 --run 60a1b2c3d4e5f6a7b8c9d0e1
```

**Corresponds to**: [`GET /v1/syncs/{_syncId}/events`](https://developer.celigo.com/api/api-reference/syncs)

***

## `celigo syncs usage`

Report the volume of records loaded. By default, `usage` reports per sync for the current calendar month in UTC. `--by` changes the breakdown.

| `--by` value  | Result                                                                              |
| ------------- | ----------------------------------------------------------------------------------- |
| omitted       | Per sync, current calendar month.                                                   |
| `month`       | Account-wide monthly history against the license entitlement, up to 14 months back. |
| `environment` | Per environment, current month.                                                     |

**Signature**

```bash
celigo syncs usage [flags]
```

**Arguments**

None.

**Flags**

| Flag               | Type   | Default | Description                                                                  |
| ------------------ | ------ | ------- | ---------------------------------------------------------------------------- |
| `--by <dimension>` | string | —       | Break down by `month` or `environment` instead of per sync.                  |
| `--from <YYYY-MM>` | string | —       | First month to include. Requires `--by month`.                               |
| `--to <YYYY-MM>`   | string | —       | Last month to include. Requires `--by month`, and must not be in the future. |

**Example**

```bash
# Records loaded per sync this month
celigo syncs usage --format table

# Monthly history against the license entitlement
celigo syncs usage --by month --from 2026-01 --to 2026-08

# This month, split by environment
celigo syncs usage --by environment
```

**Corresponds to**: the sync usage endpoints under [Syncs](https://developer.celigo.com/api/api-reference/syncs). `--by month` rows carry an `entitlement` field alongside the volume, so you can compare consumption to the license.

***

## `celigo syncs sources`

List the applications supported as a sync source.

**Signature**

```bash
celigo syncs sources
```

**Arguments**

None.

**Example**

```bash
celigo syncs sources --format table
```

**Corresponds to**: [`GET /v1/di/metadata/sources`](https://developer.celigo.com/api/api-reference/syncs) (operationId: `listSyncSources`)

***

## `celigo syncs destinations`

List the applications supported as a sync destination.

**Signature**

```bash
celigo syncs destinations
```

**Arguments**

None.

**Example**

```bash
celigo syncs destinations --format table
```

**Corresponds to**: [`GET /v1/di/metadata/destinations`](https://developer.celigo.com/api/api-reference/syncs) (operationId: `listSyncDestinations`)

***

## Gotchas

* **A sync can only live in a syncs integration.** An integration holds either flows or syncs, never both. Create the parent first with `syncs` enabled:

  ```bash
  echo '{"name": "Warehouse replication", "syncs": true}' | celigo integrations create
  ```
* **Full CRUD arrived in celigo-cli 2026.8.1.** Earlier releases could run a sync and manage its jobs, but not create, list, or delete one. If you scripted around that gap, `syncs list` and `syncs create` now replace the workaround.
* **`cancel-jobs` and `sync-jobs cancel` differ in scope.** `syncs cancel-jobs <syncId>` cancels every running job for a sync in one call. [`sync-jobs cancel <syncJobId>`](/cli/commands/sync-jobs.md) targets a single job.
* **Inspecting runs lives under `sync-jobs`.** Listing, fetching, and reading errors for the jobs a sync produces is done with [sync-jobs](/cli/commands/sync-jobs.md), not `syncs`.
* **`events` is retention-bounded.** Older events age out, so a window that predates the retention period returns nothing. `--time-gte` must not be in the future.
* **`--type` values contain a space.** Quote them: `--type "Schema Drift"`, not `--type Schema Drift`.
* **`--from` and `--to` require `--by month`.** Passing them with the default per-sync breakdown, or with `--by environment`, is rejected. Both take `YYYY-MM`, not a full date.
* **Datasets decide what a sync replicates.** Creating a sync does not select any tables. Use [datasets](/cli/commands/datasets.md) to choose them and set each one's ingestion mode.

## Related

* [datasets](/cli/commands/datasets.md) — choose which source tables and objects a sync replicates, and how.
* [sync-jobs](/cli/commands/sync-jobs.md) — inspect and cancel the individual jobs produced by `syncs run`.
* [integrations](/cli/commands/integrations.md) — the container that owns syncs.
* [jobs](/cli/commands/jobs.md) — flow execution history, which is distinct from sync jobs.


---

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