Setup and maintenance

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.

Commands

`wa session`

link this profile to WhatsApp as a device, or unlink it

`wa session start`

link by QR code (default) or a pairing code, then keep the pushed history

Changes something in WhatsApp.

wa session start [method]

Argument	Requirement	What it is
`method`	optional	how to link. One of: `qr`, `phone`. Default: `qr`.

`wa session end`

unlink this device on WhatsApp's side and delete its keys here

Changes something in WhatsApp.

wa session end

`wa setup`

set up WhatsApp and connect your agent

Changes something in WhatsApp.

wa setup [options]

Option	What it does
`--agent <agent>`	install the skill for this agent; asks at a terminal, otherwise none. One of: `none`, `codex`, `cursor`, `claude`, `gemini`, `all`.
`--method <method>`	how to log in when there is no session. One of: `qr`, `phone`. Default: `qr`.

`wa account`

the logged-in account

`wa account list`

every profile on this computer, and the account each is logged in as; asks the messenger nothing

wa account list [query]

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

`wa account show`

who this profile is logged in as; the phone number shows its last four digits

wa account show [options]

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

`wa account update`

change the name, the description or the photo everyone sees on your profile

Changes something in WhatsApp.

wa account update [options]

Option	What it does
`--first-name <name>`	your first name.
`--last-name <name>`	your last name.
`--description <text>`	about you.
`--photo <file>`	a new profile photo — a .jpg or .jpeg file.

`wa account sessions`

where else this account is logged in — not wa session, which is this tool's own login

`wa account sessions list`

every device and app logged in to this account; nothing is ended

wa account sessions list [query]

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

`wa account privacy`

who may find, call or add the account

`wa account privacy show`

the account's privacy settings; reading changes nothing

wa account privacy show

`wa account privacy set`

change who may find, call or add the account; the settings not named stay

Changes something in WhatsApp.

wa account privacy set [options]

Option	What it does
`--last-seen <who>`	who sees when the account was last online: everyone, contacts or nobody.
`--hide-online <on\|off>`	hide online status and last seen.
`--profile-photo <who>`	who sees the profile photo: everyone, contacts or nobody.
`--about-text <who>`	who sees the about text: everyone, contacts or nobody.
`--read-receipts <on\|off>`	send read receipts.
`--chat-invites <who>`	who may add the account to groups and channels: everyone, contacts or nobody.
`--calls <who>`	whose calls ring: everyone, contacts or nobody.

`wa models`

models that run on this machine

`wa models keys`

API keys for embedding and analysis providers

`wa models keys set`

store a key, typed at a hidden prompt or piped on stdin — never as an argument

Changes something on this computer only.

wa models keys set <provider>

Argument	Requirement	What it is
`provider`	required	openai, anthropic, or the host of a --base-url server that wants a key.

`wa models keys remove`

forget a stored key

Changes something on this computer only.

wa models keys remove <provider>

Argument	Requirement	What it is
`provider`	required	openai, anthropic, or a server's host.

`wa models list`

speech and embedding models, their download status and the default of each kind

wa models list [query]

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

`wa models download`

download and verify one speech or embedding model

Reads from an outside service.

wa models download <model> [options]

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

Option	What it does
`--accept-terms`	accept the model's licence terms, for a model that has its own.

`wa watch`

print new messages as they arrive, until Ctrl-C or --timeout (either ends it normally)

wa watch [options]

Option	What it does
`--events`	include changes and receipts; each item names its event.

`wa serve`

keep the local store current until stopped — what a systemd or launchd unit runs

Changes something in WhatsApp.

wa serve

`wa server`

wa serve in the background: start, stop, restart, status, logs; install adds a systemd or launchd unit

`wa server start`

start serve in the background — through the unit if one is installed — and answer once it connects

Changes something on this computer only.

wa server start

`wa server stop`

stop this profile's serve — through the unit if it runs under one

Changes something on this computer only.

wa server stop

`wa server restart`

stop it and start it again

Changes something on this computer only.

wa server restart

`wa server status`

whether serve runs for this profile, since when, who started it, and the unit if there is one

wa server status

