Quickstart

Six steps, about 15 minutes. At the end you have sent your first WhatsApp message from Terminal, read the chat it went to, and listed who is still waiting for your answer. Read this page on the Mac you install on: you copy commands from it into that Mac.

You need: a Mac with macOS 14.4 or later (Apple or Intel), a Mac account that can install software (an administrator account), and the WhatsApp app for Mac, linked to your phone, with your chats showing. To see which macOS you have, open the Apple menu, then About This Mac; the window shows the version. On a work Mac where you cannot install apps, ask whoever manages that Mac.

  1. Download

    Download for Mac

    The file is Namjai-0.2.13.pkg (22.5 MB). Your browser puts it in your Downloads folder. If you already downloaded it from the Overview page, do not download it again: use that file.

    Want to check the file before you install it? (optional)

    This proves your file is exactly the Namjai this guide describes. Do it before step 2. Open Terminal (press Command and Space, type Terminal, press Return) and, if the file is in your Downloads folder, run:

    shasum -a 256 ~/Downloads/Namjai-0.2.13.pkg

    If it is somewhere else, take the other route: type shasum -a 256 with a space at the end, drag the file from Finder into the Terminal window (Terminal types its location for you), and press Return.

    Good result

    One line: a code of 64 letters and digits, two spaces, then where the file is. With your own user name instead of you:

    Terminal
    d24175071641e7c076ebfff81fdabdd6c90a49539f6ca72647f72704aa11ee18  /Users/you/Downloads/Namjai-0.2.13.pkg

    Compare your code with the code of Namjai 0.2.13, here in groups of four:

    d241 7507 1641 e7c0 76eb fff8 1fda bdd6 c90a 4953 9f6c a726 47f7 2704 aa11 ee18

    Check the first four characters (d241), the last four (ee18), and every group in between. If they are all the same, your file is exactly the Namjai 0.2.13 this guide describes. The check proves nothing about a different file or a different version. If the codes differ, do not install; tell the person who gave you the file.

    If you see No such file or directory instead: the file is not in Downloads. Use the other route above: type shasum -a 256 with a space at the end, drag the file from Finder into the Terminal window, and press Return.

    If nothing downloads, ask the person who sent you this guide for the file.

  2. Install

    The installer is not signed with an Apple developer certificate yet, so macOS stops it on almost every Mac the first time you open it. That is expected. A file that did not come through a browser download, such as one copied from a USB stick, carries no warning, and the installer opens straight away. Here is the whole path, in order.

    1. Open your Downloads folder and double-click Namjai-0.2.13.pkg.
    2. macOS shows a warning instead of opening it. If the installer opens straight away with no warning, skip to When the installer opens, below. Otherwise pick your macOS version (Apple menu, About This Mac) and follow its tab:
      1. macOS says: Apple could not verify "Namjai-0.2.13.pkg" is free of malware that may harm your Mac or compromise your privacy. Click Done (not Move to Trash).
      2. Open the Apple menu, then System Settings, then Privacy & Security.
      3. Scroll down to the line about Namjai-0.2.13.pkg and click Open Anyway. Confirm with your Mac password.
      4. If the installer has not opened by itself, double-click Namjai-0.2.13.pkg again. If macOS asks once more, click Open.

      Then carry on with When the installer opens.

    3. When the installer opens: click Continue, then Install, and type your Mac password when asked. Then click Close. The Installer may ask at the end whether to move the installer to the Trash; either answer is fine.
    4. When it finishes, Shortcuts opens a window that asks whether to add the Namjai Send shortcut. Click Add Shortcut. This is the one click that lets Namjai send a WhatsApp message for you, and only when you type nj wp send. If the window did not appear, or you closed it, nothing is lost: step 3 offers it again.

    Namjai is now the command namjai, kept in /usr/local/bin, with the short name nj beside it. Both do the same; this guide uses nj. Nothing appears in your Dock: Namjai has no window, you use it from Terminal.

  3. Connect it to WhatsApp

    Open Terminal, the Mac app where you type commands: press Command and Space, type Terminal, press Return. If no search box opened, open Finder, then Applications, then Utilities, and double-click Terminal.

    Make sure the WhatsApp app is open on this Mac with your chats showing. Click Copy, click inside the Terminal window, press Command and V, then Return:

    nj setup

    If setup prints macOS did not let this program read WhatsApp's chats, open the box below named for it: It says: macOS did not let this program read WhatsApp's chats.

    Permission, two cases: when you run nj setup, macOS can ask whether Terminal may access data from other apps. Click Allow, and nothing more is needed. The other case is the message above, which needs the Full Disk Access steps.

    Its fourth step switches on sending. If you already clicked Add Shortcut at the end of the installer, it says ok and goes on. If not, Shortcuts opens the same window now: click Add Shortcut in it. Either click is enough, and setup waits up to 2 minutes for it. If you do not click, reading still works, and running nj setup again offers it again.

    Its last step sends you one test message. The first time the Namjai Send shortcut sends, macOS asks whether it may send messages with WhatsApp. Setup brings that question up now, so that it does not appear in the middle of your first real message: type your own WhatsApp number with + and the country code and press Return, and when macOS asks, click Always Allow. Setup then says ok, the test message arrived. To skip the step, press Return with nothing typed; nj setup offers it again. Your number is used for this one message and is not saved in the settings.

    Good result: it ends with Ready.

    Terminal
    Step 1 of 5: finding WhatsApp on this computer
      found it
    Step 2 of 5: saving the settings
      saved in /Users/you/Library/Application Support/Namjai/settings.env (time zone Asia/Bangkok)
    Step 3 of 5: checking that it works
    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, 24 messages
    ok   the store has a recent message: the newest is 18m old
    ok   sending WhatsApp messages: not switched on yet; reading WhatsApp does not need it, and nj setup offers it
    --   sending chats to Namjai: not set up; reading WhatsApp on this computer does not need it
    Step 4 of 5: switching on sending
      Shortcuts opened a window that asks whether to add the Namjai Send shortcut.
      Click Add Shortcut in it. Waiting up to 2 minutes for the click.
      ok, the Namjai Send shortcut is in Shortcuts
    Step 5 of 5: sending yourself a test message
      The first time Namjai Send sends, macOS asks whether it may send messages with WhatsApp.
      Click Always Allow in that question, and macOS does not ask again.
      One test message to your own WhatsApp number brings the question up now, not in the middle of your first real message.
      Your own WhatsApp number, with + and the country code (or press Return to skip): +99900000100
      Sending the test message to +99900000100. If macOS asks, click Always Allow.
      ok, the test message arrived at 01:25. Sending is ready.
    
    Ready. Try:  nj wp waiting

    The samples were made in the Asia/Bangkok time zone at one moment. Your dates, times and ages follow your Mac and the moment you run the command.

    The dates and times you see follow your own Mac's time zone, so they differ from the samples on this guide. Your own numbers, time zone and Mac user name appear instead: /Users/you stands for your home folder. The line -- sending chats to Namjai: not set up is expected: the upload to a Namjai server is off (see Privacy). Setup counts its own five steps (Step 1 of 5); they are not the steps of this page.

    Words in the output: the store is the file where WhatsApp keeps your chats on this Mac (a database named ChatStorage.sqlite; nothing to do with the App Store). The reader is the part of Namjai that reads it. settings.env is Namjai's small settings file.

    It says: WhatsApp is not on this computer yet
    Terminal
    Step 1 of 5: finding WhatsApp on this computer
    WhatsApp is not on this computer yet.
      1. Install WhatsApp from the App Store.
      2. Open it and link it to your phone: on the phone, WhatsApp > Settings > Linked Devices > Link a Device.
      3. Wait until your chats appear, then run: nj setup

    Namjai reads the WhatsApp app for Mac, so it must be installed and linked first. Do the three steps it prints. To link: on your phone, open WhatsApp, go to Settings, then Linked Devices, then Link a Device, and scan the code the Mac app shows. When your chats appear on the Mac, run nj setup again.

    It says: macOS did not let this program read WhatsApp's chats
    Terminal
    Step 1 of 5: finding WhatsApp on this computer
    macOS did not let this program read WhatsApp's chats.
      1. Open System Settings > Privacy & Security > Full Disk Access.
      2. Turn on the app you are typing in (Terminal).
      3. Quit that app, open it again, then run: nj setup

    macOS protects other apps' data. Give Terminal permission once, called Full Disk Access:

    1. Open the Apple menu, then System Settings.
    2. Click Privacy & Security, then Full Disk Access.
    3. Find Terminal in the list and turn its switch on. If Terminal is not in the list, click +, open Applications, then Utilities, choose Terminal and click Open. Type your Mac password if asked.
    4. Quit Terminal (Command and Q), open it again, and run nj setup again.

    Full Disk Access stays on for as long as you use Namjai, and it covers everything you run in Terminal, not only Namjai. Turn it off in the same place when you remove Namjai.

    It says: could not read this computer's time zone, or: is not a time zone name

    Setup prints nj setup: could not read this computer's time zone. Run: nj setup --time-zone Asia/Bangkok (with your own zone). This happens when you gave no --time-zone and macOS did not say which zone it is in; it exits with 1. If you did give one and it is not a known name, such as nj setup --time-zone Mars/Base, setup prints nj setup: --time-zone "Mars/Base" is not a time zone name; use one such as Asia/Jerusalem or America/New_York, then See: nj help, and exits with 2. Either way, run setup again with your own time zone's name. The name is a region, a slash, then a city, in English, with _ instead of a space. Four examples:

    • Israel: Asia/Jerusalem
    • United Kingdom: Europe/London
    • New York and the US east coast: America/New_York
    • Thailand: Asia/Bangkok

    An example to edit: change Asia/Bangkok to your own zone before you press Return (see How to change an example word).

    nj setup --time-zone Asia/Bangkok
    It says: command not found
    Terminal
    zsh: command not found: nj

    The installer puts Namjai in /usr/local/bin, a folder every new Terminal window looks in. Open a new Terminal window (Command and N) and run the command again. If it still says this, the installer did not finish: install again. To check the install by itself, run this; it prints the version:

    nj version
    Terminal
    namjai 0.2.13

    The version line says namjai whichever name you type.

  4. Send your first message

    Send a message to someone you already chat with on WhatsApp. First check it with --dry-run: Namjai finds the chat and says who it would send to, and sends nothing. Change laura to part of a name in your own WhatsApp, and the text to your own (see How to change an example word):

    nj wp send laura "Yes, the Tokyo tour in April has places. Shall I hold two for you?" --dry-run
    Terminal
    Would send 66 characters to Laura Kim (+99900000419). Nothing was sent: --dry-run.

    If the name in brackets is the person you meant, send it: the same command without --dry-run.

    nj wp send laura "Yes, the Tokyo tour in April has places. Shall I hold two for you?"
    Terminal
    sent to Laura Kim at 01:25

    Nothing opens on your screen. Namjai hands the message to WhatsApp through the Namjai Send shortcut, then finds it in WhatsApp on this Mac before it prints sent to. If macOS asks whether Namjai Send may send messages with WhatsApp, click Always Allow; the test message in step 3 is there so that you have already answered it. If it says the shortcut is not in Shortcuts, run nj setup again and click Add Shortcut.

    Someone you have never written to: give their whole number with + and the country code, and add --new, such as nj wp send +99900000499 "Hello" --new. Without --new, a number with no chat on this Mac is refused, so a mistyped number does not reach a stranger. The record of sends: every attempt, dry runs too, is one line in sends.jsonl in ~/Library/Application Support/Namjai/state on this Mac: when, to which number, how it ended, and the length of the text, never the text itself. See send.

  5. Read the chat

    Read the chat the message went to. Your message is the last line, after You:.

    nj wp read laura
    Terminal
    Chat with Laura Kim
    
    Nov 18 01:07  Laura Kim: Hi, is the Tokyo tour in April still available?
    Nov 18 01:25  You: Yes, the Tokyo tour in April has places. Shall I hold two for you?
    2 messages
  6. List who is waiting

    Who wrote to you and is still waiting for your reply? Commands about WhatsApp start with nj wp: wp stands for WhatsApp.

    nj wp waiting
    Terminal
         47m  Dana Levi · unread
              them: And can we get a late checkout?
      3h 10m  Sarah Cohen · unread
              them: Can you send the flight times for the 14th?
      5h 20m  ⁨יעל אברהם⁩‎ · unread
              them: ⁨שלום, יש מקום פנוי לטיסה לאילת ביום שלישי?⁩‎
          1d  James Carter · unread · archived
              them: Hi again, we want to book the same hotel for Easter
    4 people waiting for your answer in the last 7d. For longer: nj wp waiting --within 30d

    The person you just answered is not on the list any more: the last message in that chat is now yours. "Waiting" means a one-to-one chat whose last message is theirs. Namjai does not read what the message says, so a closing "Thanks!" from them counts as waiting, and a question you answered with "will check" does not. Groups and WhatsApp's own notices chat are left out; to see groups with unread messages, use nj wp new.

    • The number on the left is how long they have been waiting since their last message.
    • Under each name is that last message, after them:; unread and archived describe the chat.
    • By default you see people waiting 15 minutes or more, over the last 7 days.

    Also a good result: nobody is waiting

    Terminal
    0 people waiting for your answer in the last 7d. For longer: nj wp waiting --within 30d

    This means nobody in a one-to-one chat has a last message that is theirs and between 15 minutes and 7 days old, as far as this Mac has synced (see What Namjai sees).

    It says: nj: configuration
    Terminal
    nj: configuration:
    NAMJAI_WHATSAPP_STORE is not set: give it the path of WhatsApp's ChatStorage.sqlite on this computer
    NAMJAI_TIME_ZONE must be an IANA time zone name such as Asia/Bangkok, got ""
    If you have not yet, run: nj setup

    Setup has not been run on this Mac account. Do step 3.

    How to change an example word in a command

    How to run any command on this guide: click its Copy button, click inside the Terminal window, press Command and V to paste, then press Return. The $ in front of each command is only a marker on this guide; it is not copied and you do not type it.

    Words to change: a word with a dashed line under it is an example, such as dana. The easy way: type the command yourself, with your own word in place of the underlined one, then press Return.

    Or with the arrow keys: Terminal does not show the line, so note the word before you paste. After pasting, the cursor is at the end of the line. Press the left arrow until the cursor is just after the example word, press Delete once per letter of that word, type your own, then press Return. You do not need to move back to the end first.

    Two marked words, worked through: to search for flight in Sarah's chat, paste nj wp search hotel --chat dana. The cursor is already just after dana: press Delete 4 times and type sarah. Then press the left arrow 13 times (the 5 letters of sarah and the 8 characters of --chat , both spaces included), so the cursor is just after hotel. Press Delete 5 times, type flight, and press Return. Terminal now runs nj wp search flight --chat sarah and prints:

    Terminal
    Nov 17 22:15  Sarah Cohen: Can you send the flight times for the 14th?
    1 message

    If it prints 0 messages, check the word you typed: no message in that chat holds it.

    What next

    Follow Next through the guides to the Cheat sheet; that is everything for daily use. The rest is reference.

