vibcrawl

vibcrawl is a local-first, read-only CLI for querying the Viber Desktop message archive on macOS. It follows the same basic operating model as discrawl: use the local archive as the source of truth, expose focused search/export/query commands, and keep private chat data out of Git.

The implementation opens Viber Desktop's encrypted SQLite/SEE database through Viber's bundled Qt SQLite driver. It does not automate the Viber network or send messages.

What It Does

• finds the newest local ~/Library/Application Support/ViberPC/*/viber.db
• opens it read-only using Viber's packaged Qt SQL stack
• syncs a normalized local archive into ~/.vibcrawl/vibcrawl.db
• uses SQLite FTS5 for archive-backed message search
• reports archive status and table counts
• lists chats, contacts, and recent messages
• searches message body, subject, chat names, and contact names/numbers
• exports contacts, chats, and messages to JSON/JSONL
• allows guarded read-only SQL for ad hoc analysis

Requirements

• macOS
• Viber Desktop installed at /Applications/Viber.app
• Homebrew Qt headers available through qmake6
• a synced Viber Desktop profile under ~/Library/Application Support/ViberPC

Install Qt headers if needed:

brew install qt

Quick Start

Build on first use and verify the archive opens:

./scripts/vibcrawl status

Create the local vibcrawl archive and import Viber Desktop history:

./scripts/vibcrawl init
./scripts/vibcrawl doctor
./scripts/vibcrawl sync --full
./scripts/vibcrawl db info

Search recent messages:

./scripts/vibcrawl search "invoice" --limit 20
./scripts/vibcrawl search "domain" --chat "KIDS Reg Site" --limit 20 --json

List recent messages from a chat:

./scripts/vibcrawl messages --chat "Project Name" --limit 50 --json

Run read-only SQL:

./scripts/vibcrawl sql 'select ChatID, Name from ChatInfo order by TimeStamp desc limit 20' --json

Export a local archive snapshot:

./scripts/vibcrawl export --out ./exports/viber-export

Generated exports are ignored by Git. Do not commit raw message dumps, local DBs, or derived archive files.

Commands

status

./scripts/vibcrawl status
./scripts/vibcrawl status --json

Shows source DB path, Qt plugin path, core row counts, and latest raw Viber event timestamp. When the vibcrawl archive exists, it also includes archive counts and last sync metadata.

init, doctor, sync, and db info

./scripts/vibcrawl init
./scripts/vibcrawl doctor --json
./scripts/vibcrawl sync
./scripts/vibcrawl sync --full --json
./scripts/vibcrawl db info --json

init creates ~/.vibcrawl, a starter config file, and the archive schema. doctor checks the Viber source DB, bundled Qt plugin path, and local archive. sync imports Viber Desktop rows into ~/.vibcrawl/vibcrawl.db; --full clears and rebuilds the archive. Read commands use --sync auto by default, so searches and listings refresh the archive when the source DB is newer or stale.

search

./scripts/vibcrawl search "payment failed" --limit 25 --json
./scripts/vibcrawl search "launch" --chat "Team Chat" --limit 10

Uses archive-backed SQLite FTS5 over message body, subject, chat name, contact name, contact number, and payload path. Keep limits focused unless you are exporting to files.

messages

./scripts/vibcrawl messages --limit 20 --json
./scripts/vibcrawl messages --chat "123" --limit 50 --json
./scripts/vibcrawl messages --chat "Client Name" --limit 50
./scripts/vibcrawl messages --from-me --after 2026-04-01 --limit 50
./scripts/vibcrawl messages --has-media --limit 50

--chat matches chat ID, chat name, or chat token. --after and --before accept ISO dates or raw Viber epoch milliseconds. --from-me, --from-them, and --has-media are available on archive-backed reads.

chats and contacts

./scripts/vibcrawl chats --limit 50 --json
./scripts/vibcrawl contacts --limit 50 --json

Use these to discover chat IDs, chat names, contacts, and numbers before deeper queries.

schema

./scripts/vibcrawl schema
./scripts/vibcrawl schema --json

Lists tables and views available in the unlocked local archive.

sql

./scripts/vibcrawl sql 'select name from sqlite_master where type="table" order by name'

Only SELECT, PRAGMA, and EXPLAIN statements are accepted, and this command targets the read-only Viber source DB.

Development

Run local checks:

./scripts/check

Build and run the CLI:

./scripts/vibcrawl status --json
./scripts/vibcrawl doctor --json
./scripts/vibcrawl sync --full --json
./scripts/vibcrawl db info --json

The wrapper compiles src/vibcrawl.cpp into bin/vibcrawl when the binary is missing or stale. bin/ is generated and ignored.

Privacy Rules

• Do not commit Viber DBs, exports, raw chat logs, screenshots of private chats, or generated summaries containing private message bodies.
• Do not print DB keys or derived key material in logs.
• Prefer small JSON query results for inspection.
• Summarize sensitive messages instead of pasting full raw bodies into issues, commits, or docs.