@wirecat/whatsapp-cli 0.0.0-stage → 0.1.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 +204 -0
- package/README.md +282 -2
- package/dist/adapter/adapter.d.ts +9 -0
- package/dist/adapter/adapter.d.ts.map +1 -0
- package/dist/adapter/adapter.js +326 -0
- package/dist/adapter/adapter.js.map +1 -0
- package/dist/adapter/checks.d.ts +7 -0
- package/dist/adapter/checks.d.ts.map +1 -0
- package/dist/adapter/checks.js +3 -0
- package/dist/adapter/checks.js.map +1 -0
- package/dist/adapter/errors.d.ts +18 -0
- package/dist/adapter/errors.d.ts.map +1 -0
- package/dist/adapter/errors.js +40 -0
- package/dist/adapter/errors.js.map +1 -0
- package/dist/adapter/format-markdown.d.ts +8 -0
- package/dist/adapter/format-markdown.d.ts.map +1 -0
- package/dist/adapter/format-markdown.js +80 -0
- package/dist/adapter/format-markdown.js.map +1 -0
- package/dist/adapter/groups.d.ts +21 -0
- package/dist/adapter/groups.d.ts.map +1 -0
- package/dist/adapter/groups.js +210 -0
- package/dist/adapter/groups.js.map +1 -0
- package/dist/adapter/map.d.ts +9 -0
- package/dist/adapter/map.d.ts.map +1 -0
- package/dist/adapter/map.js +72 -0
- package/dist/adapter/map.js.map +1 -0
- package/dist/adapter/polls.d.ts +21 -0
- package/dist/adapter/polls.d.ts.map +1 -0
- package/dist/adapter/polls.js +103 -0
- package/dist/adapter/polls.js.map +1 -0
- package/dist/app.d.ts +6 -0
- package/dist/app.d.ts.map +1 -0
- package/dist/app.js +16 -0
- package/dist/app.js.map +1 -0
- package/dist/bin/wa.d.ts +3 -0
- package/dist/bin/wa.d.ts.map +1 -0
- package/dist/bin/wa.js +27 -0
- package/dist/bin/wa.js.map +1 -0
- package/dist/commands/answer.d.ts +7 -0
- package/dist/commands/answer.d.ts.map +1 -0
- package/dist/commands/answer.js +11 -0
- package/dist/commands/answer.js.map +1 -0
- package/dist/commands/session.d.ts +37 -0
- package/dist/commands/session.d.ts.map +1 -0
- package/dist/commands/session.js +202 -0
- package/dist/commands/session.js.map +1 -0
- package/dist/commands/setup.d.ts +3 -0
- package/dist/commands/setup.d.ts.map +1 -0
- package/dist/commands/setup.js +192 -0
- package/dist/commands/setup.js.map +1 -0
- package/dist/commands/update.d.ts +2 -0
- package/dist/commands/update.d.ts.map +1 -0
- package/dist/commands/update.js +36 -0
- package/dist/commands/update.js.map +1 -0
- package/dist/diagnose.d.ts +77 -0
- package/dist/diagnose.d.ts.map +1 -0
- package/dist/diagnose.js +84 -0
- package/dist/diagnose.js.map +1 -0
- package/dist/engine/contract.d.ts +617 -0
- package/dist/engine/contract.d.ts.map +1 -0
- package/dist/engine/contract.js +186 -0
- package/dist/engine/contract.js.map +1 -0
- package/dist/engine/events.d.ts +9 -0
- package/dist/engine/events.d.ts.map +1 -0
- package/dist/engine/events.js +23 -0
- package/dist/engine/events.js.map +1 -0
- package/dist/engine/go-engine.d.ts +23 -0
- package/dist/engine/go-engine.d.ts.map +1 -0
- package/dist/engine/go-engine.js +238 -0
- package/dist/engine/go-engine.js.map +1 -0
- package/dist/engine/groups.d.ts +159 -0
- package/dist/engine/groups.d.ts.map +1 -0
- package/dist/engine/groups.js +64 -0
- package/dist/engine/groups.js.map +1 -0
- package/dist/engine-binary.d.ts +5 -0
- package/dist/engine-binary.d.ts.map +1 -0
- package/dist/engine-binary.js +18 -0
- package/dist/engine-binary.js.map +1 -0
- package/dist/install/postinstall.d.ts +8 -0
- package/dist/install/postinstall.d.ts.map +1 -0
- package/dist/install/postinstall.js +62 -0
- package/dist/install/postinstall.js.map +1 -0
- package/dist/messenger.d.ts +64 -0
- package/dist/messenger.d.ts.map +1 -0
- package/dist/messenger.js +171 -0
- package/dist/messenger.js.map +1 -0
- package/dist/paths.d.ts +5 -0
- package/dist/paths.d.ts.map +1 -0
- package/dist/paths.js +7 -0
- package/dist/paths.js.map +1 -0
- package/dist/program.d.ts +8 -0
- package/dist/program.d.ts.map +1 -0
- package/dist/program.js +114 -0
- package/dist/program.js.map +1 -0
- package/dist/reasons.d.ts +4 -0
- package/dist/reasons.d.ts.map +1 -0
- package/dist/reasons.js +13 -0
- package/dist/reasons.js.map +1 -0
- package/dist/update.d.ts +8 -0
- package/dist/update.d.ts.map +1 -0
- package/dist/update.js +26 -0
- package/dist/update.js.map +1 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +2 -0
- package/dist/version.js.map +1 -0
- package/install/postinstall.mjs +3 -0
- package/install/windows.ps1 +161 -0
- package/package.json +89 -4
- package/skills/whatsapp-cli/SKILL.md +290 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
Copyright (c) 2026 Viacheslav Ptsarev
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
Apache License
|
|
5
|
+
Version 2.0, January 2004
|
|
6
|
+
http://www.apache.org/licenses/
|
|
7
|
+
|
|
8
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
9
|
+
|
|
10
|
+
1. Definitions.
|
|
11
|
+
|
|
12
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
13
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
14
|
+
|
|
15
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
16
|
+
the copyright owner that is granting the License.
|
|
17
|
+
|
|
18
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
19
|
+
other entities that control, are controlled by, or are under common
|
|
20
|
+
control with that entity. For the purposes of this definition,
|
|
21
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
22
|
+
direction or management of such entity, whether by contract or
|
|
23
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
24
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
25
|
+
|
|
26
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
27
|
+
exercising permissions granted by this License.
|
|
28
|
+
|
|
29
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
30
|
+
including but not limited to software source code, documentation
|
|
31
|
+
source, and configuration files.
|
|
32
|
+
|
|
33
|
+
"Object" form shall mean any form resulting from mechanical
|
|
34
|
+
transformation or translation of a Source form, including but
|
|
35
|
+
not limited to compiled object code, generated documentation,
|
|
36
|
+
and conversions to other media types.
|
|
37
|
+
|
|
38
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
39
|
+
Object form, made available under the License, as indicated by a
|
|
40
|
+
copyright notice that is included in or attached to the work
|
|
41
|
+
(an example is provided in the Appendix below).
|
|
42
|
+
|
|
43
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
44
|
+
form, that is based on (or derived from) the Work and for which the
|
|
45
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
46
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
47
|
+
of this License, Derivative Works shall not include works that remain
|
|
48
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
49
|
+
the Work and Derivative Works thereof.
|
|
50
|
+
|
|
51
|
+
"Contribution" shall mean any work of authorship, including
|
|
52
|
+
the original version of the Work and any modifications or additions
|
|
53
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
54
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
55
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
56
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
57
|
+
means any form of electronic, verbal, or written communication sent
|
|
58
|
+
to the Licensor or its representatives, including but not limited to
|
|
59
|
+
communication on electronic mailing lists, source code control systems,
|
|
60
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
61
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
62
|
+
excluding communication that is conspicuously marked or otherwise
|
|
63
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
64
|
+
|
|
65
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
66
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
67
|
+
subsequently incorporated within the Work.
|
|
68
|
+
|
|
69
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
70
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
71
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
72
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
73
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
74
|
+
Work and such Derivative Works in Source or Object form.
|
|
75
|
+
|
|
76
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
77
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
78
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
79
|
+
(except as stated in this section) patent license to make, have made,
|
|
80
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
81
|
+
where such license applies only to those patent claims licensable
|
|
82
|
+
by such Contributor that are necessarily infringed by their
|
|
83
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
84
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
85
|
+
institute patent litigation against any entity (including a
|
|
86
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
87
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
88
|
+
or contributory patent infringement, then any patent licenses
|
|
89
|
+
granted to You under this License for that Work shall terminate
|
|
90
|
+
as of the date such litigation is filed.
|
|
91
|
+
|
|
92
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
93
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
94
|
+
modifications, and in Source or Object form, provided that You
|
|
95
|
+
meet the following conditions:
|
|
96
|
+
|
|
97
|
+
(a) You must give any other recipients of the Work or
|
|
98
|
+
Derivative Works a copy of this License; and
|
|
99
|
+
|
|
100
|
+
(b) You must cause any modified files to carry prominent notices
|
|
101
|
+
stating that You changed the files; and
|
|
102
|
+
|
|
103
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
104
|
+
that You distribute, all copyright, patent, trademark, and
|
|
105
|
+
attribution notices from the Source form of the Work,
|
|
106
|
+
excluding those notices that do not pertain to any part of
|
|
107
|
+
the Derivative Works; and
|
|
108
|
+
|
|
109
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
110
|
+
distribution, then any Derivative Works that You distribute must
|
|
111
|
+
include a readable copy of the attribution notices contained
|
|
112
|
+
within such NOTICE file, excluding those notices that do not
|
|
113
|
+
pertain to any part of the Derivative Works, in at least one
|
|
114
|
+
of the following places: within a NOTICE text file distributed
|
|
115
|
+
as part of the Derivative Works; within the Source form or
|
|
116
|
+
documentation, if provided along with the Derivative Works; or,
|
|
117
|
+
within a display generated by the Derivative Works, if and
|
|
118
|
+
wherever such third-party notices normally appear. The contents
|
|
119
|
+
of the NOTICE file are for informational purposes only and
|
|
120
|
+
do not modify the License. You may add Your own attribution
|
|
121
|
+
notices within Derivative Works that You distribute, alongside
|
|
122
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
123
|
+
that such additional attribution notices cannot be construed
|
|
124
|
+
as modifying the License.
|
|
125
|
+
|
|
126
|
+
You may add Your own copyright statement to Your modifications and
|
|
127
|
+
may provide additional or different license terms and conditions
|
|
128
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
129
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
130
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
131
|
+
the conditions stated in this License.
|
|
132
|
+
|
|
133
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
134
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
135
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
136
|
+
this License, without any additional terms or conditions.
|
|
137
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
138
|
+
the terms of any separate license agreement you may have executed
|
|
139
|
+
with Licensor regarding such Contributions.
|
|
140
|
+
|
|
141
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
142
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
143
|
+
except as required for reasonable and customary use in describing the
|
|
144
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
145
|
+
|
|
146
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
147
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
148
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
149
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
150
|
+
implied, including, without limitation, any warranties or conditions
|
|
151
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
152
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
153
|
+
appropriateness of using or redistributing the Work and assume any
|
|
154
|
+
risks associated with Your exercise of permissions under this License.
|
|
155
|
+
|
|
156
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
157
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
158
|
+
unless required by applicable law (such as deliberate and grossly
|
|
159
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
160
|
+
liable to You for damages, including any direct, indirect, special,
|
|
161
|
+
incidental, or consequential damages of any character arising as a
|
|
162
|
+
result of this License or out of the use or inability to use the
|
|
163
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
164
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
165
|
+
other commercial damages or losses), even if such Contributor
|
|
166
|
+
has been advised of the possibility of such damages.
|
|
167
|
+
|
|
168
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
169
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
170
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
171
|
+
or other liability obligations and/or rights consistent with this
|
|
172
|
+
License. However, in accepting such obligations, You may act only
|
|
173
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
174
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
175
|
+
defend, and hold each Contributor harmless for any liability
|
|
176
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
177
|
+
of your accepting any such warranty or additional liability.
|
|
178
|
+
|
|
179
|
+
END OF TERMS AND CONDITIONS
|
|
180
|
+
|
|
181
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
182
|
+
|
|
183
|
+
To apply the Apache License to your work, attach the following
|
|
184
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
185
|
+
replaced with your own identifying information. (Don't include
|
|
186
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
187
|
+
comment syntax for the file format. We also recommend that a
|
|
188
|
+
file or class name and description of purpose be included on the
|
|
189
|
+
same "printed page" as the copyright notice for easier
|
|
190
|
+
identification within third-party archives.
|
|
191
|
+
|
|
192
|
+
Copyright [yyyy] [name of copyright owner]
|
|
193
|
+
|
|
194
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
195
|
+
you may not use this file except in compliance with the License.
|
|
196
|
+
You may obtain a copy of the License at
|
|
197
|
+
|
|
198
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
199
|
+
|
|
200
|
+
Unless required by applicable law or agreed to in writing, software
|
|
201
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
202
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
203
|
+
See the License for the specific language governing permissions and
|
|
204
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,283 @@
|
|
|
1
|
-
#
|
|
1
|
+
# wa — WhatsApp CLI for AI agents
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Your personal WhatsApp in the terminal, searchable on your computer, and ready for Claude Code, Codex, Cursor or any
|
|
4
|
+
agent — within limits you set.
|
|
5
|
+
|
|
6
|
+
> **Early.** `wa` links, reads into its local store, sends text and files, edits, deletes for everyone, reacts and
|
|
7
|
+
> runs groups. What comes next is on the [roadmap](docs/roadmap.md).
|
|
8
|
+
|
|
9
|
+
An example conversation (invented people, illustrative output):
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
You: Use wa CLI. Who is waiting for my answer since yesterday?
|
|
13
|
+
Agent: (runs wa personal review 'date>1d' --unanswered: 3 chats)
|
|
14
|
+
· Alice Example asked about Saturday's table, 18:40 yesterday
|
|
15
|
+
· "Book club" — Bob Sample asked who brings the next book
|
|
16
|
+
You: Tell Alice: yes, 8 pm.
|
|
17
|
+
Agent: Draft to Alice Example: "Yes, 8 pm." Send it?
|
|
18
|
+
You: Yes.
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npm install -g @wirecat/whatsapp-cli
|
|
25
|
+
wa personal setup --agent claude # also codex, cursor, gemini, all or none
|
|
26
|
+
wa personal server install # keep receiving in the background
|
|
27
|
+
wa personal inbox # other people's unread messages; nothing is marked read
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Allow about five minutes. `wa personal setup` links `wa` to your account as a device — you scan a QR code in
|
|
31
|
+
WhatsApp → Settings → Linked devices — keeps the history your phone sends right after linking, checks your first
|
|
32
|
+
chats and installs the agent skill.
|
|
33
|
+
|
|
34
|
+
It needs **Node 22.16+ or 24+** on macOS, Linux or Windows. npm also installs the engine, the small program that
|
|
35
|
+
speaks WhatsApp's protocol, as a separate package for your system.
|
|
36
|
+
|
|
37
|
+
More: [installation guide](docs/installation.md) · [linking](docs/sessions.md)
|
|
38
|
+
|
|
39
|
+
## What can you do?
|
|
40
|
+
|
|
41
|
+
**Catch up.** *"Use wa CLI. What came in since this morning, and who is waiting for my answer?"*
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
wa personal inbox
|
|
45
|
+
wa personal review 'date>1d' --unanswered
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Find anything.** *"Use wa CLI. When did we agree on the venue with Alice?"* — an answer with the date and the
|
|
49
|
+
message itself.
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
wa personal search all "venue" # messages and notes kept on this computer
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Keep your promises.** *"Use wa CLI. What did I promise, and what am I still waiting on?"*
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
wa personal review --new # what changed since the last review --new
|
|
59
|
+
wa personal tasks list state:open
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Answer, when you say so.**
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
wa personal messages send "Book club" "Call at 3?" --reply-to 3EB0A1B2C3D4E5F6A7B8
|
|
66
|
+
wa personal messages edit "Book club" 3EB0A1B2C3D4E5F6A7B8 "Call at 4?" # your own, within 20 minutes
|
|
67
|
+
wa personal reactions add "Book club" 3EB0A1B2C3D4E5F6A7B8 👍
|
|
68
|
+
wa personal messages delete "Book club" 3EB0A1B2C3D4E5F6A7B8 --for-everyone
|
|
69
|
+
wa personal chats mark-read "Book club" # the other side sees it
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
More: [recipes, with a schedule for each](docs/recipes.md) · [using wa](docs/usage.md)
|
|
73
|
+
|
|
74
|
+
## Built for AI agents
|
|
75
|
+
|
|
76
|
+
- **Agents with a terminal** (Claude Code, Codex, Gemini CLI) run `wa` commands themselves. The bundled
|
|
77
|
+
[skill](skills/whatsapp-cli/SKILL.md) tells them how: `wa personal setup --agent …` or `wa skill install` puts it in
|
|
78
|
+
place, and `wa skill show` prints it before linking. An agent links with `--qr-file` and shows you the picture; it
|
|
79
|
+
never asks for your phone number or a code.
|
|
80
|
+
- **Apps without a terminal** (Claude Desktop, Cursor and other MCP clients) connect to `wa personal mcp`.
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
wa personal mcp setup claude-code # or: wa personal mcp setup codex
|
|
84
|
+
wa personal mcp config # the entry for Claude Desktop, Cursor and others
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
More: [the MCP server](docs/mcp.md) · [from the browser](docs/remote.md)
|
|
88
|
+
|
|
89
|
+
## How it differs from tg and max
|
|
90
|
+
|
|
91
|
+
`wa` is part of the [WireCat](https://wirecat.dev) family, beside [tg](https://github.com/WireCatLabs/tg-cli) for
|
|
92
|
+
Telegram and [max](https://github.com/WireCatLabs/max-cli) for MAX. All three share their commands, their store and
|
|
93
|
+
their agent tools, so what you learn in one works in the others. WhatsApp is different in three ways:
|
|
94
|
+
|
|
95
|
+
- **History comes from your phone.** WhatsApp's servers keep no history to ask for. Your phone sends your recent
|
|
96
|
+
chats once, when `wa` links, and `wa serve` keeps receiving new ones. Older messages of one chat can be asked of the
|
|
97
|
+
phone, 50 at a time, while WhatsApp is open on it (`wa personal messages sync`). Every read answers from the local
|
|
98
|
+
store and never connects.
|
|
99
|
+
- **One connection per device.** WhatsApp allows one. While `wa serve` runs, other commands for the same profile,
|
|
100
|
+
a send included, run through its connection. On Windows they are refused until `serve` stops, for now.
|
|
101
|
+
- **Unofficial.** WhatsApp's terms forbid unofficial clients, and WhatsApp may ban an account that uses one. `wa`
|
|
102
|
+
never sends in bulk or to strangers, never sends "online" or "typing", and marks nothing read unless you ask.
|
|
103
|
+
|
|
104
|
+
## The local store and search
|
|
105
|
+
|
|
106
|
+
Everything `wa` receives is kept in a local store on your computer, shared with tg and max. Search runs over it;
|
|
107
|
+
nothing leaves your computer.
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
wa personal search messages 'contract chat:"Project Alpha"'
|
|
111
|
+
wa personal store status # how much of each chat is kept
|
|
112
|
+
wa personal store export "Project Alpha" --format markdown --output alpha.md
|
|
113
|
+
wa personal messages evidence "Project Alpha" --json # bounded evidence for a chat brief
|
|
114
|
+
wa personal store backup ~/wa-backup.db # a copy, safe while the store is in use
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
More: [search](docs/search.md) · [the local store](docs/archive.md) · [query language](docs/query-language.md)
|
|
118
|
+
|
|
119
|
+
## Groups you run
|
|
120
|
+
|
|
121
|
+
```sh
|
|
122
|
+
wa personal review chat:Hiking --unanswered # questions nobody answered
|
|
123
|
+
wa personal review 'chat:Hiking date>7d' # the week: decisions, promises, open questions
|
|
124
|
+
wa personal stats chats show Hiking --offline # the group's activity, from the local store
|
|
125
|
+
wa personal chats create "Hiking 2027" 100000000000002@lid # a new group, with people you know
|
|
126
|
+
wa personal chats members add 120363000000000001@g.us 100000000000002@lid
|
|
127
|
+
wa personal chats update 120363000000000001@g.us --join-approval on
|
|
128
|
+
wa personal chats requests list 120363000000000001@g.us
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Renaming a group, members and admins, the invite link, join requests and who may send or add people are commands
|
|
132
|
+
too. The members see each change, so each passes the profile's permissions and hourly limit. `wa` adds only people in
|
|
133
|
+
your address book or that you have written to: WhatsApp bans accounts that add strangers.
|
|
134
|
+
|
|
135
|
+
More: [groups](docs/groups.md)
|
|
136
|
+
|
|
137
|
+
## Output for scripts and agents
|
|
138
|
+
|
|
139
|
+
With `--json` a command prints only data, as one JSON value. `--jsonl` prints one object per line. Every list has
|
|
140
|
+
one shape:
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
An error goes to stderr as one line, with stdout empty, and the command exits with a fixed code: `4` link the
|
|
147
|
+
profile, `5` the profile may not do this, `6` chat or message not found, `8` a limit, `12` another command holds the
|
|
148
|
+
device, `14` unknown whether a message went. `wa commands --json` is the whole command tree.
|
|
149
|
+
|
|
150
|
+
More: [CLI contract](docs/cli-contract.md) · [every command and exit code](docs/commands.md)
|
|
151
|
+
|
|
152
|
+
## Log in and profiles
|
|
153
|
+
|
|
154
|
+
`wa` links to your account as a device, the way WhatsApp Web does. There is no password and no app to register: you
|
|
155
|
+
link once, from the phone, and the device keys go to one file only your user can read.
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
wa personal session start # a QR code: WhatsApp → Settings → Linked devices → Link a device
|
|
159
|
+
wa personal session start phone # or your number, then a pairing code you type on the phone
|
|
160
|
+
wa personal session start --qr-file login.png # the QR code as a picture, for an agent to show you
|
|
161
|
+
wa personal account show # who this profile is linked as
|
|
162
|
+
wa account list # every profile here, and who each is linked as
|
|
163
|
+
wa personal session end # unlink, and delete the device keys here
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Several accounts are several profiles, and the profile is **the first word**, not an option:
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
wa personal chats list # profile "personal"
|
|
170
|
+
wa work chats list # profile "work"
|
|
171
|
+
export WA_PROFILE=work # or for the whole shell session
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`wa` never picks a profile for you, not even the only one: a command that uses an account and has no profile named
|
|
175
|
+
stops and lists the profiles on this computer. Name one or set `WA_PROFILE`. Each profile is a linked device of its
|
|
176
|
+
own, with its own one connection.
|
|
177
|
+
|
|
178
|
+
More: [linking, devices and profiles](docs/sessions.md) · [profiles](docs/profiles.md)
|
|
179
|
+
|
|
180
|
+
## Settings and permissions
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
wa personal config set permissions.messages readonly # no change to messages from this profile
|
|
184
|
+
wa personal config set permissions.messages.send ask # a question in the terminal before each send
|
|
185
|
+
wa personal config set sends_per_hour 10 # at most 10 sends an hour (30 by default)
|
|
186
|
+
wa personal recipients add "Book club" # the first add turns the recipient list on
|
|
187
|
+
wa personal sends list # every attempt: sent, refused, failed or not known
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
More: [permissions](docs/permissions.md) · [profiles](docs/profiles.md) · [configuration](docs/configuration.md) ·
|
|
191
|
+
[limits](docs/limits.md)
|
|
192
|
+
|
|
193
|
+
## Limits
|
|
194
|
+
|
|
195
|
+
Each profile has one request pace, shared by every command, `serve` and the MCP server at once, so a script stays far
|
|
196
|
+
from what WhatsApp bans. A profile sends at most 30 messages an hour by default. One command at a time may connect a
|
|
197
|
+
profile; another one is refused with exit code `12` and names the holder, unless `serve` runs and carries it on its
|
|
198
|
+
connection. There is nothing to download in bulk: reads answer from the local store.
|
|
199
|
+
|
|
200
|
+
More: [limits and waits](docs/limits.md)
|
|
201
|
+
|
|
202
|
+
## Security
|
|
203
|
+
|
|
204
|
+
- The device keys are one file readable only by your user. Whoever copies it can read and send as you until you
|
|
205
|
+
remove the device on your phone. No command takes a phone number or a pairing code as an argument.
|
|
206
|
+
- The local store holds the full text of what was received, unencrypted and readable only by your user.
|
|
207
|
+
- Every send, from a command or over MCP, passes the profile's limits and is written to a journal — without its
|
|
208
|
+
text.
|
|
209
|
+
- Nothing `wa` sends to WhatsApp names this tool: it links as a desktop browser.
|
|
210
|
+
|
|
211
|
+
To report a vulnerability: [SECURITY.md](SECURITY.md). More: [security](docs/security.md)
|
|
212
|
+
|
|
213
|
+
## When something goes wrong
|
|
214
|
+
|
|
215
|
+
```sh
|
|
216
|
+
wa personal doctor # the engine, the device keys' file modes and who holds the connection
|
|
217
|
+
wa personal doctor --online # also connect once and read the account
|
|
218
|
+
wa personal runs list # recorded runs
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
More: [troubleshooting by symptom](docs/troubleshooting.md) · [diagnostics](docs/diagnostics.md)
|
|
222
|
+
|
|
223
|
+
## Technical docs
|
|
224
|
+
|
|
225
|
+
Every page is in [`docs/`](docs/README.md):
|
|
226
|
+
|
|
227
|
+
| Page | Answers |
|
|
228
|
+
|---|---|
|
|
229
|
+
| [index](docs/index.md) | The docs site's start page: what `wa` is, the first minute, where to go next |
|
|
230
|
+
| [installation](docs/installation.md) | How do I install it, and what does it need? |
|
|
231
|
+
| [usage](docs/usage.md) | How do I link, read, send and change a message — in that order? |
|
|
232
|
+
| [sessions](docs/sessions.md) | How does linking work: QR or pairing code, one connection per device, profiles, unlinking? |
|
|
233
|
+
| [archive](docs/archive.md) | What does the local store keep, how is it filled, and how do I export and back it up? |
|
|
234
|
+
| [search](docs/search.md) | How do I find a message by its words, sender, chat, date, file or label, save a search and count? |
|
|
235
|
+
| [attachments](docs/attachments.md) | Sending, saving and forwarding files; their text, and voice notes as text |
|
|
236
|
+
| [query-language](docs/query-language.md) | Every search field, operator, preset, limit and the JSON answer |
|
|
237
|
+
| [groups](docs/groups.md) | How do I keep up with a group, and run one? |
|
|
238
|
+
| [people](docs/people.md) | One person: what the store holds about them, your own names and notes |
|
|
239
|
+
| [mcp](docs/mcp.md) | How do I connect Claude Desktop, Cursor or another client without a terminal? |
|
|
240
|
+
| [remote](docs/remote.md) | ChatGPT or Claude in the browser, through a login and a tunnel |
|
|
241
|
+
| [recipes](docs/recipes.md) | What can an agent do for me every day, and how do I run it on a schedule? |
|
|
242
|
+
| [commands](docs/commands.md) | Every command, option and exit code — **generated** from the program |
|
|
243
|
+
| [configuration](docs/configuration.md) | How do I configure common behaviour? |
|
|
244
|
+
| [permissions](docs/permissions.md) | What a profile may read, what asks first, and what may go ahead |
|
|
245
|
+
| [profiles](docs/profiles.md) | Several accounts on one computer, and how a command picks one |
|
|
246
|
+
| [configuration-reference](docs/configuration-reference.md) | Every key, default, scope and variable |
|
|
247
|
+
| [cli-contract](docs/cli-contract.md) | Invocation, output, errors, headless runs, bounds and previews |
|
|
248
|
+
| [limits](docs/limits.md) | Limits, waits and the one connection per device |
|
|
249
|
+
| [diagnostics](docs/diagnostics.md) | What did a command do, and what is never recorded? |
|
|
250
|
+
| [troubleshooting](docs/troubleshooting.md) | Something does not work: what the screen says, and what to do |
|
|
251
|
+
| [security](docs/security.md) | What does `wa` keep on my computer, and what can go wrong? |
|
|
252
|
+
| [roadmap](docs/roadmap.md) | What is coming next? |
|
|
253
|
+
|
|
254
|
+
What each version changed: [CHANGELOG.md](CHANGELOG.md).
|
|
255
|
+
|
|
256
|
+
## Development
|
|
257
|
+
|
|
258
|
+
```sh
|
|
259
|
+
pnpm install
|
|
260
|
+
pnpm lint && pnpm typecheck && pnpm test
|
|
261
|
+
pnpm engine:build && pnpm engine:test # the Go engine; needs Go
|
|
262
|
+
pnpm generate # rewrites docs/commands.md from the command tree
|
|
263
|
+
bin/wa personal chats list # everything under .wa/ in this checkout, never the real profile
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Everything that is not specific to WhatsApp — the commands, the store, the send guard, the MCP server — lives in
|
|
267
|
+
[cli-core](https://github.com/WireCatLabs/cli-core), shared with tg and max.
|
|
268
|
+
|
|
269
|
+
More: [ARCHITECTURE](docs/dev/ARCHITECTURE.md) · [TESTING](docs/dev/TESTING.md)
|
|
270
|
+
|
|
271
|
+
## Contributing
|
|
272
|
+
|
|
273
|
+
Pull requests, bug reports and ideas are welcome in [issues](https://github.com/WireCatLabs/whatsapp-cli/issues).
|
|
274
|
+
|
|
275
|
+
Custom automation with WhatsApp, other messengers and AI agents: [info@neirox.ai](mailto:info@neirox.ai).
|
|
276
|
+
|
|
277
|
+
## License
|
|
278
|
+
|
|
279
|
+
The CLI is [Apache-2.0](LICENSE). The engine is not: the Go program in [`engine/`](engine/) and the
|
|
280
|
+
`@wirecat/whatsapp-engine-*` packages that carry it are [GPL-3.0-only](engine/LICENSE), because the engine links
|
|
281
|
+
go.mau.fi/libsignal, which is under the GNU General Public License 3.0, through whatsmeow. The two are separate
|
|
282
|
+
programs: `wa` starts the engine as a child process and talks to it only over stdin and stdout. Each engine package
|
|
283
|
+
says where its source is and lists every Go module it links in `THIRD_PARTY_NOTICES`.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { type MarkdownFormatting } from "@wirecat/cli-core";
|
|
2
|
+
import type { LiveUpdates, MessageEditing, MessageMedia, MessageReactions, MessengerCore, PushedHistory, ReadState, ServerReads, StoredMessages } from "@wirecat/cli-core/cli";
|
|
3
|
+
import { type WhatsAppEngine } from "../engine/contract.js";
|
|
4
|
+
import { type Words } from "./checks.js";
|
|
5
|
+
import { type GroupAdapter } from "./groups.js";
|
|
6
|
+
import { type PollAdapter } from "./polls.js";
|
|
7
|
+
export type WhatsAppAdapter = MessengerCore & LiveUpdates & PushedHistory & Pick<MessageEditing, "edit" | "delete" | "forward"> & Pick<MessageMedia, "download"> & MessageReactions & ReadState & Pick<ServerReads, "history"> & MarkdownFormatting & PollAdapter & GroupAdapter;
|
|
8
|
+
export declare const whatsAppAdapter: (engine: WhatsAppEngine, stored?: StoredMessages, words?: Words) => WhatsAppAdapter;
|
|
9
|
+
//# sourceMappingURL=adapter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/adapter.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,kBAAkB,EAKxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,SAAS,EAGT,WAAW,EACX,cAAc,EACf,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,aAAa,CAAA;AAGnD,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,aAAa,CAAA;AAE7D,OAAO,EAAE,KAAK,WAAW,EAA2C,MAAM,YAAY,CAAA;AAEtF,MAAM,MAAM,eAAe,GAAG,aAAa,GACzC,WAAW,GACX,aAAa,GACb,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC,GACnD,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAC9B,gBAAgB,GAChB,SAAS,GACT,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAC5B,kBAAkB,GAClB,WAAW,GACX,YAAY,CAAA;AAsId,eAAO,MAAM,eAAe,WAClB,cAAc,WACd,cAAc,UACf,KAAK,KACX,eA+PF,CAAA"}
|