Commands: find, read, search and send

Find a person or chat, read a chat, search your messages, and send a message to one person.

find

Find a contact or chat by part of its name, by a person's number, or by its exact chat ID.

nj wp find [words] [--limit n]

What you type is read one of three ways. Words match the chat's name only: it lists every chat, groups included, whose name holds them (capitals do not matter). A number, digits only with or without a leading +, matches one-to-one chats only: those whose number holds those digits, so +99900000411 finds that person's own chat and never a group they are in. A number with spaces in it is read as words, so type it without spaces. Something with @ must equal a whole WhatsApp chat ID, such as 99900000411-1731600000@g.us, and finds that one chat. A group is found by its name or by its exact chat ID. When nothing matches it prints 0 chats, exit code 0. With no words, it lists every chat. Newest last message first. The lines and columns are the chat lines and columns of the lists; the count line is 1 chat or 3 chats.

OptionDefaultAccepted valuesWhat it does
--limit n50a whole number, 1 or moreMost chats printed.
--text, --table, --csv, --json, --format namewhat nj set format saved, else texttext, table, csv, jsonThe same result in another format. See Formats and spreadsheets.

Mistakes. A mistake prints one line that says what was wrong, then See: nj help, to the error output, and exits with 2. A value it cannot use: nj wp find: --limit must be a whole number above 0, got "many"; nj wp find: --limit needs a value. An option it does not take: nj wp find: --chat is not an option of this command; it takes --csv, --format, --json, --limit, --table, --text. Two different formats: nj wp find: choose one format, not both --csv and --json. Every word after find is part of what it looks for, so there is no stray word; with no words it lists every chat.

nj wp find +99900000411
Terminal
     47m  Dana Levi · unread
          them: And can we get a late checkout?
1 chat
nj wp find trip --table
Terminal
chat_id                      name                kind   unread  archived  last_at                    last_from  minutes_since_last  last_kind  last_text
99900000411-1731600000@g.us  Phuket trip, March  group  1       false     2026-11-18T00:59:00+07:00  them       26                  text       Which day is the boat trip?

read

Read a chat: its last messages, oldest first.

nj wp read name [--limit n]

The words name the chat, read the three ways find reads them: words match the name, a number matches a person's own chat, and something with @ must equal a whole chat ID. A number that starts with + must be the person's whole number. When one chat matches, or when several match and exactly one has that whole name (capitals do not matter) or that whole number, it is that chat. A group is read by its name or its exact chat ID. A name, number or chat ID that matches no chat prints the no chat matches line below and exits with 1. Prints the last --limit messages (50), oldest first, notices included. Reading changes nothing in WhatsApp: it does not mark the chat read.

As text: Chat with and the name, an empty line, then one line per message: the day and time, who sent it (You, the person's name, or in a group the sender's number), and its text, cut at 90 characters, or its kind in brackets. The last line counts the messages. Words are required: nj wp read alone prints nj wp read: needs the name or number of a chat and See: nj help, and exits with 2.

OptionDefaultAccepted valuesWhat it does
--limit n50a whole number, 1 or moreHow many of the last messages to print.
--text, --table, --csv, --json, --format namewhat nj set format saved, else texttext, table, csv, jsonThe same result in another format. See Formats and spreadsheets.

Mistakes. A mistake prints one line that says what was wrong, then See: nj help, to the error output, and exits with 2. A value it cannot use: nj wp read: --limit must be a whole number above 0, got "many"; nj wp read: --limit needs a value. An option it does not take: nj wp read: --within is not an option of this command; it takes --csv, --format, --json, --limit, --table, --text. Two different formats: nj wp read: choose one format, not both --csv and --json. Every word after read is part of the name, so a stray word changes the name it looks for. No words: nj wp read: needs the name or number of a chat.

nj wp read dana --limit 3
Terminal
Chat with Dana Levi

Nov 13 01:25  You: Bangkok-options.pdf
Nov 18 00:33  Dana Levi: Thanks! Is breakfast included at the riverside hotel?
Nov 18 00:38  Dana Levi: And can we get a late checkout?
3 messages
Terminal: nj wp read a
nj wp read: 7 chats match "a":
  Laura Kim
  Phuket trip, March
  Dana Levi
  Sarah Cohen
  James Carter
  Michael Brooks
  Daniel Reed
Use more of the name, or the number
Terminal: nj wp read +9990000041
nj wp read: 9 chats match "+9990000041":
  Laura Kim
  Dana Levi
  Sarah Cohen
  ⁨יעל אברהם⁩‎
  James Carter
  Michael Brooks
  Emily Turner
  ⁨אורי מזרחי⁩‎
  …
Use the whole number, or more of the name
MessageCauseExit code
nj wp read: no chat matches "name". To list every chat: nj wp findNo chat's name holds those words, no person's number holds that number, or no chat has that chat ID. Someone who only called you has no chat: nj wp calls shows them1
nj wp read: 7 chats match "a":, then up to eight names, one per line, then Use more of the name, or the numberSeveral chats' names hold those words, and none has exactly that name1
nj wp read: 9 chats match "+9990000041":, then the names, one per line, then Use the whole number, or more of the namePart of a number: several people's numbers hold those digits, and none is exactly that number1

