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

# async-helpers

Polling configurations that let exports and imports issue server-side callbacks during execution — used for long-running API operations (Amazon SP-API feeds, Salesforce Bulk 2.0, Shopify Bulk). Referenced by exports and imports via `_asyncHelperId`.

**REST API**: [Async Helpers](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers)

**OpenAPI spec**: `dist/asynchelper.yml` in `@celigo/api-specs` — see [OpenAPI specs](https://developer.celigo.com/api/using-the-api/openapi-specs)

```
celigo async-helpers <subcommand> [args] [flags]
```

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

***

## Subcommands

| Subcommand             | Purpose                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `list`                 | List all async helpers.                                                                                       |
| `get <id>`             | Fetch one async helper by ID.                                                                                 |
| `create`               | Create an async helper from a JSON body (`--file <path>` or stdin).                                           |
| `update <id>`          | Full replace from a JSON body (`--file <path>` or stdin); destructive `PUT`.                                  |
| `set <id> key=value …` | Safe field edit: whitelisted fields via `PATCH`, others via GET → modify → PUT. Supports `key=file://<path>`. |
| `delete <id>`          | Delete an async helper.                                                                                       |
| `dependencies <id>`    | List resources that depend on this async helper (alias: `used-by`).                                           |
| `audit <id>`           | Show the change-history audit log for one async helper.                                                       |

***

## `celigo async-helpers list`

List every async helper in the account.

**Signature**

```bash
celigo async-helpers list [flags]
```

**Arguments**

None.

**Flags**

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

Plus the [global flags](/cli/getting-started/global-flags.md) (`--format`, `--jq`, `--profile`, `--verbose`).

**Example**

```bash
celigo async-helpers list --format table
```

**Corresponds to**: [`GET /v1/asynchelpers`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#get-v1-asynchelpers)

***

## `celigo async-helpers get`

Fetch a single async helper by ID.

**Signature**

```bash
celigo async-helpers get <id>
```

**Arguments**

| Argument | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| `<id>`   | string | Yes      | Async helper `_id`. |

**Flags**

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

**Example**

```bash
celigo async-helpers get 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/asynchelpers/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#get-v1-asynchelpers-_id)

***

## `celigo async-helpers create`

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

**Signature**

```bash
celigo async-helpers create --file <path>
celigo async-helpers create < async-helper.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). |

**Request body**

A JSON body matching the async helper resource shape. See the request schema on [`POST /v1/asynchelpers`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#post-v1-asynchelpers).

**Example**

```bash
celigo async-helpers create --file ./async-helper.json
cat async-helper.json | celigo async-helpers create
```

**Corresponds to**: [`POST /v1/asynchelpers`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#post-v1-asynchelpers)

***

## `celigo async-helpers update`

Replace an async helper with a JSON body (`--file <path>` or stdin).

> ⚠️ **`update` erases omitted fields.** It sends a `PUT`, not a `PATCH`, so any field missing from the body is cleared. `GET` the helper first, edit it, then send back the complete object — or use `set` for partial edits.

**Signature**

```bash
celigo async-helpers update <id> --file <path>
celigo async-helpers update <id> < async-helper.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| `<id>`   | string | Yes      | Async helper `_id`. |

**Flags**

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

**Request body**

Pass the complete resource. Any field you omit will be removed on save.

**Example**

```bash
celigo async-helpers update 5f83a9b2c7d3e8f1a2b3c4d5 --file ./async-helper.json
cat async-helper.json | celigo async-helpers update 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PUT /v1/asynchelpers/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#put-v1-asynchelpers-_id)

***

## `celigo async-helpers set`

Safe field edit. Whitelisted fields (`name`, `debugUntil`, `schedule.*`, and similar) are applied via an atomic `PATCH`; any other field goes through GET → modify → PUT. Prefer this over `update` for partial changes.

A `key=file://<path>` value loads that field's value from a file instead of the command line, which avoids hand-escaping multi-line content. A leading `~` and paths relative to the current directory are supported.

**Signature**

```bash
celigo async-helpers set <id> <assignments...>
```

**Arguments**

| Argument           | Type   | Required | Description                                                                                                                                                                                                                  |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`             | string | Yes      | Async helper `_id`.                                                                                                                                                                                                          |
| `<assignments...>` | string | Yes      | One or more `key=value` pairs. Values are JSON-parsed (`disabled=false` → boolean, `debugUntil=null` removes the field). Dot notation and array indexing are supported. Use `key=file://<path>` to load a value from a file. |

**Example**

```bash
celigo async-helpers set 5f83a9b2c7d3e8f1a2b3c4d5 name="SP-API feed poller"
```

**Corresponds to**: [`GET /v1/asynchelpers/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#get-v1-asynchelpers-_id) then [`PUT /v1/asynchelpers/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#put-v1-asynchelpers-_id)

***

## `celigo async-helpers delete`

Delete an async helper by ID.

> ⚠️ **`delete` is immediate.** Any export or import that carries this `_id` in `_asyncHelperId` is left with a dangling reference. Run `dependencies` first.

**Signature**

```bash
celigo async-helpers delete <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| `<id>`   | string | Yes      | Async helper `_id`. |

**Flags**

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

**Example**

```bash
celigo async-helpers delete 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: [`DELETE /v1/asynchelpers/{_id}`](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers#delete-v1-asynchelpers-_id)

***

## `celigo async-helpers dependencies`

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

**Signature**

```bash
celigo async-helpers dependencies <id>
celigo async-helpers used-by <id>
```

**Arguments**

| Argument | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| `<id>`   | string | Yes      | Async helper `_id`. |

**Example**

```bash
celigo async-helpers dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo async-helpers audit`

Show the audit log (change history) for one async helper.

**Signature**

```bash
celigo async-helpers audit <id>
```

**Arguments**

| Argument | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| `<id>`   | string | Yes      | Async helper `_id`. |

**Example**

```bash
celigo async-helpers audit 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## Gotchas

* **Referenced by exports and imports.** Before deleting an async helper, confirm no active export or import carries its `_id` in `_asyncHelperId` — the reference will dangle.
* **API path is `asynchelpers` (no hyphen).** The CLI command is `async-helpers`; the underlying endpoint is `/v1/asynchelpers`.

## Related

* [flows](/cli/commands/flows.md) — flows execute the exports and imports that reference async helpers.
* [exports](/cli/commands/exports.md) and [imports](/cli/commands/imports.md) — set `_asyncHelperId` on an export or import to attach a polling config.
* [scripts](/cli/commands/scripts.md) — server-side JavaScript hooks that run alongside async helper callbacks.