Personal account

Your WhatsApp chats, messages, contacts, search, files, polls and explicit sends.

Options for every command

Option	What it does
`-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.

`wa chats`

the account's chats

`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

wa chats list [query] [options]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.

`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

wa chats events <chat> [query]

Argument	Requirement	What it is
`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`

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

wa chats inspect <link>

Argument	Requirement	What it is
`link`	required	an invite link or a public one.

`wa chats show`

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

wa chats show <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats documents`

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

`wa chats documents list`

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

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

Argument	Requirement	What it is
`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.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.

`wa chats mark-read`

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

Changes something in WhatsApp.

wa chats mark-read <chat> [options]

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

Option	What it does
`--until-id <id>`	only up to this message id; the newest by default.

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

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

wa chats tracking list [query]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

`wa chats tracking show`

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

wa chats tracking show <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats tracking add`

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

Changes something on this computer only.

wa chats tracking add <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats tracking remove`

stop fetching it daily; the history already kept stays

Changes something on this computer only.

wa chats tracking remove <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats join`

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

Changes something in WhatsApp.

wa chats join <link>

Argument	Requirement	What it is
`link`	required	an invite link, or a public one.

`wa chats leave`

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

Changes something in WhatsApp.

wa chats leave <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats folders`

your chat folders

`wa chats folders list`

your chat folders, in the order the app shows them

wa chats folders list [query]

Argument	Requirement	What it is
`query`	optional	field:value terms; this list filters by none yet.

`wa chats folders show`

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

wa chats folders show <folder>

Argument	Requirement	What it is
`folder`	required	the folder's id, or its title exactly.

`wa chats folders create`

create a chat folder

Changes something in WhatsApp.

wa chats folders create <title> [options]

Argument	Requirement	What it is
`title`	required	the folder's name; the app may refuse a long one.

Option	What it does
`--chat <chat>`	a chat to put in it, by id or name; repeat it for more.

`wa chats folders update`

rename a folder, or change which chats are in it

Changes something in WhatsApp.

wa chats folders update <folder> [options]

Argument	Requirement	What it is
`folder`	required	folder id, or its title exactly.

Option	What it does
`--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`

delete a folder; the chats in it stay

Changes something in WhatsApp.

wa chats folders delete <folder>

Argument	Requirement	What it is
`folder`	required	folder id, or its title exactly.

`wa chats rules`

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

`wa chats rules show`

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

wa chats rules show <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats rules set`

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

Changes something on this computer only.

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

Argument	Requirement	What it is
`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`

put one rule back to its default

Changes something on this computer only.

wa chats rules unset <chat> <key>

Argument	Requirement	What it is
`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`

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

Changes something in WhatsApp.

wa chats mute <chat> [options]

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

Option	What it does
`--until <time>`	only until then: 2026-09-25T09:00 (local time), or 30m, 2h, 7d from now.

`wa chats unmute`

hear a muted chat again

Changes something in WhatsApp.

wa chats unmute <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats archive`

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

Changes something in WhatsApp.

wa chats archive <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats unarchive`

bring an archived chat back to the chat list

Changes something in WhatsApp.

wa chats unarchive <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats mark-unread`

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

Changes something in WhatsApp.

wa chats mark-unread <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa chats clear`

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

Changes something in WhatsApp.

wa chats clear <chat> [options]

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

Option	What it does
`--allow-dangerous`	go ahead without the question an ask level puts before a deletion.

`wa contacts`

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

`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

wa contacts list [query] [options]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--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`

one person and the chats you share with them

wa contacts show <person> [options]

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name.

Option	What it does
`--with-notes`	include your private notes, subject to contacts.notes.list permission.

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

wa contacts info <person> [options]

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name.

Option	What it does
`--show-phone`	print the whole phone number.

`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

wa contacts context <person> [options]

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name.

Option	What it does
`--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`

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

wa contacts prepare <person> [options]

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name.

Option	What it does
`--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`

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

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

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name.
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--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`

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

wa contacts check <person> [options]

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name.

Option	What it does
`--no-registries`	do not ask the public ban lists; nothing about them leaves this machine.

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

wa contacts link <person> <other>

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name.
`other`	required	the same in another messenger of the store, as : — max:Ana; me: it is you, as zoom: me.

`wa contacts unlink`

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

Changes something on this computer only.

wa contacts unlink <person>

