@zorinto/viwa 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,29 @@
1
+ viwa Licence
2
+
3
+ Copyright (c) 2026 Zorinto Ltd (company number 15494238). All rights reserved.
4
+
5
+ viwa ("the Software") is free to use but is not open source. By installing or using it you agree to this licence.
6
+
7
+ 1. Licence. Zorinto Ltd grants you a free, non-exclusive, non-transferable, revocable licence to install and use the unmodified Software, in the form Zorinto Ltd distributes it, on Macs you own or control, for your own personal or internal business purposes.
8
+
9
+ 2. Restrictions. You may not, and may not allow anyone else to:
10
+ (a) copy the Software, except as needed to install and use it and to keep a backup;
11
+ (b) modify, adapt, translate or create derivative works of the Software;
12
+ (c) decompile, disassemble or reverse engineer the Software, except to the extent the law expressly allows despite this restriction;
13
+ (d) distribute, sell, rent, lend, sublicense or otherwise make the Software available to others, or offer it as part of a product or service;
14
+ (e) use the Software, or knowledge gained from studying it, to build, train or offer a product or service that competes with it;
15
+ (f) remove or change any copyright, trade mark or licence notice in the Software.
16
+
17
+ 3. Ownership. The Software is licensed, not sold. Zorinto Ltd keeps all rights, title and interest in it, including all intellectual property rights.
18
+
19
+ 4. Third-party services. The Software works with WhatsApp Desktop, which is provided by WhatsApp LLC under its own terms. You are solely responsible for your use of WhatsApp and for complying with its terms and with the law. WhatsApp is a trade mark of WhatsApp LLC; the Software is not affiliated with, endorsed by or sponsored by WhatsApp or Meta.
20
+
21
+ 5. No warranty. The Software is provided "as is" and "as available", without warranty of any kind, express or implied, including any warranty of satisfactory quality, fitness for a particular purpose or non-infringement. Zorinto Ltd does not warrant that the Software will work with any version of WhatsApp or will be free of errors.
22
+
23
+ 6. Limitation of liability. To the fullest extent the law allows, Zorinto Ltd is not liable for any loss or damage arising from the use of, or inability to use, the Software, including loss of data, messages, accounts, profits or business, or any restriction or ban of a WhatsApp account. Nothing in this licence limits or excludes liability for death or personal injury caused by negligence, for fraud, or for anything else that cannot be limited or excluded by law.
24
+
25
+ 7. Termination. This licence ends automatically if you break it. When it ends you must stop using the Software and delete every copy.
26
+
27
+ 8. Changes. Zorinto Ltd may release later versions of the Software under different terms. Each version is governed by the licence that comes with it.
28
+
29
+ 9. Law. This licence is governed by the law of England and Wales, and the courts of England and Wales have exclusive jurisdiction.
package/README.md CHANGED
@@ -1,3 +1,382 @@
1
- # Temporary Holding Version
1
+ # viwa
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Read and reply to WhatsApp from the Mac terminal, for people, AI agents and scripts.
4
+
5
+ viwa is a command-line tool **for WhatsApp Desktop on macOS**. It reads the database the official WhatsApp app already keeps on your Mac, and it sends replies by driving that same app through macOS Accessibility, as if you had typed them yourself. There is no linked device and no unofficial web protocol: WhatsApp's servers only ever see their own app.
6
+
7
+ viwa is an independent project. It is not affiliated with, endorsed by or sponsored by WhatsApp or Meta.
8
+
9
+ ## Requirements
10
+
11
+ - macOS 14 or later.
12
+ - WhatsApp Desktop for Mac (the app with bundle id `net.whatsapp.WhatsApp`), installed and logged in. viwa is tested with WhatsApp **26.45.13**; `viwa doctor` warns when your version differs.
13
+ - WhatsApp's interface in **English**. Buttons and menus are found by their English names.
14
+ - WhatsApp Business for Mac is **not supported**.
15
+
16
+ ## Install
17
+
18
+ viwa runs on **macOS on Apple silicon** (M1 or later). Intel Macs are not supported.
19
+
20
+ ### pnpm
21
+
22
+ ```sh
23
+ pnpm add -g @zorinto/viwa
24
+ ```
25
+
26
+ To try it without installing:
27
+
28
+ ```sh
29
+ pnpm dlx @zorinto/viwa doctor
30
+ ```
31
+
32
+ ### Homebrew
33
+
34
+ ```sh
35
+ brew install zorinto/viwa/viwa
36
+ ```
37
+
38
+ Both install the same prebuilt binary; no developer tools are needed. The binary is not code-signed or notarised. If macOS ever refuses to run it, remove the quarantine flag from the installed binary:
39
+
40
+ ```sh
41
+ xattr -d com.apple.quarantine "$(command -v viwa)"
42
+ ```
43
+
44
+ Then check your setup:
45
+
46
+ ```sh
47
+ viwa doctor
48
+ ```
49
+
50
+ ## Permissions
51
+
52
+ **Accessibility (needed for `reply`, `chat`, `message`, `poll`, `group` and `call`).** viwa sends by typing into WhatsApp's message box and pressing its Send button through macOS Accessibility. macOS grants that to the app viwa runs inside, not to viwa itself, so allow your terminal app (Terminal, iTerm2, Ghostty and so on, or the app that runs your AI agent) in **System Settings > Privacy & Security > Accessibility**. Reading commands do not need it.
53
+
54
+ If you added the viwa binary itself to the Accessibility list, rather than your terminal, a rebuild or upgrade may need it added again, because viwa is not code-signed yet.
55
+
56
+ **Reading the database.** `chats`, `read`, `search`, `media` and `watch` open WhatsApp's database read-only at `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite`. They need no extra permission as long as your terminal can read that folder. If macOS refuses access, `viwa doctor` shows "Database readable" as failed with exit code 5; allow your terminal app under **System Settings > Privacy & Security > Full Disk Access** and try again.
57
+
58
+ viwa never writes to WhatsApp's database. Reading it does not mark anything as read.
59
+
60
+ ## Commands
61
+
62
+ Every command accepts `--json` for machine-readable output on stdout. Progress, warnings and errors go to stderr; with `--json`, an error is also printed on stdout as `{"code": ..., "error": ...}` (`watch` prints it on stderr instead). Every command that reads the database accepts `--db <path>`, or the `VIWA_DB` environment variable, to read another copy of the database.
63
+
64
+ A `<chat>` can be a name, a phone number (with or without `+`, spaces ignored) or a JID (`...@s.whatsapp.net`, `...@g.us`, `...@lid`). Names are matched ignoring case and the invisible direction marks WhatsApp adds: an exact name wins (so `Mum` finds "Mum", not "Mumbai Team"), otherwise each word you give must start a word of the name (`ravi trad` finds "Ravi Traders"). When a name matches more than one chat, viwa stops and lists them:
65
+
66
+ ```console
67
+ $ viwa read Ravi
68
+ 'Ravi' matches more than one chat. Use the JID or a longer name:
69
+ Ravi Traders 447700900001@s.whatsapp.net last message 2025-11-05 01:46
70
+ Ravi Kumar 90000000000002@lid last message 2025-10-31 10:40
71
+ ```
72
+
73
+ ### `chats`: list chats, newest first
74
+
75
+ ```console
76
+ $ viwa chats --limit 2
77
+ NAME JID UNREAD LAST MESSAGE
78
+ Ravi Traders 447700900001@s.whatsapp.net 2 2025-11-05 01:46
79
+ Mumbai Team 120363000000000004@g.us 0 2025-11-03 22:00
80
+ ```
81
+
82
+ Options: `--unread`, `--groups`, `--archived` (archived chats only; they are left out otherwise), `--limit <n>`.
83
+
84
+ ### `read <chat>`: show messages in one chat, oldest first
85
+
86
+ ```console
87
+ $ viwa read "Ravi Traders" --limit 3
88
+ [2025-11-04 23:16] #2 Ravi: [image]
89
+ [2025-11-04 23:33] #3 Ravi: https://example.com/catalogue
90
+ [2025-11-05 01:46] #5 me: Thanks, noted
91
+ ```
92
+
93
+ The number after `#` is the message id, used by `reply --quote`. Options: `--since 30m|12h|2d|1w|YYYY-MM-DD`, `--limit <n>` (default 50, the newest are kept), `--before <id>` and `--after <id>` (only messages with a lower, or a higher, id: `read Mum --before 81458` shows the 50 messages before that one, so you can page back through a chat), `--from <sender>` (`me`, or part of a sender's name or JID, ignoring case) and `--starred`. With `--json`, messages with no text (media, deleted) have `"text": null`, and `starred` says whether you starred the message. A poll shows as `Poll: <question> [a | b | c]` (`search` too, though it does not search poll questions); in JSON its `kind` is `poll` and `poll` holds `{"question", "options"}` (`null` for other messages, and for a poll whose question cannot be read).
94
+
95
+ ### `search <text>`: search message text, newest first
96
+
97
+ ```console
98
+ $ viwa search noted
99
+ Ravi Traders [2025-11-05 01:46] #5 me: Thanks, noted
100
+ ```
101
+
102
+ Options: `--chat <chat>`, `--since <time>`, `--has-media`, `--starred`, `--limit <n>` (default 20). Media captions are searched too. Case is ignored in every script (`café` finds "CAFÉ"); accents are not (`cafe` does not find "café").
103
+
104
+ ### `media <chat>`: list or copy a chat's media
105
+
106
+ ```sh
107
+ viwa media "Mumbai Team"
108
+ viwa media "Mumbai Team" --export ~/Downloads/mumbai-team
109
+ ```
110
+
111
+ `--export` copies the files into the folder and never overwrites: a name that already exists gets " (1)", " (2)" and so on. Files that are not on the Mac are reported as missing on stderr.
112
+
113
+ ### `reply <chat> <text>`: type a reply, and send it only with `--send`
114
+
115
+ ```sh
116
+ # Types the text into the chat's message box and leaves it there, unsent.
117
+ viwa reply "Ravi Traders" "Thanks, I will collect it at 4."
118
+
119
+ # Types and sends, then confirms the message reached WhatsApp's database.
120
+ viwa reply "Ravi Traders" "Thanks, I will collect it at 4." --send
121
+
122
+ # Replies to a specific message (an id from read or search), or to their latest message.
123
+ viwa reply "Ravi Traders" "Yes, that one." --quote 3 --send
124
+ viwa reply Mum "On my way" --quote last --send
125
+
126
+ # Sends one file with the text as its caption.
127
+ viwa reply "Mumbai Team" "Minutes from today" --file ~/Documents/minutes.pdf --send
128
+
129
+ # Sends several files (up to 10) from one preview, the text as the first one's caption.
130
+ viwa reply Mum "Notes from today" --file ~/Documents/one.pdf --file ~/Documents/two.pdf --send
131
+
132
+ # Sends a file as a reply to a message.
133
+ viwa reply "Ravi Traders" "Here is the invoice" --file ~/Documents/invoice.pdf --quote 3 --send
134
+
135
+ # Your own "Message yourself" chat.
136
+ viwa reply You "Reminder: call the bank" --send
137
+
138
+ # The text from standard input (give - as the text), so a script or agent need not quote it for the shell.
139
+ printf '%s' "It's ready, see you at 4" | viwa reply Mum -
140
+ ```
141
+
142
+ Line breaks in the text stay inside one message. With `-` as the text, one line break at the very end of the input is dropped. Without `--send`, nothing is sent: the text stays in WhatsApp's box (or, with `--file`, in WhatsApp's attachment preview) for you to check and send yourself.
143
+
144
+ `--quote last` means the latest real message from the other side (in a group, from anyone but you), not system messages or reactions. A message further up the chat is scrolled to in the background, as for message actions (below); if the reply then fails, viwa opens the chat again at its newest messages.
145
+
146
+ With `--quote` and `--file` together, viwa chooses Reply on the message first, then types the text and pastes the files. After Send it checks in WhatsApp's database that the files went out quoting that message. If they did not, they were still sent: viwa says so (exit 7) and never sends them again.
147
+
148
+ **A number with no chat yet.** When `<chat>` is a phone number that is not in WhatsApp's database, `reply` starts the chat: it opens the number's `whatsapp://send?phone=` link (never with the text in it). Give the number with its country code (`+44 7700 900123`). If WhatsApp says "The phone number ... isn't on WhatsApp.", viwa presses OK and stops with "+447700900123 is not on WhatsApp. Nothing was sent." (exit 3). If that alert has no single OK, or does not close, viwa stops with exit 10 instead, saying the alert is still open in WhatsApp and to press OK there by hand. Otherwise viwa confirms the chat by its number, not its name: it opens the chat's Contact Info from the Chat menu, in the background, checks the number shown there is the one you gave, and closes it. From then on the header WhatsApp shows (the number, or a saved contact's name) is what viwa checks before and after typing and before Send. With `--send`, the message is confirmed by a new message of yours in the chat with that number's JID, which WhatsApp adds with the first message. `--file` works too; `--quote` does not, as there is nothing to quote. Names and JIDs still need an existing chat.
149
+
150
+ ### `chat <action> <chat>...`: chat actions from WhatsApp's Chat menu
151
+
152
+ ```sh
153
+ viwa chat mark-read "Ravi Traders" Mum
154
+ viwa chat archive "Old Supplier"
155
+ viwa chat mute "Mumbai Team" --for 1w
156
+ viwa chat delete "Old Supplier" --yes
157
+ ```
158
+
159
+ viwa opens and confirms each chat as `reply` does, presses the item in WhatsApp's menu bar Chat menu, then checks that the change happened. Every chat is found before anything is done, and a chat named twice is acted on once. Several chats are handled one after another; viwa stops at the first failure with its exit code, after printing what it did before it; the error line starts with the chat's name. A chat already in the wanted state is left alone ("Mum was already archived."): the database must say so and the Chat menu must no longer offer the item. If the database says so but the menu still offers the item, viwa presses it. With `--json` it prints an array of `{"chat", "action", "status"}`, where `status` is `done` or `already`; on a failure, `{"done": [...], "query": ..., "chat": ..., "error": ..., "code": ...}`, where `query` is the argument that failed and `chat` the chat it named, when it was found.
160
+
161
+ | Action | Checked in WhatsApp's database by |
162
+ |---|---|
163
+ | `mark-read`, `mark-unread` | the chat's unread count is 0, or not 0 |
164
+ | `archive`, `unarchive` | the chat's archived flag |
165
+ | `pin`, `unpin` | not in the database: the Chat menu now offers Unpin, or Pin |
166
+ | `mute`, `unmute` | a mute end in the future, or none. `--for 8h` (default), `1w` or `always` |
167
+ | `clear` | no messages left in the chat, other than system messages |
168
+ | `delete` | the chat is gone from the chat list |
169
+ | `block`, `unblock` | the chat is on WhatsApp's block list, or not |
170
+
171
+ **Chats without a conversation to confirm.** Channels, groups you have left and blocked chats may show no header viwa can match, and the Chat menu may lack an item. Then viwa uses the chat's own menu in the chat list instead (the menu you get by right-clicking the chat there): it finds the one row whose name is the chat (searching for it first when it is not showing; only a row's own name counts, the first text in the row, looked for up to four levels under the chat list, never a later text inside a row, such as another chat's last message "Mum, call me back"), opens its menu, and chooses the item by its identifier, not its English title. Mark read and unread, archive and unarchive, pin and unpin, mute (`8h`, `1w`, `always`) and unmute, clear and delete work this way; block and unblock do not, as that menu has no Block. The checks are the same: already done is left alone, the change is confirmed from the database (pin and unpin by reading the row's menu again), and clear and delete still check WhatsApp's confirmation sheet before pressing its button. WhatsApp comes to the front for a moment each time the row's menu opens, as for message actions. viwa stops (exit 10) when no single row is the chat, or when another chat's name is this one's followed by a comma (or the other way round), as the two rows could then read alike. After the press, the row's menu is read again at most four times, at least 1.5 seconds apart, so the reads cover the whole 5 seconds allowed to confirm the change.
172
+
173
+ `delete` of a group you are still in: WhatsApp's Chat menu offers "Exit group" instead of "Delete chat", as it deletes a group chat only after you exit the group. `chat delete` stops there (exit 10) with nothing changed; use `group exit <group> --delete --yes` instead. A group you have already left is deleted from its row's menu in the chat list, as above. WhatsApp may then ask "Delete this group?" in a modal alert instead of its sheet: `--yes` is the consent to press that alert's button titled exactly "Delete" (with WhatsApp in front for the press); without a single Delete, viwa presses Cancel and stops (exit 10). `VIWA_DRY_CONFIRM=1`, Ctrl-C or SIGTERM press its Cancel instead, and any other question that shows is closed without agreeing to anything (exit 10).
174
+
175
+ For the actions in pairs, the Chat menu also confirms the change: while the header still shows the chat, the menu no longer offers the pressed item and offers its opposite (`Unmute` after a mute, `Block Mum` after an unblock). WhatsApp can store a mute or block under an identifier the chat row does not carry, so the database alone can miss it.
176
+
177
+ `clear`, `delete` and `block` need `--yes`, or they stop (exit 64) before touching WhatsApp. They take only the chat's full name (case aside), its phone number or its JID: a name that only starts like a chat's, such as `Mum` for "Mumbai Team", is not found (exit 3). WhatsApp then asks for confirmation in a sheet; viwa presses its confirm button only when the sheet's prompt asks exactly that for this chat ("Delete chat with Mum?", "Clear chat with Mum?", or for block a prompt starting "Block Mum?"), and otherwise presses Cancel and stops (exit 10). Ctrl-C or SIGTERM before the confirm button is pressed also makes viwa press Cancel, and it exits with 130 or 143. WhatsApp comes to the front while that sheet shows, and viwa gives the front back straight after pressing the button. The other actions run with WhatsApp in the background, except that after WhatsApp was started in the background it lists its chat items in the Chat menu only once it has been the active app, so viwa brings it to the front once, for under a second, to build the menu. If the change does not show within 5 seconds, viwa stops with exit 10; check the chat in WhatsApp.
178
+
179
+ ### `message <action> <chat> <message-id>`: message actions from the message's own menu
180
+
181
+ ```sh
182
+ viwa message star Mum 81458
183
+ viwa message react "Ravi Traders" 81460 --emoji 👍
184
+ viwa message pin "Mumbai Team" 81461 --for 24h
185
+ viwa message edit "Ravi Traders" 81462 --text "Ready by Friday" --yes
186
+ viwa message delete Mum 81458 --yes
187
+ viwa message delete Mum 81459 --everyone --yes
188
+ viwa message forward Mum 81458 --to "Ravi Traders" --yes
189
+ ```
190
+
191
+ `<message-id>` is the id `read` and `search` print (the same one `reply --quote` takes). One chat and one message per run. viwa opens and confirms the chat as `reply` does, finds the message's bubble as `--quote` does (scrolling up to it if needed), chooses the action from the bubble's menu, then checks the change in WhatsApp's database. A message already in the wanted state is left alone ("Message 81458 in Mum was already starred."): for `star`, `unstar` and `edit` the database decides and nothing in WhatsApp is touched. `react` and `unreact` are decided in WhatsApp's reaction tray, which marks your current reaction, and `pin` and `unpin` in the message's menu, which offers only the item that changes the pin; the database settles them without opening WhatsApp only when it already shows your reaction (that emoji, for `react`) or none (for `unreact`), or when its latest pin record is yours. `delete` of an id whose message is gone reports it already deleted for you; an id beyond the newest message in WhatsApp's database is not found (exit 3). A system message is refused (exit 64). With `--json` it prints `{"chat", "message", "action", "status"}`, where `status` is `done` or `already`.
192
+
193
+ | Action | Options | Checked in WhatsApp's database by |
194
+ |---|---|---|
195
+ | `star`, `unstar` | | the message's starred flag |
196
+ | `react` | `--emoji <emoji>` (required) | your reaction to the message is that emoji |
197
+ | `unreact` | | you have no reaction to the message |
198
+ | `pin`, `unpin` | `--for 24h`, `7d` (default) or `always` | the message's pin, or none |
199
+ | `edit` | `--text <new text>` (required), `--yes` | the message's text is the new text |
200
+ | `delete` | `--yes`; `--everyone` | the message is gone (allowing up to 10 seconds); with `--everyone`, it shows as deleted (no text left), also within 10 seconds |
201
+ | `forward` | `--to <chat>` (required), `--yes` | a new message from you in that chat with the same text |
202
+
203
+ - **Older messages are scrolled to.** When the message is not loaded on screen, viwa scrolls the chat up in the background, a page at a time, until its bubble shows, and once the action is over (done or not) opens the chat again so WhatsApp is back at the newest messages. An old message can take a while (about 0.6 seconds a page, at most 300 pages); Ctrl-C or SIGTERM stops the search with nothing changed. viwa stops (exit 10) with nothing changed at the start of the chat, once the chat shows messages from more than a day before the message without showing it, after 300 pages, or if the open chat changes; if WhatsApp comes to the front meanwhile, it stops and leaves the chat as it is. The message is found by its side (yours or not), its text (or, without text, its kind) and the minute it shows, so viwa first looks in the database for another message in the chat that matches all three, loaded on screen or not, and stops (exit 10) with nothing changed if there is one.
204
+ - **WhatsApp comes to the front for up to a few seconds** while the message's menu is open, and viwa gives the front back straight after choosing the item. viwa will not open the menu while WhatsApp is the app in front, or while another menu, sheet or popover shows there. For `react` it stays in front longer (up to about 4 seconds), as its reaction tray closes as soon as WhatsApp leaves the front; the front is given back once the tray has closed. For an emoji from WhatsApp's emoji picker it stays in front for several seconds (up to about 10), as the picker closes in the same way. `delete` brings WhatsApp forward again for the press of "Delete for me" (or "Delete for everyone"), which does nothing in the background, and gives the front back once the popover has closed (up to about 3 seconds in all); it brings WhatsApp forward only once that exact button is found, and stops with nothing changed if WhatsApp does not come forward within a second. Do not type while an action runs.
205
+ - **`edit`, `delete` and `forward` need `--yes`**, or they stop (exit 64) before touching WhatsApp. They take only the chat's full name (case aside), its phone number or its JID, for `--to` too. An option used with the wrong action, a missing required option or an empty `--text` also stops with exit 64.
206
+ - **`delete` deletes the message for you only**: viwa presses "Delete for me" and never "Delete for everyone". **`delete --everyone --yes`** deletes it for everyone instead: viwa presses only "Delete for everyone" and never "Delete for me", and stops with nothing changed (exit 10) when WhatsApp does not offer it (your own chat, a message too old to delete for everyone, or someone else's message). It works on your own messages; in a direct chat someone else's message is refused (exit 64) before WhatsApp is touched. In a group where you are an admin, WhatsApp also offers it on other people's messages ("Delete message from Ravi Kumar?"), and viwa allows that too, but only with both `--everyone` and `--yes`. A message already showing as deleted is reported as already done; one already deleted for you only (gone from the database) cannot be reached any more (exit 3).
207
+ - **`react` takes any single emoji.** A quick reaction (the row of emoji WhatsApp's tray shows) is pressed in the tray. Any other emoji is chosen in WhatsApp's emoji picker ("Add custom reaction"): viwa searches for it by its Unicode name (🦄 as "unicorn face") and presses the result showing exactly that emoji, or stops with nothing changed ("WhatsApp's emoji search did not find 🦄."). An emoji with a skin tone is searched by the plain emoji's name and must show among the results with that tone. Flags, keycaps (such as 1️⃣), emoji joined from several (such as 👩‍💻) and more than one emoji are refused with nothing changed.
208
+ - **`unreact` of a reaction chosen in the emoji picker replaces it with 👍 first.** WhatsApp's tray does not take such a reaction away when it is pressed again, so viwa reacts with 👍 from the quick reactions (stopping with nothing changed if the tray does not show 👍), waits for the database to show it, then takes 👍 away and checks the database shows no reaction. **The other person may briefly see 👍**, and may be notified of it. If anything fails or you stop it after 👍 was added, viwa says "Your reaction was replaced by 👍 but could not be removed; check the message in WhatsApp." (exit 10).
209
+ - **`edit` works only on your own text messages that WhatsApp still lets you edit** (recent ones). viwa replaces the text in the box by typing in the background and presses Edit; it never presses Return. The message box must be empty first (no text, draft or quote), or `edit` stops with exit 9, as editing loads the message into the box.
210
+ - `pin` answers WhatsApp's "how long" sheet with the length you chose. `forward` finds the chat in WhatsApp's forward picker and ticks only that one, and checks that only that chat is chosen before pressing Forward; your own chat is `You` (viwa tells it by your own JID when the database shows it). A forwarded message without text is confirmed by a new message of the same kind in the target chat.
211
+ - If anything fails before the final press, viwa undoes what it opened (the menu, the tray, the sheet, edit mode, or the selection, by opening the chat again) and stops with exit 10. If the pin sheet, edit mode, the delete popover or the forward picker is still open 2 seconds after the final press, WhatsApp seems not to have taken it: viwa cancels it and stops with exit 10, saying the change may still have happened; check WhatsApp before trying again. Ctrl-C or SIGTERM before the final press does the same as a failure and exits with 130 or 143. If the change does not show within 5 seconds (10 for `delete`), viwa stops with exit 10; check the message in WhatsApp. After "Delete for everyone", viwa watches 2 seconds for any further question from WhatsApp (only a dialog, alert, sheet or popover that was not showing just before the press counts); one that shows is closed without agreeing to anything (Cancel, Not now, Close, or OK when it is the only button) and viwa stops with exit 10, saying what WhatsApp asked and that the delete may have taken effect.
212
+
213
+ ### `group <action> <group>`: create and manage groups
214
+
215
+ ```sh
216
+ viwa group create "Mumbai Office" --member Mum --member "Ravi Kumar" --yes
217
+ viwa group rename "Mumbai Team" "Mumbai Office" --yes
218
+ viwa group add "Mumbai Team" --member "Ravi Traders" --yes
219
+ viwa group remove "Mumbai Team" --member "Ravi Kumar" --yes
220
+ viwa group admin "Mumbai Team" --member "Ravi Kumar"
221
+ viwa group dismiss-admin "Mumbai Team" --member Mum
222
+ viwa group exit "Mumbai Team" --yes
223
+ viwa group exit "Mumbai Team" --delete --yes
224
+ ```
225
+
226
+ One group per run. The group and every `--member` take only a chat's full name (case aside), its phone number or its JID, as `chat delete` does; a member must be someone you already have a direct chat with in WhatsApp's database (for `add`, someone known only from your contacts or from a group is refused, exit 3, as the picker could then tick another contact of the same name), never a group or your own chat, and a name shared by two chats is refused. viwa opens the group and confirms its header, as `reply` does, then works through WhatsApp's menu bar and the group's Group Info in the background, checks that Group Info shows the group's name before doing anything in it, and confirms the change in WhatsApp's database (allowing up to 10 seconds). A group already in the wanted state is left alone, decided from the database first and, for `admin` and `dismiss-admin`, again from the member list. With `--json` it prints `{"group", "action", "member", "status"}`, where `status` is `done` or `already`.
227
+
228
+ | Action | What viwa does in WhatsApp | Checked in WhatsApp's database by |
229
+ |---|---|---|
230
+ | `create "<name>" --member <chat>...` | File > New group; in the participant picker, searches for each member and ticks the one contact whose name reads exactly theirs, checking the picker's count of chosen members goes up by one each time; Next; types the name; Create | a new group chat with that name |
231
+ | `rename <group> "<new name>"` | Group Info > Edit group; clears the name, types the new one, checks it, presses Done | the group's name |
232
+ | `add <group> --member <chat>` | Group Info > members > Add members; ticks the member in the picker as for `create`; Add | the member's row in the group is active |
233
+ | `remove <group> --member <chat>` | Group Info > members > the member's row > Remove from group; then Remove, once WhatsApp asks to remove that member from that group | the member's row is inactive (or gone) |
234
+ | `admin`, `dismiss-admin <group> --member <chat>` | Group Info > members > the member's row > Make group admin, or Dismiss as admin | the member's admin flag |
235
+ | `exit <group>` | Chat menu > Exit group; in its sheet, Exit group | your own member row (by your number, your own chat's privacy identifier, or the chat that carries yours) is inactive or gone, where it was there before the press; nothing else counts |
236
+ | `exit <group> --delete` | the same, with Exit and delete for me; then Delete in WhatsApp's "Delete this group?" | the group's chat is gone |
237
+
238
+ - **Every action but `admin` and `dismiss-admin` needs `--yes`**, or it stops (exit 64) before touching WhatsApp; so does an option used with the wrong action (`--member` with `rename` or `exit`, `--delete` without `exit`, a new name without `rename`), `add`, `remove`, `admin` or `dismiss-admin` without exactly one `--member`, `create` without one, an empty name, or a name with a line break. A name that another chat already has is refused (exit 64), as the group could then not be told apart on screen.
239
+ - **Members are found by their exact name.** The picker must show exactly one contact reading the member's name once its list has settled, or viwa stops with nothing changed (exit 10); so it does when the member list does not show the member's row (in a large group, a member far down the list may not be loaded), or shows more than one row with that name. A member whose name another of your chats also has is refused before WhatsApp is touched, even when given by number. `remove` of someone with no member row in WhatsApp's database is refused (exit 3, nothing changed), and `admin` and `dismiss-admin` need a current member (exit 64): a name in WhatsApp's member list alone could be another person's.
240
+ - **`create` confirms its members.** Once the new group shows in the database, each member you named must show as an active member of it within 10 seconds, or viwa stops with exit 10 naming the missing ones (the group exists; check its members in WhatsApp now).
241
+ - **A further question after Add or Create** (for example WhatsApp offering to invite someone whose privacy settings stop them being added) is never answered: viwa watches 2 seconds after the press, closes any dialog, alert, sheet or popover that was not showing just before the press, without agreeing to anything and pressing only a button inside it, and stops with exit 10, saying what WhatsApp asked and that the action may have taken effect. macOS's automatic capitalisation is undone in the name fields, and the name must read exactly as you gave it before Create or Done is pressed.
242
+ - **`exit`** presses its button only when the sheet asks "Exit group?", names the group in WhatsApp's quotes, and its "Report this group" box reads unticked; if viwa cannot tell, it presses Cancel and stops. The exit button was not seen pressed with WhatsApp in the background, so if the sheet is still open 2 seconds after the press, viwa brings WhatsApp to the front and presses it once more, then gives the front back. A plain `exit` is confirmed only by your own member row turning inactive or disappearing; if no row of yours can be found before the press, or it does not change, viwa stops with exit 10 ("check WhatsApp"). A plain `exit` after you have already left the group (your row, found the same way, reads inactive) is reported as already done; `exit --delete` then stops (exit 64) and points to `chat delete`.
243
+ - **`exit --delete`** brings WhatsApp to the front for "Exit and delete for me" and keeps it there until WhatsApp's second question, "Delete this group?" (a modal alert that blocks WhatsApp until answered), is answered. viwa looks for that alert for up to 5 seconds among the dialogs, alerts, sheets and popovers that were not showing just before the press (never in an ordinary window), presses only its button titled exactly "Delete", and checks the alert has gone; it never presses the exit button again. If the alert has no single Delete, it presses Cancel when there is one and says so (you have then left the group but kept its chat). If no alert shows, the database decides: the chat gone is success. If it has not gone within the 5 seconds, viwa looks for the alert once more and answers it as above if it shows now; otherwise it stops with exit 10, saying WhatsApp may still ask "Delete this group?" and that you should answer it there. Any other question that shows is closed without agreeing to anything and reported (exit 10).
244
+ - If anything fails before the final press, viwa closes what it opened (the member's menu, the picker, Edit group after putting the old name back, Group Info, the exit sheet) and stops with exit 10 and nothing changed. If WhatsApp does not seem to take the final press, viwa closes what is still open and stops with exit 10, saying the change may still have happened. Ctrl-C or SIGTERM before the final press does the same and exits with 130 or 143. `VIWA_DRY_CONFIRM=1` checks everything up to the final press, then closes it all and stops with nothing changed.
245
+ - Group descriptions and group settings (who can send messages or edit the group's details, disappearing messages, the group photo) are not supported yet.
246
+
247
+ ### `call <chat>`, `call end`: start or end a call
248
+
249
+ ```sh
250
+ viwa call Mum --yes
251
+ viwa call "Ravi Traders" --video --yes
252
+ viwa call end
253
+ ```
254
+
255
+ `call <chat> --yes` opens and confirms the chat as `reply` does, then presses "Voice Call" (or with `--video`, "Video Call") in WhatsApp's Chat menu, which rings the other side; for a group, it rings every member of the group. Without `--yes` it stops (exit 64) before touching WhatsApp or even reading its database, and says so, whether or not the chat can be found. viwa stops (exit 10) with nothing pressed while a call is already in progress (End Call is offered); end it first, for example with `call end`. A further question after the press (a dialog, alert, sheet or popover that was not showing just before it, such as "Start a call with N people?") is closed without agreeing to anything and reported (exit 10); the call's own window never counts. The chat takes only its full name (case aside), its phone number or its JID; a chat named "end" is reached by its number or JID. If the item is missing or greyed out (WhatsApp greys out some Chat menu items while it is in the background), viwa stops (exit 10) without bringing WhatsApp forward. `call end` presses "End Call" in WhatsApp's Call menu and checks that it is greyed out afterwards; if it was greyed out already, no call was in progress and nothing is pressed ("No WhatsApp call was in progress.", exit 0). With `--json` they print `{"chat", "action", "status"}`: `action` is `voice`, `video` or `end`, and `status` is `pressed`, `ended` or `none`.
256
+
257
+ **Calls are not confirmed from WhatsApp's database**, which does not show them: viwa confirms only that it pressed the menu item (and, for `call end`, that End Call is no longer offered). **Calls have not been tested live** (nobody was rung while viwa was being built), so check WhatsApp after a call command. Unlike the other commands, `call` never restarts WhatsApp, as quitting it would end a call. As after other commands, viwa gives the front back to the app you were using if WhatsApp has taken it; whether WhatsApp's call window comes to the front has not been seen.
258
+
259
+ ### `poll <chat>`: create a poll, and send it only with `--send`
260
+
261
+ ```sh
262
+ # Fills in WhatsApp's poll form, checks it, then presses Cancel: nothing is sent.
263
+ viwa poll "Mumbai Team" --question "Lunch where?" --option Cafe --option Canteen
264
+
265
+ # Sends it, then confirms the poll reached WhatsApp's database.
266
+ viwa poll "Mumbai Team" --question "Lunch where?" --option Cafe --option Canteen --option Desk --send
267
+
268
+ # Only one answer per person (WhatsApp allows several by default).
269
+ viwa poll Mum --question "Dinner at 7?" --option Yes --option No --single --send
270
+ ```
271
+
272
+ viwa opens and confirms the chat as `reply` does, then opens WhatsApp's attach menu and chooses Poll. That menu closes as soon as WhatsApp leaves the front, so WhatsApp comes to the front from the attach press until the poll form shows, usually about a second, and viwa then gives the front back. The form stays open in the background, where viwa types the question and each option, accepts the capital WhatsApp gives the first letter of a sentence (it cannot be put back in the form; see Known gaps), sets "Allow multiple answers" (off with `--single`), and reads every field back. Just before Send it reads them all once more. With `--send` the poll is confirmed by a new poll of yours in the chat whose question and options match; without it, viwa presses the form's Cancel and prints what would have been sent. The form is never left open: any failure, and Ctrl-C or SIGTERM before Send (exit 130 or 143), presses its Cancel. If the form is still open 3 seconds after Send, viwa presses Cancel, says so, and still checks the database.
273
+
274
+ A poll needs a question and 2 to 12 options, each different (ignoring case), none empty and none with a line break; otherwise viwa stops before touching WhatsApp (exit 64). `poll --send` counts towards the send limit, and like `reply` it does not start while WhatsApp is the app in front. With `--json` it prints `{"status", "chat", "messageID", "poll", "multipleAnswers"}`, where `status` is `checked` or `sent` and `messageID` is `null` when the poll was only checked.
275
+
276
+ ### `watch`: stream new messages
277
+
278
+ ```console
279
+ $ viwa watch
280
+ {"caption":null,"chat":"Ravi Traders","chatID":1,"date":"2025-11-05T04:33:20Z","fromMe":false,"id":900,"kind":"text","mediaPath":null,"poll":null,"quotedText":null,"senderJID":"447700900001@s.whatsapp.net","senderName":"Ravi Traders","starred":false,"text":"Order is ready for collection"}
281
+ ```
282
+
283
+ `watch` prints one JSON object per line (NDJSON) for each new message until you press Ctrl-C. It always prints NDJSON; `--json` is accepted for consistency. Options: `--chat <chat>`, `--include-own` (also your own messages), `--interval <seconds>` (default 1), `--after <id>` (start after that message id, the `id` of the last line you handled, instead of from now, so a watcher that was stopped and started again misses nothing). If the database cannot be read, it retries and says so on stderr; after 5 failures in a row it stops with the error as one JSON line on stderr.
284
+
285
+ ### `doctor`: check your setup
286
+
287
+ ```console
288
+ $ viwa doctor
289
+ ok WhatsApp installed: version 26.45.13
290
+ ok WhatsApp Business: not installed
291
+ ok Database readable: readable
292
+ ok Own account found: found
293
+ ok Accessibility permission: granted
294
+ ok WhatsApp running in English: running, English menus
295
+ ok WhatsApp window readable: readable
296
+ ```
297
+
298
+ Each line is `ok`, `warn` (works, but worth knowing, such as an untested WhatsApp version) or `fail`. `--json` prints the same checks as an array of `{"name", "ok", "warning", "detail"}`, where `warning` is true for a `warn` line. The exit code is 0 when nothing failed, otherwise the code of the first failure (see [Exit codes](#exit-codes)). "Database readable" also fails (exit 6) when the database opens but lacks a table or column viwa reads, naming it: WhatsApp has then changed how it stores chats, and viwa needs an update.
299
+
300
+ `doctor` only reads. It never opens a chat, types, clicks, brings WhatsApp to the front or touches the clipboard, and it does not print your phone number or any contact or message.
301
+
302
+ ## Safety rules
303
+
304
+ - **Nothing is sent without `--send`.** The default is to type the reply and leave it unsent.
305
+ - **Existing chats, or a number checked on screen.** `reply` goes to chats already in WhatsApp's database (not removed or hidden), found by name, number or JID. It starts a new chat only for a phone number, and only once the chat WhatsApp opens shows that number in its Contact Info.
306
+ - **No guessing.** A name matching more than one chat is refused with the list of matches (exit 4). If two chats share the same display name, viwa refuses to reply to either of them, even by JID, because the screen cannot tell them apart (exit 10); rename one contact in WhatsApp. The same goes for a chat named "X, verified user" or "X, verified business" beside a chat named "X", as WhatsApp shows a verified business's name that way.
307
+ - **The right chat, checked again and again.** The chat header in WhatsApp must match the chat's name before typing and again after typing. With `--send`, just before Send is pressed viwa looks once more: the header (or, for a file, the preview's recipient) must still match, the message box (or the caption) must still hold exactly the reply text (a curly apostrophe or quotation mark counts as the straight one you typed, see Known gaps), and WhatsApp must not be the app in front. Otherwise viwa stops without pressing Send (exit 10).
308
+ - **Your drafts are safe.** If the message box already holds text, a draft, a quote or a file preview, viwa refuses (exit 9) and never appends to, replaces or clears it. This includes text an earlier `reply` without `--send` left there: send or clear it first.
309
+ - **Sends are confirmed.** `--send` reports success only once the message appears in WhatsApp's database (exit 7 otherwise: the message may still have been sent, so check WhatsApp before trying again).
310
+ - **Send limit.** At least 3 seconds between sends and at most 10 sends in any 60 seconds, shared by every viwa process. Going over is an error (exit 8), not a queue, and the limit cannot be changed. Every `reply --send` counts, even one that is refused later. The send times are kept in `~/Library/Application Support/viwa/sends.json`.
311
+ - **One reply at a time.** Every `reply`, with or without `--send`, holds a lock (`~/Library/Application Support/viwa/reply.lock`) from just after the chat is found until it has finished tidying up, so two replies never drive WhatsApp at once. A reply that starts while another is running waits up to 10 seconds, then stops with "Another viwa reply is running. Try again in a moment." (exit 8). `chat`, `message`, `poll`, `group` and `call` share the same lock; a waiting one says "Another viwa command is driving WhatsApp. Try again in a moment." Reading commands, `watch` and `doctor` never wait for it.
312
+ - **If a reply fails or you stop it** (Ctrl-C, or SIGTERM from a script or agent runner), viwa finishes the step it is on, cancels any attachment preview it opened, puts your clipboard back and, while WhatsApp still shows the same chat, removes the text it typed and any quote it added. If WhatsApp has switched to another chat, or viwa cannot tidy up, it leaves that chat alone and says so on stderr. A stopped reply exits with 130 (Ctrl-C) or 143 (SIGTERM) and says "Nothing was sent." A signal that arrives after Send was pressed does not cut the reply short: viwa still waits for the confirmation and reports whether the message was sent.
313
+
314
+ ## What you will notice
315
+
316
+ - **Opening a chat marks it read**, just as when you open it yourself. Reading commands do not.
317
+ - **WhatsApp may show "typing..."** to the other person while viwa types. That includes `reply` without `--send` to a number with no chat yet: viwa opens that number's chat and types into it, so a stranger may see "typing...", and the empty chat stays in your chat list.
318
+ - **viwa never answers a question it did not ask, and never quits WhatsApp over one.** While WhatsApp shows a question, sheet or form (a dialog or alert window, or a sheet in its main window), viwa stops before doing anything: "WhatsApp is showing a question or form ("<its text>"). Answer or close it in WhatsApp, then try again. Nothing was changed." (exit 10; "Nothing was sent." for `reply` and `poll`). `doctor` reports the same as a failed check. Ordinary extra windows (a call's window, a chat opened in its own window, a viewer) never count as a question, whatever their size. A chat open in its own window while the main window also shows a chat still stops `reply`, `chat`, `message`, `poll` and `group`, for another reason: with two message boxes on screen the right one cannot be confirmed ("More than one WhatsApp window is open", exit 10). viwa knows WhatsApp's main window by its Accessibility identifier and its chat list or message box, never by its title alone.
319
+ - **WhatsApp comes to the front only briefly.** When viwa opens a chat by its phone number (a `whatsapp://` link), WhatsApp brings itself to the front for a moment; viwa gives the front back to the app you were using, usually within half a second, checks again just before typing, and stops (exit 10) if WhatsApp is still in front. Do not type while a reply runs: keys pressed in that moment can land in the chat. WhatsApp also comes to the front in two longer spans, usually about a second each: while `--file` pastes the files in, all in one paste (through the clipboard, and your clipboard is restored afterwards unless you copy something in the meantime), and while `--quote` chooses Reply from the message's menu. viwa then gives the front back to the app you were using. Typing and clearing happen in the background: if WhatsApp does not take viwa's keystrokes, viwa tries once more in the background, and then restarts WhatsApp as described below. Run file sends from a terminal that is in front.
320
+ - **`reply` will not run while WhatsApp is the app in front**, because your typing would land in the chat it opens. It stops with "WhatsApp is the app in front, so your typing could land in the chat. Switch to another app and try again. Nothing was sent." (exit 10), and checks again just before pressing Send.
321
+ - If WhatsApp is not running, or its window is closed, `reply` starts or reopens it and waits up to 15 seconds for its window. If the window is minimised, `reply` restores it for the reply and minimises it again afterwards. WhatsApp may come to the front as it does; viwa gives the front back as above.
322
+ - **WhatsApp sometimes stops taking viwa's keystrokes** (seen with 26.44.21 after a while in the background). Before retrying a search, viwa nudges the window by one point and back, which can make WhatsApp lay it out again. If WhatsApp still takes none of the keystrokes typed into its search field or message box, and viwa has confirmed that none of its own text is left in the box, it quits WhatsApp, opens it again in the background and tries the reply once more, saying so on stderr. This happens at most once per reply and only before Send is pressed, and never while WhatsApp shows a question, sheet or form; quitting WhatsApp ends a WhatsApp call in progress. When the keystrokes land but read back differently (for example WhatsApp changed a letter's case), or a search finds no matching chat, viwa does not restart WhatsApp: it stops with exit 10 and nothing sent.
323
+ - **`message` actions bring WhatsApp to the front for up to a few seconds**, as described for `message` above, and do not start while WhatsApp is the app in front. `poll` brings it to the front for about a second to open the poll form, and chat actions on a chat's row in the chat list for a moment each time the row's menu opens.
324
+ - **`group` actions run in the background**, except that, as for `chat`, WhatsApp may come forward once for under a second to build its Chat menu, `exit` may bring it forward for its press, and `exit --delete` keeps it in front until "Delete this group?" is answered (see `group` above). They do not start while WhatsApp is the app in front.
325
+ - Set `VIWA_DEBUG=1` to see on stderr which steps `reply`, `chat`, `message`, `poll`, `group` or `call` took.
326
+
327
+ ## Exit codes
328
+
329
+ | Code | Meaning |
330
+ |---|---|
331
+ | 0 | Success |
332
+ | 3 | Chat (or the message to quote or act on, or the group member) not found, or the number is not on WhatsApp |
333
+ | 4 | Chat name is ambiguous; the matches are listed |
334
+ | 5 | Permission missing: Accessibility, write access to `~/Library/Application Support/viwa`, or (from `doctor`) access to the database |
335
+ | 6 | WhatsApp not available: not installed, not running, no readable window, or its database cannot be read |
336
+ | 7 | Send not confirmed, or files sent with `--quote` went out without the quote |
337
+ | 8 | Send limit reached, or another viwa reply is still running after a 10 second wait |
338
+ | 9 | WhatsApp's message box is not empty (text, draft, quote or file preview) |
339
+ | 10 | The chat cannot be confirmed in the app, WhatsApp is the app in front, WhatsApp shows a question or form, a change could not be confirmed, or WhatsApp did not take viwa's typing even after a restart |
340
+ | 11 | Unsupported setup (WhatsApp Business, or an interface not in English) |
341
+ | 130, 143 | Stopped by Ctrl-C (SIGINT) or SIGTERM before Send or the action's final press; nothing was sent or changed |
342
+ | 64 | Invalid arguments |
343
+
344
+ ## Known gaps
345
+
346
+ - Tested with WhatsApp Desktop 26.45.13 on macOS only (group member actions, clear and block were mapped on 26.44.21). English interface only. WhatsApp Business is not supported.
347
+ - Sending depends on WhatsApp's Accessibility tree, so WhatsApp's window must be on the current desktop (not on another desktop, and not behind a locked screen; a minimised window is restored for the reply). When the window is on screen but viwa cannot find its chat list or message box, `reply`, `chat`, `message`, `poll` and `group` restart WhatsApp once (as below, and never while it shows a question or form) and then stop with exit 10; with no window at all they exit 6. `viwa doctor` checks it ("WhatsApp window readable"). Two causes seen with 26.44.21: WhatsApp's photo or file viewer covering the window (close it), and WhatsApp no longer exposing its window to Accessibility (click once on an empty part of the window).
348
+ - macOS capitalises the first letter of a sentence once the next space is typed, so WhatsApp's box can read "Plain test" or "ok. Thanks" for what you wrote. viwa puts each such letter back as you wrote it, in the background with the arrow keys (never select all, never Return), in the message box, in a file's caption and in `message edit`, and stops without sending (exit 10) if the text still does not match yours exactly.
349
+ - Up to 10 files per reply. They are pasted into one preview and sent together, each as its own message, with the text as the first one's caption; with `--send`, viwa waits for one new message per file. Two files with the same name cannot go in one reply, as the preview lists them by name. A folder cannot be sent.
350
+ - Files sent with `--quote` are confirmed as quoting from WhatsApp's database, by the quoted message's id stored with them (or its text), the layout seen for text replies. If WhatsApp stores a file's quote differently, viwa reports the quote as missing (exit 7) although it was sent with it; check the chat in WhatsApp.
351
+ - `--quote` and message actions find the message by its text and the date and time its bubble shows, so two identical messages sent in the same minute cannot be told apart. Bubbles from an earlier year are assumed to read "8 November 2025 at 11:08" (not yet seen); if they read otherwise, such a message is not found (exit 10). After a quoted reply typed or sent from further up the chat, viwa leaves the chat where WhatsApp shows it.
352
+ - `react` with an emoji outside the quick reactions relies on WhatsApp's emoji search knowing the emoji's Unicode name, which can differ from the name WhatsApp uses (🦊, "fox face", is not found); viwa then stops with nothing changed. Flags, keycaps and joined emoji cannot be reactions yet. `unreact` of a reaction chosen in the emoji picker swaps it for 👍 first, which the other person may briefly see, and needs 👍 among your quick reactions.
353
+ - Polls were mapped live on one poll in your own chat. A poll's question and options are read from where WhatsApp stored them for that poll (its receipt info); a poll stored differently shows as `[poll]` with `poll: null`, and a sent one is then reported as not confirmed (exit 7) although it was sent. Whether Send in the form works with WhatsApp in the background, and WhatsApp's length limits for questions and options, are not known yet: a question or option the form cuts short stops the poll before Send (exit 10). Contact cards and events from the attach menu are not supported.
354
+ - Quoted media and polls show `quotedText: null`. The layout of quoted messages in WhatsApp's database was worked out by inspection and may change with WhatsApp updates.
355
+ - macOS smart quotes turn a straight `'` or `"` into a curly one as it is typed, and viwa does not put it back: the message is sent with the curly quote, and counts as the text you gave. Any other change the box makes to the text, apart from the capitals described above, still stops the reply with nothing sent (exit 10).
356
+ - Search does not ignore accents, and does not search poll questions.
357
+ - `read --before` and `--after` compare message ids, which follow the order WhatsApp stored the messages in; a message that reached this Mac late can sit out of date order.
358
+ - The send limit (3 seconds apart, 10 per 60 seconds, across processes) is not configurable.
359
+ - `watch` prints NDJSON only; `--json` is accepted on every command.
360
+ - `chat pin` and `chat unpin` are confirmed from WhatsApp's Chat menu, not the database, because WhatsApp does not store pins there. Chat actions are found by their English menu titles as of 26.44.21; the `clear` and `block` sheets were checked live without confirming (`VIWA_DRY_CONFIRM=1`); a real Clear or Block has not been run.
361
+ - Group actions were mapped live with WhatsApp 26.44.21 on a test group, and `create`, `rename`, `add`, `remove`, `admin` and `dismiss-admin` were run through viwa there, with and without `VIWA_DRY_CONFIRM=1`, which used Group Info's close button, the text showing the group's name and the buttons that leave the participant picker. Whether the exit sheet's buttons take a press in the background is not known. If something differs, viwa stops with nothing changed and may leave Group Info or the picker open (it says so); close it by hand. A member who shows twice in the participant picker (as a suggestion and as a contact) is refused rather than guessed. Members far down a large group's member list may not be found. Group descriptions and settings are not supported.
362
+ - `call` and `call end` were not tested live and are not confirmed from the database (WhatsApp does not store calls there); viwa confirms only its press of the menu item. "Voice Call" and "Video Call" may be greyed out while WhatsApp is in the background, in which case `call` stops with nothing changed.
363
+ - Chats whose header viwa cannot confirm (channels, groups you have left, possibly blocked contacts) are acted on from their row's menu in the chat list. That route was mapped live on one chat only: the row label format beyond "starts with the chat's name", the identifiers for mark read, unarchive and unmute (inferred from mark_as_unread, archive and the Mute submenu), pressing a Mute submenu item without opening the submenu, and the clear and delete sheets from that menu have not been checked yet. Run with `VIWA_DEBUG=1` to see the menu's identifiers. Block and unblock still need the conversation.
364
+ - A reply to a number with no chat yet is confirmed in the chat with that number's phone JID. If you already chat with that person under a privacy identifier (`...@lid`) and a name, the number is not found as that chat, WhatsApp may put the message there, and viwa then reports the send as not confirmed (exit 7) although it was sent; check WhatsApp, and use the chat's name next time. A number without its country code is refused, as Contact Info shows it with one.
365
+ - Chat actions do not work on channels: WhatsApp lists them under Updates, not in the chat search viwa uses, so they stop with exit 10 and nothing changed.
366
+ - WhatsApp capitalises the first letter of a poll's question and options as they are typed, and its poll form does not let viwa put that right, so a poll is accepted and confirmed when it differs from what you wrote only by a capital at the start of a sentence (the first letter, or one after ". ", "? " or "! "); any other change of case is refused (for messages, viwa still puts every letter back exactly).
367
+ - **Run end to end on WhatsApp 26.45.13:** a plain `group exit`, `group exit --delete` (WhatsApp showed "Delete this group?" as a sheet, answered by viwa), `message delete --everyone`, and `chat delete` of a group you have left through the chat list row's menu ("Delete “<name>”?" with "Delete group"). **Not yet run end to end through viwa:** `call`, replies to a real number with no chat yet (only a number not on WhatsApp was tried), several photos in one reply (only text files were sent), and the late look for "Delete this group?" after `exit --delete`. The checks after a final press for a further question (`add`, `create`, `call`, `delete --everyone`) have not met such a question live.
368
+ - viwa is not code-signed or notarised yet.
369
+
370
+ ## Privacy
371
+
372
+ viwa runs only on your Mac. It sends nothing anywhere: no analytics, no telemetry, no network connections of its own. It reads WhatsApp's database read-only, it changes WhatsApp only through the WhatsApp app itself when you run `reply`, `chat`, `message`, `poll`, `group` or `call`, and it never stores your messages anywhere else. What it prints goes only where you send it (your terminal, a file, or the AI agent you run it from), so treat that output as you would your chats.
373
+
374
+ ## Use at your own risk
375
+
376
+ viwa drives the official WhatsApp app on your behalf. Using it, especially to send messages automatically, may be against WhatsApp's Terms of Service, and WhatsApp can restrict or ban accounts it believes are automated. You are responsible for how you use viwa and for following WhatsApp's terms and the law. viwa is provided as is, without warranty; see the licence.
377
+
378
+ ## Licence
379
+
380
+ viwa is free to download and use, but it is not open source. Copyright (c) 2026 Zorinto Ltd, all rights reserved. Use is under the viwa licence in the `LICENSE` file that comes with the package: you may install and use the unmodified program for free, for personal or business purposes, but not copy, modify, redistribute, resell or reverse engineer it, or use it to build a competing product.
381
+
382
+ WhatsApp is a trade mark of WhatsApp LLC. viwa is not affiliated with WhatsApp or Meta, and this project uses no WhatsApp logo.
package/bin/viwa.js ADDED
@@ -0,0 +1,31 @@
1
+ #!/usr/bin/env node
2
+ // Launcher: runs the prebuilt Apple silicon viwa binary with the same arguments.
3
+ const { spawn } = require("node:child_process");
4
+ const path = require("node:path");
5
+
6
+
7
+ if (process.platform !== "darwin") {
8
+ console.error("viwa only runs on macOS.");
9
+ process.exit(1);
10
+ }
11
+
12
+ const binary = path.join(__dirname, "..", "vendor", "viwa");
13
+
14
+ const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
15
+ for (const signal of ["SIGINT", "SIGTERM"]) {
16
+ process.on(signal, () => child.kill(signal));
17
+ }
18
+ child.on("error", (error) => {
19
+ if (error.code === "ENOENT") {
20
+ console.error(`viwa binary not found at ${binary}. Reinstall @zorinto/viwa.`);
21
+ } else {
22
+ console.error(`viwa could not start: ${error.message}`);
23
+ }
24
+ process.exit(1);
25
+ });
26
+ child.on("exit", (code, signal) => {
27
+ if (signal) {
28
+ process.exit(128 + ({ SIGINT: 2, SIGTERM: 15 }[signal] ?? 1));
29
+ }
30
+ process.exit(code ?? 1);
31
+ });
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "@zorinto/viwa",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.5.0",
4
+ "description": "Read, reply to and manage WhatsApp Desktop chats from the Mac terminal, for people, AI agents and scripts. Free to use; not open source.",
5
+ "license": "SEE LICENSE IN LICENSE",
6
+ "os": [
7
+ "darwin"
8
+ ],
9
+ "cpu": [
10
+ "arm64"
11
+ ],
12
+ "bin": {
13
+ "viwa": "bin/viwa.js"
14
+ },
15
+ "files": [
16
+ "bin",
17
+ "vendor",
18
+ "README.md",
19
+ "LICENSE"
20
+ ],
21
+ "engines": {
22
+ "node": ">=18"
23
+ },
24
+ "keywords": [
25
+ "whatsapp",
26
+ "macos",
27
+ "cli"
28
+ ]
6
29
  }
package/vendor/viwa ADDED
Binary file