> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tai42.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# tai states

> Manage the subject-keyed state store.

Manage the subject-keyed state store.

```console theme={null}
$ tai states [OPTIONS] COMMAND [ARGS]...
```

## `tai states apply`

Apply an ordered op batch to a subject's document.

```console theme={null}
$ tai states apply [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `<str>` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `<str>` | The subject's conversation-target name. *(required)*              |
| `--kind` `<str>`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `<str>`         | The subject key within its kind. *(required)*                     |
| `--data` `<str>`        | A JSON array of ops (or \{ops, op\_id}).                          |
| `--file` `<path>`       | A file holding the ops JSON.                                      |
| `--op-id` `<str>`       | An idempotency key for the batch.                                 |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |

## `tai states attach`

Attach a template on a state at a path with its parameters and declarations.

```console theme={null}
$ tai states attach [OPTIONS] {name} {template}
```

| Argument   | Description                     |
| ---------- | ------------------------------- |
| `name`     | The state name. *(required)*    |
| `template` | The template name. *(required)* |

| Option                  | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `--data` `<str>`  | The attach body JSON (path/parameters/declarations). |
| `--file` `<path>` | A file holding the attach body JSON.                 |
| `--json` / `--no-json`  | Emit raw JSON instead of human tables.               |

## `tai states attachments`

List the templates attached on a state.

```console theme={null}
$ tai states attachments [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states consumers`

List everything that binds a state — flows, hooks, schedules, agents.

```console theme={null}
$ tai states consumers [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states delete`

Delete a state with its records, attachments and aliases.

```console theme={null}
$ tai states delete [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states detach`

Detach a template from a state.

```console theme={null}
$ tai states detach [OPTIONS] {name} {template}
```

| Argument   | Description                     |
| ---------- | ------------------------------- |
| `name`     | The state name. *(required)*    |
| `template` | The template name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states erase`

Erase a subject's record.

```console theme={null}
$ tai states erase [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `<str>` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `<str>` | The subject's conversation-target name. *(required)*              |
| `--kind` `<str>`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `<str>`         | The subject key within its kind. *(required)*                     |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |

## `tai states fold`

Fold this subject's record into another canonical subject.

```console theme={null}
$ tai states fold [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                        | Description                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `--target-kind` `<str>` | The subject's conversation-target kind (agent/tool). *(required)*              |
| `--target-name` `<str>` | The subject's conversation-target name. *(required)*                           |
| `--kind` `<str>`        | The subject kind (e.g. person, thread). *(required)*                           |
| `--key` `<str>`         | The subject key within its kind. *(required)*                                  |
| `--into` `<str>`        | The canonical subject JSON \{target\_kind,target\_name,kind,key}. *(required)* |
| `--mode` `<str>`        | The fold mode. *(required)*                                                    |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                                         |

## `tai states get`

Show a state's declaration, effective schema, attachments and regimes.

```console theme={null}
$ tai states get [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states get-attachment`

Read one template's attachment on a state (404 when it is not attached).

```console theme={null}
$ tai states get-attachment [OPTIONS] {name} {template}
```

| Argument   | Description                     |
| ---------- | ------------------------------- |
| `name`     | The state name. *(required)*    |
| `template` | The template name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states list`

List every declared state.

```console theme={null}
$ tai states list [OPTIONS]
```

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states merge`

Shallow-merge a patch into a subject's document.

```console theme={null}
$ tai states merge [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `<str>` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `<str>` | The subject's conversation-target name. *(required)*              |
| `--kind` `<str>`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `<str>`         | The subject key within its kind. *(required)*                     |
| `--data` `<str>`        | The patch JSON.                                                   |
| `--file` `<path>`       | A file holding the patch JSON.                                    |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |

## `tai states prune`

Prune every record past its state's retention horizon.

```console theme={null}
$ tai states prune [OPTIONS]
```

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states put`

Create or re-declare a state from a declaration document.

```console theme={null}
$ tai states put [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                  | Description                            |
| ----------------------- | -------------------------------------- |
| `--data` `<str>`  | The declaration JSON object.           |
| `--file` `<path>` | A file holding the declaration JSON.   |
| `--json` / `--no-json`  | Emit raw JSON instead of human tables. |

## `tai states read`

Read a subject's record (null when none exists).

```console theme={null}
$ tai states read [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `<str>` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `<str>` | The subject's conversation-target name. *(required)*              |
| `--kind` `<str>`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `<str>`         | The subject key within its kind. *(required)*                     |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |

## `tai states replace`

Replace a subject's whole document.

```console theme={null}
$ tai states replace [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `<str>` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `<str>` | The subject's conversation-target name. *(required)*              |
| `--kind` `<str>`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `<str>`         | The subject key within its kind. *(required)*                     |
| `--data` `<str>`        | The document JSON.                                                |
| `--file` `<path>`       | A file holding the document JSON.                                 |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |

## `tai states search`

Search a state's records by document containment.

```console theme={null}
$ tai states search [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                    | Description                                                  |
| ------------------------- | ------------------------------------------------------------ |
| `--filters` `<str>` | A JSON object the record document must contain. *(required)* |
| `--limit` `<int>`   | Page size.                                                   |
| `--cursor` `<str>`  | A keyset cursor from a prior page.                           |
| `--json` / `--no-json`    | Emit raw JSON instead of human tables.                       |

## `tai states stats`

Show a state's record counts (total and per subject kind).

```console theme={null}
$ tai states stats [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                 | Description                            |
| ---------------------- | -------------------------------------- |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states subjects`

Page the subjects holding a record for a state.

```console theme={null}
$ tai states subjects [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                   | Description                            |
| ------------------------ | -------------------------------------- |
| `--kind` `<str>`   | Restrict to one subject kind.          |
| `--limit` `<int>`  | Page size.                             |
| `--cursor` `<str>` | A keyset cursor from a prior page.     |
| `--json` / `--no-json`   | Emit raw JSON instead of human tables. |

## `tai states template-jq`

Evaluate/apply a state's template\_jq programs.

```console theme={null}
$ tai states template-jq [OPTIONS] COMMAND [ARGS]...
```

### `tai states template-jq apply`

Apply an update-purpose template\_jq program to a subject's record.

```console theme={null}
$ tai states template-jq apply [OPTIONS] {name} {program}
```

| Argument  | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| `name`    | The state name. *(required)*                                         |
| `program` | The template\_jq program name (or \<template>.\<name>). *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)*              |
| `--kind` `&lt;str&gt;`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `&lt;str&gt;`         | The subject key within its kind. *(required)*                     |
| `--input` `&lt;str&gt;`       | The program's input as JSON, or @\<file> to read it from a file.  |
| `--op-id` `&lt;str&gt;`       | An idempotency key for the apply.                                 |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |

### `tai states template-jq eval`

Evaluate an input-purpose template\_jq program for a subject.

```console theme={null}
$ tai states template-jq eval [OPTIONS] {name} {program}
```

| Argument  | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| `name`    | The state name. *(required)*                                         |
| `program` | The template\_jq program name (or \<template>.\<name>). *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)*              |
| `--kind` `&lt;str&gt;`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `&lt;str&gt;`         | The subject key within its kind. *(required)*                     |
| `--param` `&lt;str&gt;`       | An input-program parameter as key=\<json> (repeatable).           |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |

## `tai states update-attachment`

Replace an attachment's static declaration values, with optional reconcile options.

```console theme={null}
$ tai states update-attachment [OPTIONS] {name} {template}
```

| Argument   | Description                     |
| ---------- | ------------------------------- |
| `name`     | The state name. *(required)*    |
| `template` | The template name. *(required)* |

| Option                         | Description                                                     |
| ------------------------------ | --------------------------------------------------------------- |
| `--declarations` `&lt;str&gt;` | The attachment declaration values JSON object. *(required)*     |
| `--options` `&lt;str&gt;`      | The reconcile options JSON object passed to attach reconcilers. |
| `--json` / `--no-json`         | Emit raw JSON instead of human tables.                          |

## `tai states writes`

Page a subject's write audit trail.

```console theme={null}
$ tai states writes [OPTIONS] {name}
```

| Argument | Description                  |
| -------- | ---------------------------- |
| `name`   | The state name. *(required)* |

| Option                        | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)*              |
| `--kind` `&lt;str&gt;`        | The subject kind (e.g. person, thread). *(required)*              |
| `--key` `&lt;str&gt;`         | The subject key within its kind. *(required)*                     |
| `--limit` `&lt;int&gt;`       | Page size.                                                        |
| `--cursor` `&lt;str&gt;`      | A keyset cursor from a prior page.                                |
| `--json` / `--no-json`        | Emit raw JSON instead of human tables.                            |