Argument	Requirement	What it is
`person`	required	their id, @username, or part of their name; : for another messenger.

`wa contacts lookup`

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

wa contacts lookup

`wa contacts sync`

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

Changes something on this computer only.

wa contacts sync

`wa contacts aliases`

a private local display name in the selected account

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

wa contacts aliases set <person> <alias>

Argument	Requirement	What it is
`person`	required	the person's id, reference or known name.
`alias`	required	the private name to use for this person.

`wa contacts aliases remove`

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

Changes something on this computer only.

wa contacts aliases remove <person>

Argument	Requirement	What it is
`person`	required	the person's id, reference or known name.

`wa contacts notes`

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

`wa contacts notes list`

every private note you keep on a person, oldest first

wa contacts notes list <person> [query]

Argument	Requirement	What it is
`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`

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

wa contacts notes show <person> <id>

Argument	Requirement	What it is
`person`	required	the person's id, reference or known name.
`id`	required	the note id from contacts notes list.

`wa contacts notes add`

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

Changes something on this computer only.

wa contacts notes add <person> [options]

Argument	Requirement	What it is
`person`	required	the person's id, reference or known name.

Option	What it does
`--text-file <path>`	read note text from a file; omitted or - reads stdin.

`wa contacts notes edit`

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

Changes something on this computer only.

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

Argument	Requirement	What it is
`person`	required	the person's id, reference or known name.
`id`	required	the note id from contacts notes list.

Option	What it does
`--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`

delete one private note on a person

Changes something on this computer only.

wa contacts notes remove <person> <id>

Argument	Requirement	What it is
`person`	required	the person's id, reference or known name.
`id`	required	the note id from contacts notes list.

`wa contacts add`

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

Changes something in WhatsApp.

wa contacts add <person>

Argument	Requirement	What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.

`wa contacts block`

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

Changes something in WhatsApp.

wa contacts block <person>

Argument	Requirement	What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.

`wa contacts unblock`

let a blocked person write to you again

Changes something in WhatsApp.

wa contacts unblock <person>

Argument	Requirement	What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.

`wa contacts rename`

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

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`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`

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

Changes something in WhatsApp.

wa contacts import <file>

Argument	Requirement	What it is
`file`	required	one person per line: number, then a comma, a tab or a semicolon, then the name.

`wa messages`

read and send messages

`wa messages evidence`

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

wa messages evidence <chat> [options]

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

Option	What it does
`--limit <n>`	how many, 1–100.
`--cursor <cursor>`	go on from where page.next says the last packet stopped.

`wa messages list`

a chat's messages, oldest to newest

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

Argument	Requirement	What it is
`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.

Option	What it does
`--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`

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

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`text`	optional	the message.

Option	What it does
`--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`

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

wa messages show <chat> [message]

Argument	Requirement	What it is
`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`

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

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

Argument	Requirement	What it is
`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.

Option	What it does
`--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`

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.

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

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	optional	the message id; left out with --all.

Option	What it does
`--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`

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

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

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	the id of a voice message.

Option	What it does
`--local`	use the model on this machine, never the messenger.
`--model <model>`	which downloaded model; implies --local (`models list`).

`wa messages edit`

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

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`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.

Option	What it does
`--md`	read this messenger's Markdown; see its formatting guide for supported syntax.

`wa messages delete`

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

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`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.

Option	What it does
`--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`

forward one message to another chat

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`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.

Option	What it does
`--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`

pin a message in a chat; its members are told

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	the message id.

Option	What it does
`--expire-time <time>`	how long the pin lasts: 24h, 7d or 30d; 7d by default.

`wa messages unpin`

unpin a message in a chat

Changes something in WhatsApp.

wa messages unpin <chat> <message>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	the message id.

`wa messages star`

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

Changes something in WhatsApp.

wa messages star <chat> <message>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	the message id.

`wa messages unstar`

take the star off a message

Changes something in WhatsApp.

wa messages unstar <chat> <message>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	the message id.

`wa messages link`

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

wa messages link <chat> [message]

Argument	Requirement	What it is
`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`

the comments received under a post, oldest to newest

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

Argument	Requirement	What it is
`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.

Option	What it does
`--limit <n>`	how many.
`--cursor <cursor>`	go on from where the last page stopped; page.next gives it.

`wa messages links`

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

wa messages links <chat> <message>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	the message id.

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

