How the wacli doctor Command Diagnoses Connection and Authentication Issues

The wacli doctor command runs a comprehensive diagnostic suite that checks the local store directory, file lock status, WhatsApp authentication state, and optional live network connectivity to pinpoint exactly why wacli commands are failing.

The wacli doctor command is a built-in diagnostic tool in the steipete/wacli repository that inspects the most common failure points when the CLI tries to communicate with WhatsApp. It validates the store directory, file locks, authentication status, and network connectivity without requiring a full sync operation. By running these checks in sequence, the command provides a concise snapshot of the runtime state that explains why subsequent wacli send, wacli sync, or wacli search commands might fail.

Diagnostic Checks Performed by wacli doctor

The diagnostic logic is implemented in cmd/wacli/doctor.go. The command constructs the application using newApp(..., needLock=true, allowUnauthed=true) from cmd/wacli/root.go, which allows the diagnostic to run even when the store is not yet authenticated.

Store Location and Lock Status

First, the command resolves the data directory (defaulting to ~/.config/wacli) using config.DefaultStoreDir() from internal/config/config.go. It displays the absolute path to help users verify they are operating on the correct store.

Next, it checks the lock status by reading a LOCK file in the store directory. Using the lock.Acquire logic from internal/lock/lock.go, it attempts to acquire a lock. If another wacli process (such as wacli sync) is currently running, the lock acquisition fails and the doctor reports the lock holder's PID and command. This immediately identifies concurrency conflicts that would block write operations.

Authentication Verification

The command calls a.OpenWA() followed by a.WA().IsAuthed() to verify that a valid WhatsApp session exists. This check determines whether the device has completed the QR-code pairing process and whether the session credentials are still valid. If authentication fails, the doctor reports AUTHENTICATED: false, indicating that the user needs to re-run wacli login or check for session expiry.

Optional Live Connection Test

When invoked with the --connect flag, the doctor attempts to open a live WebSocket connection to WhatsApp using a.Connect. This test reveals network-level issues, proxy misconfigurations, or session-expiry problems that only manifest during actual communication. A successful connection displays CONNECTED: true, while failures surface specific error messages from the underlying WhatsApp Web library.

Full-Text Search (FTS) Availability

For users experiencing search failures, the command queries a.DB().HasFTS() to confirm that the SQLite FTS5 extension is loaded. This diagnostic is crucial because the wacli search command depends on FTS5 for full-text indexing. If the extension is missing, the doctor reports FTS5: false, explaining why search operations return errors.

Structured JSON Output

Automation and CI pipelines can consume the diagnostic results by passing the --json flag. The command emits a structured JSON object containing fields such as store_dir, lock_held, authenticated, connected, and fts_enabled. This format enables programmatic health checks and monitoring without parsing human-readable text.

Practical Usage Examples

Basic Health Check

Run the standard diagnostic to see the current state of your wacli installation:

wacli doctor

Typical output:

STORE   /home/user/.config/wacli
LOCKED  false
AUTHENTICATED  true
CONNECTED  false
FTS5    true

This indicates a healthy store that is authenticated but not currently connected to WhatsApp.

JSON-Formatted Report for Automation

Integrate health checks into monitoring scripts using the JSON output:

wacli doctor --json

{
  "store_dir": "/home/user/.config/wacli",
  "lock_held": false,
  "authenticated": true,
  "connected": false,
  "fts_enabled": true
}

Test Live Connectivity

Diagnose network or session issues by forcing a connection attempt:

wacli doctor --connect

If the session is valid and the network is accessible, the output includes CONNECTED: true. Connection failures surface specific error messages indicating whether the issue is network-related, proxy-related, or due to an expired session.

Diagnosing a Locked Store

When another wacli process is running, the doctor reports:

LOCKED  true
LOCK_INFO  sync running (PID 12345)
Tip: stop the running `wacli sync` before running write operations.

This immediately identifies which process holds the lock and advises the user to terminate it before attempting write operations like wacli send.

Summary

• The wacli doctor command provides a comprehensive diagnostic snapshot by checking the store directory, file locks, authentication status, and network connectivity.
• It uses newApp(..., needLock=true, allowUnauthed=true) from cmd/wacli/root.go to ensure diagnostics can run even on unauthenticated stores.
• Key implementation files include cmd/wacli/doctor.go for the diagnostic logic, internal/lock/lock.go for lock management, and internal/config/config.go for store path resolution.
• The --connect flag tests live WhatsApp WebSocket connections, while --json enables machine-readable output for CI pipelines.
• By reporting FTS5 availability, the command also explains search functionality failures.

Frequently Asked Questions

What does wacli doctor check first when diagnosing issues?

The command first resolves and displays the store directory using config.DefaultStoreDir() from internal/config/config.go. It then immediately checks the lock status by attempting to acquire a lock via lock.Acquire in internal/lock/lock.go, reporting if another process is currently using the store.

Can wacli doctor run if I haven't authenticated yet?

Yes. The doctor command explicitly initializes the application with allowUnauthed=true in the newApp call from cmd/wacli/root.go. This allows the diagnostic to inspect the store location, lock status, and FTS availability even when no WhatsApp session exists, though it will report authenticated: false.

How do I test if my WhatsApp connection is working with wacli doctor?

Pass the --connect flag to the command. This triggers a call to a.Connect which attempts to open a live WebSocket connection to WhatsApp. If successful, the output shows connected: true; if the session expired or network issues exist, the command surfaces the specific error message.

What does the FTS5 check in wacli doctor indicate?

The FTS5 check queries a.DB().HasFTS() to verify that the SQLite FTS5 extension is loaded in the store database. This is critical because the wacli search command depends on FTS5 for full-text indexing. If the doctor reports fts_enabled: false, it explains why search operations are failing and indicates a missing SQLite extension.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}