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

# stacks

On-premise bridge runtimes — run data-residency-sensitive flows inside your own network. Stacks host the execution environment (server or AWS Lambda) that integrator.io invokes for custom code, hooks, and wrappers.

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

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

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

***

## Subcommands

| Subcommand            | Purpose                                                                     |
| --------------------- | --------------------------------------------------------------------------- |
| `list`                | List all stacks, both your own and any shared with you.                     |
| `get <id>`            | Fetch one stack by ID (secrets masked as `******`).                         |
| `create`              | Create a stack from a JSON body (`--file <path>` or stdin).                 |
| `update <id>`         | Full-replace PUT from a JSON body (`--file <path>` or stdin).               |
| `set <id> <k>=<v>...` | Partial edit via atomic `PATCH` (whitelisted fields) or GET → modify → PUT. |
| `delete <id>`         | Delete a stack by ID.                                                       |
| `dependencies <id>`   | List resources that depend on this stack (alias `used-by`).                 |
| `token <id>`          | Retrieve the unmasked system token for a server stack.                      |
| `rotate-token <id>`   | Rotate the server stack's system token.                                     |
| `audit <id>`          | Show the audit log (change history) for a stack.                            |

***

## `celigo stacks list`

List every stack configured on the account (server and Lambda), both your own and any shared with you (`shared=true`).

**Signature**

```bash
celigo stacks list
```

**Arguments**

None.

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md). Default table columns: `_id`, `name`, `lastModified`.

**Example**

```bash
celigo stacks list --format table
```

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

***

## `celigo stacks get <id>`

