# Cuenta personal (/es/docs/wa/commands-personal)

Tus chats de WhatsApp, mensajes, contactos, búsquedas, archivos, encuestas y envíos explícitos.

## Opciones globales [#opciones-globales]

| Opción | Qué hace |
| --- | --- |
| `-V, --version` | output the version number. |
| `-v, --verbose` | more detail in what is shown: -v ids, -vv everything we know. Default: `0`. |
| `--json` | machine-readable output: one JSON value on stdout; --json=id,text keeps only those fields. |
| `--jsonl` | machine-readable output: one JSON object per line, for streaming and jq. |
| `--quiet` | diagnostics off; a failure is still said. |
| `--trace` | the connection's own log lines on stderr — never message content. |
| `--debug` | on a failure, its whole record — cause and stack — in place of the short line. |
| `--timeout <duration>` | give up on the whole command after this — 30s, 2m, 500ms. |
| `--offline` | answer from what was recorded and never connect; fails if nothing was. |
| `--no-input` | never prompt or open interactive login; piped input remains available. |
| `--max-input-bytes <bytes>` | maximum buffered input bytes (default: 16777216). |
| `--max-output-bytes <bytes>` | maximum machine output bytes (default: 4194304; 0 disables). |
| `--brief` | found messages as reference, title, time, sender and excerpt only. |
| `--full` | found messages with their whole text and every provider field. |
| `--dry-run` | preview parsed arguments and permissions before running the action. |
| `--yes` | go ahead without the question an ask level puts before a write. |
| `--record` | keep this run — ids and timings, never message content. |
| `--no-record` | do not keep it, whatever the configuration says. |

## Comandos [#comandos]

## `wa chats` [#wa-chats]

the account's chats

### `wa chats list` [#wa-chats-list]

chats, newest first, archived ones included; the query is answered from the local store, so online, where the messenger filters nothing, it needs --offline

