Wacli

Use this for wacli repo work and local WhatsApp linked-device stores. Prefer read-only commands for inspection unless the user explicitly asks to auth, sync, send, mutate chats/groups, or release.

Sources

• Repo: ~/Projects/wacli
• CLI in repo: ./dist/wacli after pnpm build
• Installed CLI: wacli
• Default config: ~/.wacli/config.yaml
• Default macOS store: ~/.wacli
• Named account stores: ~/.wacli/accounts/<name>
• App DB: <store>/wacli.db
• WhatsApp session DB: <store>/session.db

Safety

• Use --read-only or WACLI_READONLY=1 for inspection.
• Use --json for parsing.
• Do not send messages unless explicitly asked.
• Do not write session.db directly.
• Do not merge account data into one wacli.db; named accounts are isolated stores.
• Watch dirty worktrees; leave unrelated files alone.

Account Workflow

List accounts and store paths:

wacli accounts list --json

Inspect one account without connecting:

wacli --account me doctor --read-only --json
wacli --account me auth status --read-only --json

Use --account NAME for normal multi-account work. Use --store DIR only for one-off legacy/manual store debugging.

Message/Store Checks

Prefer CLI first:

wacli --account me messages list --read-only --json --limit 20
wacli --account me messages search --read-only --json "query"
wacli --account me chats list --read-only --json

For DB health or aggregate checks, use SQLite read-only where possible:

sqlite3 "$HOME/.wacli/accounts/me/wacli.db" "pragma integrity_check;"
sqlite3 "$HOME/.wacli/accounts/me/wacli.db" \
  "select count(*) from messages;
   select count(*) from messages_fts;"

Useful consistency checks:

select count(*) from (
  select chat_jid, msg_id, count(*) c
  from messages
  group by chat_jid, msg_id
  having c > 1
);

select count(*)
from messages m
left join chats c on c.jid = m.chat_jid
where c.jid is null;

select count(*) from messages where revoked = 0 and deleted_for_me = 0;
select count(*) from messages_fts;

Sync/Auth UX

auth pairs and then bootstraps sync. sync never shows QR and requires an authenticated store.

Common commands:

wacli --account me auth
wacli --account me sync --once
wacli --account me sync --follow
wacli --account me sync --once --events 2>events.ndjson

Interactive TTY sync progress should be concise; warnings must remain visible. --events must keep stderr as NDJSON.

Repo Workflow

Read docs before coding when behavior changes:

pnpm -s docs:list || bin/docs-list || true

Focused tests first, then full gate:

go test ./internal/app
go test ./internal/store
pnpm docs:site && pnpm format:check && pnpm lint && pnpm test && pnpm build && git diff --check

User-facing changes need docs and CHANGELOG.md. Use committer with explicit file paths.

Release

Read docs/release.md before release work. Release is tag-driven; verify workflow state with gh run list/view. If a release workflow is cancelled or partially failed, state exactly which jobs completed and which did not.