Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

celigo stacks <subcommand> [args] [flags]

Supports all global flags.

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

Arguments

None.

Flags

None beyond global flags. Default table columns: _id, name, lastModified.

Example

Corresponds to: GET /v1/stacks

celigo stacks get <id>

Fetch a single stack by ID. For server stacks, server.systemToken is returned masked as ****** — use token for the real value.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Stack ID.

Flags

None beyond global flags.

Example

Corresponds to: 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

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

Corresponds to: 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

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

Corresponds to: 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

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.

Example

Corresponds to: GET /v1/stacks/{_id} then 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

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Stack ID.

Flags

Flag
Type
Default
Description

-y, --yes

boolean

false

Skip the interactive confirmation.

Example

Corresponds to: 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

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Stack ID.

Example

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 GETs the stack to verify type === "server" — running it against a Lambda stack fails before any token call is made.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Stack ID. Must be a server-type stack.

Flags

None beyond global flags.

Example

Corresponds to: 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

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

Corresponds to: DELETE /v1/stacks/{_id}/systemToken

celigo stacks audit <id>

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

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Stack ID.

Example

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 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 — stacks belong to a specific environment; flows can only reference stacks in the matching environment.

  • on-premise-agents — the on-premise agent (OPA) that runs behind a server stack's hostURI and exchanges the systemToken with the integrator.io control plane.

Previousscripts
Nextstate

Last updated

Was this helpful?