```sh
wa chats list [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |
| `--all` | every row, no paging. |

### `wa chats events` [#wa-chats-events]

who joined, left, was added or removed, and by whom — from the chat's service messages; the last 7 days unless the query names time

```sh
wa chats events <chat> [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

### `wa chats inspect` [#wa-chats-inspect]

what an invite or public link leads to, without joining it

```sh
wa chats inspect <link>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `link` | required | an invite link or a public one. |

### `wa chats show` [#wa-chats-show]

one chat: its kind, unread count, last message time and who is in it

```sh
wa chats show <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa chats documents` [#wa-chats-documents]

the Google Docs and Drive documents linked in a chat's stored messages

#### `wa chats documents list` [#wa-chats-documents-list]

every document link in the chat, newest first, and whether the store has it

```sh
wa chats documents list <chat> [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |

### `wa chats mark-read` [#wa-chats-mark-read]

mark a chat read; the other side sees that you read it

**Changes something in WhatsApp.**

```sh
wa chats mark-read <chat> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

| Opción | Qué hace |
| --- | --- |
| `--until-id <id>` | only up to this message id; the newest by default. |

### `wa chats tracking` [#wa-chats-tracking]

the chats whose member lists serve fetches daily into the local store — chats members fetch --track adds one

#### `wa chats tracking list` [#wa-chats-tracking-list]

every tracked chat: since when, and its last member count

```sh
wa chats tracking list [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

#### `wa chats tracking show` [#wa-chats-tracking-show]

one chat: whether it is tracked, and its member count per day for the last 30 days

```sh
wa chats tracking show <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

#### `wa chats tracking add` [#wa-chats-tracking-add]

fetch this chat's member list daily while serve runs, from its next run

**Changes something on this computer only.**

```sh
wa chats tracking add <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

#### `wa chats tracking remove` [#wa-chats-tracking-remove]

stop fetching it daily; the history already kept stays

**Changes something on this computer only.**

```sh
wa chats tracking remove <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa chats join` [#wa-chats-join]

join a group or channel by its link; the others in it see that you joined

**Changes something in WhatsApp.**

```sh
wa chats join <link>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `link` | required | an invite link, or a public one. |

### `wa chats leave` [#wa-chats-leave]

leave a group or channel; the others in it see that you left

**Changes something in WhatsApp.**

```sh
wa chats leave <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa chats folders` [#wa-chats-folders]

your chat folders

#### `wa chats folders list` [#wa-chats-folders-list]

your chat folders, in the order the app shows them

```sh
wa chats folders list [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms; this list filters by none yet. |

#### `wa chats folders show` [#wa-chats-folders-show]

one chat folder, with the names of the chats in it

```sh
wa chats folders show <folder>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `folder` | required | the folder's id, or its title exactly. |

#### `wa chats folders create` [#wa-chats-folders-create]

create a chat folder

**Changes something in WhatsApp.**

```sh
wa chats folders create <title> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `title` | required | the folder's name; the app may refuse a long one. |

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat to put in it, by id or name; repeat it for more. |

#### `wa chats folders update` [#wa-chats-folders-update]

rename a folder, or change which chats are in it

**Changes something in WhatsApp.**

```sh
wa chats folders update <folder> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `folder` | required | folder id, or its title exactly. |

| Opción | Qué hace |
| --- | --- |
| `--title <title>` | a new name. |
| `--add <chat>` | put a chat in it; repeat it for more. |
| `--remove <chat>` | take a chat out of it, and off its excluded and pinned lists; repeat it for more. |

#### `wa chats folders delete` [#wa-chats-folders-delete]

delete a folder; the chats in it stay

**Changes something in WhatsApp.**

```sh
wa chats folders delete <folder>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `folder` | required | folder id, or its title exactly. |

### `wa chats rules` [#wa-chats-rules]

what `chats moderate` judges a group by, kept in a file of this profile

#### `wa chats rules show` [#wa-chats-rules-show]

the group's rules; the defaults, marked not saved, if it has none yet

```sh
wa chats rules show <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

#### `wa chats rules set` [#wa-chats-rules-set]

change one rule; the group's first change writes every rule with its default

**Changes something on this computer only.**

```sh
wa chats rules set <chat> <key> <value>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `key` | required | one of: trusted, blocked, blockedNames, links, invites, forwards, blockedPeople, flood.messages, flood.minutes, flood.action, newAccount.days, newAccount.action, consent.delete, consent.remove. |
| `value` | required | the new value; a list is comma-separated. |

#### `wa chats rules unset` [#wa-chats-rules-unset]

put one rule back to its default

**Changes something on this computer only.**

```sh
wa chats rules unset <chat> <key>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `key` | required | one of: trusted, blocked, blockedNames, links, invites, forwards, blockedPeople, flood.messages, flood.minutes, flood.action, newAccount.days, newAccount.action, consent.delete, consent.remove. |

### `wa chats mute` [#wa-chats-mute]

stop notifications from a chat, for good or until a time; nobody in it is told

**Changes something in WhatsApp.**

```sh
wa chats mute <chat> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

| Opción | Qué hace |
| --- | --- |
| `--until <time>` | only until then: 2026-09-25T09:00 (local time), or 30m, 2h, 7d from now. |

### `wa chats unmute` [#wa-chats-unmute]

hear a muted chat again

**Changes something in WhatsApp.**

```sh
wa chats unmute <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa chats archive` [#wa-chats-archive]

move a chat into the archive; nobody in it is told

**Changes something in WhatsApp.**

```sh
wa chats archive <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa chats unarchive` [#wa-chats-unarchive]

bring an archived chat back to the chat list

**Changes something in WhatsApp.**

```sh
wa chats unarchive <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa chats mark-unread` [#wa-chats-mark-unread]

mark a chat unread on your own devices; nobody in it is told

**Changes something in WhatsApp.**

```sh
wa chats mark-unread <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa chats clear` [#wa-chats-clear]

delete every message in a chat for this account; the others in it keep theirs

**Changes something in WhatsApp.**

```sh
wa chats clear <chat> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

| Opción | Qué hace |
| --- | --- |
| `--allow-dangerous` | go ahead without the question an ask level puts before a deletion. |

## `wa contacts` [#wa-contacts]

people this account has a one-to-one chat with

### `wa contacts list` [#wa-contacts-list]

people you have a one-to-one chat with; name: matches the name, your local alias or the @username, notes: your private notes about them

```sh
wa contacts list [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |
| `--all` | every row, no paging. |
| `--order <recent\|name>` | newest conversation first, or alphabetical. Default: `recent`. |

### `wa contacts show` [#wa-contacts-show]

one person and the chats you share with them

```sh
wa contacts show <person> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name. |

| Opción | Qué hace |
| --- | --- |
| `--with-notes` | include your private notes, subject to contacts.notes.list permission. |

### `wa contacts info` [#wa-contacts-info]

everything the messenger says about one person — handles, flags, last seen, when they registered — and how many of their messages the store holds in each chat you share, the first and the last, and the earlier names and usernames the store saw them with

```sh
wa contacts info <person> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name. |

| Opción | Qué hace |
| --- | --- |
| `--show-phone` | print the whole phone number. |

### `wa contacts context` [#wa-contacts-context]

what the store holds about one person, in every messenger linked to them: shared chats, the last messages each way, their recent messages, where others mentioned them — never connects

```sh
wa contacts context <person> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | at most this many messages in each list; 10 if not given. |
| `--since-time <time>` | nothing older than this ISO 8601 time, or 2h / 1d ago. |
| `--chat <chat>` | a chat, by id or name; repeat it for more — then their newest messages in each, 20 unless --limit, short unless -v. |

### `wa contacts prepare` [#wa-contacts-prepare]

before you talk to someone: what contacts context gives, plus the one-to-one chats where they wrote last, open tasks, accepted facts, your notes and their recent meetings, each with its reference; never connects

```sh
wa contacts prepare <person> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | at most this many messages, and items in each section; 10 if not given. |
| `--since-time <time>` | no message or meeting older than this ISO 8601 time, or 2h / 1d ago. |

### `wa contacts events` [#wa-contacts-events]

everything one person took part in, in every messenger linked to them — messages they wrote or were mentioned in, chats, mail, meetings, tasks — newest first, from the store; never connects

```sh
wa contacts events <person> [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name. |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | at most this many; 50 if not given. |
| `--cursor <cursor>` | go on from where the last page stopped; page.next gives it, with the same filters. |

### `wa contacts check` [#wa-contacts-check]

whether one person looks like a bot, a fake or a spammer: their profile and what they wrote in the store — a hint, never a verdict; the public ban lists cover Telegram only, so nothing is sent

```sh
wa contacts check <person> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name. |

| Opción | Qué hace |
| --- | --- |
| `--no-registries` | do not ask the public ban lists; nothing about them leaves this machine. |

### `wa contacts link` [#wa-contacts-link]

record that two people in the store are one person — the same name is never enough

**Changes something on this computer only.**

```sh
wa contacts link <person> <other>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name. |
| `other` | required | the same in another messenger of the store, as <messenger>:<person> — max:Ana; me: it is you, as zoom:<id> me. |

### `wa contacts unlink` [#wa-contacts-unlink]

undo contacts link for one identity: it is a person of its own again

**Changes something on this computer only.**

```sh
wa contacts unlink <person>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | their id, @username, or part of their name; <messenger>:<person> for another messenger. |

### `wa contacts lookup` [#wa-contacts-lookup]

who has this phone number — asks for it, or reads it from stdin; never an argument

```sh
wa contacts lookup
```

### `wa contacts sync` [#wa-contacts-sync]

take the whole contact list from the messenger into the local store

**Changes something on this computer only.**

```sh
wa contacts sync
```

### `wa contacts aliases` [#wa-contacts-aliases]

a private local display name in the selected account

#### `wa contacts aliases set` [#wa-contacts-aliases-set]

your own name for a person in this account; kept on this machine, never sent

**Changes something on this computer only.**

```sh
wa contacts aliases set <person> <alias>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | the person's id, reference or known name. |
| `alias` | required | the private name to use for this person. |

#### `wa contacts aliases remove` [#wa-contacts-aliases-remove]

drop your local name for a person; their own name shows again

**Changes something on this computer only.**

```sh
wa contacts aliases remove <person>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | the person's id, reference or known name. |

### `wa contacts notes` [#wa-contacts-notes]

your private notes on a stored contact, the same in every account that sees them

#### `wa contacts notes list` [#wa-contacts-notes-list]

every private note you keep on a person, oldest first

```sh
wa contacts notes list <person> [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | the person's id, reference or known name. |
| `query` | optional | field:value terms; this list filters by none yet. |

#### `wa contacts notes show` [#wa-contacts-notes-show]

one private note on a person, with its revision for edit

```sh
wa contacts notes show <person> <id>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | the person's id, reference or known name. |
| `id` | required | the note id from contacts notes list. |

#### `wa contacts notes add` [#wa-contacts-notes-add]

add a private note on a person from stdin or --text-file; never sent

**Changes something on this computer only.**

```sh
wa contacts notes add <person> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | the person's id, reference or known name. |

| Opción | Qué hace |
| --- | --- |
| `--text-file <path>` | read note text from a file; omitted or - reads stdin. |

#### `wa contacts notes edit` [#wa-contacts-notes-edit]

replace a note's text; --revision must match the one you read

**Changes something on this computer only.**

```sh
wa contacts notes edit <person> <id> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | the person's id, reference or known name. |
| `id` | required | the note id from contacts notes list. |

| Opción | Qué hace |
| --- | --- |
| `--text-file <path>` | read note text from a file; omitted or - reads stdin. |
| `--revision <n>` | the revision you read before editing. |

#### `wa contacts notes remove` [#wa-contacts-notes-remove]

delete one private note on a person

**Changes something on this computer only.**

```sh
wa contacts notes remove <person> <id>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | the person's id, reference or known name. |
| `id` | required | the note id from contacts notes list. |

### `wa contacts add` [#wa-contacts-add]

add a person to your contacts — `contacts list` still shows only people you have a dialog with

**Changes something in WhatsApp.**

```sh
wa contacts add <person>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | person id — `contacts lookup` finds one — or part of a known name. |

### `wa contacts block` [#wa-contacts-block]

stop a person from writing to you — they need not be a contact

**Changes something in WhatsApp.**

```sh
wa contacts block <person>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | person id — `contacts lookup` finds one — or part of a known name. |

### `wa contacts unblock` [#wa-contacts-unblock]

let a blocked person write to you again

**Changes something in WhatsApp.**

```sh
wa contacts unblock <person>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | person id — `contacts lookup` finds one — or part of a known name. |

### `wa contacts rename` [#wa-contacts-rename]

rename the contact in the messenger address book; use contacts alias for a private local name

**Changes something in WhatsApp.**

```sh
wa contacts rename <person> <first-name> [last-name]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `person` | required | person id — `contacts lookup` finds one — or part of a known name. |
| `first-name` | required | the name you want to see for them. |
| `last-name` | optional | the last name you want to see for them. |

### `wa contacts import` [#wa-contacts-import]

upload phone numbers and add the people the messenger has under them

**Changes something in WhatsApp.**

```sh
wa contacts import <file>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `file` | required | one person per line: number, then a comma, a tab or a semicolon, then the name. |

## `wa messages` [#wa-messages]

read and send messages

### `wa messages evidence` [#wa-messages-evidence]

general chat context, newest first, with references, coverage and fingerprints for verification

```sh
wa messages evidence <chat> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many, 1–100. |
| `--cursor <cursor>` | go on from where page.next says the last packet stopped. |

### `wa messages list` [#wa-messages-list]

a chat's messages, oldest to newest

```sh
wa messages list <chat> [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `query` | optional | where to start: id\<42, date>2026-10-01; starred:true keeps the ones you starred. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many. |
| `--cursor <cursor>` | go on from where the last page stopped; page.next gives it. |
| `--transcribe` | turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes. |
| `--model <model>` | which downloaded speech model hears them, with --transcribe; `models list` shows them. |

### `wa messages send` [#wa-messages-send]

send a text message; without \[text], the text is read from stdin

**Changes something in WhatsApp.**

```sh
wa messages send <chat> [text] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `text` | optional | the message. |

| Opción | Qué hace |
| --- | --- |
| `--reply-to <message>` | answer this message, by its id in the same chat. |
| `--operation-id <id>` | repeat a send whose outcome was unknown, without risking a second copy. |
| `--no-preview` | no preview card for a link in the text. |
| `--md` | read this messenger's Markdown; see its formatting guide for supported syntax. |
| `--file <file>` | attach a file; the text becomes its caption; repeat it for an album. Default: \`\`. |
| `--photo <file>` | attach a .jpg, .png or .webp as a photo; the text becomes its caption; repeat it for an album. Default: \`\`. |
| `--as-file` | send each --file as a file to download, a video included. |
| `--voice <file>` | send an Ogg Opus file as a voice message, alone, with no text. |
| `--allow-any-file` | send a file even from credential folders or this CLI's own folders. |
| `--filename <name>` | the name others see for the --file, instead of its name on disk. |
| `--sticker-file <file>` | send a .webp file as a sticker, alone, with no text. |

### `wa messages show` [#wa-messages-show]

one message, by its chat and id or by its msg: locator

```sh
wa messages show <chat> [message]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter); or a msg: locator, with no message id after it. |
| `message` | optional | the message id. |

### `wa messages context` [#wa-messages-context]

a message and what came either side of it, oldest first

```sh
wa messages context <chat> [message] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter); or a msg: locator, with no message id after it. |
| `message` | optional | the message id. |

| Opción | Qué hace |
| --- | --- |
| `--thread` | the stored reply chain and replies instead of time neighbours; falls back when no graph exists. |
| `--thread-hops <n>` | at most this many links from the hit (default: 8). |
| `--thread-messages <n>` | at most this many messages in each thread context (default: 50). |
| `--thread-bytes <n>` | at most this many bytes of whole messages and links in each context (default: 65536). |
| `--thread-within <duration>` | messages within this long either side of the hit (default: 1d). |
| `--before-n <n>` | how many before it. Default: `5`. |
| `--after-n <n>` | how many after it. Default: `5`. |

### `wa messages download` [#wa-messages-download]

save a message's photos, files, videos and voice notes to a folder — or a whole chat's with --all

**Changes something on this computer only.**

```sh
wa messages download <chat> [message] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | optional | the message id; left out with --all. |

| Opción | Qué hace |
| --- | --- |
| `--output-dir <dir>` | where to save them; created if missing. Default: `.`. |
| `--all` | every file of the chat, newest first; run it again to continue where it stopped. |
| `--pause <duration>` | with --all, a pause between pages, to stay under the provider's limits. Default: `2s`. |
| `--extract` | read text layers from the files this download maps into the local content index. |

### `wa messages transcribe` [#wa-messages-transcribe]

a voice message as text — by WhatsApp where it can, else by a model on this machine

```sh
wa messages transcribe <chat> <message> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the id of a voice message. |

| Opción | Qué hace |
| --- | --- |
| `--local` | use the model on this machine, never the messenger. |
| `--model <model>` | which downloaded model; implies --local (`models list`). |

### `wa messages edit` [#wa-messages-edit]

change the text of your own message; the other side may have read it already

**Changes something in WhatsApp.**

```sh
wa messages edit <chat> <message> [text] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the id of your own message. |
| `text` | optional | the new text; without it, read from stdin. |

| Opción | Qué hace |
| --- | --- |
| `--md` | read this messenger's Markdown; see its formatting guide for supported syntax. |

### `wa messages delete` [#wa-messages-delete]

delete messages for you only; with --for-everyone, for everyone in the chat

**Changes something in WhatsApp.**

```sh
wa messages delete <chat> <message> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message ids, by spaces or commas, at most 10. |

| Opción | Qué hace |
| --- | --- |
| `--for-everyone` | delete for everyone in the chat, not only for you — they cannot get it back. |
| `--allow-dangerous` | go ahead without the question an ask level puts before a deletion. |

### `wa messages forward` [#wa-messages-forward]

forward one message to another chat

**Changes something in WhatsApp.**

```sh
wa messages forward <chat> <message> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | the chat the message is in: a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |

| Opción | Qué hace |
| --- | --- |
| `--to <chat>` | where it goes: a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--operation-id <id>` | repeat a forward whose outcome was unknown, without risking a second copy. |

### `wa messages pin` [#wa-messages-pin]

pin a message in a chat; its members are told

**Changes something in WhatsApp.**

```sh
wa messages pin <chat> <message> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |

| Opción | Qué hace |
| --- | --- |
| `--expire-time <time>` | how long the pin lasts: 24h, 7d or 30d; 7d by default. |

### `wa messages unpin` [#wa-messages-unpin]

unpin a message in a chat

**Changes something in WhatsApp.**

```sh
wa messages unpin <chat> <message>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |

### `wa messages star` [#wa-messages-star]

star a message, so it is easy to find again; only you see the star

**Changes something in WhatsApp.**

```sh
wa messages star <chat> <message>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |

### `wa messages unstar` [#wa-messages-unstar]

take the star off a message

**Changes something in WhatsApp.**

```sh
wa messages unstar <chat> <message>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |

### `wa messages link` [#wa-messages-link]

a message permalink when supported, and its account-scoped locator

```sh
wa messages link <chat> [message]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter); or a msg: locator, with no message id after it. |
| `message` | optional | the message id. |

### `wa messages comments` [#wa-messages-comments]

the comments received under a post, oldest to newest

```sh
wa messages comments <chat> <post> [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | the chat: a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `post` | required | the post's message id in the chat. |
| `query` | optional | where to start: id\<42. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many. |
| `--cursor <cursor>` | go on from where the last page stopped; page.next gives it. |

### `wa messages links` [#wa-messages-links]

why a message is in its conversation: each link it has, and the chain of answers back to the start

```sh
wa messages links <chat> <message>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |

### `wa messages sync` [#wa-messages-sync]

bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat

**Changes something on this computer only.**

```sh
wa messages sync [chat] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | optional | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

| Opción | Qué hace |
| --- | --- |
| `--all` | every chat, most recently active first — what search needs; the last 90d unless --since-time or --last. |
| `--limit <n>` | at most this many messages in this run, per chat with --all; 1000 if not given. |
| `--page-size <n>` | how many messages one request asks for; 50 if not given. |
| `--pause <duration>` | the least pause between pages, to stay under the provider's limits; each is up to twice that. Default: `2s`. |
| `--since-time <time>` | stop once it reaches messages older than this: ISO 8601, or 2h / 1d ago. |
| `--last <n>` | stop once the newest n messages are held. |
| `--catch-up` | prepare local search after this run; overrides search_catch_up. |
| `--no-catch-up` | skip local preparation after this run. |
| `--catch-up-chunks <n>` | at most this many local vector chunks. |
| `--catch-up-messages <n>` | skip a graph rebuild larger than this many messages. |
| `--catch-up-time <duration>` | local preparation time budget, 30s by default. |
| `--background` | run as a job that outlives this command; `store jobs show` follows it. |
| `--dry-run` | only estimate how many messages, requests and minutes a full fetch would still take — from the store, no request. |

## `wa reactions` [#wa-reactions]

react to messages

### `wa reactions add` [#wa-reactions-add]

put your reaction on a message; it replaces the one you had

**Changes something in WhatsApp.**

```sh
wa reactions add <chat> <message> <emoji>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |
| `emoji` | required | one emoji, for example 👍. |

### `wa reactions remove` [#wa-reactions-remove]

take your reaction off a message

**Changes something in WhatsApp.**

```sh
wa reactions remove <chat> <message>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the message id. |

## `wa polls` [#wa-polls]

read a poll, vote in it, create one

### `wa polls show` [#wa-polls-show]

a poll and its answer ids, as the message carries it now

```sh
wa polls show <chat> <message>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the id of the message that carries the poll. |

### `wa polls voters` [#wa-polls-voters]

who voted for what, newest first

```sh
wa polls voters <chat> <message> [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the id of the message that carries the poll. |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |

### `wa polls vote` [#wa-polls-vote]

vote in a poll, or take your vote back; the others see it

**Changes something in WhatsApp.**

```sh
wa polls vote <chat> <message> [answers] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | the id of the message that carries the poll. |
| `answers` | optional | answer ids, as `polls show` prints them. |

| Opción | Qué hace |
| --- | --- |
| `--retract` | take your vote back. |

### `wa polls create` [#wa-polls-create]

send a poll to a chat, as a message of its own; everyone sees who voted for what

**Changes something in WhatsApp.**

```sh
wa polls create <chat> <question> <answers> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `question` | required | the question. |
| `answers` | required | two answers or more. |

| Opción | Qué hace |
| --- | --- |
| `--multiple` | people may pick several answers. |
| `--operation-id <id>` | repeat a create whose outcome was unknown, without risking a second poll. |

## `wa inbox` [#wa-inbox]

other people's unread messages in every chat; --new for what arrived since the last check

```sh
wa inbox [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | from when: date>2h, date>2026-10-01; the saved point stays put. |

| Opción | Qué hace |
| --- | --- |
| `--new` | what arrived since the last check, each message once — for scheduled runs. |
| `--limit <n>` | at most this many per chat, the newest. |
| `--all` | muted and archived chats too — left out unless they mention you or reply to you. |
| `--transcribe` | turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes. |
| `--model <model>` | which downloaded speech model hears them, with --transcribe; `models list` shows them. |

## `wa review` [#wa-review]

every message, yours too, in chats that changed since a point — for reviewing who owes what

```sh
wa review [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | where the last review ended and which chat: date>2h, chat:"Book club"; 3 days ago if no date. |

| Opción | Qué hace |
| --- | --- |
| `--unanswered [duration]` | only questions to you or a group's admins that nobody answered, asked at least this long ago — 4h, 1d; 24h if not given. |
| `--all` | muted and archived chats too — left out unless they mention you or reply to you. |
| `--transcribe` | turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes. |
| `--model <model>` | which downloaded speech model hears them, with --transcribe; `models list` shows them. |
| `--new` | what changed since the last `review --new`, a point per chat — for scheduled runs. |

## `wa conversations` [#wa-conversations]

the conversations inside a chat, found in the stored messages by replies, mentions and who wrote next

### `wa conversations list` [#wa-conversations-list]

a chat's conversations, the newest first: when, how many messages, how many people

```sh
wa conversations list <chat> [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many. |

### `wa conversations show` [#wa-conversations-show]

one conversation's messages, oldest first — by its id, or the one a message is in

```sh
wa conversations show <conversation> [message]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `conversation` | required | a conversation id from `conversations list`; or a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter), with a message. |
| `message` | optional | a message id in that chat: show the conversation it is in. |

### `wa conversations related` [#wa-conversations-related]

the conversations nearest in meaning to the one a message is in, in every built chat, best first — from the vectors `conversations embed` stored; runs no model

```sh
wa conversations related <chat> <message> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `message` | required | a message id in that chat. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many. |
| `--model <model>` | local: a model id from `models list` (default: e5-small); remote: the provider's model. |
| `--embedding-provider <provider>` | embedding provider: local or openai; flags override profile settings. |
| `--base-url <url>` | a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine. |
| `--dims <n>` | remote: the vector size — needed with --base-url; shortens an OpenAI model's. |

### `wa conversations status` [#wa-conversations-status]

how fresh each built chat's conversations and vectors are: messages the build has not seen, chunks with a current, stale or missing vector

```sh
wa conversations status [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | only this chat: a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--model <model>` | local: a model id from `models list` (default: e5-small); remote: the provider's model. |
| `--embedding-provider <provider>` | embedding provider: local or openai; flags override profile settings. |
| `--base-url <url>` | a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine. |
| `--dims <n>` | remote: the vector size — needed with --base-url; shortens an OpenAI model's. |

### `wa conversations batches` [#wa-conversations-batches]

windows of a chat for your own AI agent to link: which earlier message each one answers

#### `wa conversations batches status` [#wa-conversations-batches-status]

how many messages still wait for an answer, in how many batches, and how much text

```sh
wa conversations batches status [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--size <n>` | messages to answer per batch, 10–200; 50 by default. |

#### `wa conversations batches show` [#wa-conversations-batches-show]

the next window to answer, with the messages before it; message text goes to stdout only

```sh
wa conversations batches show [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--size <n>` | messages to answer per batch, 10–200; 50 by default. |

### `wa conversations links` [#wa-conversations-links]

message links and the conversations derived from them

#### `wa conversations links rebuild` [#wa-conversations-links-rebuild]

find a chat's conversations in what the store holds, replacing the last build; without --chat, every chat that changed since its build and every group never built; never asks the messenger

**Sends text to an outside service.**

```sh
wa conversations links rebuild [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--analyze` | link batches using the configured analysis provider; requires --chat and remembers consent for this chat/provider. |
| `--analysis-provider <provider>` | analysis: agent, openai or anthropic. |
| `--model <model>` | analysis model; overrides analysis_model. |
| `--base-url <url>` | analysis API endpoint; overrides analysis_base_url. |
| `--size <n>` | analysis answer messages per batch, 10–200; default 50. |
| `--max-tokens <n>` | analysis input/output reservation cap per run; default 100000. |
| `--max-chats <n>` | at most this many chats in one run; 20 if not given. |

#### `wa conversations links add` [#wa-conversations-links-add]

store your agent's answer to a batch, read as JSON from stdin: \{ "model", "answers": \[\{ "message", "parent", "confidence" }] }; all or nothing

**Changes something on this computer only.**

```sh
wa conversations links add [options]
```

| Opción | Qué hace |
| --- | --- |
| `--batch <id>` | the batch id `conversations batches show` printed. |

#### `wa conversations links clear` [#wa-conversations-links-clear]

drop your agent's answers for a chat, or only one model's; messages are never touched

**Changes something on this computer only.**

```sh
wa conversations links clear [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--answer-model <model>` | only the stored answers this model gave. |

### `wa conversations embeddings` [#wa-conversations-embeddings]

stored conversation vectors

#### `wa conversations embeddings status` [#wa-conversations-embeddings-status]

how many chunks of a chat have a vector of the model, how many are left, and what is left costs

```sh
wa conversations embeddings status [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--model <model>` | local: a model id from `models list` (default: e5-small); remote: the provider's model. |
| `--embedding-provider <provider>` | embedding provider: local or openai; flags override profile settings. |
| `--base-url <url>` | a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine. |
| `--dims <n>` | remote: the vector size — needed with --base-url; shortens an OpenAI model's. |

#### `wa conversations embeddings clear` [#wa-conversations-embeddings-clear]

drop a chat's vectors, or only one model's; messages and conversations are never touched

**Changes something on this computer only.**

```sh
wa conversations embeddings clear [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--model <model>` | local: a model id from `models list` (default: e5-small); remote: the provider's model. |
| `--embedding-provider <provider>` | embedding provider: local or openai; flags override profile settings. |
| `--base-url <url>` | a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine. |
| `--dims <n>` | remote: the vector size — needed with --base-url; shortens an OpenAI model's. |

### `wa conversations rebuild` [#wa-conversations-rebuild]

build, then embed with the model on this machine, the chats that changed since their build and the group chats never built — or only --chat; bounded per run, so run it again for the rest; never asks the messenger, downloads no model and sends no text anywhere

**Changes something on this computer only.**

```sh
wa conversations rebuild [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--max-chats <n>` | at most this many chats in one run; 20 if not given. |
| `--max-chunks <n>` | at most this many chunks embedded in one run; 2000 if not given. |

### `wa conversations consents` [#wa-conversations-consents]

remembered analysis permissions for this account's chats and provider endpoints

#### `wa conversations consents list` [#wa-conversations-consents-list]

which chats and provider endpoints you allowed to analyse, and when

```sh
wa conversations consents list [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

#### `wa conversations consents remove` [#wa-conversations-consents-remove]

forget analysis permissions so the next analysis asks again

**Changes something on this computer only.**

```sh
wa conversations consents remove [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | revoke only this chat's consents; defaults to every chat. |
| `--consent-provider <identity>` | exact provider identity from consents list; defaults to every provider. |

### `wa conversations embed` [#wa-conversations-embed]

compute a vector for each chunk of a chat's conversations for search by meaning — on this machine, or with --embedding-provider through a service and your key; resumes where it stopped; without --chat, every built chat with chunks left, on this machine only

**Sends text to an outside service.**

```sh
wa conversations embed [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--model <model>` | local: a model id from `models list` (default: e5-small); remote: the provider's model. |
| `--embedding-provider <provider>` | embedding provider: local or openai; flags override profile settings. |
| `--base-url <url>` | a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine. |
| `--dims <n>` | remote: the vector size — needed with --base-url; shortens an OpenAI model's. |
| `--threads <n>` | local: threads in all (default: min(8, cores)). |
| `--concurrency <n>` | remote: requests at once (default: 4). |
| `--max-tokens <n>` | remote: stop before a run that could send more tokens than this. |
| `--max-chats <n>` | at most this many chats in one run; 20 if not given. |
| `--max-chunks <n>` | at most this many chunks embedded in one run; 2000 if not given, and no limit with --chat. |

## `wa attachments` [#wa-attachments]

the files of stored messages: their text in the local store, where search finds it

### `wa attachments extract` [#wa-attachments-extract]

read the text of downloaded files — text, PDF/DOCX text layers, ODT/ODS/XLSX/PPTX/EPUB — into the local store, where search finds them

**Changes something on this computer only.**

```sh
wa attachments extract [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | only this chat's files; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--from-dir <dir>` | match files in this nonrecursive directory; needs --chat. |
| `--cursor <cursor>` | continue from the cursor returned by a bounded extraction. |
| `--download` | first save the files no download saved yet, from the messenger, into --output-dir. |
| `--output-dir <dir>` | with --download, where to save them; created if missing. |
| `--limit <n>` | read at most this many files; run it again to continue. |
| `--ocr` | explicitly call models.ocr for bulk image and scanned-PDF text extraction. |
| `--concurrency <n>` | remote: requests at once (default: 4). |

### `wa attachments list` [#wa-attachments-list]

files of stored messages, newest first: where each was saved and whether its text is held — never the text

```sh
wa attachments list [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |
| `--all` | every row, no paging. |

### `wa attachments show` [#wa-attachments-show]

read a bounded chunk of one retained attachment; JSON includes base64 bytes

```sh
wa attachments show <chat> [message] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter); or a msg: locator alone. |
| `message` | optional | the message id. |

| Opción | Qué hace |
| --- | --- |
| `--attachment <n>` | file position from 1; required for several files. |
| `--page <n>` | render one PDF page as PNG, from 1; optional unpdf/canvas, no OCR. |
| `--offset-bytes <n>` | byte offset from 0. |
| `--chunk-bytes <n>` | bytes to return, 1–1048576 (default524288). |
| `--expected-fingerprint <hash>` | require the whole file SHA-256 from the preceding chunk. |

### `wa attachments update` [#wa-attachments-update]

keep the text an agent read from a file — a scan, a photo — so search finds it; nothing is sent

**Changes something on this computer only.**

```sh
wa attachments update <chat> [message] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter); or a msg: locator, with no message id after it. |
| `message` | optional | the message id. |

| Opción | Qué hace |
| --- | --- |
| `--attachment <n>` | which file of the message, from 1; needed when it has more than one. |
| `--text-file <path>` | read the text from this file; - or none reads stdin. |

### `wa attachments download` [#wa-attachments-download]

archive media from selected chats; verify and keep existing copies

**Changes something on this computer only.**

```sh
wa attachments download <dir> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | archive directory; created if missing. |

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | only this chat; repeat for more; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). Default: \`\`. |
| `--since-time <time>` | include messages from this ISO timestamp with a time zone. |
| `--pause <duration>` | pause between history pages. Default: `2s`. |

### `wa attachments check` [#wa-attachments-check]

rehash all archived files without connecting to the messenger

```sh
wa attachments check <dir>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | archive directory. |

### `wa attachments jobs` [#wa-attachments-jobs]

daily media archive timers for this profile

#### `wa attachments jobs install` [#wa-attachments-jobs-install]

install a Linux daily archive timer for this directory; starts nothing

**Changes something on this computer only.**

```sh
wa attachments jobs install <dir> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | archive directory, used with the same profile as install. |

| Opción | Qué hace |
| --- | --- |
| `--at <HH:mm>` | daily start time. Default: `03:00`. |
| `--timezone <zone>` | IANA time zone of the daily start time. Default: `UTC`. |
| `--chat <chat>` | only this chat; repeat for more; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). Default: \`\`. |
| `--since-time <time>` | include messages from this ISO timestamp with a time zone. |

#### `wa attachments jobs start` [#wa-attachments-jobs-start]

enable the installed archive timer at login and start its daily schedule

**Changes something on this computer only.**

```sh
wa attachments jobs start <dir>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | archive directory, used with the same profile as install. |

#### `wa attachments jobs stop` [#wa-attachments-jobs-stop]

disable the archive timer; a download already running finishes

**Changes something on this computer only.**

```sh
wa attachments jobs stop <dir>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | archive directory, used with the same profile as install. |

#### `wa attachments jobs status` [#wa-attachments-jobs-status]

show whether this directory's archive timer is installed and active

```sh
wa attachments jobs status <dir>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | archive directory, used with the same profile as install. |

#### `wa attachments jobs uninstall` [#wa-attachments-jobs-uninstall]

remove this directory's stopped archive timer; keep archived files

**Changes something on this computer only.**

```sh
wa attachments jobs uninstall <dir>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | archive directory, used with the same profile as install. |

### `wa attachments move` [#wa-attachments-move]

move older images into another verified archive; remember their new locations

**Changes something on this computer only.**

```sh
wa attachments move <dir> <archive-dir> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `dir` | required | source media archive directory. |
| `archive-dir` | required | destination archive directory; created if needed. |

| Opción | Qué hace |
| --- | --- |
| `--before-time <time>` | move images whose message date is before this ISO timestamp with zone. |
| `--dry-run` | show counts and bytes without moving files or creating the destination. |

## `wa tags` [#wa-tags]

your own labels on chats, people, messages and tasks, kept in the local store and never sent; tag: in a search finds them

### `wa tags rebuild` [#wa-tags-rebuild]

derive local group/channel tags from cached metadata using keyword rules

**Changes something on this computer only.**

```sh
wa tags rebuild [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a stored group/channel; repeat to select several. Default: \`\`. |
| `--limit <n>` | process at most 1–500 chats. Default: `50`. |
| `--sync-first` | read current descriptions from the messenger before classifying. |
| `--dry-run` | preview cached classification without changing the store. |

### `wa tags add` [#wa-tags-add]

put tags on one chat, person, message or task

**Changes something on this computer only.**

```sh
wa tags add <tag> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `tag` | required | one or more tags: 1–32 letters a–z, digits and hyphens; upper case is lowered. |

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | the chat to tag, or the chat of --message; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--contact <person>` | the person to tag: their id, @username or name, as the local store knows them. |
| `--message <message>` | the message to tag: its id in --chat, or a msg: locator alone. |
| `--task <id>` | the task to tag: its id or key, as tasks list shows it. |

### `wa tags remove` [#wa-tags-remove]

take tags off one chat, person, message or task

**Changes something on this computer only.**

```sh
wa tags remove <tag> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `tag` | required | one or more tags: 1–32 letters a–z, digits and hyphens; upper case is lowered. |

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | the chat to untag, or the chat of --message; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--contact <person>` | the person to untag: their id, @username or name, as the local store knows them. |
| `--message <message>` | the message to untag: its id in --chat, or a msg: locator alone. |
| `--task <id>` | the task to untag: its id or key, as tasks list shows it. |
| `--claim <claim>` | remove only this ownership claim: manual or auto. |

### `wa tags list` [#wa-tags-list]

what is tagged: this account's chats, messages and tasks, and the people of its messenger

```sh
wa tags list [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

## `wa mentions` [#wa-mentions]

phones, e-mail, links, documents, names and addresses in stored messages

### `wa mentions list` [#wa-mentions-list]

this account's mentions matching the query, newest first; --new for those found since the last review

```sh
wa mentions list [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | fields below; a bare word is a value, so a phone typed with 8 finds it written with +7. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |
| `--new` | undecided mentions found since the last --new run that showed them all; the first run shows every one. |

### `wa mentions domains` [#wa-mentions-domains]

the sites this account's links point to, most linked first, with chats and first and last time

```sh
wa mentions domains [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | narrows the links counted: the fields below; dismissed links are never counted. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |

### `wa mentions places` [#wa-mentions-places]

confirmed addresses, in every account, most mentioned first; `mentions confirm <id>` adds one

```sh
wa mentions places [options]
```

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |

### `wa mentions show` [#wa-mentions-show]

one mention, the text around it, and how many other places hold its value

```sh
wa mentions show <id>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `id` | required | the mention's id, from mentions list. |

### `wa mentions confirm` [#wa-mentions-confirm]

say what a mention is: a phone's owner everywhere it is written, the stored document, who a name means, an address as a place

**Changes something on this computer only.**

```sh
wa mentions confirm <id> [person] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `id` | required | the mention's id, from mentions list. |
| `person` | optional | person:<uid> or organization:<id> that owns the phone or the e-mail address; person:<uid> a name means; a document or a street address needs none. |

| Opción | Qué hace |
| --- | --- |
| `--all-in-chat` | a name: also every undecided place of the same name in its chat. |
| `--as-owner` | record it as yours although an agent's terminal runs the tool (AI_AGENT or CLAUDECODE set). |

### `wa mentions reject` [#wa-mentions-reject]

not a real mention: dismiss its value everywhere and on later syncs; a name only where it is

**Changes something on this computer only.**

```sh
wa mentions reject <id> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `id` | required | the mention's id, from mentions list. |

| Opción | Qué hace |
| --- | --- |
| `--all-in-chat` | a name: also every undecided place of the same name in its chat. |
| `--as-owner` | record it as yours although an agent's terminal runs the tool (AI_AGENT or CLAUDECODE set). |

### `wa mentions rebuild` [#wa-mentions-rebuild]

find the mentions of every stored message again; decisions are kept

**Changes something on this computer only.**

```sh
wa mentions rebuild [kind]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `kind` | optional | only this kind: person-name after people were added or renamed. One of: `phone`, `email`, `url`, `document`, `person-name`, `place`. |

## `wa images` [#wa-images]

search pictures by what they show, with a model on this machine

### `wa images embed` [#wa-images-embed]

compute a vector for each picture the store knows and has none for — downloading it through the messenger, keeping only the vector; needs `picture_search` on in the profile and `images models download clip-b32`; resumes where it stopped

**Changes something on this computer only.**

```sh
wa images embed [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | only this chat; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--limit <n>` | at most this many pictures in one run; 100 if not given. |

### `wa images models` [#wa-images-models]

models that read pictures, for `images embed` and picture search

#### `wa images models list` [#wa-images-models-list]

the picture models, which are downloaded, and which one is the default

```sh
wa images models list [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms; this list filters by none yet. |

#### `wa images models download` [#wa-images-models-download]

download a picture model once, checked against the sha256 this version expects

**Reads from an outside service.**

```sh
wa images models download <model>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `model` | required | a model id from `images models list`. |

## `wa metadata` [#wa-metadata]

cached group/channel descriptions for local automatic tags

### `wa metadata show` [#wa-metadata-show]

a stored chat's cached description, as automatic tags read it

```sh
wa metadata show [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a stored chat. |

### `wa metadata sync` [#wa-metadata-sync]

fetch group and channel descriptions again and cache them

**Changes something on this computer only.**

```sh
wa metadata sync [options]
```

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | stored group/channel; repeat for several. Default: \`\`. |
| `--only-missing` | only chats with no metadata yet; without --chat, every stored group/channel. |
| `--limit <n>` | process at most 1–500 chats. Default: `50`. |

## `wa tasks` [#wa-tasks]

what waits on you — unanswered questions, mentions, requests, promises — kept in the local store; review and serve add them

### `wa tasks list` [#wa-tasks-list]

tasks, oldest first, with their message or note source

```sh
wa tasks list [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many. |

### `wa tasks add` [#wa-tasks-add]

add a task for a stored message or note — a promise, a request

**Changes something on this computer only.**

```sh
wa tasks add <message> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `message` | required | a message locator, msg:<provider>/<account>/<chat>/<message>, or note:<id>. |

| Opción | Qué hace |
| --- | --- |
| `--type <type>` | the task's type: question, request, mention or promise. |
| `--category <name>` | what it is about, from the list tasks categories prints: money, documents, meeting, …. |
| `--into <id>` | when tasks add listed tasks that may be the same job: link the message to this one instead of opening a task. |
| `--new` | when tasks add listed tasks that may be the same job: open the task anyway. |
| `--title <title>` | one line: the action and its object — send Alex the API token. |
| `--description <text>` | the detail, in Markdown: who owes whom, done when, next step, keywords. |
| `--due <time>` | when it must be done: an ISO 8601 time or 2h, 3d from now; none clears it. |
| `--remind-time <time>` | when to look at it again: an ISO 8601 time or 2h, 3d from now; none clears it. |
| `--assignee <person...>` | who does it: sender (whoever sent the task's message) or person:<id>; none clears it. Leave it out when unsure: a task with no assignee is better than none. |

### `wa tasks update` [#wa-tasks-update]

update a task's text, schedule, category, assignees, priority or parent; nothing reaches the messenger

**Changes something on this computer only.**

```sh
wa tasks update <task> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |

| Opción | Qué hace |
| --- | --- |
| `--category <name>` | what it is about, from the list tasks categories prints: money, documents, meeting, …; a change is kept in the task's history. |
| `--priority <n>` | priority from 0 (urgent) through 4 (low). |
| `--parent <id>` | parent task in the same project; none clears it. |
| `--title <title>` | one line: the action and its object — send Alex the API token. |
| `--description <text>` | the detail, in Markdown: who owes whom, done when, next step, keywords. |
| `--due <time>` | when it must be done: an ISO 8601 time or 2h, 3d from now; none clears it. |
| `--remind-time <time>` | when to look at it again: an ISO 8601 time or 2h, 3d from now; none clears it. |
| `--assignee <person...>` | who does it: sender (whoever sent the task's message) or person:<id>; none clears it. Leave it out when unsure: a task with no assignee is better than none. |

### `wa tasks link` [#wa-tasks-link]

link a task to messages, chats, people or URLs — or to another task: task:<id>

**Changes something on this computer only.**

```sh
wa tasks link <task> [targets] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |
| `targets` | optional | msg: locators, person:<id>, document:<id>, note:<id>, a URL; or task:<id>, which links two project tasks. |

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | a chat it concerns, repeatable; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--kind <kind>` | related-to (default), evidence — it shows the task is real — or created-from; for task:<id>, related-to, blocked-by, follow-up-of, duplicate-of or discovered-from. |

### `wa tasks show` [#wa-tasks-show]

one task: its plan and everything linked to it

```sh
wa tasks show <task>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |

### `wa tasks related` [#wa-tasks-related]

tasks that may be the same job as this one, best first, each with a band — likely, maybe, different — and the reasons; merges nothing

```sh
wa tasks related <task> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many, at most 40 (default 10). |

### `wa tasks duplicates` [#wa-tasks-duplicates]

pairs of tasks that may be one job

#### `wa tasks duplicates list` [#wa-tasks-duplicates-list]

pairs of tasks a rule opened that may be one job, newest first, with score and reasons: merge, reject or defer each; decision:unsure lists the ones deferred to the owner

```sh
wa tasks duplicates list [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many. |

#### `wa tasks duplicates reject` [#wa-tasks-duplicates-reject]

two tasks are not the same job: the pair leaves the list and is never offered again

**Changes something on this computer only.**

```sh
wa tasks duplicates reject <task> <other-task>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task listed as the duplicate, by its id or key. |
| `other-task` | required | the task it was paired with. |

#### `wa tasks duplicates defer` [#wa-tasks-duplicates-defer]

the fields and the text cannot tell: leave the pair to the owner, who lists it with decision:unsure

**Changes something on this computer only.**

```sh
wa tasks duplicates defer <task> <other-task>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task listed as the duplicate, by its id or key. |
| `other-task` | required | the task it was paired with. |

### `wa tasks merge` [#wa-tasks-merge]

one job seen twice: link every message of the duplicate to the task and close the duplicate dismissed, duplicate-of the task; nothing is deleted, and tasks unmerge undoes it

**Changes something on this computer only.**

```sh
wa tasks merge <task> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the duplicate, by its id or key; it must be open. |

| Opción | Qué hace |
| --- | --- |
| `--into <id>` | the task that stays, by its id or key. |

### `wa tasks unmerge` [#wa-tasks-unmerge]

undo a merge: reopen the task and remove its duplicate-of relation; messages the merge linked stay linked

**Changes something on this computer only.**

```sh
wa tasks unmerge <task>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the merged task, by its id or key. |

### `wa tasks agenda` [#wa-tasks-agenda]

what needs a look today, from the local store and without message text: tasks overdue, due or to check, chats where you owe an answer, chats where you wait for one, open tasks someone else does

```sh
wa tasks agenda [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--due-within <duration>` | list tasks due within this: 30m, 2h, 1d (default 1d). |
| `--unanswered <duration>` | list chats where someone else wrote last this long ago (default 1d). |
| `--waiting <duration>` | list chats where you wrote last this long ago (default 7d). |
| `--within <duration>` | leave out chats silent longer than this: they ended (default 30d). |
| `--holder <name>` | who you are for claims: a session id or a chat id; default WIRECAT_HOLDER, else Claude Code's session, else the agent's name. |

### `wa tasks categories` [#wa-tasks-categories]

the categories a task takes, with what each means and the words a rule picks it by

```sh
wa tasks categories
```

### `wa tasks scan` [#wa-tasks-scan]

the task rules over a chat's newest stored messages: in a one-to-one chat a question you did not answer, in a group only a question in reply to you and a mention of you, open a task, and your answer closes one; a channel opens none — for a chat the first sync left alone (config task_first_pass_per_chat). Lists what would open and changes nothing unless --yes; with --yes the duplicate check runs as on a sync. Reads only the local store

**Changes something on this computer only.**

```sh
wa tasks scan <chat> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

| Opción | Qué hace |
| --- | --- |
| `--last <n>` | read the newest n stored messages of each chat (default 50, at most 1000). |

### `wa tasks claim` [#wa-tasks-claim]

take an open task so no other agent works it at once; the claim lapses by itself

**Changes something on this computer only.**

```sh
wa tasks claim <task> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |

| Opción | Qué hace |
| --- | --- |
| `--lease <duration>` | how long the claim lasts: 30m, 2h (default 30m); claiming again extends it. |
| `--holder <name>` | who you are for claims: a session id or a chat id; default WIRECAT_HOLDER, else Claude Code's session, else the agent's name. |

### `wa tasks release` [#wa-tasks-release]

give back a task you claimed, before the claim lapses; the owner may release any

**Changes something on this computer only.**

```sh
wa tasks release <task> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |

| Opción | Qué hace |
| --- | --- |
| `--holder <name>` | who you are for claims: a session id or a chat id; default WIRECAT_HOLDER, else Claude Code's session, else the agent's name. |

### `wa tasks close` [#wa-tasks-close]

close a task: done, or dismissed when it needs no answer. An agent (AI_AGENT or CLAUDECODE set) states its --certainty; below config task_agent_close_min, or with task_agent_close off, the task stays open and the close waits on the owner, who confirms it with tasks close or refuses it with tasks reject. A closed task stays closed, unless tasks unmerge reopens a merged one

**Changes something on this computer only.**

```sh
wa tasks close <task> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |

| Opción | Qué hace |
| --- | --- |
| `--as <state>` | how it is closed: done, or dismissed — it needs no answer; the owner may leave it out to confirm an agent's close. |
| `--reason <text>` | why, kept with the task — no-reply-needed, for example. |
| `--certainty <n>` | an agent's: how sure it is, 0 to 1, that the task needs nothing more. |
| `--as-owner` | close it as yours although an agent's terminal runs the tool (AI_AGENT or CLAUDECODE set). |

### `wa tasks reject` [#wa-tasks-reject]

refuse the close an agent suggested: the task stays open and leaves close:suggested; the agent may close it again

**Changes something on this computer only.**

```sh
wa tasks reject <task> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `task` | required | the task's id or key, as tasks list shows it. |

| Opción | Qué hace |
| --- | --- |
| `--as-owner` | refuse it as yours although an agent's terminal runs the tool (AI_AGENT or CLAUDECODE set). |

## `wa search` [#wa-search]

find things by text: one resource when you know it (messages, notes), or search all across messages and notes; for mail, the separate memo CLI: memo search mail

### `wa search all` [#wa-search-all]

search messenger messages and notes in the local store, and a meeting account's transcripts when --source names one — best match first; not mail (the separate memo CLI searches it: memo search mail), tasks, people, memories or projects. Use it when you do not know where something was written; search messages or notes reads one kind with all its fields

```sh
wa search all <query> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | required | strict Lucene query: words, "phrases", AND/OR/NOT, field groups and date ranges. |

| Opción | Qué hace |
| --- | --- |
| `--only <resources>` | only these resources, separated by commas: messages, notes; meetings when --source names a meeting account. |
| `--source <accounts>` | only these accounts, separated by commas: provider:account as a hit shows it, a provider, a kind or group:<name>; each resource reads the ones of its kind, and meetings only when it names one. |
| `--max-meetings <n>` | how many of the meeting account's meetings to look through, newest first, or all for every one (default 100). |
| `--limit <n>` | how many. |
| `--page <n>` | which page, starting at 1. |
| `--exact` | bare words and quotes match their exact form only, as exact:word does. |
| `--timezone <zone>` | the IANA timezone for calendar date boundaries. |

### `wa search messages` [#wa-search-messages]

search messenger messages in the local store — what was read, fetched or kept by serve; --discover searches the archive only

```sh
wa search messages [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | strict Lucene query: words, "phrases", AND/OR/NOT, field groups and date ranges; with --saved, more words AND-ed to it. |

| Opción | Qué hace |
| --- | --- |
| `--thread` | the stored reply chain and replies instead of time neighbours; falls back when no graph exists. |
| `--thread-hops <n>` | at most this many links from the hit (default: 8). |
| `--thread-messages <n>` | at most this many messages in each thread context (default: 50). |
| `--thread-bytes <n>` | at most this many bytes of whole messages and links in each context (default: 65536). |
| `--thread-within <duration>` | messages within this long either side of the hit (default: 1d). |
| `--source <accounts>` | every account of this messenger held in the store; personal, bots or all — the same as in: in the query; or a list: group:work,telegram:Alice. |
| `--limit <n>` | how many. |
| `--page <n>` | which page, starting at 1. |
| `--newest` | newest first instead of best first. |
| `--exact` | bare words and quotes match their exact form only, as exact:word does; text: still matches every form. |
| `--context <n>` | messages before and after each hit; 2 in the terminal, 0 otherwise. |
| `--discover` | find partial lexical matches and eligible replies in the local archive; results are evidence, not confirmed answers. |
| `--timezone <zone>` | the IANA timezone for calendar date boundaries. |
| `--saved <name\|id>` | run a saved search or an earlier run; options typed here replace its own. |

### `wa search notes` [#wa-search-notes]

search the notes — written in memo, or imported from a notes folder — by words and, with the local text model, by meaning; each hit says which found it and what it links to

```sh
wa search notes <query> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | required | strict Lucene query: words, "phrases", AND/OR/NOT, tag:, source:internal (written in memo) or source:file (from a notes folder) and date ranges. |

| Opción | Qué hace |
| --- | --- |
| `--source <accounts>` | only these notes accounts, separated by commas: notes:internal for notes written in memo, notes:<folder id> as a hit shows it, notes, documents or group:<name>. |
| `--filter <query>` | a query every hit must also match; it does not change the search by meaning. |
| `--limit <n>` | how many. |
| `--page <n>` | which page, starting at 1. |
| `--exact` | words as written only; meaning is not searched. |
| `--timezone <zone>` | the IANA timezone for calendar date boundaries. |

### `wa search conversations` [#wa-search-conversations]

the conversations nearest to a query in meaning and in words, best first, in one chat or every one — meaning after `conversations embed`; runs on this machine

**Reads from an outside service.**

```sh
wa search conversations <query> [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | required | what to look for, in your own words, in any language the model reads. |

| Opción | Qué hace |
| --- | --- |
| `--model <model>` | local: a model id from `models list` (default: e5-small); remote: the provider's model. |
| `--embedding-provider <provider>` | embedding provider: local or openai; flags override profile settings. |
| `--base-url <url>` | a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine. |
| `--dims <n>` | remote: the vector size — needed with --base-url; shortens an OpenAI model's. |
| `--max-chats <n>` | at most this many chats in one run; 20 if not given. |
| `--max-chunks <n>` | at most this many chunks embedded in one run; 2000 if not given. |
| `--chat <chat>` | only this chat: a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--since-time <time>` | only those still going at this ISO 8601 time, or 30m / 2h / 1d ago, or later. |
| `--filter <query>` | strict Lucene filter: any message in a conversation must match; does not change the meaning query. |
| `--source <accounts>` | accounts to search: personal, bots, all, a provider, or a list like group:work,telegram:Alice,email:[me@example.com](mailto:me@example.com); defaults to the active account. |
| `--timezone <zone>` | IANA timezone for filter dates; system timezone by default. |
| `--limit <n>` | how many. |
| `--catch-up` | first build and embed, on this machine, the chats in scope that changed or were never built — within --max-chats and --max-chunks. |

## `wa searches` [#wa-searches]

saved searches and the history of search messages and stats messages show, kept in the local store; --saved runs one

### `wa searches create` [#wa-searches-create]

save a search under a name without running it; search messages --saved <name> runs it

**Changes something on this computer only.**

```sh
wa searches create <name> [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `name` | required | up to 64 letters a–z, digits and hyphens, not only digits. |
| `query` | optional | the query, as for search messages; none matches every stored message. |

| Opción | Qué hace |
| --- | --- |
| `--chat <chat>` | only this chat — the same as chat: in the query; a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| `--source <accounts>` | every account of this messenger held in the store; personal, bots or all — the same as in: in the query; or a list: group:work,telegram:Alice,email:[me@example.com](mailto:me@example.com). |
| `--limit <n>` | how many. |
| `--newest` | newest first instead of best first. |
| `--exact` | bare words and quotes match their exact form only, as exact:word does; text: still matches every form. |
| `--context <n>` | messages before and after each hit. |
| `--timezone <zone>` | the IANA timezone for calendar date boundaries. |
| `--by <group>` | count by chat, sender, day or hour for stats messages show --saved. |
| `--selection <json>` | save the resolved parent ranking query and options from a drilldown. |
| `--replace` | overwrite a saved search of the same name. |

### `wa searches show` [#wa-searches-show]

one saved search or earlier run: its query, options and how often it ran

```sh
wa searches show <name|id>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `name\|id` | required | a saved search's name, or the id of any row of searches history. |

### `wa searches list` [#wa-searches-list]

the saved searches, by name

```sh
wa searches list [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms; this list filters by none yet. |

### `wa searches history` [#wa-searches-history]

the searches and counts that ran, newest first — saved ones included; never their results

```sh
wa searches history [options]
```

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |
| `--all` | every row, no paging. |

### `wa searches delete` [#wa-searches-delete]

delete a saved search, or one run from the history

**Changes something on this computer only.**

```sh
wa searches delete <name|id>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `name\|id` | required | a saved search's name, or the id of any row of searches history. |

### `wa searches clear` [#wa-searches-clear]

empty the history; saved searches stay

**Changes something on this computer only.**

```sh
wa searches clear
```

## `wa recipients` [#wa-recipients]

the chats this profile may send to, when the list is on

### `wa recipients list` [#wa-recipients-list]

the chats on the list; empty and off until the first add

```sh
wa recipients list [query]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

### `wa recipients add` [#wa-recipients-add]

allow sending to this chat; the first add turns the list on

**Changes something on this computer only.**

```sh
wa recipients add <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |

### `wa recipients remove` [#wa-recipients-remove]

stop allowing this chat; the list stays on

**Changes something on this computer only.**

```sh
wa recipients remove <chat>
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `chat` | required | chat id, or the title as the list shows it. |

### `wa recipients clear` [#wa-recipients-clear]

delete the list, which turns it off: this profile may send to any chat again

**Changes something on this computer only.**

```sh
wa recipients clear
```

## `wa sends` [#wa-sends]

every attempt to send from this profile — never the text

### `wa sends list` [#wa-sends-list]

attempts to send, newest first: sent, refused, failed, or not known

```sh
wa sends list [query] [options]
```

| Argumento | Obligatoriedad | Qué es |
| --- | --- | --- |
| `query` | optional | field:value terms that narrow the list — the fields are below. |

| Opción | Qué hace |
| --- | --- |
| `--limit <n>` | how many to show. |
| `--page <n>` | which page, starting at 1. |
| `--all` | every row, no paging. |

## Códigos de salida [#códigos-de-salida]

Branch on the code, not on the text: the text can change, the code does not.

| Code | When |
| --- | --- |
| `0` | it worked |
| `2` | `validation_error` |
| `3` | `configuration_error` |
| `4` | `authentication_error` |
| `5` | `permission_error` |
| `6` | `not_found` |
| `7` | `confirmation_required` |
| `8` | `rate_limited` |
| `9` | `timeout` |
| `10` | `network_error` |
| `11` | `provider_error` |
| `12` | `provider_unavailable` |
| `13` | `invalid_response` |
| `14` | `outcome_unknown` |
| `130` | `cancelled` |
| `1` | anything else |

`0` and only `0` means the operation was done. `14` (`outcome_unknown`) means a message **may**
have gone: repeat it only with the same `--operation-id`, which WhatsApp uses to drop a second copy.