`wa server logs`

serve's latest log lines — from the journal under systemd, else its log file

wa server logs [options]

Option	What it does
`-n, --limit <n>`	how many lines. Default: `50`.

`wa server install`

write a systemd user unit or a launchd agent for this profile; starts nothing

Changes something on this computer only.

wa server install

`wa server uninstall`

remove this profile's unit; stop it first

Changes something on this computer only.

wa server uninstall

`wa store`

the local store of messages

`wa store status`

per chat: messages stored, the oldest and newest, and the stretches held completely

wa store status [chat]

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

`wa store gaps`

inspect recorded interior coverage gaps and explicitly fetch them

`wa store gaps show`

local coverage plan; missing message ids alone do not imply missing history

wa store gaps show <chat>

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

`wa store gaps repair`

fetch bounded interior gaps and recheck coverage; never delete unseen messages

Changes something on this computer only.

wa store gaps repair <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>`	total messages in this repair, 500 by default.
`--max-gaps <n>`	at most this many gaps, 5 by default.
`--repair-time <duration>`	time budget for the repair, 30s by default. Default: `30s`.
`--page-size <n>`	messages per provider page.
`--pause <duration>`	provider pause between pages. Default: `2s`.
`--fingerprint <hash>`	refuse if this previously inspected coverage plan changed.
`--catch-up`	prepare local search after repair; overrides search_catch_up.
`--no-catch-up`	skip local search preparation after repair.
`--catch-up-chunks <n>`	maximum local chunks prepared.
`--catch-up-messages <n>`	maximum stored messages read for preparation.
`--catch-up-time <duration>`	preparation time within the repair's remaining budget.
`--background`	repair as an existing store job; inspect store jobs show.

`wa store jobs`

background sync jobs

`wa store jobs list`

background sync jobs, newest first

wa store jobs 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 store jobs show`

one background job — the newest when none is named — and what the store now holds of its chat

wa store jobs show [job]

Argument	Requirement	What it is
`job`	optional	the job id `messages sync --background` printed.

`wa store jobs cancel`

stop a running background job after its current page; a later sync resumes where it stopped

Changes something on this computer only.

wa store jobs cancel <job>

Argument	Requirement	What it is
`job`	required	the job id.

`wa store jobs retry`

start a partial, failed or died job again, as a new job; the sync resumes where the store stopped

Changes something on this computer only.

wa store jobs retry [job] [options]

Argument	Requirement	What it is
`job`	optional	the job id.

Option	What it does
`--failed`	every chat whose newest job partial, failed or died.

`wa store jobs clear`

forget finished jobs and remove their logs; a running job is kept

Changes something on this computer only.

wa store jobs clear

`wa store export`

a chat's stored messages, oldest first: --jsonl one message per line, --json the list envelope of messages; never asks the messenger

Changes something on this computer only.

wa store export [chat] [options]

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

Option	What it does
`--format <format>`	jsonl: one message per line, the default with --output; markdown: a transcript with a heading per day, replies and forwards quoted.
`--since-time <time>`	only from this ISO 8601 time, or 30m / 2h / 1d ago, on.
`--output <file>`	write JSON lines, or the transcript, to this new file, readable only by you.
`--output-dir <dir>`	write into this folder, a file per chat and a manifest; run again on it for only what changed since.
`--include <kinds>`	with --output-dir: every stored chat of these kinds, comma-separated: dialog, group, channel, saved.
`--all`	with --output-dir: every stored chat of this account.
`--encrypt`	compress and encrypt with a password, typed at a hidden prompt or piped on stdin; it is never kept — lose it and the file cannot be opened.

`wa store clear`

delete from the store the chats this account has left, with their messages

Changes something on this computer only.

wa store clear [options]

Option	What it does
`--left`	the chats this account has left — the only thing this clears.
`--allow-dangerous`	yes, delete — it cannot be undone, and a chat you left cannot be fetched again.
`--dry-run`	list the chats it would delete, and delete nothing.

`wa store info`

the store file: where it is, its size, its schema and how many rows it holds; changes nothing

wa store info

`wa store check`

whether the store is healthy — integrity, search indexes, disk, and which chats are behind