wa messages sync [chat] [options]

Argument	Requirement	What it is
`chat`	optional	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

Option	What it does
`--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`

react to messages

`wa reactions add`

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

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`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`

take your reaction off a message

Changes something in WhatsApp.

wa reactions remove <chat> <message>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	the message id.

`wa polls`

read a poll, vote in it, create one

`wa polls show`

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

wa polls show <chat> <message>

Argument	Requirement	What it is
`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`

who voted for what, newest first

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

Argument	Requirement	What it is
`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.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.

`wa polls vote`

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

Changes something in WhatsApp.

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

Argument	Requirement	What it is
`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.

Option	What it does
`--retract`	take your vote back.

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

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

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`question`	required	the question.
`answers`	required	two answers or more.

Option	What it does
`--multiple`	people may pick several answers.
`--operation-id <id>`	repeat a create whose outcome was unknown, without risking a second poll.

`wa inbox`

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

wa inbox [query] [options]

Argument	Requirement	What it is
`query`	optional	from when: date>2h, date>2026-10-01; the saved point stays put.

Option	What it does
`--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`

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

wa review [query] [options]

Argument	Requirement	What it is
`query`	optional	where the last review ended and which chat: date>2h, chat:"Book club"; 3 days ago if no date.

Option	What it does
`--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`

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

`wa conversations list`

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

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

Argument	Requirement	What it is
`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.

Option	What it does
`--limit <n>`	how many.

`wa conversations show`

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

wa conversations show <conversation> [message]

Argument	Requirement	What it is
`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.

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

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

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).
`message`	required	a message id in that chat.

Option	What it does
`--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`

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

wa conversations status [options]

Option	What it does
`--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`

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

`wa conversations batches status`

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

wa conversations batches status [options]

Option	What it does
`--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`

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

wa conversations batches show [options]

Option	What it does
`--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`

message links and the conversations derived from them

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

wa conversations links rebuild [options]

Option	What it does
`--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`

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.

wa conversations links add [options]

Option	What it does
`--batch <id>`	the batch id `conversations batches show` printed.

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

wa conversations links clear [options]

Option	What it does
`--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`

stored conversation vectors

`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

wa conversations embeddings status [options]

Option	What it does
`--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`

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

Changes something on this computer only.

wa conversations embeddings clear [options]

Option	What it does
`--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`

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.

wa conversations rebuild [options]

Option	What it does
`--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`

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

`wa conversations consents list`

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

wa conversations consents list [query]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

`wa conversations consents remove`

forget analysis permissions so the next analysis asks again

Changes something on this computer only.

wa conversations consents remove [options]

Option	What it does
`--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`

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.

wa conversations embed [options]

Option	What it does
`--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`

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

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

wa attachments extract [options]

Option	What it does
`--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`

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

wa attachments list [query] [options]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.

`wa attachments show`

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

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

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter); or a msg: locator alone.
`message`	optional	the message id.

Option	What it does
`--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`

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.

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

Argument	Requirement	What it is
`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.

Option	What it does
`--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`

archive media from selected chats; verify and keep existing copies

Changes something on this computer only.

wa attachments download <dir> [options]

Argument	Requirement	What it is
`dir`	required	archive directory; created if missing.

Option	What it does
`--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`

rehash all archived files without connecting to the messenger

wa attachments check <dir>

Argument	Requirement	What it is
`dir`	required	archive directory.

`wa attachments jobs`

daily media archive timers for this profile

`wa attachments jobs install`

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

Changes something on this computer only.

wa attachments jobs install <dir> [options]

Argument	Requirement	What it is
`dir`	required	archive directory, used with the same profile as install.

Option	What it does
`--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`

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

Changes something on this computer only.

wa attachments jobs start <dir>

Argument	Requirement	What it is
`dir`	required	archive directory, used with the same profile as install.

`wa attachments jobs stop`

disable the archive timer; a download already running finishes

Changes something on this computer only.

wa attachments jobs stop <dir>

Argument	Requirement	What it is
`dir`	required	archive directory, used with the same profile as install.

`wa attachments jobs status`

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

wa attachments jobs status <dir>

Argument	Requirement	What it is
`dir`	required	archive directory, used with the same profile as install.

`wa attachments jobs uninstall`

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

Changes something on this computer only.

wa attachments jobs uninstall <dir>

Argument	Requirement	What it is
`dir`	required	archive directory, used with the same profile as install.

