Install wa

Connect your WhatsApp account to an AI agent on your computer. When you finish, the agent can read saved chats, find messages and prepare replies. Keep your phone signed in to WhatsApp nearby and allow about five minutes for recent history to arrive.

The stepsCopy Anchor Link

1. Install wa: the command-line tool and its WhatsApp engine.
2. Link your account: scan a QR code in WhatsApp on your phone.
3. Connect your agent: install its instructions, called a skill.
4. Check the result: see the selected account and a few saved chats.

This is an unofficial client. Read security and limits before linking; WhatsApp can restrict or ban accounts using unofficial clients.

1. Install waCopy Anchor Link

With your agentCopy Anchor Link

Use an agent with terminal access on this computer, such as Codex, Claude Code, Cursor or Gemini CLI. For a browser-only chat, use web or mobile access instead.

Use wa CLI. Help connect my WhatsApp account to my AI agent. Follow https://wirecat.dev/en/docs/wa/installation. Check the required programs and install the tool. Ask which account and profile name I want; personal is an example. I will approve device linking on my phone. Install the skill and show my account and a few chats. Do not send messages or start background work without asking.

By hand in a terminalCopy Anchor Link

Open Terminal on macOS or Linux, or PowerShell on Windows. You need Node.js 22.16 or later within 22.x, or 24 or later, with npm; see runtime setup.

npm install -g @wirecat/whatsapp-cli
wa --version
wa doctor

Keep optional packages enabled: npm installs the WhatsApp engine for your operating system and processor. A manager may report blocked install scripts; check the installation with the commands below. If the engine is missing, see troubleshooting. On Windows, open a new terminal if the command is not found.

2. Link your WhatsApp accountCopy Anchor Link

In these examples, personal names a profile: one linked account on this computer. Choose any name and repeat it in later commands. The tool never chooses an account for you.

wa personal setup

1. Run setup in the terminal. It checks folders and starts device linking; an already linked profile is reused.
2. On your phone, open WhatsApp → Settings → Linked devices → Link a device. Use the scanner inside WhatsApp to scan the QR shown by setup.
3. Keep WhatsApp open while recent chats arrive. Setup checks your account and up to five saved chats, then offers the agent skill.

This adds a linked device, like WhatsApp Web. Remove it at any time from Linked devices on your phone. If you prefer a pairing code, use wa personal setup --method phone; the number is entered in the terminal. Complete the confirmation yourself. Older history is a separate request to the phone.

3. Connect your agentCopy Anchor Link

A skill is a short instruction file that tells a terminal agent how to use wa. Setup can install it for your chosen agent. To install it separately:

wa skill install --for all

An app without terminal access can use MCP. Choose the profile’s permissions before connecting: MCP offers writing commands as well as reading commands.

4. Check the resultCopy Anchor Link

wa personal account show
wa personal chats list --limit 5

The account must be the one you chose on your phone. The chat list comes from saved history and sends no read receipts. Empty or incomplete history is not evidence that a chat has no messages; see history coverage.

To keep receiving new messages, run wa personal serve in a terminal; Ctrl-C stops it. Only one connection can use a linked device. Read the connection rule before running another connected command.

Questions and answersCopy Anchor Link

The QR code is not visibleCopy Anchor Link

Ask your agent to show the terminal or paste the text QR into the chat. Use WhatsApp’s scanner. If the terminal is too narrow, widen it and wait for the next QR. Other linking failures are covered in troubleshooting.

Advanced installation and maintenanceCopy Anchor Link

git clone https://github.com/WireCatLabs/whatsapp-cli.git
cd whatsapp-cli
pnpm install
pnpm build
pnpm engine:build   # needs Go
node dist/bin/wa.js --version

Where files goCopy Anchor Link

The device keys, the settings and the local store each have their own place: where the parts are kept.

UpgradeCopy Anchor Link

wa upgrade            # with the package manager that installed wa
wa upgrade --check    # only say whether a newer version exists; installs nothing

upgrade asks npm, so --offline is refused with exit code 2. upgrade --check runs under WA_READ_ONLY; upgrade without it does not.

After an update, wa upgrade restarts each running background serve, so it does not keep running the old code. The engine comes as a package of wa, so it updates with it. Once a day wa says on stderr when a newer version exists; WA_NO_UPDATE_CHECK=1, or update_check: false in the settings, turns that off.

From source: git pull && pnpm install && pnpm build && pnpm engine:build.

UninstallCopy Anchor Link

Removing the command leaves your data. Unlink first, while wa is still there:

wa personal server uninstall         # if you installed the background unit; stop it first
wa personal session end              # unlinks the device on WhatsApp's side and deletes its keys here
npm uninstall -g @wirecat/whatsapp-cli
rm -rf ~/.config/whatsapp-cli ~/.local/share/whatsapp-cli ~/.cache/whatsapp-cli

Repeat session end for each profile. The local store is shared with other WireCat tools. Delete ~/.local/share/WireCat/ only if nothing else uses it: it holds the messages every one of them has kept.

NextCopy Anchor Link

Link a profile and read your first chats.