Core Concepts and Architecture

wacli is architected as a modular command-line interface application, primarily written in Go, designed for robust local management and interaction with WhatsApp. Its core functionality revolves around local message synchronization, efficient offline searching, and direct message/group management.

High-Level Architecture

The architecture of wacli is structured into several key internal packages that interact to provide the CLI functionality:

• cmd/wacli: This is the entry point for the CLI. It parses user commands and flags (using Cobra) and orchestrates the higher-level application logic by calling functions within the internal/app package.
• internal/app: This serves as the main application logic layer. It acts as an orchestrator, bridging the internal/wa (WhatsApp client) and internal/store (local database) packages. It handles complex workflows like message synchronization, history backfill, and media management.
• internal/wa: This package provides a wrapper around the whatsmeow library, abstracting the complexities of the WhatsApp Web protocol.
• internal/store: This package manages the local SQLite database, responsible for persisting all synchronized data and enabling search functionalities.
• internal/lock: Ensures that only a single instance of wacli can operate on a given store directory at any time, preventing data corruption or conflicting operations.
• internal/out: Handles formatting the CLI output, supporting both human-readable text and machine-readable JSON formats.

Commands issued via cmd/wacli flow to internal/app, which then utilizes internal/wa to communicate with WhatsApp servers and internal/store to manage local data.

whatsmeow as the WhatsApp Web Protocol Interface

The README highlights that wacli is "built on top of whatsmeow." The internal/wa package encapsulates the whatsmeow.Client and serves as wacli's dedicated interface for interacting with the WhatsApp network. Its responsibilities include:

• Authentication and Connection: Managing the WhatsApp session, including displaying QR codes for initial login and handling reconnections.
• Message Sending: Providing methods to send text and media messages to individual contacts or groups.
• Media Handling: Facilitating the upload of files to WhatsApp and providing the necessary information for media downloads.
• Contact and Group API Interaction: Fetching contact details, listing joined groups, retrieving group information, and executing group management actions (e.g., renaming, participant management, invite link handling).
• Event Handling: Registering event handlers with whatsmeow to receive real-time updates (new messages, status changes, history sync data) from the WhatsApp server. It translates these raw whatsmeow events into wacli's internal data structures.

Local Message History Sync and Continuous Capture

wacli aims for "best-effort local sync of message history + continuous capture." This is achieved through the internal/app/sync.go component:

1. Initial Bootstrap/Continuous Capture: When wacli auth or wacli sync --follow is run, the internal/app initiates a connection via internal/wa. An event handler is registered to listen for whatsmeow events.
2. Event Processing: The handler processes two primary types of message events:
   • events.Message: These represent live messages as they are sent or received.
   • events.HistorySync: These are bulk transfers of message history, often received during the initial authentication or in response to specific history requests.
3. Message Parsing and Storage: Messages from whatsmeow are parsed (internal/wa/messages.go) into a standardized ParsedMessage format. This includes extracting content, sender information, timestamps, and media metadata.
4. Database Persistence: The parsed messages are then stored into the local SQLite database (internal/store/store.go) using UpsertMessage. This process also updates related chats and contacts metadata to ensure a comprehensive local record.
5. Best-Effort Principle: The term "best-effort" acknowledges that WhatsApp's protocol may not always provide a complete, unbroken history. wacli stores whatever is provided opportunistically.
6. On-Demand Backfill: To supplement history, wacli history backfill allows users to explicitly request older messages for a specific chat from their primary device (phone). This mechanism, implemented in internal/app/backfill.go, sends a request via internal/wa and waits for a corresponding events.HistorySync response, which is then processed and stored. This functionality requires the primary device to be online.
7. Background Media Download: If enabled, internal/app/media.go manages concurrent downloads of media attachments in the background, ensuring that local message records include the actual media files.

Fast Offline Search with FTS5 Support

wacli's design for "fast offline search" leverages SQLite's capabilities, specifically its Full-Text Search (FTS5) extension:

1. FTS5 Integration: During database initialization (internal/store/store.go), wacli attempts to create a virtual table named messages_fts using FTS5. This table indexes the text content of messages, media captions, filenames, chat names, and sender names.
2. Automatic Indexing: SQLite triggers are set up to automatically update the messages_fts table whenever messages are inserted, updated, or deleted in the main messages table. This keeps the search index always synchronized with the message history.
3. Optimized Search Queries: When a user performs a search (wacli messages search), the internal/store/searchFTS function is called if FTS5 is successfully enabled. This function queries the messages_fts table using the MATCH operator, providing highly efficient and relevant results, often including "snippets" that highlight the matching terms.
4. LIKE Fallback: If FTS5 is not available (e.g., SQLite was compiled without FTS5 support, or the virtual table creation failed), wacli gracefully falls back to a slower LIKE based search (internal/store/searchLIKE). This ensures basic search functionality, though without the performance and advanced features of FTS5. The build process explicitly enables FTS5 by default (e.g., go build -tags sqlite_fts5).

For a more general introduction to wacli's features and purpose, please refer to the [Overview] page.