`wa attachments move`

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

Changes something on this computer only.

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

Argument	Requirement	What it is
`dir`	required	source media archive directory.
`archive-dir`	required	destination archive directory; created if needed.

Option	What it does
`--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`

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`

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

Changes something on this computer only.

wa tags rebuild [options]

Option	What it does
`--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`

put tags on one chat, person, message or task

Changes something on this computer only.

wa tags add <tag> [options]

Argument	Requirement	What it is
`tag`	required	one or more tags: 1–32 letters a–z, digits and hyphens; upper case is lowered.

Option	What it does
`--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`

take tags off one chat, person, message or task

Changes something on this computer only.

wa tags remove <tag> [options]

Argument	Requirement	What it is
`tag`	required	one or more tags: 1–32 letters a–z, digits and hyphens; upper case is lowered.

Option	What it does
`--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`

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

wa tags list [query]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

`wa mentions`

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

`wa mentions list`

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

wa mentions list [query] [options]

Argument	Requirement	What it is
`query`	optional	fields below; a bare word is a value, so a phone typed with 8 finds it written with +7.

Option	What it does
`--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`

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

wa mentions domains [query] [options]

Argument	Requirement	What it is
`query`	optional	narrows the links counted: the fields below; dismissed links are never counted.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.

`wa mentions places`

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

wa mentions places [options]

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.

`wa mentions show`

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

wa mentions show <id>

Argument	Requirement	What it is
`id`	required	the mention's id, from mentions list.

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

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

Argument	Requirement	What it is
`id`	required	the mention's id, from mentions list.
`person`	optional	person: or organization: that owns the phone or the e-mail address; person: a name means; a document or a street address needs none.

Option	What it does
`--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`

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

Changes something on this computer only.

wa mentions reject <id> [options]

Argument	Requirement	What it is
`id`	required	the mention's id, from mentions list.

Option	What it does
`--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`

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

Changes something on this computer only.

wa mentions rebuild [kind]

Argument	Requirement	What it is
`kind`	optional	only this kind: person-name after people were added or renamed. One of: `phone`, `email`, `url`, `document`, `person-name`, `place`.

`wa images`

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

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

wa images embed [options]

Option	What it does
`--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`

models that read pictures, for images embed and picture search

`wa images models list`

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

wa images models list [query]

Argument	Requirement	What it is
`query`	optional	field:value terms; this list filters by none yet.

`wa images models download`

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

Reads from an outside service.

wa images models download <model>

Argument	Requirement	What it is
`model`	required	a model id from `images models list`.

`wa metadata`

cached group/channel descriptions for local automatic tags

`wa metadata show`

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

wa metadata show [options]

Option	What it does
`--chat <chat>`	a stored chat.

`wa metadata sync`

fetch group and channel descriptions again and cache them

Changes something on this computer only.

wa metadata sync [options]

Option	What it does
`--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`

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

`wa tasks list`

tasks, oldest first, with their message or note source

wa tasks list [query] [options]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--limit <n>`	how many.

`wa tasks add`

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

Changes something on this computer only.

wa tasks add <message> [options]

Argument	Requirement	What it is
`message`	required	a message locator, msg:///, or note:.

Option	What it does
`--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:; none clears it. Leave it out when unsure: a task with no assignee is better than none.

`wa tasks update`

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

Changes something on this computer only.

wa tasks update <task> [options]

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.

Option	What it does
`--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:; none clears it. Leave it out when unsure: a task with no assignee is better than none.

`wa tasks link`

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

Changes something on this computer only.

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

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.
`targets`	optional	msg: locators, person:, document:, note:, a URL; or task:, which links two project tasks.

Option	What it does
`--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:, related-to, blocked-by, follow-up-of, duplicate-of or discovered-from.

`wa tasks show`

one task: its plan and everything linked to it

wa tasks show <task>

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.

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

wa tasks related <task> [options]

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.

Option	What it does
`--limit <n>`	how many, at most 40 (default 10).

`wa tasks duplicates`

pairs of tasks that may be one job

`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

wa tasks duplicates list [query] [options]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--limit <n>`	how many.

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

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

Argument	Requirement	What it is
`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`

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.

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

Argument	Requirement	What it is
`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`

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.

wa tasks merge <task> [options]

Argument	Requirement	What it is
`task`	required	the duplicate, by its id or key; it must be open.

Option	What it does
`--into <id>`	the task that stays, by its id or key.

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

wa tasks unmerge <task>

Argument	Requirement	What it is
`task`	required	the merged task, by its id or key.

`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

