wacli: CLI for local WhatsApp sync and fast offline search
wacli is a whatsmeow-based CLI that provides continuous local WhatsApp sync, fast offline search, and message sending — suitable for personal backup and automation, but requires attention to compliance and licensing.
GitHub steipete/wacli Updated 2026-04-17 Branch main Stars 2.1K Forks 243
Go Node/pnpm CLI tool WhatsApp Web protocol local sync offline full-text search

💡 Deep Analysis

5
What specific problems does wacli solve? How does it bring WhatsApp conversation data into CLI or automation workflows?

Core Analysis

Project Positioning: wacli’s core is local-first + scriptable access to WhatsApp conversations. It addresses the lack of terminal/script access for searching, retrieving, and managing WhatsApp history.

Technical Features

  • Continuous local sync: Uses whatsmeow to receive WhatsApp Web pushes and persist messages to ~/.wacli, with sync --follow for a daemonized sync loop.
  • Offline full-text search: Employs SQLite FTS5 (build with -tags sqlite_fts5) for low-latency searches across large message stores.
  • Scriptable output: CLI supports --json, enabling easy integration with jq, cron jobs, or backend services.

Practical Recommendations

  1. Getting started: Install via Homebrew or build locally ensuring FTS5 is enabled for search performance.
  2. Automation: Run wacli sync --follow as a background process and drive logic using messages search --json.

Note: History backfill is best-effort and depends on the primary device being online—old messages may not always be returned.

Summary: wacli is a pragmatic solution for bringing WhatsApp data into CLI and automation workflows; it is effective technically but requires realistic expectations about history completeness and upstream protocol behavior.

90.0%
How can wacli's local storage data be secured? What concise, actionable hardening recommendations exist?

Core Analysis

Core Issue: wacli stores messages/media under ~/.wacli by default and README does not mention DB encryption; external countermeasures are needed to protect sensitive local data.

Technical Analysis

  • Risk points: SQLite DB and media files stored in plaintext can be exposed if the device or backups are compromised.
  • Viable controls: OS-level disk/directory encryption, strict file permissions, encrypted backups, and retention policies.

Practical Recommendations (Actionable)

  1. Encrypted storage: Place ~/.wacli on an encrypted partition/container (LUKS, FileVault, BitLocker, or encrypted folder).
  2. Least privilege: Set directory perms to 700 and DB files to 600, run wacli under a dedicated user account.
  3. Backup strategy: Encrypt backups and use secure key management (never store keys on the same host).
  4. Lifecycle management: Regularly purge old media, enforce retention limits, and keep an audit trail.
  5. Runtime hygiene: Avoid leaking env vars in CI/hosts, and include wacli doctor in health checks.

Note: For strict compliance, consider transparent DB encryption or purpose-built encrypted storage beyond file-system level.

Summary: Strengthen default storage with disk encryption, tight permissions, and encrypted backups—don’t rely on plaintext local storage for sensitive long-term retention.

90.0%
In which scenarios should you choose wacli first, and when should you consider alternatives such as the official Business API?

Core Analysis

Core Question: Choose wacli or an official/hosted solution based on scale, compliance needs, and desire for local data control.

Suitable Scenarios (Choose wacli)

  • Research/inspection and local analysis: Researchers or compliance staff who need local full-text search over message history.
  • Terminal/script workflows: Engineers who drive WhatsApp interactions from scripts, CI, or cron jobs.
  • Low-to-medium volume automation: Batch sending, media downloads, or ops notifications.

When to consider alternatives

  1. High-volume customer service / high concurrency: Use the official WhatsApp Business API for SLA and managed support.
  2. Strict compliance & auditability: Official channels provide stronger guarantees and supported export/archival features.
  3. Guaranteed long-term archives: Device-side backups or official export are preferable when absolute completeness is required.

Tip: Use wacli for development, testing, and small-scale production; plan migration to official APIs as volume/compliance needs grow.

Summary: wacli excels where local control and fast search matter; official/hosted APIs are better for scale, SLAs, and strict compliance.

88.0%
How should you deploy and maintain wacli locally to achieve stable sync and search? (Include build, run, and monitoring essentials)

Core Analysis

Core Issue: Reliable long-term use of wacli requires engineered ops around build, daemonized sync, persistent storage, and monitoring.

Technical Analysis

  • Build: Prefer Homebrew binaries to avoid build variance; if building locally, include -tags sqlite_fts5 to enable full-text search.
  • Run mode: Run wacli sync --follow as a system service (systemd/launchd) under a dedicated user and point --store to a controlled path.
  • DB maintenance: Regularly run SQLite VACUUM, monitor FTS index size, and perform index maintenance to preserve search performance.

Ops Recommendations (stepwise)

  1. Deploy binary: Use Homebrew or CI-built binaries for consistency.
  2. Service management: Manage sync --follow via systemd/container supervisor with auto-restart and log retention.
  3. Monitoring & alerts: Collect wacli doctor output, sync lag, failure rates, and disk usage—set alert thresholds.
  4. Backup & security: Periodically encrypt backups of the --store directory and enforce strict file permissions.
  5. Backfill policy: Schedule chunked history backfill runs and persist failed chat IDs for retries.

Note: Even with good ops, protocol changes or primary device offline events will impact functionality—include these in alerting and recovery playbooks.

Summary: Standardize builds, daemonize sync, maintain DB, and monitor health to run wacli stably, while preparing for external dependency failures.

88.0%
Why does wacli use whatsmeow and SQLite FTS5? What are the architectural advantages and potential risks of this tech choice?

Core Analysis

Project Positioning: wacli’s choice of whatsmeow + SQLite FTS5 enables a lightweight, self-contained CLI optimized for local-first workflows without external services.

Technical Strengths

  • whatsmeow (protocol client): Reuses a mature WhatsApp Web implementation, reducing protocol maintenance and providing reliable connection handling.
  • SQLite FTS5 (embedded search): Single-file storage, low ops overhead, controlled memory footprint, and fast full-text queries—easy to back up and migrate.
  • Overall lightness: No need for a separate search cluster or DB server, fitting developer workstations and small backend integrations.

Potential Risks

  1. Protocol dependence: Changes in WhatsApp Web or anti-automation measures can break functionality.
  2. Concurrency & scale: SQLite is not designed for heavy concurrent writes or distributed access—bulk media or high throughput may hit limits.
  3. Local security: Messages/media appear stored locally without documented encryption—administrators must add safeguards.

Recommendation: For higher availability or scale, export data periodically to a dedicated search/storage (e.g., Elastic or managed DB). For initial deployments, embedded SQLite minimizes operational overhead.

Summary: The stack is pragmatic and appropriate for terminal-driven, small-to-medium use, but production-grade deployments need mitigations for protocol drift, scale, and data protection.

87.0%

✨ Highlights

  • Supports continuous local message sync and capture
  • Built-in fast offline search (FTS5-capable)
  • Third-party use of WhatsApp Web protocol carries compliance risk
  • License unknown and contributor data appears incomplete

🔧 Engineering

  • CLI covers auth, continuous sync, search, send, and group management
  • Optional local build (Go) and Homebrew install; supports SQLite FTS5 for search

⚠️ Risks

  • Using the WhatsApp Web protocol may trigger service limits or account bans
  • Strong coupling to external dependencies (whatsmeow and primary device online requirement)
  • Repository license unknown; enterprises must clarify legal/compliance boundaries before adoption
  • Public data shows zero contributors/commits, which may indicate incomplete metadata or low community activity

👥 For who?

  • Individual users and tinkerers: for backups, offline search, and automated sending
  • Ops and security researchers: can serve as a base component for message archiving and incident search