If you need more

Something looks wrong: run the health check

The command to run any time something looks wrong:

nj wp doctor

Good result

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, 24 messages
ok   the store has a recent message: the newest is 18m 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

How to read it: every line starts with ok, or with FAIL and the reason. A line that starts with -- is a part you have not set up, which is fine: the upload to a Namjai server is not needed to read your WhatsApp. The line the store has a recent message prints how old the newest message on this Mac is. It fails only when there is no message at all, so if the newest message is hours or days old, open WhatsApp on the Mac and let it catch up, unless nobody has written to you since then.

If you see this instead: FAIL the settings to read WhatsApp are set

Terminal
FAIL the settings to read WhatsApp are set: NAMJAI_WHATSAPP_STORE is not set: give it the path of WhatsApp's ChatStorage.sqlite on this computer; NAMJAI_TIME_ZONE must be an IANA time zone name such as Asia/Bangkok, got ""
ok   sending WhatsApp messages: not switched on yet; reading WhatsApp does not need it, and nj setup offers it
--   sending chats to Namjai: not set up; reading WhatsApp on this computer does not need it

The capitalised names in the first line are Namjai's own setting names; you do not need them. Setup has not finished on this Mac account. Go back to step 3 and run nj setup until it ends with Ready. For anything else, see Troubleshooting.