wacrawl makes a read-only snapshot of the macOS WhatsApp Desktop databases and imports chats, contacts, messages, and media metadata into a local SQLite archive. It is for people who want fast local search, structured exports, a private web viewer, or encrypted Git backups without connecting to WhatsApp's network protocol.

Homebrew is the smallest path:

brew install openclaw/tap/wacrawl

Upgrade later with brew upgrade openclaw/tap/wacrawl.

Or install from source with Go 1.26.5 or newer:

go install github.com/openclaw/wacrawl/cmd/wacrawl@latest

Direct source discovery requires macOS and the desktop WhatsApp app. Release builds for macOS, Linux, and Windows can work with an existing archive or encrypted backup.

Check the source, import it, then inspect the archive:

wacrawl doctor
wacrawl sync
wacrawl status
wacrawl search "invoice"

Read commands refresh a stale archive when the WhatsApp source is newer. To browse instead:

wacrawl web

The viewer prints a private local URL, binds only to 127.0.0.1, and stops with Ctrl-C.

WhatsApp Desktop keeps its macOS data under:

~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared

wacrawl snapshots ChatStorage.sqlite, ContactsV2.sqlite, and their SQLite sidecars before reading. With --copy-media, it also copies referenced files from Message/Media/. Its own archive defaults to ~/.wacrawl/wacrawl.db.

Imports merge by stable source identity, retain older history that has disappeared from the current desktop snapshot, and preserve explicit edits and deletions as revisions or tombstones. Use a separate --db for another WhatsApp account; source adoption and exact restore are deliberate operations described in the command reference.

Search covers message text, chat and sender names, and media titles:

wacrawl search "release notes" --from-them --after 2026-01-01
wacrawl messages --chat 1234567890@s.whatsapp.net --has-media
wacrawl sql "SELECT count(*) FROM messages"

Add --json for scripts and agents:

wacrawl --json --sync never search "invoice"
wacrawl --json --sync never contacts export

See the command reference for filters, sync modes, SQL constraints, and every subcommand.

wacrawl backup exports deterministic JSONL shards, compresses them, and encrypts them to one or more X25519 age recipients before Git sees the data. Copied media can travel in content-deduplicated encrypted blobs, and restores verify hashes and cross-table references before replacing the archive.

wacrawl backup init --repo ~/Projects/backup-wacrawl --remote <git-url>
wacrawl backup push
wacrawl backup snapshots
wacrawl backup pull

The manifest remains cleartext and reveals backup timing, public recipients, counts, shard paths, encrypted sizes, and hashes. Read the backup guide and threat model before relying on it for recovery.

• The WhatsApp databases are opened read-only through a temporary SQLite snapshot.
• Normal archive and search commands do not upload data or write into WhatsApp's app container.
• The web viewer is loopback-only, read-only, protected by a random per-run access key, and restricts media reads to known roots.
• backup push is the explicit networked path; it sends age-encrypted shards to the configured Git remote.

The archive still contains private message data in plaintext. Keep ~/.wacrawl/wacrawl.db and copied media out of commits, shared logs, and untrusted backups unless sharing them is intentional.

Run wacrawl help <command> or open the full command reference.

• Commands, filters, paths, and sync behavior
• Encrypted backups, recovery, and threat model
• Archive identities and data model
• Release process

Requires Go 1.26.5 or newer.

make build
make test
make check

make check mirrors the local CI gates: formatting, analysis, tests, race and coverage checks, dependency and vulnerability checks, a credential-free GoReleaser snapshot, release-script tests, and secret scans.

MIT. See LICENSE.