ghostwire/docs/CLI.md

Ghostwire CLI reference

Use the portable file from a writable folder:

python whatsapp.py --help
python whatsapp.py <command> --help

For development, replace python whatsapp.py with python -m whatsapp_suite. With no arguments, either entry point runs offline tests.

Core commands

Live commands require signed-in Windows WhatsApp Desktop, x64 Windows and 64-bit Python 3.11+. The core path uses the Python standard library and bundled native helpers, without CDP or UI automation.

Command	Result	Useful options
test	Synthetic regression results	--output, explicit --live / --capabilities
contacts-export	Selected fields from all local contact rows	--output, --pid
export-zip	Local message records and manifest in ZIP	--output, --batch-size, --redact-text, --pid
live	Fixed app probes and detailed report	--suite, --output, --pid
desktop-search QUERY	App search results with message metadata	--limit, --output, --pid
send-self	One actual self-message and verification receipt	--output, --pid
webhook	Listener installation, status, delivery and restoration	See below

python whatsapp.py contacts-export --output exports/contacts.json
python whatsapp.py export-zip --output exports/messages.zip
python whatsapp.py live --suite history-read
python whatsapp.py desktop-search "keyword" --limit 10

live --suite accepts math, capabilities, all, message-json, contacts and history-read. The latter reads the five oldest records after a bounded timestamp scan. It saves decoded body/caption text when present.

Work with saved exports

These commands read existing JSON/JSONL files, without running WhatsApp:

python whatsapp.py stats messages.jsonl
python whatsapp.py search messages.jsonl "keyword" --limit 20 --redact-text

Extract messages.jsonl from a message ZIP before searching it; the search command does not read ZIP files directly. Search supports --chat-id and --output. inventory lists local storage files and sizes.

Webhook commands

python whatsapp.py webhook install --endpoint https://your-endpoint.example/events --self-only --auto-restore --config listener.json
python whatsapp.py webhook status
python whatsapp.py webhook stop --config listener.json

Set the endpoint token in the environment variable named by --token-env (default WHATSAPP_INJECTOR_WEBHOOK_TOKEN). Never place the token in the URL.

Action	Behavior
install	Subscribe to message events and start the resident native relay; installer exits
install --restore --config FILE	Reuse and re-enable an existing configuration
status	Report listener and relay counters
stop --config FILE	Stop the listener and disable restoration in that configuration
auto-restore --config FILE	Register/enable the per-user minute task for a direct HTTPS listener
ensure --config FILE	Check once and restore a missing configured listener
watch --config FILE	Optional continuous restoration loop
serve --restore-config FILE --store FILE	Run the optional loopback receiver with SQLite storage and restoration

Direct installation also accepts --endpoint, --token-env, --self-only, --auto-restore, --config and --pid. Loopback installation uses --port instead of --endpoint. Full setup, payload and task removal are in the webhook guide.

Output and failure behavior

• Commands emit compact JSON summaries; exports and detailed reports are local files.
• Success normally returns exit code 0; reported failures return a nonzero code. webhook ensure may exit 0 while waiting for WhatsApp: inspect its status file, not only the exit code.
• ZIP exports contain messages.jsonl and manifest.json. They cover local rows up to the initial upper key, with no phone sync or media download.
• The scan is not an atomic snapshot. Decode failures remain visible as error records and make the export fail.
• Existing export outputs are refused. Interrupted ZIP exports retain .zip.partial and an adjacent .zip.report.json.
• send-self reserves its receipt before sending. It verifies the recipient, stored plaintext and acknowledgement; an uncertain attempt is not retried automatically.
• Live reports include compatibility and cleanup information. A version warning does not certify support for that build.

Keep private outputs out of Git. See troubleshooting and security.

Optional research commands

These commands have distinct transports and are separate from the core no-CDP workflow. Always inspect their help before use.

Command	Purpose / dependency
webview-test	Separate WebView2 host test; may download its SDK
analyze	Storage inspection, optionally an existing CDP session; websockets for CDP
history-export	Bulk history through an existing Desktop CDP endpoint; websockets
ram-read, ram-search	Inspect loaded models in RAM; not complete history
native-search	Experimental injected SQLite search/index export; frida
qr-memory	Pairing QR candidates in RAM; qrcode[pil]
qr-window	Capture an already displayed pairing QR; Pillow, zxing-cpp
pairing	Isolated browser linking QR; Chrome, websockets, qrcode[pil]

requirements-whatsapp-optional.txt lists optional Python packages. No optional research action, pairing operation or send is performed by default tests.