Metadata-Version: 2.5
Name: waidrop-cli
Version: 1.0.1
Summary: Query encrypted WAiDrop archives in Dropbox by name/number and time window
Project-URL: Homepage, https://github.com/thabiger/waidrop-cli
Project-URL: Repository, https://github.com/thabiger/waidrop-cli
Project-URL: Issues, https://github.com/thabiger/waidrop-cli/issues
Project-URL: Changelog, https://github.com/thabiger/waidrop-cli/blob/main/CHANGELOG.md
Author-email: Tomasz Habiger <tomasz.habiger@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: archive,backup,cli,dropbox,privacy,whatsapp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: System :: Archiving :: Backup
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: tzdata>=2025.2; sys_platform == 'win32'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
Description-Content-Type: text/markdown

# waidrop-cli

[![PyPI](https://img.shields.io/pypi/v/waidrop-cli.svg)](https://pypi.org/project/waidrop-cli/)
[![CI](https://github.com/thabiger/waidrop-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/thabiger/waidrop-cli/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/waidrop-cli.svg)](https://pypi.org/project/waidrop-cli/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Query the WhatsApp archive written by the **WAiDrop** Chrome extension into a
Dropbox App Folder. Fetch messages for one or more conversations — by phone number,
contact name (wildcards supported), chat hash or JID — over a date- or hour-precise
window.

The CLI talks only to Dropbox and runs entirely locally. It decrypts encrypted
archives with your archive key; no server is involved.

> **Companion extension:** the WAiDrop Chrome extension is required to create
> the archive. The store link will be added here.

## Requirements

- Python ≥ 3.10.
- An encrypted WhatsApp archive created by the WAiDrop Chrome extension.
- The archive key generated by the extension.
- A Dropbox account connected to the same Dropbox app. The built-in app key is
  used by default.

On Windows, the `tzdata` package is installed automatically so `--tz` can use
IANA timezones.

## Install

```sh
pip install waidrop-cli
```

Other installers:

```sh
uv tool install waidrop-cli
pipx install waidrop-cli
```

From source:

```sh
git clone https://github.com/thabiger/waidrop-cli.git
cd waidrop-cli
uv sync
uv run waidrop --help
```

Upgrade or remove:

```sh
pip install --upgrade waidrop-cli
uv tool upgrade waidrop-cli

pip uninstall waidrop-cli
uv tool uninstall waidrop-cli
```

## Dropbox setup

The CLI uses **OAuth 2.0 with PKCE** and the same Dropbox app as the Chrome
extension, so both see the same App Folder. The built-in app key is a public
client id; no client secret is involved for the built-in app. Each user
authorizes once and the CLI stores a long-lived refresh token locally.

### Connect the CLI

```sh
waidrop auth
```

This opens a browser (or prints a URL), asks you to click **Allow** on Dropbox,
and prompts for the authorization code. Credentials are stored at
`~/.config/waidrop/credentials.json` (file mode `0600`, directory `0700`).
On Windows the default is `%APPDATA%\waidrop\credentials.json`.

On headless hosts or over SSH:

```sh
waidrop auth --no-browser          # print URL only
waidrop auth --code <CODE>         # non-interactive (pass the code)
waidrop auth --loopback            # localhost callback (desktop)
```

For `--loopback`, register `http://127.0.0.1:53682/callback` as a redirect URI
in the Dropbox App Console. The paste flow needs no redirect URI.

Check or remove the connection:

```sh
waidrop auth --status              # human-readable
waidrop auth --status --json       # machine-readable
waidrop auth --revoke              # revoke remote access + delete local credentials
```

`auth --revoke` only deletes local credentials after a successful remote
revoke. If Dropbox cannot be reached, the local credentials are kept and the
command exits with code `5`.

### Custom Dropbox apps

The built-in app key is `wqiz8ksk2f0jwmd`. To use your own app, create a
**Scoped access** app with **App folder** access in the
[Dropbox App Console](https://www.dropbox.com/developers/apps), enable and
submit these permissions:

- `account_info.read` (account display)
- `files.metadata.read` (list folders/files)
- `files.content.read` (downloads; used by this CLI)
- `files.content.write` (uploads + folder creation; used by the extension)

Use PKCE; never ship a client secret. Set the app key with
`--dropbox-app-key` or `WAIDROP_DROPBOX_APP_KEY`.

> **Production note:** Dropbox apps in development mode are limited to test
> users, and some scopes require review. Verify the app status and scopes before
> announcing the CLI publicly.

> **Old archives:** a Dropbox App Folder is namespaced per app. If your archive
> was created with a different app key, pass `--dropbox-app-key <old-key>` or
> set `WAIDROP_DROPBOX_APP_KEY` so the CLI looks in the matching folder.

## Archive format

The CLI reads `account=<alias>/_format.json` before fetching data. Only
encrypted archives are supported:

- **encrypted** — objects use `.enc` envelopes and keyed HMAC path hashes.
  `--key` / `WAIDROP_KEY` is required.
- **legacy v2** — an archive without `_format.json` is treated as encrypted and
  still requires a key.

Plaintext archives are not supported. An archive whose `_format.json` declares
`"mode": "plaintext"` is rejected with a clear error.

## Configuration

Flags override environment, which overrides the credentials file.

| Setting | Flag | Env | Default |
|---|---|---|---|
| Dropbox access token | `--dropbox-token` | `WAIDROP_DROPBOX_TOKEN` | credentials file |
| Dropbox refresh token | `--dropbox-refresh-token` | `WAIDROP_DROPBOX_REFRESH_TOKEN` | credentials file |
| Dropbox app key | `--dropbox-app-key` | `WAIDROP_DROPBOX_APP_KEY` | built-in / credentials file |
| Dropbox app secret | `--dropbox-app-secret` | `WAIDROP_DROPBOX_APP_SECRET` | — (not needed for built-in) |
| credentials file | `--credentials-file` | `WAIDROP_CREDENTIALS` | `~/.config/waidrop/credentials.json` |
| archive encryption key | `--key` | `WAIDROP_KEY` | required |
| account alias | `--account` | `WAIDROP_ACCOUNT` | `primary` |
| subfolder in app folder | `--folder` | `WAIDROP_FOLDER` | app-folder root |
| timezone for bounds | `--tz` | — | system local |
| HTTP timeout (s) | `--timeout` | — | 60 |
| part guard | `--max-parts` | — | 1000 |

An explicit access or refresh token (flag/env) disables the credentials file so
secrets injected by a host are never overwritten. The archive key is the base64
32-byte key generated by the extension. It is required; without it the archive
cannot be decrypted.

Prefer environment variables or the credentials file over command-line secrets:
`--dropbox-token`, `--key` and `--code` can appear in shell history and process
listings.

## Usage

```sh
# store the archive key and account for MCP and headless use
waidrop config

# list chats (no messages fetched): names, phones, hashes, jids
waidrop chats
waidrop chats --name "*Family*"

# by contact name (glob/substring, case-insensitive) for a date range
waidrop query --name "Alice*" --from 2026-10-01 --to 2026-10-17

# by phone number (any format) for an hour-precise window
waidrop query --number "+1 555 0100" --from "2026-10-17 08:00" --to "2026-10-17 18:00"

# rolling window
waidrop query --name "Alice*" --last 36h
waidrop query --name "Alice*" --last 7d --format text

# all chats, recent window (no selectors)
waidrop query --last 1h
waidrop query --from "2026-10-17 08:00" --to "2026-10-17 18:00" --format csv

# export full-resolution images/stickers/GIFs plus manifest.ndjson
waidrop query --name "*" --last 24h --media-out ./waidrop-media

# multiple selectors / formats / output file
waidrop query --name "Alice*" --name "*Family*" --number +15550100 \
  --from 2026-10-01 --to 2026-10-17 --format csv --out october.csv

# direct targeting
waidrop query --chat 0123456789abcdef --jid 15550100@c.us --last 2w

# per-chat conversation chunks for an analysis window
waidrop context --from 2026-10-01 --to 2026-10-17 --format text
waidrop context --name "Alice*" --last 6h --context-before 30m \
  --max-chars 12000 --format text

# context chunks plus exported images/stickers/GIFs and their local paths
waidrop context --last 6h --media-out ./waidrop-media --format text
```

### Bounds

`--from` / `--to` accept, in local time (or `--tz`):

| Input | Meaning |
|---|---|
| `2026-10-01` | date precision: `from` = 00:00; `to` includes the whole day |
| `2026-10-01T14` | hour precision: to includes `14:00–14:59:59.999` |
| `2026-10-01T14:30` | minute precision: to includes `14:30–14:30:59.999` |
| `2026-10-01T14:30:45` | second precision |

`--from` is required unless `--last` is used. `--to` defaults to now.
`--last` accepts `m` (minutes), `h` (hours), `d` (days), `w` (weeks) and cannot be
combined with `--from`/`--to`.

With **no selectors**, `query` and `context` cover **all chats** (e.g.
`--last 1h`). Chats whose `firstSeen`/`lastSeen` cannot overlap the window are
skipped, and only part objects whose `[firstTs, lastTs]` interval can overlap
the window are downloaded (legacy parts without `lastTs` use a start-anchor
heuristic). `--max-parts` still caps the selected parts. `--context-before`
expands the fetched window and therefore counts toward `--max-parts`.

### Output

- `--format ndjson` (default): archive records, one JSON object per line.
- `--format text`: `2026-10-17 12:00 ← Alice / Alice: message…`
- `--format csv`: `msgId,ts,chatName,chatPhone,senderName,direction,type,text`
- `--out FILE` writes to a file with mode `0600`; progress goes to stderr
  (`--quiet` silences it).
- `--media-out DIR` downloads and decodes (or decrypts) full-resolution media
  referenced by the selected records into `DIR`, plus `DIR/manifest.ndjson`
  (override with `--media-manifest`). Files are written `0600`, directory
  `0700`, and names are derived from the timestamp and message id only.
  `--media-max-bytes` (default 25 MiB) skips larger objects;
  `--media-fail-fast` aborts on the first decode/download error. Media records
  whose status is not `stored` are reported as skipped.

Text output escapes control characters. CSV output prefixes cells that start
with `=`, `+`, `-`, `@`, tab or carriage return with `'` to reduce spreadsheet
formula injection. CSV files still contain untrusted chat data; open them with
care.

### Context output

`context` returns conversation-oriented chunks instead of flat records:

- `--format ndjson` (default): one JSON object per chat chunk, with `chat`,
  `window`, `part`/`parts`, `contextBeforeMs`, `oversized` and the full message
  records (`inWindow` marks messages inside the analysis window).
- `--format text`: delimited per-chat blocks with `=== CHAT … ===` /
  `=== END CHAT (i/n) ===`; newlines inside messages are escaped as `\n`.
- `--context-before DURATION` includes earlier messages as context (default `0`).
  Those messages appear in the chunk but are marked `inWindow: false` and
  `[context]` in text output.
- `--max-chars N` splits a chat into `part i/n` at message boundaries when its
  rendered message lines exceed `N` characters (default `0` = one chunk per
  chat); headers/footers are not counted. A single oversized message is kept
  whole in its own part and flagged `oversized: true`.
- `--media-out DIR` decodes or decrypts full-resolution images, stickers and GIFs
  referenced by the emitted chunks into `DIR` and adds a `mediaExport` object to each
  NDJSON media message:
  `{ "status": "exported", "file": "/abs/path/...jpg", "error": null }`.
  Paths are absolute. Text output appends `(file: "…")` for exported media and
  `(media: <status>)` or `(media: not exported)` otherwise. The manifest defaults
  to `DIR/manifest.ndjson`; `--media-max-bytes` and `--media-fail-fast` behave
  like `query`. Media from `--context-before` messages is included.
- Chats with no messages inside the analysis window are omitted, even if they
  have context-only messages.

Exit codes: `0` ok, `2` usage/config error, `3` no matched chats / no messages in
window, `4` `--max-parts` guard tripped, `5` Dropbox/network/archive read error.

## Running on a headless host

The CLI auto-refreshes access tokens from the stored refresh token, so no manual
rotation is needed. Run `waidrop auth` once on the host (or copy the
credentials file). Then store the archive key in the environment file:

```sh
waidrop config
```

It prompts for the key without echoing it, then for the account alias. On a
rerun, values already in the env file are offered as defaults: press Enter to
keep the existing key (shown as `[keep existing]`, never printed) or the
existing alias. It writes `~/.config/waidrop/env` with mode `0600` (directory
`0700`). Use `--account work` to set a non-primary alias, `--env-file PATH` for
a custom location, or set `WAIDROP_KEY` / `WAIDROP_ACCOUNT` to skip the
corresponding prompt. The file contains:

```sh
# ~/.config/waidrop/env  (must be 0600)
WAIDROP_KEY=<base64 archive key from the extension>
WAIDROP_ACCOUNT=primary
```

On Windows the default is `%APPDATA%\waidrop\env`. On macOS and Linux the file
must not be readable or writable by group or others; the CLI and MCP server
reject insecure files and read only `WAIDROP_*` keys. `chats`, `query`, and
`context` load the file automatically, so nothing needs to be exported in your
shell; explicit flags and shell environment variables take precedence. The file
next to a custom `--credentials-file` is used when one is passed.

A cron or agent wrapper can still source the file (`set -a; .
~/.config/waidrop/env; set +a`) before running other tools:

```sh
waidrop context --last 6h --context-before 30m --max-chars 12000 --format text
```

Health check:

```sh
waidrop auth --status --json   # exit 0 = ok, 2 = missing scopes
```

If the refresh token is ever revoked, re-run `waidrop auth` on the host.
Rotate the archive key only with a re-encryption plan (key loss means unreadable
history). Never put access tokens in env files or cron lines; the credentials
file handles them.

## MCP server (optional)

Install `waidrop-cli[mcp]` to expose a local, read-only MCP stdio server:

```sh
pip install "waidrop-cli[mcp]"
waidrop-mcp --print-setup
```

The server exposes `list_chats` and `get_context`, backed by the same archive
reader as the CLI. It works with any MCP-compatible client and does not contact
an AI service; selected text is returned only to the connected client. See
[`docs/mcp.md`](https://github.com/thabiger/waidrop-cli/blob/main/docs/mcp.md).

## Security and privacy

- The CLI never uploads archive content and has no telemetry. Archives are
  decrypted in memory.
- The optional MCP server is also local and read-only. It returns selected
  archive text to the connected MCP client over stdio; it does not send content
  to any AI service itself. A cloud-backed client may transmit that data.
- Dropbox credentials are stored in `~/.config/waidrop/credentials.json`
  (`0600`; parent `0700`). The refresh token grants access to the archive, so
  protect the file.
- Output files (`--out`, `--media-out`, manifests) are written with private
  permissions. Remove them when they are no longer needed.
- `waidrop auth --revoke` revokes Dropbox access and removes local
  credentials. If the remote revoke fails, local credentials are kept.
- Text output escapes terminal control characters. CSV output reduces
  spreadsheet formula injection but remains untrusted data.
- Report vulnerabilities using the process in [SECURITY.md](SECURITY.md).

**Disclaimer:** this project is not affiliated with WhatsApp or Meta. Use it
only for conversations you are authorized to access. Archiving may violate
WhatsApp's Terms of Service; use at your own risk. The software is provided
without warranty under the Apache-2.0 license.

## Troubleshooting

- **`missing_scope`**: enable the listed scope in the Dropbox App Console →
  Permissions → Submit, then re-authorize. Existing tokens do not gain scopes.
- **`invalid_access_token`**: token revoked/expired; re-authorize with
  `waidrop auth`.
- **`chat index could not be decrypted` / `cannot decrypt …`**: wrong archive key
  for the archive.
- **`plaintext archives are no longer supported`**: re-export the archive with
  encryption enabled.
- **`archive is encrypted; encryption key required`**: provide `--key` or
  `WAIDROP_KEY`.
- **`archive format marker is invalid` / `unsupported archive format`**: verify
  `_format.json` or update `waidrop-cli`.
- **`chat directory is empty`**: nothing has been uploaded yet (connect the
  extension and upload once).
- **No chats found**: if the archive was created with a different Dropbox app
  key, pass `--dropbox-app-key <old-key>`.
- **Dates look shifted by a day**: `dt=` is the capturing browser's local date;
  the CLI pads ±1 day and filters by exact `ts`, so this is handled
  automatically — ensure `--tz` matches how you want bounds interpreted.

## Limitations

- **LID chats** (`@lid`) have no phone number in the jid; number search works only
  when the archive recovered `chatPhone`. Otherwise select by name.
- **Phone formats** should include the country code; digits are compared.
- **Names are snapshots** inside message records; `chats` shows the latest name
  from the archive index.
- **DOM-only records with no `chatId`** are grouped by `chatName` in `context`
  output. Duplicate names cannot be mapped reliably, so they remain separate
  name-only chats with `hash: null`.
- **Only `stored` media can be exported.** `context --media-out` reports
  `not_downloaded`, `pending`, `view_once`, `too_large` and failed records as
  media messages without files. Capture is passive by default: only media
  WhatsApp already downloaded is stored; `not_downloaded` records have only the
  preview. Video, audio and documents remain metadata/placeholders. Records
  written before media capture cannot be backfilled from the archive.
- **Exported media files are unencrypted.** `context --media-out` writes
  full-resolution files to `DIR`; keep it private (files are `0600`, directory
  `0700`) and remove it after analysis if it is no longer needed.

## Development

```sh
uv sync
uv run pytest -q            # MCP server tests skip without the extra
uv sync --extra mcp
uv run pytest -q            # includes the MCP server tests
uv run ruff check .
uv run ruff format --check .
uv build
uvx twine check dist/*
```

Tests run against a local fake Dropbox server (stdlib `http.server`) with
encrypted fixtures and the shared cross-language crypto vector. No Dropbox
account is needed.

The crypto contract is shared with the extension. Do not change the envelope
magic, version bytes, HKDF salt, or key derivation without updating both
projects.

## Release

See [RELEASING.md](RELEASING.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
