contacts

Read when: finding synced contacts, importing macOS Contacts names, or managing local contact metadata.

wacli contacts works with contact metadata stored locally. Aliases and tags are local to wacli; they do not edit WhatsApp contacts on the phone.

#Commands

wacli contacts search <query> [--limit N]
wacli contacts show --jid JID
wacli contacts check <phone> [phone...]
wacli contacts refresh
wacli contacts import-system [--input FILE] [--dry-run] [--clear]
wacli contacts alias set --jid JID --alias NAME
wacli contacts alias rm --jid JID
wacli contacts tags add --jid JID --tag TAG
wacli contacts tags rm --jid JID --tag TAG

#Notes

search matches alias, full name, push name, first name, business name, phone, and JID.
search and show combine phone-number and @lid contact rows only when the local WhatsApp session has a verified mapping. Matching names alone never merge contacts. The combined result uses the phone-number JID and its actual phone number; an unmapped @lid stays separate with an empty phone field.
Search matches metadata and stored IDs on either row, as well as the resolved phone number. --limit applies after combining duplicates. A contact stored only as @lid is also searchable by its mapped phone number, including partial numbers.
For combined contacts, local aliases and system names retain their display precedence, with the phone-number row winning conflicts within each field. show accepts either stored JID or the resolved phone-number JID and combines tags. Reading contacts never rewrites their stored rows or metadata.
Alias and tag commands accept either verified identity, including the JID returned by search or show. Changes apply atomically to both identities so removing metadata cannot reveal an older copy on the other row. These local commands read the session mapping without connecting to WhatsApp or modifying its session database; an unreadable session database fails the command before a metadata write.
check connects with the account session and asks WhatsApp's servers whether each number is registered (accepts +E164, common formatting, or user JIDs). Results are reported per query and not stored locally; use --json for scripting. A number the server did not answer for is reported as no response (JSON "responded": false) — treat it as unknown, not as a confirmed negative.
refresh imports contacts from the whatsmeow session store into wacli.db.
import-system imports display names from macOS Contacts by matching phone numbers against already-synced wacli contacts. Run contacts refresh first.
import-system --input FILE reads a JSON array or newline-delimited JSON contacts file with full_name and phones fields instead of opening macOS Contacts.
Imported system names are local wacli metadata. They do not edit WhatsApp contacts or macOS Contacts.
Display precedence is local alias, imported system name, then WhatsApp names.
Use import-system --dry-run before writing. Use import-system --clear to remove imported system names.
See contacts import-system for the full import workflow, JSON shape, file format, and verification steps.
Tags are local grouping metadata for scripts and future workflows.

#Examples

wacli contacts search Alice
wacli contacts show --jid 1234567890@s.whatsapp.net
wacli contacts check +43 664 12345678 --json
wacli contacts refresh
wacli contacts import-system --dry-run
wacli contacts alias set --jid 1234567890@s.whatsapp.net --alias mom
wacli contacts tags add --jid 1234567890@s.whatsapp.net --tag family