# struere threads

> Manage conversation threads

The `threads` command lets you list, view, archive, and reset conversation threads from the terminal.

## Usage

```bash
bunx struere threads list
bunx struere threads view <id>
bunx struere threads archive <id>
bunx struere threads reset --phone "+56912345678"
```

## Subcommands

### threads list

List conversation threads.

```bash
bunx struere threads list
bunx struere threads list --channel whatsapp --env production
bunx struere threads list --limit 10 --json
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--channel <channel>` | Filter by channel: `whatsapp`, `api`, `widget`, `dashboard` |
| `--limit <n>` | Number of threads to return. Default: `25` |
| `--json` | Output results as JSON |

The output table shows:

| Column | Description |
|--------|-------------|
| ID | Thread ID |
| Channel | Channel type (whatsapp, api, widget, dashboard) |
| Participant | Contact name or phone number |
| Agent | Currently assigned agent slug |
| Last Message | Truncated last message text |
| Time | Relative timestamp of last activity |

### threads view

View thread details and recent messages.

```bash
bunx struere threads view m57abc123
bunx struere threads view m57abc123 --env production --json
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |

Displays the thread metadata (channel, agent, participant, creation time) followed by the most recent messages with role labels and timestamps.

### threads archive

Archive a thread, freeing its `externalId` for reuse.

```bash
bunx struere threads archive m57abc123
bunx struere threads archive m57abc123 --env production --confirm
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--confirm` | Skip production environment confirmation prompt |
| `--json` | Output results as JSON |

Archiving a thread marks it as inactive. For WhatsApp threads, this frees the `externalId` so that the next inbound message from that phone number creates a fresh thread.

### threads reset

Archive a thread by phone number. Finds the active thread for the given phone number and archives it.

```bash
bunx struere threads reset --phone "+56912345678"
bunx struere threads reset --phone "+56912345678" --env production --confirm
```

| Flag | Description |
|------|-------------|
| `--phone <number>` | Phone number to look up (required) |
| `--env <environment>` | Environment. Default: `production` |
| `--confirm` | Skip production environment confirmation prompt |
| `--json` | Output results as JSON |

This is a shortcut for finding a WhatsApp thread by phone number and archiving it in one step.

## Examples

```bash
# List WhatsApp threads in production
bunx struere threads list --channel whatsapp --env production

# View a specific thread
bunx struere threads view m57abc123

# Archive a thread in production
bunx struere threads archive m57abc123 --env production --confirm

# Reset a WhatsApp thread by phone number
bunx struere threads reset --phone "+56912345678" --env production
```

## Error Cases

| Scenario | Behavior |
|----------|----------|
| Thread ID not found | Exits with error: `Thread not found: <id>` |
| Phone number has no active thread | Exits with error: `No active thread found for <number>` |
| Not authenticated | Prompts for login or exits with error |