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

# state

Manage state key-value stores — durable JSON values keyed by name. Commands target global (account-wide) state by default; pass `--resource-type` and `--resource-id` together to target a specific resource's state instead.

**REST API**: [State](https://developer.celigo.com/api/api-reference/data-stores/state)

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

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

## Subcommands

| Subcommand     | Purpose                                                |
| -------------- | ------------------------------------------------------ |
| `list`         | List state keys — global, or a resource's.             |
| `get <key>`    | Get a state value — global, or a resource's.           |
| `set <key>`    | Set a state key from a JSON body (stdin, or `--file`). |
| `delete <key>` | Delete one state key — global, or a resource's.        |
| `purge`        | Delete all state keys — global, or a resource's.       |

The `--resource-type <type>` and `--resource-id <id>` flags switch any subcommand from global state to a resource's state. They must be passed together.

***

## `celigo state list`

List state keys. Global by default; pass `--resource-type`/`--resource-id` to list a resource's keys instead.

**Signature**

```bash
celigo state list [flags]
```

**Flags**

| Flag                     | Type   | Default | Description                                                                                            |
| ------------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------ |
| `--resource-type <type>` | string | —       | Target a resource's state (e.g. `flows`, `exports`) instead of global state. Requires `--resource-id`. |
| `--resource-id <id>`     | string | —       | Resource id whose state to target. Requires `--resource-type`.                                         |

**Example**

```bash
celigo state list --format table
celigo state list --resource-type flows --resource-id 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/state` (global) or `GET /v1/{resourceType}/{resourceId}/state` (resource-scoped).

***

## `celigo state get`

Get the value stored under one state key.

**Signature**

```bash
celigo state get <key> [flags]
```

**Arguments**

| Argument | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `<key>`  | string | Yes      | State key name. |

**Flags**

| Flag                     | Type   | Default | Description                                                                  |
| ------------------------ | ------ | ------- | ---------------------------------------------------------------------------- |
| `--resource-type <type>` | string | —       | Target a resource's state instead of global state. Requires `--resource-id`. |
| `--resource-id <id>`     | string | —       | Resource id whose state to target. Requires `--resource-type`.               |

**Example**

```bash
celigo state get lastRunCheckpoint --format json
celigo state get cursor --resource-type flows --resource-id 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/state/{key}` (global) or `GET /v1/{resourceType}/{resourceId}/state/{key}` (resource-scoped).

***

## `celigo state set`

Set a state key from a JSON body read from stdin or `--file`. Full replace of the value stored under the key.

**Signature**

```bash
celigo state set <key> [flags]
```

**Arguments**

| Argument | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `<key>`  | string | Yes      | State key name. |

**Flags**

| Flag                     | Type   | Default | Description                                                                  |
| ------------------------ | ------ | ------- | ---------------------------------------------------------------------------- |
| `-f, --file <path>`      | string | stdin   | Read the JSON body from a file instead of stdin (`-` also means stdin).      |
| `--resource-type <type>` | string | —       | Target a resource's state instead of global state. Requires `--resource-id`. |
| `--resource-id <id>`     | string | —       | Resource id whose state to target. Requires `--resource-type`.               |

**Request body**

Reads JSON on stdin (or from `--file`). The body is stored verbatim as the value for the key.

**Example**

```bash
echo '{"cursor":"2026-06-13T00:00:00Z"}' | celigo state set lastRunCheckpoint
celigo state set lastRunCheckpoint --file checkpoint.json
celigo state set cursor --resource-type flows --resource-id 5f83a9b2c7d3e8f1a2b3c4d5 --file cursor.json
```

**Corresponds to**: `PUT /v1/state/{key}` (global) or `PUT /v1/{resourceType}/{resourceId}/state/{key}` (resource-scoped).

***

## `celigo state delete`

Delete one state key. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Deleting a state key is permanent.** The value stored under the key is removed and cannot be recovered.

**Signature**

```bash
celigo state delete <key> [flags]
```

**Arguments**

| Argument | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `<key>`  | string | Yes      | State key name. |

**Flags**

| Flag                     | Type    | Default | Description                                                                  |
| ------------------------ | ------- | ------- | ---------------------------------------------------------------------------- |
| `-y, --yes`              | boolean | `false` | Skip confirmation.                                                           |
| `--resource-type <type>` | string  | —       | Target a resource's state instead of global state. Requires `--resource-id`. |
| `--resource-id <id>`     | string  | —       | Resource id whose state to target. Requires `--resource-type`.               |

**Example**

```bash
celigo state delete lastRunCheckpoint -y
celigo state delete cursor --resource-type flows --resource-id 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: `DELETE /v1/state/{key}` (global) or `DELETE /v1/{resourceType}/{resourceId}/state/{key}` (resource-scoped).

***

## `celigo state purge`

Delete all state keys in scope. Global by default; pass `--resource-type`/`--resource-id` to purge a resource's keys instead. Prompts for confirmation unless `-y` is passed.

> ⚠️ **`purge` deletes every key in scope.** All state values for the target — global, or the specified resource — are removed and cannot be recovered.

**Signature**

```bash
celigo state purge [flags]
```

**Flags**

| Flag                     | Type    | Default | Description                                                                  |
| ------------------------ | ------- | ------- | ---------------------------------------------------------------------------- |
| `-y, --yes`              | boolean | `false` | Skip confirmation.                                                           |
| `--resource-type <type>` | string  | —       | Target a resource's state instead of global state. Requires `--resource-id`. |
| `--resource-id <id>`     | string  | —       | Resource id whose state to target. Requires `--resource-type`.               |

**Example**

```bash
celigo state purge -y
celigo state purge --resource-type flows --resource-id 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: `DELETE /v1/state` (global) or `DELETE /v1/{resourceType}/{resourceId}/state` (resource-scoped).

***

## Gotchas

* **`set` is a full replace.** The JSON body you pipe in replaces the entire value stored under the key — there is no partial merge.
* **`--resource-type` and `--resource-id` go together.** Pass both to target a resource's state; pass neither for global state. One without the other is an error.
* **`purge` is destructive.** It drops every key in its scope (global, or the targeted resource); it prompts for confirmation unless you pass `-y`.
* **Global vs. resource scope are separate stores.** A key set globally is not visible when you target a resource, and vice versa.