cli-whatsapp 0.1.0

package/COMMANDS.md

@@ -0,0 +1,297 @@
+# WhatsApp CLI — Command Guide
+
+A fast, terminal-first WhatsApp client with a WhatsApp-green interface. Read,
+search, send, and receive messages without a browser. Reading is instant and
+offline (served from a local cache); only login, sync, send, watch, download,
+and group actions use the network.
+
+> **Tip:** run `wa` with no arguments for the interactive app (banner, live
+> chat, slash commands) — see [§10](#10-interactive-mode). Everything is also
+> available as one-shot commands below.
+
+---
+
+## 1. Getting started
+
+### Requirements
+- **Node.js ≥ 22.5** (tested on Node 25). No build step — TypeScript runs natively.
+
+### Install
+```bash
+cd whatsapp-cli
+npm install
+npm link          # optional: makes the `wa` command available everywhere
+```
+
+### How you run commands
+| If you ran… | Use this form |
+| --- | --- |
+| `npm link` | `wa <command>` |
+| nothing | `node bin/wa.js <command>` |
+
+> The examples below use `wa`. If you didn't `npm link`, just replace `wa` with `node bin/wa.js`.
+
+### First-time login (one time)
+```bash
+wa login          # a QR code appears in your terminal
+```
+On your phone: **WhatsApp → Settings → Linked Devices → Link a Device**, then scan the QR.
+Your session is saved locally, so you won't scan again unless you log out.
+
+```bash
+wa sync           # pull your recent chats & messages into the local cache
+wa chats          # you're ready — list your conversations
+```
+
+---
+
+## 2. Account
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa login` | Link with a short pairing code (prompts for your number) | `wa login` |
+| `wa login --phone <number>` | Same, but skip the prompt | `wa login --phone 9371432334` |
+| `wa login qr` | Link by scanning a QR code instead | `wa login qr` |
+| `wa logout` | Unlink this device and wipe the local session | `wa logout` |
+| `wa status` | Show login state and cache size (offline) | `wa status` |
+
+**Default login (pairing code):** `wa login` asks for your WhatsApp number and
+shows an 8-character code — no QR needed. A bare 10-digit number gets your
+country code added automatically (`+91` by default), or type the full
+international number. On your phone: **Linked Devices → Link a Device → "Link
+with phone number instead"**, then enter the code.
+
+**QR login:** prefer scanning? `wa login qr` shows a QR; scan it and the window
+confirms and closes on its own. (Tip: shrink your terminal font — Cmd/Ctrl **−**
+— to make the QR smaller; it stays scannable.)
+
+If a code or QR expires before you link, you'll get a clear message telling you
+to re-run the command for a fresh one.
+
+---
+
+## 3. Reading (instant, works offline)
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa chats` | List conversations, most recent first | `wa chats` |
+| `wa chats -a` | Include archived chats | `wa chats -a` |
+| `wa chats -n <N>` | Limit how many chats are shown | `wa chats -n 20` |
+| `wa recent` | Most recently active chats (ignores pins) | `wa recent -n 10` |
+| `wa open <chat>` | Show latest messages in a chat | `wa open Alice` |
+| `wa open <chat> -n <N>` | Show N messages | `wa open Alice -n 50` |
+| `wa history <chat>` | Extended history (defaults to 200) | `wa history Alice` |
+| `wa search <text>` | Search all cached messages | `wa search invoice` |
+| `wa contacts` | List saved contacts | `wa contacts` |
+
+> `<chat>` can be a **name** (fuzzy, e.g. `ali` → Alice), a **phone number**
+> (`916302810814`), or a full **jid**. Message ids like `#123` shown in `open`
+> are used by `reply` and `download`.
+
+---
+
+## 4. Sending
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa send <chat> <message>` | Send a text message | `wa send Alice "on my way"` |
+| `wa send <chat> [caption] --file <path>` | Send media (type auto-detected) | `wa send Alice "look" --file pic.jpg` |
+| `wa reply <id> <message>` | Reply to a cached message, quoting it | `wa reply 123 "thanks!"` |
+
+**Media types** (detected from the file extension):
+
+| Extension | Sent as |
+| --- | --- |
+| `.jpg .jpeg .png .gif` | image (with optional caption) |
+| `.mp4 .mov .webm` | video (with optional caption) |
+| `.mp3 .ogg .m4a .opus .wav` | audio |
+| `.webp` | sticker (image if a caption is given) |
+| anything else (`.pdf`, `.zip`, …) | document |
+
+```bash
+wa send Bob --file ~/Downloads/invoice.pdf        # document, no caption
+wa send Family "trip clip 🎥" --file clip.mp4      # video with caption
+```
+
+---
+
+## 5. Sync & live
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa sync` | Pull recent chats & messages (~12s) | `wa sync` |
+| `wa sync -s <seconds>` | Sync for longer (3–120s) | `wa sync -s 30` |
+| `wa watch` | Stream incoming messages live (Ctrl+C to stop) | `wa watch` |
+
+---
+
+## 6. Media
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa media` | List all cached media | `wa media` |
+| `wa media <type>` | Filter: `photos`, `videos`, `audio`, `documents`, `stickers`, `all` | `wa media photos` |
+| `wa media -n <N>` | Limit results | `wa media videos -n 10` |
+| `wa download <id>` | Download & decrypt a media message by `#id` | `wa download 51` |
+| `wa download <id> -o <file>` | Save to a specific path | `wa download 51 -o ~/Desktop/pic.jpg` |
+
+> Downloads are saved under `media/` by default.
+
+---
+
+## 7. Organize (local)
+
+These change how chats appear in **your** CLI listing (they don't sync back to WhatsApp).
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa pin <chat>` | Pin a chat to the top | `wa pin Alice` |
+| `wa unpin <chat>` | Unpin a chat | `wa unpin Alice` |
+| `wa archive <chat>` | Hide a chat from `wa chats` | `wa archive Spam` |
+| `wa unarchive <chat>` | Unhide a chat | `wa unarchive Spam` |
+
+---
+
+## 8. Groups
+
+Manage the groups you're in. These need a connection and (for most actions)
+admin rights in the group.
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa group info <group>` | Show subject, members, admins, description | `wa group info Family` |
+| `wa group invite <group>` | Get the group's invite link | `wa group invite Family` |
+| `wa group rename <group> <subject>` | Change the group subject | `wa group rename Family "Family 2.0"` |
+| `wa group add <group> <number…>` | Add participants | `wa group add Family 919999999999` |
+| `wa group remove <group> <number…>` | Remove participants | `wa group remove Family 919999999999` |
+| `wa group promote <group> <number…>` | Make participants admin | `wa group promote Family 919999999999` |
+| `wa group demote <group> <number…>` | Remove admin | `wa group demote Family 919999999999` |
+| `wa group leave <group>` | Leave the group | `wa group leave "Old Team"` |
+| `wa group create <subject> <number…>` | Create a new group | `wa group create "Trip" 9199… 9198…` |
+
+---
+
+## 9. Export
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa export <chat>` | Export a conversation to Markdown | `wa export Alice` |
+| `wa export <chat> -f <fmt>` | Format: `md`, `txt`, or `json` | `wa export Alice -f json` |
+| `wa export <chat> -n <N>` | Limit messages exported | `wa export Alice -n 500` |
+| `wa export <chat> -o <file>` | Output file (`-` for stdout) | `wa export Alice -o chat.md` |
+
+---
+
+## 10. Utility
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `wa config` | Show current configuration | `wa config` |
+| `wa config set <key> <value>` | Edit a setting (`openLimit`, `time24h`, `notifications`, `ai.enabled`) | `wa config set notifications false` |
+| `wa doctor` | Run self-diagnostics | `wa doctor` |
+| `wa version` | Print the version | `wa version` |
+| `wa --help` | Show all commands | `wa --help` |
+| `wa <command> --help` | Help for one command | `wa send --help` |
+
+---
+
+## 11. Interactive mode (the app)
+
+Run `wa` with **no arguments** (or `wa shell` / `wa chat`) to launch the
+interactive app — a WhatsApp-green banner, a persistent prompt, tab-completion,
+and a real chat experience.
+
+```
+✆ WhatsApp CLI  interactive
+● linked   973 chats · 11948 messages
+
+●  Alice  ›  hi, running 5 min late          ← just type to send (chat is open)
+20:41 Alice: no worries!                      ← incoming messages stream in live
+🔔 Bob: are we still on?                       ← notifications from other chats
+```
+
+**How it works**
+- `/open <chat>` focuses a chat — the prompt shows its name and **plain text you
+  type is sent to it** (no command needed). `/close` leaves the chat.
+- **Attach a file with `@`:** with a chat open, press `@` to open an interactive
+  file picker — **↑/↓** to move, **type** to filter, **Enter** to pick a file
+  (or open a folder), **Backspace** to go up, **Esc** to cancel. The chosen file
+  is inserted as `@path`; send it and the rest of your line becomes the caption
+  (e.g. `look at this @photo.jpg`). Just like Claude Code's `@`.
+- **Live by default:** on launch the app goes **live** automatically (if linked)
+  — one persistent connection so sends are instant and incoming messages appear
+  in real time (with desktop notifications). The prompt dot shows status:
+  `○` offline · `◐` connecting · `●` live. Turn off auto-connect with
+  `/set autoConnect false`; use `/connect` to go live manually and `/disconnect`
+  to go offline (your cached chats stay readable either way).
+- **Slash menu:** type `/` at the start of a line to open a command menu —
+  **↑/↓** to move, **type** to filter, **Enter** to pick, **Esc** to cancel.
+- **Tab** also completes chat names. **↑/↓** recalls history. **Ctrl+C** clears
+  the line (again to exit).
+
+| Slash command | Same as |
+| --- | --- |
+| *(type text with a chat open)* | send to the current chat |
+| `@` *(with a chat open)* | open the file picker to attach (↑↓/type/Enter) |
+| `/open <chat>` · `/close` | focus / leave a chat |
+| `/connect` · `/disconnect` | go live (receive) / drop the connection |
+| `/chats [n]` · `/recent [n]` · `/contacts` | list chats / recent / contacts |
+| `/history [n]` · `/search <text>` | more history / search |
+| `/send <chat> <msg>` · `/sendfile <chat> <path> [caption]` | send text / media |
+| `/reply <id> <msg>` · `/media [type]` | reply / list media |
+| `/pin` · `/unpin` · `/archive` · `/unarchive` `<chat>` | organize |
+| `/status` · `/settings` · `/set <key> <value>` | status / settings |
+| `/clear` · `/help` · `/quit` | clear screen / help / exit |
+
+> Group management (`wa group …`) is a one-shot command, not a slash command,
+> so it never opens a second connection alongside a live interactive session.
+
+---
+
+## 12. Notifications & theme
+
+- **Desktop notifications** pop for incoming messages during `wa watch` and while
+  the interactive app is **live**. On by default; toggle with
+  `wa config set notifications false` (or `/set notifications false`).
+  Supported on macOS (`osascript`) and Linux (`notify-send`).
+- **Theme** uses WhatsApp's signature green (`#25D366`). Colors auto-disable
+  under `NO_COLOR` or when output isn't a terminal.
+
+---
+
+## 13. Tips
+
+| Want to… | Do this |
+| --- | --- |
+| See verbose connection logs | prefix with `WA_DEBUG=1`, e.g. `WA_DEBUG=1 wa sync` |
+| Disable colored output | `NO_COLOR=1 wa chats` |
+| Store data elsewhere | set `WA_HOME=/path` (holds `sessions/`, `data/`, `media/`, `config.json`) |
+
+> **Privacy:** your session lives in `sessions/` and is as sensitive as being
+> logged in. It's gitignored — never share or commit it.
+
+---
+
+## Typical session, start to finish
+
+One-shot commands:
+```bash
+wa login                       # scan QR once
+wa sync                        # pull chats & messages
+wa chats                       # browse
+wa open Alice                  # read a conversation
+wa send Alice "hello 👋"        # reply (or: wa send Alice "look" --file pic.jpg)
+wa search invoice              # find something
+wa media photos                # see received photos
+wa download 51                 # save one
+wa group info Family           # inspect a group
+wa watch                       # listen for new messages live (with notifications)
+```
+
+Or just live in the app:
+```bash
+wa                             # launch interactive mode
+wa › /connect                  # go live
+wa › /open Alice               # open a chat…
+wa › on my way 🚗               # …and just type to send
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piyush Patil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# WhatsApp CLI
+
+A lightweight, fast, terminal-first WhatsApp client with a WhatsApp-green
+interface. Read, search, send, and receive messages entirely from your terminal —
+no browser, no Electron. Includes a live interactive app, media send/download,
+basic group management, and desktop notifications.
+
+> Personal use only. Uses [Baileys](https://github.com/WhiskeySockets/Baileys)
+> to talk to WhatsApp Web. Not affiliated with WhatsApp/Meta.
+
+**📖 Full command reference: [COMMANDS.md](COMMANDS.md)**
+
+## Requirements
+
+- **Node.js ≥ 22.5** (uses the built-in `node:sqlite` and native TypeScript
+  execution — no build step). Tested on Node 25.
+- A phone with WhatsApp to link the device via QR.
+
+## Install
+
+```bash
+npm install
+npm link        # optional: puts `wa` on your PATH
+```
+
+Without `npm link`, run commands as `node bin/wa.js <command>` or `npm run wa -- <command>`.
+
+## Quick start
+
+```bash
+wa login                     # link with a pairing code (prompts for your number)
+# or: wa login qr            # link by scanning a QR instead
+wa sync                      # pull recent chats & messages into the local cache
+wa chats                     # list conversations
+wa open Alice                # read a conversation (fuzzy name match)
+wa send Alice "Hi"           # send a message
+wa send Alice --file pic.jpg # send media (caption optional)
+wa search invoice            # search cached messages
+wa watch                     # stream incoming messages live (+ notifications)
+```
+
+Or launch the **interactive app** — just run `wa` with no arguments:
+
+```
+✆ WhatsApp CLI  interactive
+● linked   973 chats · 11948 messages
+
+wa › /connect          # go live
+wa › /open Alice       # open a chat…
+Alice › on my way 🚗    # …then just type to send
+```
+
+## Architecture
+
+**Local-first.** All reads (`chats`, `open`, `history`, `search`, `contacts`,
+`export`) serve from a local SQLite cache — instant and fully offline. Only
+`login`, `sync`, `send`, `reply`, `watch`, `download`, and `group` open the
+WhatsApp connection. The interactive app holds a single persistent connection so
+sends are instant and messages arrive live.
+
+```
+CLI (commander) → command → { SQLite cache  |  Baileys socket → events → SQLite }
+```
+
+- `src/cli` — command dispatcher and command implementations
+- `src/whatsapp` — Baileys client, auth, and event→DB persistence
+- `src/db` — `node:sqlite` schema and queries
+- `src/config`, `src/utils` — paths/config and formatting helpers
+
+State lives under the project directory by default (or `$WA_HOME` if set):
+`sessions/` (credentials — gitignored), `data/whatsapp.db`, `media/`, `config.json`.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `wa login` / `logout` / `status` | Link (pairing code), unlink, inspect the session |
+| `wa login qr` | Link by scanning a QR instead of a code |
+| `wa chats [-a] [-n N]` | List conversations |
+| `wa contacts [-n N]` | List contacts |
+| `wa open <chat> [-n N]` | Read latest messages |
+| `wa history <chat> [-n N]` | Read extended history |
+| `wa search <text> [-n N]` | Search cached messages |
+| `wa send <chat> [message] [--file path]` | Send a text message or media |
+| `wa reply <id> <message>` | Reply to a cached message by `#id` |
+| `wa sync [-s seconds]` | Pull recent chats/messages |
+| `wa watch` | Stream incoming messages live (+ notifications) |
+| `wa media [type] [-n N]` | List cached media (photos/videos/audio/documents/stickers/all) |
+| `wa download <id> [-o file]` | Download & decrypt a cached media message |
+| `wa group <action> …` | Group management (info/invite/rename/add/remove/promote/demote/leave/create) |
+| `wa export <chat> [-f md\|txt\|json] [-o file]` | Export a conversation |
+| `wa recent [-n N]` | Most recently active chats |
+| `wa pin/unpin/archive/unarchive <chat>` | Organize chats (local) |
+| `wa shell` / `wa chat` (or just `wa`) | Interactive app (live chat, slash commands) |
+| `wa config [set <key> <value>]` | View/edit preferences |
+| `wa doctor` | Self-diagnostics |
+
+See **[COMMANDS.md](COMMANDS.md)** for the full guide with every flag, the
+interactive slash commands, group management, and notification/theme settings.
+
+Set `WA_DEBUG=1` to see verbose Baileys connection logs.
+
+## Notes
+
+- **Baileys version matters.** WhatsApp rejects outdated protocol versions at
+  the registration handshake. This project uses Baileys `7.x`; older `6.x`
+  releases fail to connect against current WhatsApp servers.
+- Your session credentials in `sessions/` are as sensitive as being logged in.
+  They are gitignored — never commit or share them.

package/bin/wa.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Thin launcher. Node (>=22.5 with --experimental-strip-types, default in >=23.6)
+// strips TypeScript types at runtime, so no build step is required.
+import '../src/cli/index.ts';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "cli-whatsapp",
+  "version": "0.1.0",
+  "description": "A lightweight, fast, terminal-first WhatsApp client. Read, search, send, media, groups, and live notifications — from your terminal.",
+  "type": "module",
+  "bin": {
+    "wa": "bin/wa.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "COMMANDS.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "whatsapp",
+    "cli",
+    "terminal",
+    "tui",
+    "chat",
+    "messaging",
+    "baileys",
+    "keyboard-first",
+    "local-first"
+  ],
+  "scripts": {
+    "wa": "node bin/wa.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "license": "MIT",
+  "author": "Piyush Patil <piyushpatil7911@gmail.com>",
+  "dependencies": {
+    "@whiskeysockets/baileys": "^7.0.0-rc13",
+    "commander": "^15.0.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "typescript": "^5.6.0"
+  }
+}