ghostwire/docs/CLI.md

# Ghostwire CLI reference

Use the portable file from a writable folder:

```powershell
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 |

```powershell
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:

```powershell
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

```powershell
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](WEBHOOKS.md).

## 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](TROUBLESHOOTING.md) and [security](../SECURITY.md).

## 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.