wa store check

`wa store migrate`

bring the store up to this build's schema, then normalize, index and stem the messages and notes stored before it

Changes something on this computer only.

wa store migrate

`wa store rebuild`

rebuild the word index, its typo vocabulary, the stems, the files' word index, the notes' indexes and who took part in what, from what is stored; loses nothing

Changes something on this computer only.

wa store rebuild

`wa store backup`

copy the store into a new file, while it is in use; never overwrites a file

Changes something on this computer only.

wa store backup <file> [options]

Argument	Requirement	What it is
`file`	required	the new file.

Option	What it does
`--encrypt`	compress and encrypt with a password, typed at a hidden prompt or piped on stdin; it is never kept — lose it and the file cannot be opened.

`wa store restore`

put a backup in place of the store; the store it replaces is kept beside it, never deleted

Changes something on this computer only.

wa store restore <file>

Argument	Requirement	What it is
`file`	required	a file `store backup` wrote; one written with --encrypt asks for its password.

`wa store decrypt`

open a file written with --encrypt into a new file; asks for its password

Changes something on this computer only.

wa store decrypt <file> [options]

Argument	Requirement	What it is
`file`	required	a file `store backup --encrypt` or `store export --encrypt` wrote.

Option	What it does
`--output <file>`	the new file, readable only by you.

`wa store repair`

bring every table to this build's shape, deleting nothing: a table of the wrong shape is kept as a copy beside a new one

Changes something on this computer only.

wa store repair [options]

Option	What it does
`--dry-run`	say what it would do, and change nothing.

`wa store reset`

back the store up beside itself, then delete it and start an empty one at this build's schema; asks first, or --yes

Changes something on this computer only.

wa store reset [options]

Option	What it does
`--no-backup`	delete the store without backing it up first.

`wa store copies`

the tables store repair kept as copies

`wa store copies delete`

delete one copy store repair kept, named exactly; refuses any other table

Changes something on this computer only.

wa store copies delete <name>

Argument	Requirement	What it is
`name`	required	the copy's name, as `store repair` printed it.

`wa search runs`

search recorded diagnostic metadata and events; literal words and field:value terms joined by AND; no message contents

