> 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.


---

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