Personal account

Commands and instructions

Use this page to learn how a wa command line is built and where its answers come from.

wa <profile> <resource> <verb> [arguments] [options]
wa personal chats list
wa personal messages list "Book club" --limit 20
wa personal search messages "dinner"

• The first word is the profile. Any name works; wa never picks one for you.
• Reads answer from the local store, which wa <profile> serve keeps filled from your phone. A read never connects to WhatsApp.
• --json prints one JSON value on stdout for scripts and agents; diagnostics go to stderr.

Set up a profileCopy Anchor Link

wa personal setup                  # link, check five chats, offer the agent skill; about 5 minutes
wa personal setup --agent codex    # the same, and install the skill for Codex
wa personal setup --method phone   # a pairing code instead of the QR code

setup runs five steps: this computer's folders, the link (an existing device is reused and nothing is asked), the account, five chats from the local store, and the agent skill. A device linked before is checked without linking again. Without a terminal the QR code is printed as plain text, and an agent pastes it into the chat to be scanned.

Link a profileCopy Anchor Link

setup uses the same linking as session start, which does only the link:

wa personal session start          # a QR code to scan in WhatsApp > Settings > Linked devices
wa personal session start phone    # type your number, then a pairing code on the phone

Right after linking, the phone sends your history once. session start keeps it in the local store and stops when the phone goes quiet. Then wa personal server install keeps receiving in the background. wa personal session end unlinks the device and deletes its keys here.

Only one wa command may connect a profile at a time; WhatsApp would drop the first connection. While serve runs, a send for the same profile goes through serve and uses its connection. It cannot ask there, so at permission level ask it needs --yes (one connection per device).

Change a messageCopy Anchor Link

The message id 3EB0A1B2C3D4E5F6A7B8 on this page is made up; take a real one from messages list -v.

wa personal messages edit "Book club" 3EB0A1B2C3D4E5F6A7B8 "the new text"
wa personal messages delete "Book club" 3EB0A1B2C3D4E5F6A7B8                 # for you only
wa personal messages delete "Book club" 3EB0A1B2C3D4E5F6A7B8 --for-everyone
wa personal reactions add "Book club" 3EB0A1B2C3D4E5F6A7B8 👍
wa personal messages pin "Book club" 3EB0A1B2C3D4E5F6A7B8 --expire-time 24h
wa personal messages unpin "Book club" 3EB0A1B2C3D4E5F6A7B8
wa personal chats mark-read "Book club"

WhatsApp names a message by who sent it as well as by its id, so these work on messages the local store holds; keep serve running. Edit your own text messages within 15 minutes of sending; see WhatsApp’s editing help. A deletion is for you only: wa asks WhatsApp to take it from your phone and your other devices, to leave it with the others in the chat, and to keep the photos and files the phone saved from it. --for-everyone removes it for everyone. Every pin tells the chat's members: WhatsApp has no quiet pin, so no flag is needed. A pin lasts 24 hours, 7 days or 30 days (--expire-time 24h, 7d, 30d); without --expire-time, wa pins for 7 days. Nothing is marked read by reading commands. Use chats mark-read to send a read receipt explicitly.

Star a messageCopy Anchor Link

wa personal messages star "Book club" 3EB0A1B2C3D4E5F6A7B8
wa personal messages unstar "Book club" 3EB0A1B2C3D4E5F6A7B8

A star is your own mark, which WhatsApp syncs to your other devices; nobody in the chat is told. Like an edit, it needs the message in the local store. The local store keeps a star you set with wa: wa personal messages list "Book club" starred:true and wa personal search messages is:starred find those messages. While serve or watch runs, a star you set or take off on the phone reaches the store too, and watch --events prints it; so do the stars of the messages the phone pushes right after linking. Star a channel's post on the phone.

Mute a chatCopy Anchor Link

wa personal chats mute "Book club"              # for good
wa personal chats mute "Book club" --until 8h   # or until a time: --until 2026-10-09T09:00
wa personal chats unmute "Book club"

Muting is your own setting, which WhatsApp syncs to your other devices; nobody in the chat is told. A device linked a few minutes ago may not have WhatsApp's settings keys yet; keep serve running a while and try again. Mute a channel on the phone.

While serve or watch runs, a mute made on the phone is saved with its end, so inbox and review leave the chat out until the mute ends. chats show --offline shows muted and muted_until (none for good).