wa tasks agenda [query] [options]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--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`

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

wa tasks categories

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

wa tasks scan <chat> [options]

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

Option	What it does
`--last <n>`	read the newest n stored messages of each chat (default 50, at most 1000).

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

wa tasks claim <task> [options]

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.

Option	What it does
`--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`

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

Changes something on this computer only.

wa tasks release <task> [options]

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.

Option	What it does
`--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`

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.

wa tasks close <task> [options]

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.

Option	What it does
`--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`

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.

wa tasks reject <task> [options]

Argument	Requirement	What it is
`task`	required	the task's id or key, as tasks list shows it.

Option	What it does
`--as-owner`	refuse it as yours although an agent's terminal runs the tool (AI_AGENT or CLAUDECODE set).

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

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

wa search all <query> [options]

Argument	Requirement	What it is
`query`	required	strict Lucene query: words, "phrases", AND/OR/NOT, field groups and date ranges.

Option	What it does
`--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:; 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`

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

wa search messages [query] [options]

Argument	Requirement	What it is
`query`	optional	strict Lucene query: words, "phrases", AND/OR/NOT, field groups and date ranges; with --saved, more words AND-ed to it.

Option	What it does
`--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`

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

wa search notes <query> [options]

Argument	Requirement	What it is
`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.

Option	What it does
`--source <accounts>`	only these notes accounts, separated by commas: notes:internal for notes written in memo, notes: as a hit shows it, notes, documents or group:.
`--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`

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.

wa search conversations <query> [options]

Argument	Requirement	What it is
`query`	required	what to look for, in your own words, in any language the model reads.

Option	What it does
`--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:[email protected]; 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`

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

`wa searches create`

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

Changes something on this computer only.

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

Argument	Requirement	What it is
`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.

Option	What it does
`--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:[email protected].
`--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`

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

wa searches show <name|id>

Argument	Requirement	What it is
`name\|id`	required	a saved search's name, or the id of any row of searches history.

`wa searches list`

the saved searches, by name

wa searches list [query]

Argument	Requirement	What it is
`query`	optional	field:value terms; this list filters by none yet.

`wa searches history`

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

wa searches history [options]

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.

`wa searches delete`

delete a saved search, or one run from the history

Changes something on this computer only.

wa searches delete <name|id>

Argument	Requirement	What it is
`name\|id`	required	a saved search's name, or the id of any row of searches history.

`wa searches clear`

empty the history; saved searches stay

Changes something on this computer only.

wa searches clear

`wa recipients`

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

`wa recipients list`

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

wa recipients list [query]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

`wa recipients add`

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

Changes something on this computer only.

wa recipients add <chat>

Argument	Requirement	What it is
`chat`	required	a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter).

`wa recipients remove`

stop allowing this chat; the list stays on

Changes something on this computer only.

wa recipients remove <chat>

Argument	Requirement	What it is
`chat`	required	chat id, or the title as the list shows it.

`wa recipients clear`

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

Changes something on this computer only.

wa recipients clear

`wa sends`

every attempt to send from this profile — never the text

`wa sends list`

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

wa sends list [query] [options]

Argument	Requirement	What it is
`query`	optional	field:value terms that narrow the list — the fields are below.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.

Exit codes

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.

Options for every commandCopy Anchor Link

CommandsCopy Anchor Link

wa chatsCopy Anchor Link

wa chats listCopy Anchor Link

wa chats eventsCopy Anchor Link

wa chats inspectCopy Anchor Link

wa chats showCopy Anchor Link

wa chats documentsCopy Anchor Link

wa chats documents listCopy Anchor Link

wa chats mark-readCopy Anchor Link

wa chats trackingCopy Anchor Link

wa chats tracking listCopy Anchor Link

wa chats tracking showCopy Anchor Link

wa chats tracking addCopy Anchor Link

wa chats tracking removeCopy Anchor Link

wa chats joinCopy Anchor Link

wa chats leaveCopy Anchor Link

wa chats foldersCopy Anchor Link

wa chats folders listCopy Anchor Link

wa chats folders showCopy Anchor Link

wa chats folders createCopy Anchor Link

wa chats folders updateCopy Anchor Link