Search your messages for some text, in every chat or in one.

nj wp search words [--chat name] [--limit n]

Lists messages whose text holds the words, as one piece of text with the spaces in it. Capitals do not matter for the letters A to Z; for other letters, such as Hebrew, the text must match exactly. Newest first, at most --limit (50). Each line: the day and time, the chat in brackets when the sender is not the chat's name (in a group, or your own message), who sent it, and the text. The last line counts the messages; 0 messages when no message holds the words (exit code 0). With --chat, the chat is found as for read; the line it prints when that matches no chat is under Mistakes, below. Words are required.

OptionDefaultAccepted valuesWhat it does
--chat nameevery chata name, part of a name, a person's number, or a whole chat ID, found as for readSearch one chat only.
--limit n50a whole number, 1 or moreMost messages printed.
--text, --table, --csv, --json, --format namewhat nj set format saved, else texttext, table, csv, jsonThe same result in another format. See Formats and spreadsheets.

Mistakes. A mistake prints one line that says what was wrong, then See: nj help, to the error output, and exits with 2. A value it cannot use: nj wp search: --limit must be a whole number above 0, got "many"; nj wp search: --chat needs a value. An option it does not take: nj wp search: --within is not an option of this command; it takes --chat, --csv, --format, --json, --limit, --table, --text. Two different formats: nj wp search: choose one format, not both --csv and --json. Every word after search is one of the words it looks for, so there is no stray word. A --chat that matches no chat prints nj wp search: no chat matches "nobody". To list every chat: nj wp find and exits with 1. No words: nj wp search: needs the words to search for.

nj wp search hotel --limit 2
Terminal
Nov 18 00:33  Dana Levi: Thanks! Is breakfast included at the riverside hotel?
Nov 16 21:25  James Carter: Hi again, we want to book the same hotel for Easter
2 messages
nj wp search hotel --csv
Terminal
at,chat_id,chat_name,from,kind,text
2026-11-18T00:33:00+07:00,99900000411@s.whatsapp.net,Dana Levi,+99900000411,text,Thanks! Is breakfast included at the riverside hotel?
2026-11-16T21:25:00+07:00,99900000416@s.whatsapp.net,James Carter,+99900000416,text,"Hi again, we want to book the same hotel for Easter"

send

Send a WhatsApp message to one person, with nothing on your screen, and check that it arrived.

nj wp send chat "text" [--dry-run] [--new]

It takes two words: the chat, found as for read, and the text, in quotes when it holds a space. The chat must be one person's chat that WhatsApp keeps with a phone number; a group, or a chat WhatsApp keeps under a hidden ID only, is refused with one line and exit code 1. The message goes to that person's number, never to a name. A whole number with + that has no chat on this Mac is refused too, with a line that says to add --new.

The send runs the Namjai Send shortcut in Apple's Shortcuts, which you add with one click at the end of the installer or of nj setup (or with nj wp send-setup). It hands the shortcut the number and the text in a file in a new private folder, removed after. Then it looks in WhatsApp's store on this Mac, for up to 15 seconds, for a message from you with exactly that text. Found once in that chat: it prints sent to name at HH:MM and exits with 0. Found in another chat, found more than once, or not found: one line that says which, and to look at the chat before sending again, exit code 1.

Every attempt is recorded in sends.jsonl, in the state folder (NAMJAI_STATE_DIR, which nj setup saves): one line when the attempt starts and one with how it ended, each with the time, the number, the chat it was meant for, the length of the text and its SHA-256, and the chat it landed in. The text itself is never written there. With no state folder it sends nothing and says to run nj setup.

OptionDefaultAccepted valuesWhat it does
--dry-runoffno valueEvery check, and a record line with the outcome dry run; prints who it would send to and how many characters, and sends nothing.
--newoffno value; the chat must be a whole number with +Writes to a number that has no chat on this Mac yet. The message then counts as sent when it is found once in any chat.

Check first with --dry-run: it finds the chat, writes a record line and sends nothing.

nj wp send dana "Yes, breakfast is included, and late checkout is fine until 2pm" --dry-run
Terminal
Would send 63 characters to Dana Levi (+99900000411). Nothing was sent: --dry-run.

Then send. The line says which chat the message was found in, and when:

nj wp send dana "Yes, breakfast is included, and late checkout is fine until 2pm"
Terminal
sent to Dana Levi at 01:25

A group is refused, and so is a number that has no chat on this Mac, until you add --new:

nj wp send phuket "The boat trip is on Thursday"
Terminal
nj wp send: Phuket trip, March is a group; send works for one person's chat in this version
nj wp send +99900000499 "Hello from the travel agency"
Terminal
nj wp send: WhatsApp on this computer has no chat with +99900000499. To write to a number for the first time, add --new: nj wp send +99900000499 "TEXT" --new
nj wp send +99900000499 "Hello from the travel agency" --new
Terminal
sent to +99900000499 at 01:25