Fetch a single stack by ID. For server stacks, `server.systemToken` is returned masked as `******` — use [`token`](#celigo-stacks-token-id) for the real value.

**Signature**

```bash
celigo stacks get <id>
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo stacks get 5f8d43a1b9e5a80011a35f2c
```

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

***

## `celigo stacks create`

Create a new stack from a JSON payload. Read the body from a file with `-f, --file` or pipe it on stdin. `type` must be `server` or `lambda`; required sub-blocks depend on the type (`server.hostURI` for server, `lambda.accessKeyId` / `secretAccessKey` / `awsRegion` / `functionName` for Lambda).

**Signature**

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

**Request body**

Reads JSON on stdin (or from `--file`). See the `POST /v1/stacks` request schema in `dist/stack.yml` for the full payload shape (one variant per `type`: `server`, `lambda`).

**Example**

```bash
celigo stacks create < stack.json
```

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

***

## `celigo stacks update <id>`

Full-replace a stack with a JSON payload. Read the body from a file with `-f, --file` or pipe it on stdin. Because `PUT` erases omitted fields, send the complete stack object (typically `GET` → edit → `update`).

> ⚠️ **`update` replaces the entire stack.** `PUT` erases any field you omit. `GET` the stack first, edit it, then send the complete object back — or use `set` for narrow edits.

**Signature**

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

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Stack 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**

Reads JSON on stdin (or from `--file`). See `PUT /v1/stacks/{_id}` in `dist/stack.yml`. Secrets are write-only: provide a new value in the request to replace it, or omit the secret fields entirely to leave them untouched (responses always mask them as `******`).

**Example**

```bash
celigo stacks get 5f8d43a1b9e5a80011a35f2c --format json \
  | jq '.name = "Renamed stack"' \
  | celigo stacks update 5f8d43a1b9e5a80011a35f2c
```

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

***

## `celigo stacks set <id> <key=value>...`

Partial edit. Whitelisted fields (e.g. `name`) are applied via an atomic `PATCH`; other fields go through GET → modify → PUT. Dotted paths and array indices are supported; values are auto-parsed (booleans, numbers, `null` removes the field).

**Signature**

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

**Arguments**

| Argument      | Type   | Required | Description                                                                                                                                             |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`        | string | Yes      | Stack ID.                                                                                                                                               |
| `<key=value>` | string | Yes (1+) | One or more assignments. Dot notation (`server.hostURI=...`) and array indices (`server.ipRanges[0]=10.0.0.0/8`) are supported. `null` removes the key. |

**Flags**

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

**Example**

```bash
celigo stacks set 5f8d43a1b9e5a80011a35f2c name="Renamed stack"
celigo stacks set 5f8d43a1b9e5a80011a35f2c server.hostURI=https://bridge.example.com:3000
```

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

***

## `celigo stacks delete <id>`

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

> ⚠️ **Deleting a stack cannot be undone.** Flows and resources that reference this stack will fail. Run `celigo stacks dependencies <id>` first to confirm nothing depends on it.

**Signature**

```bash
celigo stacks delete <id> [-y]
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo stacks delete 5f8d43a1b9e5a80011a35f2c -y
```

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

***

## `celigo stacks dependencies <id>`

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

**Signature**

```bash
celigo stacks dependencies <id>
celigo stacks used-by <id>
```

**Arguments**

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

**Example**

```bash
celigo stacks dependencies 5f8d43a1b9e5a80011a35f2c
```

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

***

## `celigo stacks token <id>`

Retrieve the unmasked system token for a **server-type** stack. The regular `get` response always masks `server.systemToken` as `******`; this command returns the actual value so you can paste it into the on-premise bridge's config.

The command first `GET`s the stack to verify `type === "server"` — running it against a Lambda stack fails before any token call is made.

**Signature**

```bash
celigo stacks token <id>
```

**Arguments**

| Argument | Type   | Required | Description                              |
| -------- | ------ | -------- | ---------------------------------------- |
| `<id>`   | string | Yes      | Stack ID. Must be a `server`-type stack. |

**Flags**

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

**Example**

```bash
celigo stacks token 5f8d43a1b9e5a80011a35f2c
```

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

***

## `celigo stacks rotate-token <id>`

Rotate the system token for a **server-type** stack. The API generates a new token and the old one is immediately invalid — any bridge instances still using the old token will fail to authenticate until they're updated. Retrieve the new token with `token`. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Rotating the token is immediate and irreversible.** The old `systemToken` stops working the moment the new one is issued. Every on-premise bridge still using it fails to authenticate until you redeploy with the new token.

**Signature**

```bash
celigo stacks rotate-token <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description                              |
| -------- | ------ | -------- | ---------------------------------------- |
| `<id>`   | string | Yes      | Stack ID. Must be a `server`-type stack. |

**Flags**

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

**Example**

```bash
celigo stacks rotate-token 5f8d43a1b9e5a80011a35f2c -y
```

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

***

## `celigo stacks audit <id>`

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

**Signature**

```bash
celigo stacks audit <id>
```

**Arguments**

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

**Example**

```bash
celigo stacks audit 5f8d43a1b9e5a80011a35f2c
```

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

***

## Gotchas

* **`token` and `rotate-token` are server-only.** Both commands enforce `type === "server"` client-side before hitting the API — a Lambda stack aborts with `token is only available for server-type stacks`. The API itself returns `404 Not Found` for these endpoints on Lambda stacks.
* **Token rotation is immediate and non-reversible.** `rotate-token` issues a brand-new `systemToken` the instant the DELETE returns `204 No Content`. Every on-premise bridge, sidecar, or script still holding the old token will fail auth until you redeploy with the new one — coordinate the rollout before rotating.
* **Responses mask secrets.** `server.systemToken` and `lambda.secretAccessKey` always come back as `******` on `list`, `get`, `create`, and `update`. Use [`token`](#celigo-stacks-token-id) for the real server token; AWS secrets must be re-supplied in the request body each time you want to replace them.
* **`PUT` is a full replace.** `update` overwrites every field, so omit secret fields (they'll remain untouched) or include their real values. Use `set` for narrow edits — it does GET → modify → PUT for you and preserves the secret placeholders correctly.
* **On-prem security is your problem.** A server stack's `hostURI` is reachable by integrator.io's control plane — lock it down with `server.ipRanges` (CIDR allowlist) so only Celigo's egress IPs can hit the bridge. Without that, anyone who learns the `systemToken` and `hostURI` can invoke your custom code.
* **Framework is pinned.** Only `framework: "twoDotZero"` is currently supported; omit the field or set it to `twoDotZero` on create.

## Related

* [environments](/cli/commands/environments.md) — stacks belong to a specific environment; flows can only reference stacks in the matching environment.
* [on-premise-agents](/cli/commands/on-premise-agents.md) — the on-premise agent (OPA) that runs behind a server stack's `hostURI` and exchanges the `systemToken` with the integrator.io control plane.