Configuration reference
Look up WhatsApp CLI settings, defaults, scopes and environment overrides.
Use this page when you need the exact name, default or scope of a setting, or the name of an environment variable.
It lists every setting wa reads and which value wins.
No setting can hold a secret: the file has no field for the device keys, a phone number or a chat id.
Which value wins
For each setting, the first of these that is set:
- an option on the command line (
--limit 50,--record,--timeout 30s) - an environment variable (
WA_PROFILE,WA_TIMEOUT) - the profile's own entry in the config file
defaultsin the config file, shared by every profile- the built-in default
wa <profile> config show prints each setting in force and where it came from.
The file
~/.config/whatsapp-cli/config.json. No setting picks a profile: the first word (wa work …) or WA_PROFILE names
it. Without either, a command that uses an account stops with exit code 2 and lists the profiles on this computer.
A file that still has default_profile from an older wa stops that command too; wa config unset default_profile
removes it.
The settings for search stemming, phone countries, tasks and account groups (search_stemmers.*, phone_countries,
task_*, account_groups.*) are listed under wa config set.
The file is written 0600 when first created. It holds no secret.
A bot profile
A WhatsApp Business number on Meta's Cloud API (wa <profile> bot …) keeps its settings under bot in the file:
wa <profile> config set --bot <setting> <value>. They are ids from the App Dashboard's API setup page, not secrets;
the access token lives in the system keychain (a WhatsApp Business number as a bot).
Environment variables
| Variable | What it does |
|---|---|
WA_PROFILE | the profile, when the first word does not name one |
WA_PROFILE_LOCK | pins the process to one profile; any other is refused |
WA_TIMEOUT | the same as --timeout: 500ms, 30s or 2m for the whole command |
WA_REQUESTS_PER_MINUTE | the same as requests_per_minute, and wins over it |
WA_CONFIG_DIR, WA_STATE_DIR, WA_CACHE_DIR | move the three directories |
MESSAGING_STORE | the path of the local store file |
WIRECAT_STATE_DIR | the WireCat folder every CLI shares: the local store and the speech models |
WA_READ_ONLY | 1 makes this process read-only: every change, linking and unlinking the device included, is refused |
WA_ENGINE | the path of an engine program to run instead of the installed one |
WA_ENGINE_LOG | a file the engine appends its warnings to, phone numbers masked; unset, it logs nothing |
WA_NO_UPDATE_CHECK | 1 turns off the daily "a newer version exists" line |
NO_COLOR | no colour in the table view |
WA_EMBEDDING_*, WA_ANALYSIS_*, WA_MODELS_* | model settings |