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


---

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