# Collections CLI Commands

> The soat CLI commands for the Collections module, with usage and every option, generated from the OpenAPI spec.

# Collections Commands

See [Collections module docs](../../modules/collections) for permissions and data model.

### `soat list-collections`

List collections

- Method: `GET`
- Path: `/api/v1/collections`

#### Usage

```bash
soat list-collections
```

#### Options

##### `--project-id`

Project public ID (proj_ prefix)

- Source: `query`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

### `soat create-collection`

Create a collection

- Method: `POST`
- Path: `/api/v1/collections`

#### Usage

```bash
soat create-collection --name <string>
```

#### Options

##### `--project-id`

Project the collection belongs to. Optional for a project-scoped API key, which supplies it.

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--name`

Unique within the project.

- Source: `body`
- Required: yes
- Type: `string`
- Example: `support-tickets`

##### `--schema`

A JSON Schema every item's `data` must satisfy, stored as written. `null` removes it.

- Source: `body`
- Required: no
- Type: `object`
- Example: `\{"type":"object","required":["status"],"properties":\{"status":\{"type":"string"\}\}\}`

### `soat get-collection`

Get a collection

- Method: `GET`
- Path: `/api/v1/collections/{collection_id}`

#### Usage

```bash
soat get-collection
```

#### Options

This command has no options.

### `soat update-collection`

Update a collection

- Method: `PATCH`
- Path: `/api/v1/collections/{collection_id}`

#### Usage

```bash
soat update-collection
```

#### Options

##### `--name`

Unique within the project.

- Source: `body`
- Required: no
- Type: `string`
- Example: `support-tickets`

##### `--schema`

A JSON Schema every item's `data` must satisfy, stored as written. `null` removes it.

- Source: `body`
- Required: no
- Type: `object`
- Example: `\{"type":"object","required":["status"],"properties":\{"status":\{"type":"string"\}\}\}`

### `soat delete-collection`

Delete a collection

- Method: `DELETE`
- Path: `/api/v1/collections/{collection_id}`

#### Usage

```bash
soat delete-collection
```

#### Options

This command has no options.

### `soat list-collection-items`

List items

- Method: `GET`
- Path: `/api/v1/collections/{collection_id}/items`

#### Usage

```bash
soat list-collection-items
```

#### Options

This command has no options.

### `soat get-collection-item`

Get an item

- Method: `GET`
- Path: `/api/v1/collections/{collection_id}/items/{key}`

#### Usage

```bash
soat get-collection-item
```

#### Options

This command has no options.

### `soat put-collection-item`

Create or replace an item

- Method: `PUT`
- Path: `/api/v1/collections/{collection_id}/items/{key}`

#### Usage

```bash
soat put-collection-item --data <object>
```

#### Options

##### `--data`

The item's JSON object, at most 64 KB serialized. Stored as `jsonb`, so key order is not kept.

- Source: `body`
- Required: yes
- Type: `object`
- Example: `\{"status":"open","priority":2,"actor_id":"actor_V1StGXR8Z5jdHi6B"\}`

##### `--tags`

Replaces the item's tags; `null` clears them.

- Source: `body`
- Required: no
- Type: `unknown`

##### `--expected-version`

Refuses the write unless the item is at this version.

- Source: `body`
- Required: no
- Type: `unknown`

### `soat update-collection-item`

Update an item

- Method: `PATCH`
- Path: `/api/v1/collections/{collection_id}/items/{key}`

#### Usage

```bash
soat update-collection-item
```

#### Options

##### `--data`

The merge patch applied to the item's `data`.

- Source: `body`
- Required: no
- Type: `object`

##### `--tags`

Replaces the item's tags; `null` clears them.

- Source: `body`
- Required: no
- Type: `unknown`

##### `--expected-version`

Refuses the write unless the item is at this version.

- Source: `body`
- Required: no
- Type: `unknown`

### `soat delete-collection-item`

Delete an item

- Method: `DELETE`
- Path: `/api/v1/collections/{collection_id}/items/{key}`

#### Usage

```bash
soat delete-collection-item
```

#### Options

This command has no options.

### `soat get-collection-item-tags`

Get item tags

- Method: `GET`
- Path: `/api/v1/collections/{collection_id}/items/{key}/tags`

#### Usage

```bash
soat get-collection-item-tags
```

#### Options

This command has no options.

### `soat replace-collection-item-tags`

Replace item tags

- Method: `PUT`
- Path: `/api/v1/collections/{collection_id}/items/{key}/tags`

#### Usage

```bash
soat replace-collection-item-tags --tags <object>
```

#### Options

##### `--tags`

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `iam:ResourceTag/<key>` condition.  Keys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.  The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys are the platform's and do not count against the 50.

- Source: `body`
- Required: yes
- Type: `object`

### `soat merge-collection-item-tags`

Merge item tags

- Method: `PATCH`
- Path: `/api/v1/collections/{collection_id}/items/{key}/tags`

#### Usage

```bash
soat merge-collection-item-tags --tags <object>
```

#### Options

##### `--tags`

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `iam:ResourceTag/<key>` condition.  Keys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.  The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys are the platform's and do not count against the 50.

- Source: `body`
- Required: yes
- Type: `object`
