lookup-caches

In-memory key-value stores for deduplication, cross-reference resolution, and state tracking during flow execution.

REST API: Lookup Caches

Subcommands

Command	Purpose
list	List every lookup cache on the account.
get	Fetch one cache definition by id.
create	Create a new cache from a JSON body (--file <path> or stdin).
update	Full-replace PUT from a JSON body (--file <path> or stdin).
set	Patch fields with key=value assignments. Supports key=file://<path>.
delete	Delete a cache definition.
dependencies	List resources that depend on this cache (alias used-by).
audit	Show the audit log (change history) for one cache.
put-data	Upsert entries into a cache (auto-batched).
get-data	Read entries from a cache.
delete-data	Delete specific keys from a cache.
purge-data	Purge every entry from a cache.

celigo lookup-caches list

List every lookup cache. Columns: _id, name, size, lastModified.

celigo lookup-caches list

Corresponds to: GET /v1/lookupcaches

celigo lookup-caches get

Fetch one cache by id.

celigo lookup-caches get <id>

Corresponds to: GET /v1/lookupcaches/{_id}

celigo lookup-caches create

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

Flag	Description
-f, --file <path>	Read the JSON body from a file instead of stdin (--file - also means stdin). Added in celigo-cli 2026.6.1.

celigo lookup-caches create --file cache.json
celigo lookup-caches create < cache.json

Corresponds to: POST /v1/lookupcaches

celigo lookup-caches update

Full-replace PUT. Reads the complete cache document from -f, --file or stdin — omitted fields are erased.

⚠️ update replaces the entire cache definition. Any field you omit from the body is erased. GET the current document first, modify it, then PUT the complete object back — or use set for targeted edits.

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

celigo lookup-caches update <id> --file cache.json
celigo lookup-caches update <id> < cache.json

Corresponds to: PUT /v1/lookupcaches/{_id}

celigo lookup-caches set

Patch individual fields with key=value assignments. Whitelisted fields (for example name, debugUntil, schedule.*) are applied via an atomic PATCH; other fields go through GET → modify → PUT so omitted fields are preserved. Values are auto-parsed as JSON (disabled=false is a boolean, debugUntil=null removes the field). Dot notation and array indexing are supported. A key=file://<path> value loads that field from a file instead of the command line (a leading ~ and relative paths are supported). Added in celigo-cli 2026.6.1.

celigo lookup-caches set <id> name="State code cache"

Corresponds to: GET /v1/lookupcaches/{_id} then PUT /v1/lookupcaches/{_id}

celigo lookup-caches delete

Delete the cache definition. Prompts for confirmation unless -y is supplied.

⚠️ Deleting a cache removes its definition. Run dependencies first — flows and imports that reference this cache will break.

Flag	Description
-y, --yes	Skip confirmation.

celigo lookup-caches delete <id> -y

Corresponds to: DELETE /v1/lookupcaches/{_id}

celigo lookup-caches dependencies

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

celigo lookup-caches dependencies <id>

Corresponds to: GET /v1/lookupcaches/{_id}/dependencies

celigo lookup-caches audit

Show the audit log (change history) for one cache.

celigo lookup-caches audit <id>

Corresponds to: GET /v1/lookupcaches/{_id}/audit

celigo lookup-caches put-data

Upsert entries into the cache. Reads { "data": [{ "key", "value" }, ...] } on stdin and auto-batches by count (1000) and size (5 MB).

echo '{"data":[{"key":"CA","value":"California"},{"key":"NY","value":"New York"}]}' \
  | celigo lookup-caches put-data <id>

Corresponds to: POST /v1/lookupcaches/{_id}/data

celigo lookup-caches get-data

Read entries from the cache. Behaviour depends on stdin:

• No stdin — returns the first page (max 1000 keys).
• { "keys": ["k1", "k2"] } — returns only those entries.
• { "startsWith": "abc" } — returns entries whose key matches the prefix.

echo '{"keys":["CA","NY"]}' | celigo lookup-caches get-data <id>

Corresponds to: POST /v1/lookupcaches/{_id}/getData

celigo lookup-caches delete-data

Delete specific keys. Reads { "keys": ["k1", "k2", ...] } on stdin. Prompts for confirmation unless -y is supplied.

⚠️ Deleting cache entries is irreversible. The specified keys are removed; the cache definition itself is untouched.

Flag	Description
-y, --yes	Skip confirmation.

echo '{"keys":["CA","NY"]}' | celigo lookup-caches delete-data <id> -y

Corresponds to: DELETE /v1/lookupcaches/{_id}/data

celigo lookup-caches purge-data

Purge every entry from the cache. Prompts for confirmation unless -y is supplied.

⚠️ Purging clears every entry in the cache. This cannot be undone. The cache definition remains, but all stored data is removed.

Flag	Description
-y, --yes	Skip confirmation.

celigo lookup-caches purge-data <id> -y

Corresponds to: DELETE /v1/lookupcaches/{_id}/data/purge

Gotchas

• Cache data writes use POST, not PUT. put-data maps to POST /v1/lookupcaches/{_id}/data; there is no PUT on the /data endpoint.
• Reads also use POST. get-data posts to /getData so the key list or prefix filter can ride in the request body.
• 5 MB / 1000-entry batch ceiling. put-data auto-splits large payloads; size is measured in bytes of the JSON-encoded entry.
• Definition vs. contents. delete removes the cache itself. delete-data and purge-data only clear entries — the cache definition stays put.
• Empty data array is rejected. put-data errors out if the parsed data array has zero entries.

Related

• flows — flows reference caches for enrichment and deduplication during pageProcessors[] execution.
• imports — import lookups can be configured to hit a lookup cache instead of the source system.