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

# lookup-caches

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

**REST API**: [Lookup Caches](https://developer.celigo.com/api/api-reference/lookup-caches)

## Subcommands

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

## celigo lookup-caches list

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

In celigo-cli 2026.8.1 through 2026.8.8 the default `list` failed with `422 Unprocessable Entity` because the endpoint rejects the `include` projection, and only `--fields all` worked; since 2026.9.1 the default form works again (rows are trimmed client-side to the same columns).

```bash
celigo lookup-caches list
```

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

## celigo lookup-caches get

Fetch one cache by id.

```bash
celigo lookup-caches get <id>
```

**Corresponds to**: [`GET /v1/lookupcaches/{_id}`](https://developer.celigo.com/api/api-reference/lookup-caches#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. |

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

**Corresponds to**: [`POST /v1/lookupcaches`](https://developer.celigo.com/api/api-reference/lookup-caches#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.                         |

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

**Corresponds to**: [`PUT /v1/lookupcaches/{_id}`](https://developer.celigo.com/api/api-reference/lookup-caches#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.

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

**Corresponds to**: [`GET /v1/lookupcaches/{_id}`](https://developer.celigo.com/api/api-reference/lookup-caches#get-v1-lookupcaches-_id) then [`PUT /v1/lookupcaches/{_id}`](https://developer.celigo.com/api/api-reference/lookup-caches#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. |

```bash
celigo lookup-caches delete <id> -y
```

**Corresponds to**: [`DELETE /v1/lookupcaches/{_id}`](https://developer.celigo.com/api/api-reference/lookup-caches#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.

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

```bash
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).

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

**Corresponds to**: [`POST /v1/lookupcaches/{_id}/data`](https://developer.celigo.com/api/api-reference/lookup-caches#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.

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

**Corresponds to**: [`POST /v1/lookupcaches/{_id}/getData`](https://developer.celigo.com/api/api-reference/lookup-caches#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. |

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

**Corresponds to**: [`DELETE /v1/lookupcaches/{_id}/data`](https://developer.celigo.com/api/api-reference/lookup-caches#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. |

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

**Corresponds to**: [`DELETE /v1/lookupcaches/{_id}/data/purge`](https://developer.celigo.com/api/api-reference/lookup-caches#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`](/cli/commands/flows.md) — flows reference caches for enrichment and deduplication during `pageProcessors[]` execution.
* [`imports`](/cli/commands/imports.md) — import lookups can be configured to hit a lookup cache instead of the source system.


---

# 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/lookup-caches.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.