The record of those sends, with no text in it:

cat ~/Library/Application\ Support/Namjai/state/sends.jsonl
Terminal
{"at":"2026-11-17T18:25:09.589Z","number":"+99900000411","expected_chat":"99900000411@s.whatsapp.net","text_sha256":"b7c4752ccacf8feaaaf2d5b8275ff291d0d853e98d506b673fce4a1588478a91","text_length":26,"outcome":"started","landed_in":""}
{"at":"2026-11-17T18:25:09.589Z","number":"+99900000411","expected_chat":"99900000411@s.whatsapp.net","text_sha256":"b7c4752ccacf8feaaaf2d5b8275ff291d0d853e98d506b673fce4a1588478a91","text_length":26,"outcome":"no shortcut","landed_in":""}
{"at":"2026-11-17T18:25:09.662Z","number":"+99900000411","expected_chat":"99900000411@s.whatsapp.net","text_sha256":"2e9aedfe04119eb1c16345ef6ba2f5ed80df9eb6bdc604d73b651c9cd50440e7","text_length":63,"outcome":"dry run","landed_in":""}
{"at":"2026-11-17T18:25:09.67Z","number":"+99900000411","expected_chat":"99900000411@s.whatsapp.net","text_sha256":"2e9aedfe04119eb1c16345ef6ba2f5ed80df9eb6bdc604d73b651c9cd50440e7","text_length":63,"outcome":"started","landed_in":""}
{"at":"2026-11-17T18:25:09.67Z","number":"+99900000411","expected_chat":"99900000411@s.whatsapp.net","text_sha256":"2e9aedfe04119eb1c16345ef6ba2f5ed80df9eb6bdc604d73b651c9cd50440e7","text_length":63,"outcome":"sent","landed_in":"99900000411@s.whatsapp.net"}
{"at":"2026-11-17T18:25:09.707Z","number":"+99900000499","expected_chat":"99900000499@s.whatsapp.net","text_sha256":"22a29845fc3f962d6ff6a7d3c831b51450b6dbea76302971edb1a992a9584995","text_length":28,"outcome":"started","landed_in":""}
{"at":"2026-11-17T18:25:09.707Z","number":"+99900000499","expected_chat":"99900000499@s.whatsapp.net","text_sha256":"22a29845fc3f962d6ff6a7d3c831b51450b6dbea76302971edb1a992a9584995","text_length":28,"outcome":"sent","landed_in":"99900000499@s.whatsapp.net"}

It takes no format options. A mistake prints one line, then See: nj help, and exits with 2: no words, one word, more than two, an empty text, --new with a name, or an option it does not take.

send-setup

Switch sending on, when the Add Shortcut window was closed without a click. You do not need it after a normal install: the installer and nj setup already offer the same window.

nj wp send-setup

Opens the Namjai Send shortcut that comes with Namjai, signed by Apple for any Mac, in Shortcuts, which asks whether to add it. Click Add Shortcut. When the shortcut is already there it says so and changes nothing. nj wp doctor says whether sending is switched on. It takes no words or options.

Without the shortcut, a send stops and says what to run:

nj wp send dana "Yes, breakfast is included"
Terminal
nj wp send: the Namjai Send shortcut is not in Shortcuts on this Mac, so nothing was sent. Set it up with: nj wp send-setup
nj wp send-setup
Terminal
Shortcuts opened the Namjai Send shortcut, in a window that asks whether to add it.
Click Add Shortcut. Nothing is sent until you run nj wp send.
To test it without sending: nj wp send --dry-run NAME "Hello"

Run again once the shortcut is added:

nj wp send-setup
Terminal
Sending is already set up: the Namjai Send shortcut is in Shortcuts on this Mac. Nothing was changed.

The health check then says sending is set up:

nj wp doctor
Terminal
ok   the settings to read WhatsApp are set: yes
ok   the WhatsApp store opens read-only: yes
ok   the store has every column the reader uses: yes
ok   the store answers a count: 10 chats, 25 messages
ok   the store has a recent message: the newest is 0m old
ok   sending WhatsApp messages: set up, the Namjai Send shortcut is in Shortcuts
--   sending chats to Namjai: not set up; reading WhatsApp on this computer does not need it

Columns of read and search

With --table, --csv or --json, read and search print one row per message:

ColumnMeaningValues
atWhen the message was sent, in your time zonea date and time such as 2026-11-17T08:21:10+07:00
chat_idWhatsApp's ID of the chatas for the chat lists
chat_nameThe name WhatsApp shows for the chattext, or empty
fromWho sent itme for you; otherwise the sender's number, such as +99900000411, or a WhatsApp ID when there is no number
kindThe kind of messagethe kinds listed for last_kind on the lists page, plus system for a notice
textThe message text, wholetext; empty for most pictures, files and voice notes