wa search runs [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>`	matches per page, at most 100. Default: `20`.
`--page <n>`	result page. Default: `1`.

`wa flood`

the waits WhatsApp asked this profile to keep, and a hold on its writes

`wa flood clear`

forget them, lift the hold and the profile's pace, once WhatsApp no longer limits the account; changes nothing there

Changes something on this computer only.

wa flood clear

`wa runs`

recorded runs — what this tool did, and when

`wa runs list`

recorded runs, newest first

wa runs 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. Default: `20`.
`--page <n>`	which page, starting at 1. Default: `1`.

`wa runs show`

one run: what it was, how it ended, and every event it logged

wa runs show <run-id> [options]

Argument	Requirement	What it is
`run-id`	required	an id from `wa runs list`.

Option	What it does
`--problems`	only failed responses, warnings and crashes.

`wa runs path`

the directory holding one run

wa runs path <run-id>

Argument	Requirement	What it is
`run-id`	required	an id from `wa runs list`.

`wa config`

the settings in force, and where each one came from

`wa config show`

the profile, the profiles that exist, and each setting with where it came from

wa config show [options]

Option	What it does
`--bot`	the settings a bot command on this profile gets, rather than the personal account's.

`wa config set`

save a setting to the configuration file

Changes something on this computer only.

wa config set <setting> <value> [options]

Argument	Requirement	What it is
`setting`	required	one of: limit, timeout_ms, color, sender_colors, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, phone_number_id, waba_id, graph_version, read_other_bots, update_check, skill_hint, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories., task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups..
`value`	required	a number, true or false, or for allow a list like send,reaction; for a group tg:work,max:Alice,email:me@x.

Option	What it does
`--defaults`	change what every profile gets, rather than this profile.
`--personal`	only for personal accounts — the personal section of the file.
`--bot`	only for bots — the bot section of the file.

`wa config unset`

remove a setting from the configuration file

Changes something on this computer only.

wa config unset <setting> [options]

Argument	Requirement	What it is
`setting`	required	one of: limit, timeout_ms, color, sender_colors, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, phone_number_id, waba_id, graph_version, read_other_bots, update_check, skill_hint, default_profile, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories., task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups..

Option	What it does
`--defaults`	change what every profile gets, rather than this profile.
`--personal`	only for personal accounts — the personal section of the file.
`--bot`	only for bots — the bot section of the file.

`wa doctor`

the state this installation is in, without connecting unless --online

wa doctor [options]

Option	What it does
`--online`	also connect once and read the account; sends nothing.

`wa doctor reports`

problem reports

`wa doctor reports show`

what a problem report holds; writes nothing

wa doctor reports show

`wa doctor reports create`

write a problem report to a file, and say where to send it

Changes something on this computer only.

wa doctor reports create [options]

Option	What it does
`--run <id>`	the run the report is about; the newest failed one if not given.
`--output <file>`	where to write it; a new file in this directory if not given.

`wa commands`

every command by section; --json prints its contract, one path per call

`wa commands info`

one command contract, or all schemas, error reasons and explicit overrides

wa commands info [path]

Argument	Requirement	What it is
`path`	optional	one command path; without one, export schemas, error reasons and explicit overrides.

`wa complete`

shell completion: wa complete zsh prints the script to source

wa complete [words]

Argument	Requirement	What it is
`words`	optional	zsh for the shell script, or command words to complete.

`wa upgrade`

upgrade wa with the package manager that installed it; --check only looks

Changes something on this computer only.

wa upgrade [options]

Option	What it does
`--check`	say whether a newer version exists, and install nothing.

`wa mcp`

serve this profile to an agent over MCP, on stdin and stdout — claude mcp add wa -- wa <profile> mcp

Changes something in WhatsApp.

wa mcp [options]

Option	What it does
`--permission <key=level>`	make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys.
`--http`	serve over HTTP on 127.0.0.1 for ChatGPT and Claude in the browser, behind your tunnel; the profile's permissions decide.
`--port <port>`	the local port for --http (default 8765).
`--public-url <url>`	the tunnel's https address the browser apps use, e.g. https://.ts.net.
`--revoke`	forget every login given to a browser app; each must log in again.

`wa mcp config`

print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing

wa mcp config [options]

Option	What it does
`--permission <key=level>`	make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys.

`wa mcp add`

add this profile's local MCP server to Codex or Claude Code

Changes something on this computer only.

wa mcp add <client> [options]

Argument	Requirement	What it is
`client`	required	codex or claude-code.

Option	What it does
`--allow-writes`	acknowledge that this profile offers writing tools.
`--permission <key=level>`	make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys.

`wa mcp check`

check this profile's local MCP handshake and tool list

wa mcp check [options]

Option	What it does
`--permission <key=level>`	make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys.

`wa skill`

the instructions an agent is given for this tool

`wa skill show`

print SKILL.md — wa skill install puts it where Claude Code, Codex and Gemini CLI look for it

wa skill show [name]

Argument	Requirement	What it is
`name`	optional	one of the skills shipped for a task: follow-ups, link-conversations.

`wa skill install`

write SKILL.md to ~/.claude/skills/whatsapp-cli/ (Claude Code) and ~/.agents/skills/whatsapp-cli/ (Codex, Gemini CLI)

Changes something on this computer only.

wa skill install [options]

Option	What it does
`--for <agents>`	which agents to install for. One of: `claude`, `agents`, `all`. Default: `all`.

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 sessionCopy Anchor Link

wa session startCopy Anchor Link

wa session endCopy Anchor Link

wa setupCopy Anchor Link

wa accountCopy Anchor Link

wa account listCopy Anchor Link

wa account showCopy Anchor Link

wa account updateCopy Anchor Link

wa account sessionsCopy Anchor Link

wa account sessions listCopy Anchor Link

wa account privacyCopy Anchor Link

wa account privacy showCopy Anchor Link

wa account privacy setCopy Anchor Link

wa modelsCopy Anchor Link

wa models keysCopy Anchor Link

wa models keys setCopy Anchor Link

wa models keys removeCopy Anchor Link

wa models listCopy Anchor Link

wa models downloadCopy Anchor Link

wa watchCopy Anchor Link

wa serveCopy Anchor Link

wa serverCopy Anchor Link

wa server startCopy Anchor Link

wa server stopCopy Anchor Link

wa server restartCopy Anchor Link

wa server statusCopy Anchor Link

wa server logsCopy Anchor Link

wa server installCopy Anchor Link

wa server uninstallCopy Anchor Link

wa storeCopy Anchor Link

wa store statusCopy Anchor Link

wa store gapsCopy Anchor Link

wa store gaps showCopy Anchor Link

wa store gaps repairCopy Anchor Link

wa store jobsCopy Anchor Link

wa store jobs listCopy Anchor Link

wa store jobs showCopy Anchor Link

wa store jobs cancelCopy Anchor Link

wa store jobs retryCopy Anchor Link

wa store jobs clearCopy Anchor Link

wa store exportCopy Anchor Link

wa store clearCopy Anchor Link

wa store infoCopy Anchor Link

wa store checkCopy Anchor Link

wa store migrateCopy Anchor Link

wa store rebuildCopy Anchor Link

wa store backupCopy Anchor Link

wa store restoreCopy Anchor Link

wa store decryptCopy Anchor Link

wa store repairCopy Anchor Link

wa store resetCopy Anchor Link

wa store copiesCopy Anchor Link

wa store copies deleteCopy Anchor Link

wa search runsCopy Anchor Link

wa floodCopy Anchor Link

wa flood clearCopy Anchor Link

wa runsCopy Anchor Link

wa runs listCopy Anchor Link

wa runs showCopy Anchor Link

wa runs pathCopy Anchor Link

wa configCopy Anchor Link

wa config showCopy Anchor Link

wa config setCopy Anchor Link

wa config unsetCopy Anchor Link

wa doctorCopy Anchor Link

wa doctor reportsCopy Anchor Link

wa doctor reports showCopy Anchor Link

wa doctor reports createCopy Anchor Link

wa commandsCopy Anchor Link

wa commands infoCopy Anchor Link

wa completeCopy Anchor Link

wa upgradeCopy Anchor Link

wa mcpCopy Anchor Link

wa mcp configCopy Anchor Link

wa mcp addCopy Anchor Link

wa mcp checkCopy Anchor Link

wa skillCopy Anchor Link

Options for every command

Commands

`wa session`

`wa session start`

`wa session end`

`wa setup`

`wa account`

`wa account list`

`wa account show`

`wa account update`

`wa account sessions`

`wa account sessions list`

`wa account privacy`

`wa account privacy show`

`wa account privacy set`

`wa models`

`wa models keys`

`wa models keys set`

`wa models keys remove`

`wa models list`

`wa models download`

`wa watch`

`wa serve`

`wa server`

`wa server start`

`wa server stop`

`wa server restart`

`wa server status`

`wa server logs`

`wa server install`

`wa server uninstall`

`wa store`

`wa store status`

`wa store gaps`

`wa store gaps show`

`wa store gaps repair`

`wa store jobs`

`wa store jobs list`

`wa store jobs show`

`wa store jobs cancel`

`wa store jobs retry`

`wa store jobs clear`

`wa store export`

`wa store clear`

`wa store info`

`wa store check`

`wa store migrate`

`wa store rebuild`

`wa store backup`

`wa store restore`

`wa store decrypt`

`wa store repair`

`wa store reset`

`wa store copies`

`wa store copies delete`

`wa search runs`

`wa flood`

`wa flood clear`

`wa runs`

`wa runs list`

`wa runs show`

`wa runs path`

`wa config`

`wa config show`

`wa config set`

`wa config unset`

`wa doctor`

`wa doctor reports`

`wa doctor reports show`

`wa doctor reports create`

`wa commands`

`wa commands info`

`wa complete`

`wa upgrade`

`wa mcp`

`wa mcp config`

`wa mcp add`

`wa mcp check`

`wa skill`

`wa skill show`