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

# scripts

JavaScript hooks that run inside flow execution — `_id`-addressable, versioned resources that exports, imports, and flows reference by `_scriptId`.

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

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

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

***

## Subcommands

| Subcommand                            | Purpose                                                                         |
| ------------------------------------- | ------------------------------------------------------------------------------- |
| `list`                                | List all scripts.                                                               |
| `get <id>`                            | Fetch one script.                                                               |
| `create`                              | Create a script 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: GET → modify → PUT. Supports `key=file://<path>`.              |
| `delete <id>`                         | Delete a script.                                                                |
| `dependencies <id>` (alias `used-by`) | List resources that depend on this script.                                      |
| `enable-debug <id>`                   | Turn on debug logging (sets `debugUntil`).                                      |
| `disable-debug <id>`                  | Turn off debug logging (clears `debugUntil`).                                   |
| `debug-logs <id>`                     | Fetch the script's debug logs (console output captured while debug is enabled). |
| `delete-debug-logs <id>`              | Delete the script's debug logs.                                                 |
| `audit <id>`                          | Show the script's audit trail (change history).                                 |

***

## `celigo scripts list`

List every script in the account.

**Signature**

```bash
celigo scripts list [flags]
```

**Flags**

Only global flags. See [global-flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo scripts list --format table
```

**Corresponds to**: [`GET /v1/scripts`](https://developer.celigo.com/api/api-reference/scripts#get-v1-scripts) → Scripts API reference.

***

## `celigo scripts get`

Fetch one script by ID.

**Signature**

```bash
celigo scripts get <id>
```

**Arguments**

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

**Example**

```bash
celigo scripts get 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`GET /v1/scripts/{_id}`](https://developer.celigo.com/api/api-reference/scripts#get-v1-scripts-_id) → Scripts API reference.

***

## `celigo scripts create`

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

**Signature**

```bash
celigo scripts create --file <path>
celigo scripts create < body.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). Added in celigo-cli 2026.6.1. |

**Request body**

A JSON object matching the `POST /v1/scripts` request schema (see the Scripts API reference). The script body goes in the `content` field, which must be a **JSON-encoded** string — see [Gotchas](#gotchas).

**Example**

```bash
# From a checked-in JSON file — no shell escaping, works in bash and PowerShell
celigo scripts create --file ./script.json
```

**Power-user** (requires `jq` installed on your `PATH`): build the body inline, JSON-encoding the script source with `jq --rawfile`, so you don't need a separate file.

```bash
jq --rawfile src ./filter-cancelled.js \
  '{name: "Filter cancelled orders", content: $src}' \
  | celigo scripts create
```

**Corresponds to**: [`POST /v1/scripts`](https://developer.celigo.com/api/api-reference/scripts#post-v1-scripts) → Scripts API reference.

***

## `celigo scripts update`

Full replace of a script from a JSON body (`--file <path>` or stdin). Omitted fields are erased — prefer `set` for targeted edits.

> ⚠️ **`update` replaces the entire script.** Any field you omit is erased, including `content`. GET the current script first, or use `set content=file://…` to swap only the body.

**Signature**

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

**Arguments**

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

**Flags**

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

**Request body**

A JSON object matching the `PUT /v1/scripts/{_id}` request schema (see the Scripts API reference). The `content` field must be a **JSON-encoded** string — see [Gotchas](#gotchas).

**Example**

```bash
# Replace the whole script from a file
celigo scripts update 5f83a9b2c7d3e8f1a2b3c4d5 --file ./script.json
```

To swap only the script body while keeping every other field, prefer `set <id> content=file://…` below.

**Power-user** (requires `jq` installed on your `PATH`): round-trip the current resource through `jq`, replacing `content` with the JSON-encoded file.

```bash
celigo scripts get 5f83a9b2c7d3e8f1a2b3c4d5 \
  | jq --rawfile src ./filter-cancelled.js '.content = $src' \
  | celigo scripts update 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PUT /v1/scripts/{_id}`](https://developer.celigo.com/api/api-reference/scripts#put-v1-scripts-_id) → Scripts API reference.

***

## `celigo scripts set`

Safe field edit: GET the current resource, apply `key=value` assignments, then `PUT` the complete object back. Values are auto-parsed as JSON (`disabled=false` is a boolean, `debugUntil=null` removes the field), with a fallback to the literal string when the value isn't valid JSON. Dot notation and array indexing are supported.

A `key=file://<path>` value loads that field's value from a file instead of the command line — ideal for the multi-line `content` of a script, which is painful to quote and escape inline. A JSON file parses to an object; anything else (including JS source) is read as a literal string. A leading `~` and paths relative to the current directory are supported. Added in celigo-cli 2026.6.1.

**Signature**

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

**Arguments**

| Argument                 | Type   | Required | Description                                                                   |
| ------------------------ | ------ | -------- | ----------------------------------------------------------------------------- |
| `<id>`                   | string | Yes      | Script `_id`.                                                                 |
| `key=value` (repeatable) | string | Yes      | One or more assignments. Use `key=file://<path>` to load a value from a file. |

**Example**

```bash
# Update just the script body from a checked-in file — no jq, no escaping, cross-platform
celigo scripts set 5f83a9b2c7d3e8f1a2b3c4d5 content=file://./hooks/filter-cancelled.js

# Rename (inline scalar)
celigo scripts set 5f83a9b2c7d3e8f1a2b3c4d5 'name=Filter cancelled orders (v2)'
```

**Power-user** (requires `jq` installed on your `PATH`): you can JSON-encode the source inline instead of using `file://`. The `file://` form above avoids the external `jq` dependency and the shell differences entirely.

```bash
# bash
celigo scripts set 5f83a9b2c7d3e8f1a2b3c4d5 "content=$(jq -Rs . < ./filter-cancelled.js)"

# PowerShell — '<' input redirection isn't supported, so pipe instead
celigo scripts set 5f83a9b2c7d3e8f1a2b3c4d5 "content=$(Get-Content -Raw ./filter-cancelled.js | jq -Rs .)"
```

**Corresponds to**: [`GET /v1/scripts/{_id}`](https://developer.celigo.com/api/api-reference/scripts#get-v1-scripts-_id) then [`PUT /v1/scripts/{_id}`](https://developer.celigo.com/api/api-reference/scripts#put-v1-scripts-_id) → Scripts API reference.

***

## `celigo scripts delete`

Delete a script. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Deleting a script cannot be undone.** Run `dependencies` first — exports, imports, and flows that reference it by `_scriptId` will break.

**Signature**

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

**Arguments**

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

**Flags**

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

**Example**

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

**Corresponds to**: [`DELETE /v1/scripts/{_id}`](https://developer.celigo.com/api/api-reference/scripts#delete-v1-scripts-_id) → Scripts API reference.

***

## `celigo scripts dependencies`

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

**Signature**

```bash
celigo scripts dependencies <id>
```

**Arguments**

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

**Example**

```bash
celigo scripts dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/scripts/{_id}/dependencies` → Scripts API reference.

***

## `celigo scripts enable-debug`

Enable debug logging on a script by setting `debugUntil` via `PATCH`.

**Signature**

```bash
celigo scripts enable-debug <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                   | Type    | Default | Description                                                     |
| ---------------------- | ------- | ------- | --------------------------------------------------------------- |
| `--duration <minutes>` | integer | `60`    | Debug window length. Max 60 minutes; larger values are clamped. |

**Example**

```bash
celigo scripts enable-debug 5f83a9b2c7d3e8f1a2b3c4d5 --duration 30
```

**Corresponds to**: [`PATCH /v1/scripts/{_id}`](https://developer.celigo.com/api/api-reference/scripts#patch-v1-scripts-_id) (JSON-Patch `replace /debugUntil`) → Scripts API reference.

***

## `celigo scripts disable-debug`

Disable debug logging on a script by clearing `debugUntil` via `PATCH`.

**Signature**

```bash
celigo scripts disable-debug <id>
```

**Arguments**

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

**Example**

```bash
celigo scripts disable-debug 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PATCH /v1/scripts/{_id}`](https://developer.celigo.com/api/api-reference/scripts#patch-v1-scripts-_id) (JSON-Patch `remove /debugUntil`) → Scripts API reference.

***

## `celigo scripts debug-logs`

Fetch a script's debug logs — the console output (`console.log`/`warn`/`error`) captured while debug is enabled. The `/v1/scripts/{_id}/logs` endpoint only returns data while `debugUntil` is set, so run `enable-debug` first.

**Signature**

```bash
celigo scripts debug-logs <id> [flags]
```

**Arguments**

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

**Flags**

| Flag                | Type                | Default | Description                                                |
| ------------------- | ------------------- | ------- | ---------------------------------------------------------- |
| `--level <level>`   | `INFO\|WARN\|ERROR` | —       | Filter by log level.                                       |
| `--limit <n>`       | integer             | `100`   | Max entries to return (1-1000).                            |
| `--offset <n>`      | integer             | —       | Entries to skip.                                           |
| `--since <minutes>` | integer             | —       | Only return logs from the last N minutes (sets `time_gt`). |
| `--flow-id <id>`    | string              | —       | Filter logs to a specific flow.                            |
| `--time-gte <iso>`  | ISO 8601            | —       | Return entries at or after this timestamp.                 |
| `--time-lte <iso>`  | ISO 8601            | —       | Return entries at or before this timestamp.                |

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

**Example**

```bash
celigo scripts enable-debug 5f83a9b2c7d3e8f1a2b3c4d5 --duration 30
# ...trigger the flow that runs the script...
celigo scripts debug-logs 5f83a9b2c7d3e8f1a2b3c4d5 --since 30 --level ERROR

# A fixed window instead of a relative one
celigo scripts debug-logs 5f83a9b2c7d3e8f1a2b3c4d5 \
  --time-gte 2026-08-01T00:00:00Z --time-lte 2026-08-01T06:00:00Z
```

**Corresponds to**: [`GET /v1/scripts/{_id}/logs`](https://developer.celigo.com/api/api-reference/scripts#get-v1-scripts-_id-logs) → Scripts API reference.

***

## `celigo scripts delete-debug-logs`

Delete a script's debug logs (the entries shown by `scripts debug-logs`). Prompts for confirmation unless `-y` is passed.

**Signature**

```bash
celigo scripts delete-debug-logs <id> [flags]
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo scripts delete-debug-logs 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: `DELETE /v1/scripts/{_id}/logs` → Scripts API reference.

***

## `celigo scripts audit`

Get a script's audit trail (change history).

**Signature**

```bash
celigo scripts audit <id>
```

**Arguments**

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

**Example**

```bash
celigo scripts audit 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/scripts/{_id}/audit` → Scripts API reference.

***

## Hook types

The entry-function name in your script body determines which hook point it runs at:

| Entry function    | When it runs                                               |
| ----------------- | ---------------------------------------------------------- |
| `preSavePage`     | Before a page of records is saved to the import queue.     |
| `preMap`          | Before import mapping transforms records.                  |
| `postMap`         | After mapping, before the HTTP call to the destination.    |
| `postSubmit`      | After the destination returns.                             |
| `postResponseMap` | After response mapping extracts data from the destination. |
| `handleRequest`   | For Celigo APIs — handle the incoming request body.        |
| `transform`       | Standalone transform within Transformation 2.0.            |
| `branching`       | Router decision function for flow branching.               |
| `filter`          | Boolean return — include or exclude records.               |

## Gotchas

* **`content` is freeform JavaScript — let the CLI encode it, don't hand-escape.** With `create`/`update` the script source lives inside a JSON body, so pasting raw multi-line JS makes the body **invalid JSON** and the command fails with `Invalid JSON input.` *before any API call* — which is why script writes can look like a broken CLI when they're really a local parse error. With `set content=…` the value is taken literally (no JSON escaping needed), but multi-line source is still painful to quote safely on one command line. Avoid both traps: pass the file with `set content=file://<path>` or `create/update --file <path>` and the CLI handles the encoding.
* **Writing script `content` requires `full` mode.** `create`, `update`, and `delete` are full-mode-only, and `set` may only touch `content` in `full` mode (`operate` mode limits `set` to fields like `disabled`, `debugUntil`, `schedule`; `read` mode blocks all writes). A rejected write reports the required mode — switch with `celigo config set mode full` (see [config](/cli/commands/config.md)) or use a full-mode [profile](/cli/commands/profile.md).
* **AFE 2.0 uses the `record.` prefix** (`record.customerId`). AFE 1.0 uses bare `customerId` / `data.customerId`. New scripts should always be AFE 2.0.
* **`console.log` appears in the script's execution log**, not your terminal — inspect it with `scripts debug-logs <id>`.
* **Sandboxed V8, not Node.js.** No `Buffer`, `require`, `fetch`, or outbound network. Use `sjcl` for base64, `dayjs` for dates.
* **`preSavePage` is an export-only hook.** Attaching it to an import silently produces no logs.
* **No `scripts test` subcommand.** Run the script inside a flow via `flows test-run`.

## Related

* [flows](/cli/commands/flows.md) — where scripts are referenced via `_scriptId`.
* [exports](/cli/commands/exports.md), [imports](/cli/commands/imports.md) — resources that attach scripts at specific hook points.
* [audit](/cli/commands/audit.md) — per-script change history.


---

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