# Actors Commands

> See [Actors module docs](../../modules/actors) for permissions and data model.

# Actors Commands

See [Actors module docs](../../modules/actors) for permissions and data model.

### `soat list-actors`

List actors

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

#### Usage

```bash
soat list-actors
```

#### Options

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

Project ID (optional)

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

##### `--external-id`

External ID to filter by (e.g. WhatsApp phone number)

- Source: `query`
- Required: no
- Type: `string`
- Example: `+15551234567`

##### `--agent-id`

Return only actors linked to this agent

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

##### `--chat-id`

Return only actors linked to this chat

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

##### `--conversation-id`

Return only actors that participate in this conversation (derived from the conversation's messages). 

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

##### `--limit`

Maximum number of results to return

- Source: `query`
- Required: no
- Type: `integer`
- Default: `50`

##### `--offset`

Number of results to skip

- Source: `query`
- Required: no
- Type: `integer`
- Default: `0`

### `soat create-actor`

Create an actor

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

#### Usage

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

#### Options

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

Project ID. Required for JWT auth; omit when using an project key.

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

##### `--name`

—

- Source: `body`
- Required: yes
- Type: `string`
- Example: `Alice`

##### `--external-id`

Optional external identifier (e.g. WhatsApp phone number). If provided and an actor with this externalId already exists in the project, the existing actor is returned (idempotent — 200 OK).

- Source: `body`
- Required: no
- Type: `string`
- Example: `+15551234567`

##### `--instructions`

Persona-specific instructions composed into the effective system prompt during conversation generation.

- Source: `body`
- Required: no
- Type: `string \| null`

##### `--agent-id`

Agent to link this actor to. Mutually exclusive with chat_id.

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

##### `--chat-id`

Chat to link this actor to. Mutually exclusive with agent_id.

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

### `soat get-actor`

Get an actor by ID

- Method: `GET`
- Path: `/api/v1/actors/{actor_id}`

#### Usage

```bash
soat get-actor --actor-id <string>
```

#### Options

##### `--actor-id`

Actor ID

- Source: `path`
- Required: yes
- Type: `string`
- Example: `actor_V1StGXR8Z5jdHi6B`

### `soat delete-actor`

Delete an actor

- Method: `DELETE`
- Path: `/api/v1/actors/{actor_id}`

#### Usage

```bash
soat delete-actor --actor-id <string>
```

#### Options

##### `--actor-id`

Actor ID

- Source: `path`
- Required: yes
- Type: `string`
- Example: `actor_V1StGXR8Z5jdHi6B`

### `soat update-actor`

Update an actor

- Method: `PATCH`
- Path: `/api/v1/actors/{actor_id}`

#### Usage

```bash
soat update-actor --actor-id <string>
```

#### Options

##### `--actor-id`

Actor ID

- Source: `path`
- Required: yes
- Type: `string`
- Example: `actor_V1StGXR8Z5jdHi6B`

##### `--name`

—

- Source: `body`
- Required: no
- Type: `string`
- Example: `Alice Smith`

##### `--external-id`

External identifier (e.g. WhatsApp phone number)

- Source: `body`
- Required: no
- Type: `string`
- Example: `+15551234567`

##### `--instructions`

Persona-specific instructions

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

##### `--agent-id`

Agent to link this actor to. Mutually exclusive with chat_id.

- Source: `body`
- Required: no
- Type: `string \| null`

##### `--chat-id`

Chat to link this actor to. Mutually exclusive with agent_id.

- Source: `body`
- Required: no
- Type: `string \| null`

##### `--tags`

—

- Source: `body`
- Required: no
- Type: `object<string, string>`

### `soat get-actor-tags`

Get actor tags

- Method: `GET`
- Path: `/api/v1/actors/{actor_id}/tags`

#### Usage

```bash
soat get-actor-tags --actor-id <string>
```

#### Options

##### `--actor-id`

Actor ID

- Source: `path`
- Required: yes
- Type: `string`
- Example: `actor_V1StGXR8Z5jdHi6B`

### `soat replace-actor-tags`

Replace actor tags

- Method: `PUT`
- Path: `/api/v1/actors/{actor_id}/tags`

#### Usage

```bash
soat replace-actor-tags --actor-id <string>
```

#### Options

##### `--actor-id`

Actor ID

- Source: `path`
- Required: yes
- Type: `string`
- Example: `actor_V1StGXR8Z5jdHi6B`

### `soat merge-actor-tags`

Merge actor tags

- Method: `PATCH`
- Path: `/api/v1/actors/{actor_id}/tags`

#### Usage

```bash
soat merge-actor-tags --actor-id <string>
```

#### Options

##### `--actor-id`

Actor ID

- Source: `path`
- Required: yes
- Type: `string`
- Example: `actor_V1StGXR8Z5jdHi6B`