Настройка и обслуживание
Вход, профили, настройки, фоновый сервер, локальное хранилище, диагностика, подключение агента и обновления.
Вход, профили, настройки, фоновый сервер, локальное хранилище, диагностика, подключение агента и обновления.
Общие параметры
| Параметр | Назначение |
|---|---|
-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 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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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 endwa setup
set up WhatsApp and connect your agent
Changes something in WhatsApp.
wa setup [options]| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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 showwa 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]| Параметр | Назначение |
|---|---|
--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>| Аргумент | Обязательность | Назначение |
|---|---|---|
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>| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Аргумент | Обязательность | Назначение |
|---|---|---|
model | required | a model id from models list. |
| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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 servewa 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 startwa server stop
stop this profile's serve — through the unit if it runs under one
Changes something on this computer only.
wa server stopwa server restart
stop it and start it again
Changes something on this computer only.
wa server restartwa server status
whether serve runs for this profile, since when, who started it, and the unit if there is one
wa server statuswa server logs
serve's latest log lines — from the journal under systemd, else its log file
wa server logs [options]| Параметр | Назначение |
|---|---|
-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 installwa server uninstall
remove this profile's unit; stop it first
Changes something on this computer only.
wa server uninstallwa 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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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>| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Аргумент | Обязательность | Назначение |
|---|---|---|
chat | required | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter). |
| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
query | optional | field:value terms that narrow the list — the fields are below. |
| Параметр | Назначение |
|---|---|
--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]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>| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Аргумент | Обязательность | Назначение |
|---|---|---|
job | optional | the job id. |
| Параметр | Назначение |
|---|---|
--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 clearwa 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]| Аргумент | Обязательность | Назначение |
|---|---|---|
chat | optional | a chat: its name, or its WhatsApp id (…@lid, …@g.us, …@newsletter); several with --output-dir. |
| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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 infowa store check
whether the store is healthy — integrity, search indexes, disk, and which chats are behind
wa store checkwa 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 migratewa 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 rebuildwa 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]| Аргумент | Обязательность | Назначение |
|---|---|---|
file | required | the new file. |
| Параметр | Назначение |
|---|---|
--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>| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Аргумент | Обязательность | Назначение |
|---|---|---|
file | required | a file store backup --encrypt or store export --encrypt wrote. |
| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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>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]| Аргумент | Обязательность | Назначение |
|---|---|---|
query | optional | field:value terms that narrow the list — the fields are below. |
| Параметр | Назначение |
|---|---|
--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 clearwa runs
recorded runs — what this tool did, and when
wa runs list
recorded runs, newest first
wa runs list [query] [options]| Аргумент | Обязательность | Назначение |
|---|---|---|
query | optional | field:value terms that narrow the list — the fields are below. |
| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--problems | only failed responses, warnings and crashes. |
wa runs path
the directory holding one run
wa runs path <run-id>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]| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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. |
| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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.. |
| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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 showwa 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]| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
client | required | codex or claude-code. |
| Параметр | Назначение |
|---|---|
--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]| Параметр | Назначение |
|---|---|
--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]| Аргумент | Обязательность | Назначение |
|---|---|---|
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]| Параметр | Назначение |
|---|---|
--for <agents> | which agents to install for. One of: claude, agents, all. Default: all. |
Коды выхода
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.