# struere threads

> Manage conversation threads

The `threads` command lets you list, view, archive, reset, and take over 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"
bunx struere threads reply <target> -m "Hi, this is a human agent."
bunx struere threads pause <target>
bunx struere threads resume <target>
```

## Targeting a Conversation

`reply`, `pause`, and `resume` take a `<target>` that is **either** a Convex thread id **or** a phone number:

```bash
bunx struere threads reply m57abc123 -m "On it."
bunx struere threads reply "+56912345678" -m "On it."
```

When `<target>` is a phone number, the command resolves it to the single **active** matching conversation. If multiple active conversations match, the command lists them and exits, asking you to re-run with an explicit thread id.

These three commands are **WhatsApp-only**. Non-WhatsApp threads (`api`, `widget`, `voice`) are rejected with a clear error.

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

### threads reply

Send a WhatsApp text message directly to the end-user mid-conversation — the CLI equivalent of the dashboard Conversations "pop in as the agent" / human takeover. The message is delivered to the user's WhatsApp via the connected number and recorded in the conversation tagged as a human-operator message (it shows as "via CLI" in the dashboard).

```bash
bunx struere threads reply m57abc123 -m "Hi, this is a human agent — happy to help."
bunx struere threads reply "+56912345678" -m "On it, give me a moment." --env production
```

| Flag | Description |
|------|-------------|
| `-m, --message <text>` | Message text to send (required) |
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |

`reply` does **not** pause the agent — sending a message and taking over are deliberately decoupled. The agent keeps auto-responding unless you run `threads pause`. (This differs from the dashboard, where replying auto-pauses the agent.)

WhatsApp blocks free-form text outside the 24-hour customer-service window. If delivery fails (the window is closed or the connection is not connected), `reply` reports the failure, records the failed attempt on the conversation, and exits non-zero. To re-open the conversation, send an approved template via `struere run-tool whatsapp.sendTemplate`. Templates are not part of `reply`.

### threads pause

Silence the agent on a conversation. The agent stops auto-responding until you run `threads resume`.

```bash
bunx struere threads pause m57abc123
bunx struere threads pause "+56912345678" --env production
```

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

Use `pause` together with `reply` to take over a conversation: pause the agent, then reply as a human operator.

### threads resume

Hand the conversation back to the agent. The agent resumes auto-responding to inbound messages.

```bash
bunx struere threads resume m57abc123
bunx struere threads resume "+56912345678" --env production
```

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

## 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

# Take over a conversation: pause the agent, then reply as a human
bunx struere threads pause "+56912345678" --env production
bunx struere threads reply "+56912345678" -m "Hi, a human is taking over from here." --env production

# Hand the conversation back to the agent
bunx struere threads resume "+56912345678" --env production

# Reply by thread id (no auto-pause — agent keeps responding)
bunx struere threads reply m57abc123 -m "Your order shipped today."
```

## Authentication

The `threads` commands work with both authentication methods:

| Method | How it works |
|--------|-------------|
| **API key** (`STRUERE_API_KEY`) | Environment is determined by the API key |
| **Clerk session** (`struere login`) | Uses your logged-in credentials |

## 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>` |
| Phone number matches multiple active threads | Lists the matches and exits, asking you to re-run with an explicit thread id |
| `reply`, `pause`, or `resume` on a non-WhatsApp thread | Rejected with an error (these commands are WhatsApp-only) |
| `reply` without `-m/--message` | Exits with an error: the message is required |
| `reply` outside the 24h window or connection not connected | Reports the failure, records the failed attempt, exits non-zero, and suggests sending a template via `struere run-tool whatsapp.sendTemplate` |
| Not authenticated | Prompts for login or exits with error |