Archive, pin or mark a chat unreadCopy Anchor Link

wa personal chats archive "Book club"       # wa personal chats unarchive "Book club" brings it back
wa personal chats pin "Book club"           # at the top of the chat list; wa personal chats unpin "Book club"
wa personal chats mark-unread "Book club"

These are your own settings too, synced to your other devices; nobody in the chat is told. chats pin pins the chat, not a message. Archiving a chat also unpins it (whatsmeow's archive patch does both). WhatsApp's apps keep three pinned chats; wa does not count them. Archive, unarchive and mark-unread name the chat's newest message in the local store, as chats delete does, so a chat the store holds nothing of is refused. Channels are refused. A chat marked unread sends no read receipt.

chats mark-read first sends the same settings change with "read", up to the newest stored message (or --until-id), then the read receipt; a receipt alone leaves a mark-unread on the phone. Until WhatsApp has sent the settings keys it is refused and sends neither. A channel gets the receipt only.

While serve or watch runs, a chat you read on the phone gets an unread count of 0 in the local store and loses its unread mark, so inbox stops showing it. Each new message from someone else that serve or watch saves then adds one to the count. An archive and a mark-unread on the phone are saved too (archived, marked_unread), so inbox leaves an archived chat out and lists a chat marked unread. A pin, a deleted or a cleared chat on the phone is not saved yet. watch --events prints none of these changes.

A reply (messages send --reply-to 3EB0A1B2C3D4E5F6A7B8) to a message the local store holds shows the quoted text and its sender on the phone. A reply to one the store lacks is still sent, with the message's id alone; WhatsApp's apps may then show the quote as unavailable.

Delete or clear a chatCopy Anchor Link

wa personal chats clear "Book club" --allow-dangerous    # every message, starred ones too; the chat stays
wa personal chats delete "Book club" --allow-dangerous   # the chat itself

Both are for your devices alone: the others in the chat keep it and its messages. Without --allow-dangerous they ask first in a terminal and refuse in a script. WhatsApp deletes up to a message wa names: the chat's newest one in the local store, so keep serve running for it to be current, and a chat the store holds nothing of is refused. wa asks WhatsApp to leave the photos and files the phone saved from the chat. wa's local store still holds the messages afterwards.

Format a messageCopy Anchor Link

wa personal messages send "Book club" "**Friday** at _8_, see [the notes](https://example.com/n)" --md
printf '**Agenda**\n- the _new_ book\n> a quote\n' | wa personal messages send "Book club" --md
wa personal messages edit "Book club" 3EB0A1B2C3D4E5F6A7B8 "**moved** to Friday" --md

--md reads Markdown and sends it in WhatsApp's own marks: **bold** or *bold* becomes *bold*, _italic_ stays _italic_, ~~strike~~ becomes ~strike~, `code` and ``` blocks stay, quotes (>) and lists (-, 1.) stay as they are, and a # heading becomes bold. A link becomes its label and then its address, which WhatsApp makes clickable. Underline, spoilers and highlights have no mark in WhatsApp and stay plain text. WhatsApp has no way to keep a * literal, so \*word\* still reads as bold there. Without --md the text goes as typed, so WhatsApp's own marks work anyway.

PollsCopy Anchor Link

wa personal polls create "Book club" "Which day?" Monday Tuesday            # one answer each
wa personal polls create "Book club" "Which books?" Dune Emma Ulysses --multiple
wa personal polls show "Book club" 3EB0A1B2C3D4E5F6A7B8        # the question, its answer ids and the counts
wa personal polls vote "Book club" 3EB0A1B2C3D4E5F6A7B8 a1b2c3d4
wa personal polls vote "Book club" 3EB0A1B2C3D4E5F6A7B8 --retract
wa personal polls voters "Book club" 3EB0A1B2C3D4E5F6A7B8      # who voted for what, newest first

Everyone in the chat sees who voted for what, and a vote can always be changed, so there is no --anonymous and no --revote. A WhatsApp poll has 2 to 12 answers, each with its own text; it is never a quiz and never closes, so there is no polls close. Vote by the ids polls show prints; a1b2c3d4 above is made up. polls show, polls vote and polls voters work on a poll the local store holds, a poll made with wa polls create among them. WhatsApp gives a device a poll's key only when the poll reaches it, so a poll from before the link may refuse a vote.

WhatsApp has no request for the votes: each one arrives once, as its own message. wa serve and wa watch keep each person's newest vote in the local store (watch --events prints each new one), and the votes the phone sends with its history right after linking too, so the counts are what the store heard. A vote cast while nothing listened is missed until that person votes again.

PrivacyCopy Anchor Link

wa personal account privacy show                         # who sees last seen, the photo, about; receipts, groups, calls
wa personal account privacy set --last-seen contacts     # only contacts see when you were last online; the rest stays
wa personal account privacy set --hide-online on         # last seen to nobody, online only to those who see it
wa personal account privacy set --read-receipts off      # no read receipts sent, and none shown to you

show asks WhatsApp each time, not a copy kept on this computer. set changes only what you name and answers every setting as it now is; it changes your account on every device, and goes through the profile's permissions like a send (permissions.account.privacy.set). It sends one request per setting: if WhatsApp fails one, the settings sent before it stay changed and the error says so; run show to see where things are.

• --last-seen, --profile-photo and --about-text take everyone, contacts or nobody. A setting kept on the phone as "my contacts except…" shows as contacts_except; set cannot choose it, since the list of exceptions stays on the phone, and setting another value replaces it.
• --hide-online on sets last seen to nobody and online to "same as last seen", so nobody sees either. --hide-online off shows last seen to your contacts, since wa does not know the setting from before it was hidden; --last-seen everyone instead chooses who. Give one of the two, not both.
• --read-receipts off works both ways, as on the phone: others no longer see when you read their messages, and you no longer see when they read yours. chats mark-read then marks a chat read on your own devices only (whatsmeow sends a read receipt only to your devices while receipts are off).
• --chat-invites takes everyone or contacts: WhatsApp is reported to refuse nobody, so wa refuses it. A setting kept with exceptions on the phone is left out of show.
• --calls contacts is meant as the phone's "silence unknown callers" (calls from people you do not know arrive without ringing). WhatsApp has no --calls nobody, so wa refuses it.

WhatsApp has no setting for who finds you by your number or who sees it, so wa does not offer --find-by-phone or --phone-number.

Send, save and forward filesCopy Anchor Link

wa personal messages send "Book club" "the agenda" --file agenda.pdf
wa personal messages send "Book club" "us, last week" --photo photo.jpg
wa personal messages send "Book club" --voice note.ogg
wa personal messages send "Book club" --sticker-file thumbs-up.webp
wa personal messages download "Book club" 3EB0A1B2C3D4E5F6A7B8 --output-dir ~/Downloads
wa personal messages transcribe "Book club" 3EB0A1B2C3D4E5F6A7B8 --local
wa personal messages forward "Book club" 3EB0A1B2C3D4E5F6A7B8 --to "Ann Lee"

A message carries one file; the text becomes its caption, except on a voice note, which goes alone. A .mp4, .m4v or .mov goes as a video unless --as-file. A --photo and a video --file together go as one album, the text as the photo's caption. --sticker-file sends a .webp of at most 500 KiB as a sticker, alone, with no text: WhatsApp has no sticker sets to pick one from by id, so there is no --sticker. Photos, videos, voice notes, files and stickers that reach the local store can be saved and forwarded later, since the store keeps what WhatsApp needs to fetch them again; WhatsApp keeps a file for a limited time, and a download of one it no longer keeps asks your phone to upload it again, which does not work yet (not in wa yet). A place or a contact card is kept too, so it can be forwarded; neither is a file to save. WhatsApp has no speech recognition of its own, so transcribe uses a model on this machine (wa models list kind:audio). What is kept, what can be fetched again and how to search the text inside files: file attachments.

Older messagesCopy Anchor Link

WhatsApp keeps no history on its servers, so older messages can only come from your phone, 50 at a time, while WhatsApp is open on it: wa personal messages sync "Book club" asks for them, one chat at a time (how).

ChannelsCopy Anchor Link

A WhatsApp channel is a one-way chat: its admins post, everyone else follows and reads. A channel id ends in @newsletter (120363000000000001@newsletter).

wa personal chats join https://whatsapp.com/channel/AAAAAAAAAAAAAAAAAAAAAA   # follow a channel by its link
wa personal chats list 'kind:channel' --offline                            # the channels you follow
wa personal messages sync 120363000000000001@newsletter --limit 100         # read its posts into the local store
wa personal messages list 120363000000000001@newsletter
wa personal messages send 120363000000000001@newsletter "Meeting moved to 8"   # in a channel you run
wa personal messages send 120363000000000001@newsletter "New menu" --photo ~/menu.jpg
wa personal chats leave 120363000000000001@newsletter                     # unfollow it

• The channels you follow reach the chat list when wa serve or wa watch connects: wa asks WhatsApp for them once per connection. While serve runs, chats join adds the one it follows at once.
• A channel's posts are kept on WhatsApp's servers, unlike a chat's messages, so messages sync reads them from there and not from your phone: the newest first, then further back, 50 at a time. messages list then shows them from the local store.
• The channel is the sender of every post, and a post you made, one wa just sent included, reads as the channel's, not as yours (outgoing: false): WhatsApp does not say which posts are your own.
• Only the channel's owner and admins post. messages send asks WhatsApp for your role first and refuses anyone else (exit 5), before anything is uploaded. A post is text or one file (--photo, --file, --voice, the text as its caption), and not a reply; the followers see it at once. A channel's files are not encrypted, as in WhatsApp's apps. An album, a sticker, a poll, a vote, a forward, an edit or a deletion in a channel is refused, and so is a forward of a channel's file into a chat (media.channel-file-forward): with no file key it would not open there.
• chats join and chats leave go through the profile's permissions like a group's: the channel's admins see that you followed. A follower count stands in for the member list, which WhatsApp does not show.

Preview links, devices and ListsCopy Anchor Link

Inspect a group or channel invite before joining, list your linked devices, or read a custom List made on the phone:

wa personal chats inspect https://chat.whatsapp.com/INVITECODE
wa personal account sessions list
wa personal chats folders list
wa personal chats folders show "Work"

Inspecting a link joins nothing. Sessions show numeric device ids: 0 is the phone; the current device is marked. WhatsApp does not provide device names or last-active times to a linked device. End other devices from the phone's Settings → Linked devices; wa personal session end unlinks this device.

Folders are WhatsApp's custom Lists, with their titles and explicitly included chats. The first read downloads the synced Lists if this device has no snapshot; later reads use the last synced state. Built-in filters and WhatsApp Business labels are separate. Create or change a List on the phone.

Read community commentsCopy Anchor Link

Use messages comments to read replies below a post in a community's announcement group:

wa personal messages comments "Announcements" POST_ID --limit 20

The result lists comments this linked device has received and decrypted, saved under their parent post. Keep serve receiving messages to fill that history. Comments whose parent secret this device never received cannot be decrypted. WhatsApp channels have reactions, not comments. Sending community comments is not supported.

Not in wa yetCopy Anchor Link

wa shares its command tree with tg and max, so some commands are there that WhatsApp cannot run. Each one stops with exit code 2 and says why. Nothing reaches WhatsApp.

Not built yet:

• more files in one message than a photo and a video, which go as one album;
• listing a community's groups, and adding a group to one or taking it out (communities);
• making a channel (chats create --channel);
• downloading a file WhatsApp no longer keeps: the phone uploads it again under a key it does not share, so the download ends with media.retry-failed and saves nothing (file attachments).

WhatsApp has no such thing, or keeps it on the phone:

• forum topics and comments under channel posts (channels have reactions only);
• more than one invite link per group: chats links reset replaces the one there is;
• admins with only some rights: every admin has all of them;
• polls that close, quizzes and anonymous polls;
• silent, scheduled or send-as messages;
• address-book edits and imports: manage contacts from the phone; wa reads the synced address book;
• how old an account is: a newAccount rule in chats rules set is refused.

wa never answers by itself: there are no automatic replies, as WhatsApp bans accounts that answer like a bot. What is planned is on the roadmap.

Keep wa up to dateCopy Anchor Link

wa upgrade installs the newest version and restarts each running server (upgrade).

Where to go nextCopy Anchor Link

• Linking, devices and profiles — QR or pairing code, and why one command at a time may connect.
• Search and the local store — find what was said, export it, back it up.
• The MCP server — the same commands for an app with no terminal.
• Recipes — what an agent can do for you every day.

Every command and option is on the commands page.