whatsapp-cli-js

Minimal Node.js WhatsApp CLI built with Baileys.

It links a WhatsApp account, captures the initial history bootstrap, stores that snapshot in .wa-auth/chats-cache.json, and lets you inspect cached chats and messages from the terminal without reconnecting every time.

Features

• QR or pairing-code auth flow
• One-shot bootstrap capture with on-disk cache
• Cached chats listing
• Cached messages listing
• Filters for message search and chat targeting

Install

Global install:

npm install -g whatsapp-cli-js

Run without installing:

npx -y whatsapp-cli-js --help

For local development:

npm test
node index.js --help

Commands

auth

Authenticates the device, waits for the history bootstrap, writes .wa-auth/chats-cache.json, and exits.

whatsapp-cli-js auth [--pair <phone>] [--auth-dir <dir>] [--wait-ms <ms>] [--debug-file <file>]

Examples:

whatsapp-cli-js auth
whatsapp-cli-js auth --pair 8801234567890
whatsapp-cli-js auth --wait-ms 180000
npx -y whatsapp-cli-js auth

chats

Reads the saved cache and lists chats.

whatsapp-cli-js chats [--auth-dir <dir>] [--limit <n>]

Examples:

whatsapp-cli-js chats
whatsapp-cli-js chats --limit 20
npx -y whatsapp-cli-js chats --limit 20

messages

Reads the saved cache and lists messages newest-first.

whatsapp-cli-js messages [--auth-dir <dir>] [--chat <term>] [--search <term>] [--limit <n>]

Examples:

whatsapp-cli-js messages
whatsapp-cli-js messages --limit 50
whatsapp-cli-js messages --chat alice
whatsapp-cli-js messages --search invoice
whatsapp-cli-js messages --chat alice --search hello --limit 20
npx -y whatsapp-cli-js messages --limit 20

Cache and Auth Storage

• Auth files are stored in .wa-auth/ by default.
• The cached bootstrap snapshot is stored in .wa-auth/chats-cache.json.
• Run auth again whenever you want to refresh the cache.

Notes

• --pair expects digits only, without +, spaces, or punctuation.
• QR auth also writes a PNG copy of the QR code to .wa-auth/auth-debug.qr.png unless you provide --debug-file, in which case the PNG is written next to that file.
• chats and messages depend on a previously saved cache, so run auth first.

Development

npm test
npm pack --dry-run