wa chats folders deleteCopy Anchor Link

wa chats rulesCopy Anchor Link

wa chats rules showCopy Anchor Link

wa chats rules setCopy Anchor Link

wa chats rules unsetCopy Anchor Link

wa chats muteCopy Anchor Link

wa chats unmuteCopy Anchor Link

wa chats archiveCopy Anchor Link

wa chats unarchiveCopy Anchor Link

wa chats mark-unreadCopy Anchor Link

wa chats clearCopy Anchor Link

wa contactsCopy Anchor Link

wa contacts listCopy Anchor Link

wa contacts showCopy Anchor Link

wa contacts infoCopy Anchor Link

wa contacts contextCopy Anchor Link

wa contacts prepareCopy Anchor Link

wa contacts eventsCopy Anchor Link

wa contacts checkCopy Anchor Link

wa contacts linkCopy Anchor Link

wa contacts unlinkCopy Anchor Link

wa contacts lookupCopy Anchor Link

wa contacts syncCopy Anchor Link

wa contacts aliasesCopy Anchor Link

wa contacts aliases setCopy Anchor Link

wa contacts aliases removeCopy Anchor Link

wa contacts notesCopy Anchor Link

wa contacts notes listCopy Anchor Link

wa contacts notes showCopy Anchor Link

wa contacts notes addCopy Anchor Link

wa contacts notes editCopy Anchor Link

wa contacts notes removeCopy Anchor Link

wa contacts addCopy Anchor Link

wa contacts blockCopy Anchor Link

wa contacts unblockCopy Anchor Link

wa contacts renameCopy Anchor Link

wa contacts importCopy Anchor Link

wa messagesCopy Anchor Link

wa messages evidenceCopy Anchor Link

wa messages listCopy Anchor Link

wa messages sendCopy Anchor Link

wa messages showCopy Anchor Link

wa messages contextCopy Anchor Link

wa messages downloadCopy Anchor Link

wa messages transcribeCopy Anchor Link

wa messages editCopy Anchor Link

wa messages deleteCopy Anchor Link

wa messages forwardCopy Anchor Link

wa messages pinCopy Anchor Link

wa messages unpinCopy Anchor Link

wa messages starCopy Anchor Link

wa messages unstarCopy Anchor Link

wa messages linkCopy Anchor Link

wa messages commentsCopy Anchor Link

wa messages linksCopy Anchor Link

wa messages syncCopy Anchor Link

wa reactionsCopy Anchor Link

Options for every command

Commands

`wa chats`

`wa chats list`

`wa chats events`

`wa chats inspect`

`wa chats show`

`wa chats documents`

`wa chats documents list`

`wa chats mark-read`

`wa chats tracking`

`wa chats tracking list`

`wa chats tracking show`

`wa chats tracking add`

`wa chats tracking remove`

`wa chats join`

`wa chats leave`

`wa chats folders`

`wa chats folders list`

`wa chats folders show`

`wa chats folders create`

`wa chats folders update`

`wa chats folders delete`

`wa chats rules`

`wa chats rules show`

`wa chats rules set`

`wa chats rules unset`

`wa chats mute`

`wa chats unmute`

`wa chats archive`

`wa chats unarchive`

`wa chats mark-unread`

`wa chats clear`

`wa contacts`

`wa contacts list`

`wa contacts show`

`wa contacts info`

`wa contacts context`

`wa contacts prepare`

`wa contacts events`

`wa contacts check`

`wa contacts link`

`wa contacts unlink`

`wa contacts lookup`

`wa contacts sync`

`wa contacts aliases`

`wa contacts aliases set`

`wa contacts aliases remove`

`wa contacts notes`

`wa contacts notes list`

`wa contacts notes show`

`wa contacts notes add`

`wa contacts notes edit`

`wa contacts notes remove`

`wa contacts add`

`wa contacts block`

`wa contacts unblock`

`wa contacts rename`

`wa contacts import`

`wa messages`

`wa messages evidence`

`wa messages list`

`wa messages send`

`wa messages show`

`wa messages context`

`wa messages download`

`wa messages transcribe`

`wa messages edit`

`wa messages delete`

`wa messages forward`

`wa messages pin`

`wa messages unpin`

`wa messages star`

`wa messages unstar`

`wa messages link`

`wa messages comments`

`wa messages links`

`wa messages sync`

`wa reactions`

`wa reactions add`