> 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/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/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/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/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/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/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/async-helpers#get-v1-asynchelpers-_id) then [`PUT /v1/asynchelpers/{_id}`](https://developer.celigo.com/api/api-reference/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/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.


---

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