Commands: setup, health check, format, version and help

Set Namjai up, check its health, choose a format, see the version, and get help.

setup

Connect Namjai to the WhatsApp on this Mac. Run it once; run it again any time to change the WhatsApp file or the time zone. See Quickstart, step 3 for the guided steps.

nj setup [--store path] [--time-zone name]

In five steps it finds WhatsApp's chat file, saves the settings to ~/Library/Application Support/Namjai/settings.env (see Settings), runs the health check, switches on sending, and offers to send you one test message. For the fourth step, when the Namjai Send shortcut is not yet in Apple's Shortcuts, it opens the window that asks whether to add it, the same window the installer opens when it finishes, and waits up to 2 minutes for you to click Add Shortcut; when the shortcut is there it prints one ok line and opens nothing. If no click comes it prints The shortcut was not added within 2 minutes. Reading works; sending is not switched on yet: nj setup or nj wp send-setup offers it again. and still ends ready, since reading does not need it. The fifth step is offered when the shortcut is in Shortcuts and you run setup in Terminal. It says that macOS asks, the first time Namjai Send sends, whether it may send messages with WhatsApp, and that you should click Always Allow; then it asks for your own WhatsApp number with + and the country code, sends one fixed test message to it the way nj wp send does (recorded in sends.jsonl, without the text), and prints ok, the test message arrived at 23:19. Sending is ready. Press Return with nothing typed, or type no, to skip it. It does not save the number. When NAMJAI_WHATSAPP_ACCOUNT is already set it offers that number and asks for yes. When the message does not arrive it prints not done: with the reason, says to click Always Allow if macOS is still asking and to run nj setup again, and ends with Ready, except step 5: the test message is not done yet. Reading works. Try: nj wp waiting and exit code 0. When no one is at a terminal, or the shortcut is not there, it prints one line that starts with skipped:. No program can click Always Allow for you. It keeps any other value already in that file. It ends with Ready. Try: nj wp waiting and exit code 0, or Setup is not finished: fix the lines marked FAIL and run nj setup again. and exit code 1. It takes no words.

OptionDefaultAccepted valuesWhat it does
--store path~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlitethe place of WhatsApp's ChatStorage.sqliteUse a WhatsApp chat file in another place.
--time-zone namethe Mac's own time zonea zone name such as Asia/Bangkok or Europe/LondonUse this time zone for every date and time.
MessageCauseExit code
nj setup: could not read this computer's time zone. Run: nj setup --time-zone Asia/Bangkok (with your own zone)No --time-zone was given and the Mac's own time zone cannot be read1
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 helpThe --time-zone you typed is not a known zone name; the sample below shows it2
WhatsApp is not on this computer yet. and three stepsThere is no WhatsApp chat file at that place1
macOS did not let this program read WhatsApp's chats. and three stepsTerminal has no Full Disk Access1
nj setup: and a reasonThe settings file cannot be read or written, or another error opening the file1
nj setup: does not take words, got "extra"Words after setup2
nj setup: --bogus is not an option of this command; it takes --store, --time-zoneAn option it does not take2
nj setup: --time-zone needs a valueAn option with no value after it2
nj setup
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): 
  skipped. To do it later, run nj setup again.

Ready. Try:  nj wp waiting

The sample above skips the test message with Return; the one in Quickstart, step 3 sends it.

Terminal: nj setup --time-zone Mars/Base
nj setup: --time-zone "Mars/Base" is not a time zone name; use one such as Asia/Jerusalem or America/New_York
See: nj help

wp doctor

The health check. Checks that Namjai can read WhatsApp here, and whether sending is switched on, and changes nothing.

nj wp doctor

Prints one line per check. Each starts with ok, FAIL or -- (a part you have not set up, which is fine), then what was checked and what was found. Every line goes to the normal output. Exit code 0 when no line says FAIL, 1 when one does. It takes no words and no options: nj wp doctor extra prints nj wp doctor: does not take words or options, got "extra" and See: nj help, and exits with 2. Every line it can print:

LineWhat it checksWhat makes it FAIL
the settings to read WhatsApp are setThat NAMJAI_WHATSAPP_STORE and NAMJAI_TIME_ZONE are set and the zone is a real oneA missing or wrong setting; the line gives the reason. The four store lines are then skipped.
the WhatsApp store opens read-onlyThat WhatsApp's chat file exists and opensThe file is missing (stat ...: no such file or directory) or cannot be opened. The next three lines are then skipped.
the store has every column the reader usesThat WhatsApp's file still has every part Namjai readsA WhatsApp update changed the file; the line says missing and names each part.
the store answers a countCounts chats and messagesThe file cannot be read; otherwise it shows 10 chats, 24 messages, with the real numbers.
the store has a recent messageHow old the newest message is, such as the newest is 1h 19m oldThe file holds no message: it holds no message. An old message does not fail.
sending WhatsApp messagesWhether the Namjai Send shortcut is in Apple's Shortcuts: set up, the Namjai Send shortcut is in Shortcuts, or not switched on yet; reading WhatsApp does not need it, and nj setup offers it (see setup and send-setup). It cannot tell whether you clicked Always Allow when macOS asked; the test message in setup shows thatNever; sending is optional, so the line says ok either way and its words say which.
-- sending chats to NamjaiShown when no server is set: not set up; reading WhatsApp on this computer does not need itNever; -- is not a failure.
the settings to send to Namjai are setShown when a server is set: every setting nj wp sync needs; then yes, 0 chats marked clientA missing or wrong setting. The next three lines are then skipped.
the state directory can be writtenThat NAMJAI_STATE_DIR can be made and writtenThe folder cannot be made or written; the line gives the reason.
the outbox opensThat the outbox opens with its key; then yes, 0 items waiting to be sentThe outbox cannot be opened or read.
the Namjai server answersAsks the server's /healthz addressNo answer (the line gives the reason), or an answer other than 200 OK.
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, 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

On a Mac account where setup was never run:

Terminal: nj wp doctor, before setup
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

When WhatsApp's file holds no message yet:

Terminal: nj wp doctor, with no messages
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, 0 messages
FAIL the store has a recent message: it holds no message
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

set format

Choose the format every wp command prints when you add none.

nj set format text|table|csv|json

Saves NAMJAI_OUTPUT_FORMAT in the settings file. Capitals do not matter. text is the normal lines. A format option on a command (--text, --table, --csv, --json) wins over it. It confirms with Saved. Every nj wp list now prints json unless you add --text, --table, --csv or --json., with the format you chose. Exactly one word. With none it prints nj set format: needs one of text, table, csv or json; an unknown format prints nj set format: must be text, table, csv or json, got "pdf" with what you typed; more than one word prints nj set format: takes one word, got "text extra"; each is followed by See: nj help and exits with 2; a file that cannot be written prints nj set format: and the reason, exit code 1.

nj set format json
Terminal
Saved. Every nj wp list now prints json unless you add --text, --table, --csv or --json.
Terminal: nj set format pdf
nj set format: must be text, table, csv or json, got "pdf"
See: nj help
nj set format text
Terminal
Saved. Every nj wp list now prints text unless you add --text, --table, --csv or --json.

update

nj update [--check]

Puts the newest Namjai on this Mac. It reads release.json at the download address, which says the newest version, its installer's file name, size and SHA-256. When that version is not newer than yours it prints You have namjai 0.2.8, the newest version. and exits with 0; an equal or older version on the server is never installed. Otherwise it downloads the installer into a private folder, checks its size and SHA-256 against release.json, says that macOS will ask for your Mac password, and runs Apple's installer with sudo. Type your Mac password when asked (nothing shows while you type it). Then it runs the installed program's version and prints updated 0.2.8 -> 0.2.9 with the two versions. Your settings stay as they are.

The download address. You type none. The installer carries the address of the site it was downloaded from, in /usr/local/share/namjai/installer-defaults.env, so nj update works straight after you install. An address saved with nj set download wins over the installer's, and a NAMJAI_DOWNLOAD_ADDRESS in the environment wins over both. Only an installer made without a site address (0.2.12 and older) leaves none; then nj update prints nj update: no download address is set. Install the newest installer from the Namjai guide, or run: nj set download ADDRESS and exits with 1.

Mistakes.

MessageCauseExit code
nj update: NAMJAI_DOWNLOAD_ADDRESS must be an https address, got the address. Fix it with: nj set download ADDRESSThe address in the environment, the settings file or the installer's file is not https://1
nj update: could not read the newest version: and the reasonThe address did not answer, or did not hold a release.json1
nj update: the download of Namjai-0.2.9.pkg does not have the size and SHA-256 that release.json gives, so it was deleted and nothing was installedThe file changed on the way, or on the server1
nj update: the installer did not finish, the reason and the version you still haveThe password was refused three times, or the installer failed1
nj update: the installer finished, but and what version saysThe installer ran, but the program in /usr/local/bin still says the old version1
Terminal: nj update, with no download address
nj update: no download address is set. Install the newest installer from the Namjai guide, or run: nj set download ADDRESS
OptionWhat it does
--checkOnly says whether a newer version is there. Downloads and installs nothing; exit code 0 either way
nj update --check
Terminal
namjai 0.2.14 is available, you have 0.2.13. To install it: nj update
nj update
Terminal
Downloaded namjai 0.2.14 and checked it. macOS will ask for your Mac password to install it.
installer: Package name is Namjai
installer: Installing at base path /
installer: The install was successful.
updated 0.2.13 -> 0.2.14
nj version
Terminal
namjai 0.2.14

Version 0.2.8 and older do not have update: they answer nj: "update" is not a command. Update those once by hand, as in Update or remove.

set download

nj set download ADDRESS

Saves NAMJAI_DOWNLOAD_ADDRESS in the settings file, over the address the installer carries: the address of a Namjai guide, where nj update finds release.json and the installer. It must start with https://, because what it serves gets installed on your Mac; a slash at the end is dropped. A NAMJAI_DOWNLOAD_ADDRESS in the environment wins over the saved one. You need it only to update from a different guide. With no address it prints nj set download: needs the address of the Namjai guide you were given, such as https://docs.example.com/namjai; an address that is not one prints nj set download: must be an https address, got "guide.example.com"; two words print nj set download: takes one address, got "a b"; each is followed by See: nj help and exits with 2.

nj set download https://guide.example.com/namjai
Terminal
Saved. nj update now looks for the newest version at https://guide.example.com/namjai

remove

nj remove [--dry-run] [--yes]

Takes Namjai off this Mac. It first prints exactly what it will remove, then asks you to type yes; any other answer removes nothing and exits with 0. Then it deletes Namjai's own folder, ~/Library/Application Support/Namjai (settings, the record of sends, the outbox), and, with one call that asks for your Mac password (nothing shows while you type it), the shortcut file in /usr/local/share/namjai, the installer's records com.natandahan.namjai and namjai.desktop, and the program under both names, /usr/local/bin/nj and /usr/local/bin/namjai. It does not touch WhatsApp or any chat, or files you saved yourself, such as waiting.csv. A state or outbox folder you set outside Namjai's own folder is left in place and named.

The Namjai Send shortcut. macOS gives no command to delete a shortcut, so one step stays with you. When the shortcut is still there at the end, nj remove opens the Shortcuts app and prints the clicks: All Shortcuts, hold Control and click Namjai Send, Delete. When Shortcuts cannot be opened it prints the clicks anyway. It also reminds you to switch off Full Disk Access for Terminal if you switched it on only for Namjai.

OptionWhat it does
--dry-runPrints what would be removed and removes nothing
--yesRemoves without asking you to type yes

Mistakes. A word after remove is refused with nj remove: does not take words, got "everything", and an option it does not take with nj remove: --force is not an option of this command; it takes --dry-run, --yes; each is followed by See: nj help and exits with 2. When the password is refused or the call stops part of the way, it prints nj remove: macOS did not finish removing the program, a line Not removed: with what is still there, and To finish, run: nj remove, and exits with 1. Running it again is safe: what is already gone prints as No ..., nothing to remove.

nj remove --dry-run
Terminal
This takes Namjai off this Mac. It removes:
  /Users/you/Library/Application Support/Namjai
      your settings, the record of sends and the outbox
  /usr/local/bin/namjai and /usr/local/bin/nj
      the program and its short name
  /usr/local/share/namjai
      the shortcut file and the download address the installer put there
  the installer's records com.natandahan.namjai and namjai.desktop
It does not touch WhatsApp or any chat, or files you saved yourself, such as waiting.csv.
It cannot delete the Namjai Send shortcut: macOS gives no command for that. If the shortcut is still there at the end, it opens the Shortcuts app and says what to click.
macOS asks for your Mac password once.
Nothing was removed: --dry-run.
nj remove --yes
Terminal
This takes Namjai off this Mac. It removes:
  /Users/you/Library/Application Support/Namjai
      your settings, the record of sends and the outbox
  /usr/local/bin/namjai and /usr/local/bin/nj
      the program and its short name
  /usr/local/share/namjai
      the shortcut file and the download address the installer put there
  the installer's records com.natandahan.namjai and namjai.desktop
It does not touch WhatsApp or any chat, or files you saved yourself, such as waiting.csv.
It cannot delete the Namjai Send shortcut: macOS gives no command for that. If the shortcut is still there at the end, it opens the Shortcuts app and says what to click.
macOS asks for your Mac password once.
Removed /Users/you/Library/Application Support/Namjai
Removed /usr/local/share/namjai
Removed the installer's record com.natandahan.namjai
No installer's record namjai.desktop, nothing to remove
Removed /usr/local/bin/nj
Removed /usr/local/bin/namjai

Namjai is off this Mac. Still yours to do:
  1. Delete the Namjai Send shortcut. Shortcuts is open now: click All Shortcuts, hold Control and click Namjai Send, choose Delete.
  2. If you switched on Full Disk Access for Terminal only for Namjai, switch it off: System Settings, Privacy & Security, Full Disk Access.
WhatsApp and your chats were not touched. Files you saved yourself, such as waiting.csv, are yours to delete.

version

Which version you have. It says namjai whichever name you type.

nj version
nj version
Terminal
namjai 0.2.13

Anything after version is refused with nj version: does not take words, got "extra" and See: nj help, exit code 2.

help

The list of commands. nj alone, nj help and nj wp all print it, with exit code 0, and so does --help after any command, such as nj wp waiting --help. A command it does not know, such as nj wp bogus, prints one line instead: nj wp: "bogus" is not a command and See: nj help, exit code 2. A word after nj help other than settings is refused with nj help: the only topic is settings, got "extra" and See: nj help, exit code 2.

nj help
nj wp
Terminal
Namjai reads the WhatsApp on this computer, and sends a WhatsApp message
only when you run nj wp send. Nothing else leaves this computer unless
you set up a Namjai server: see nj help settings.

  First time      nj setup
  Health check    nj wp doctor
  Newest version  nj update; nj update --check only looks
                  the installer says where to look; nj set download ADDRESS changes it
  Remove it       nj remove; nj remove --dry-run only lists, --yes does not ask

  nj wp waiting            who is waiting for your answer, and how long
  nj wp unanswered         who has not answered you
  nj wp new                chats with unread messages
  nj wp find NAME          find a contact or chat
  nj wp read NAME          read a chat
  nj wp search WORDS       search your messages
  nj wp calls              calls; add --missed for missed calls only
  nj wp new-customers      chats that started this week
  nj wp labels             your labels; nj wp labelled LABEL for the chats under one
  nj wp archived           archived chats that are still active
  nj wp count              messages by type
  nj wp send CHAT "TEXT"   send to one person; --dry-run to check first, --new for a new number
  nj wp send-setup         switch sending on, if setup's Add Shortcut was not clicked

Options can go before or after the name or words:
  --limit 200      show more than 50 lines
  --within 30d     look back 30 days instead of 7 (waiting, unanswered, archived, new-customers)
  --at-least 2h    only people waiting 2 hours or more (waiting, unanswered)
  --chat NAME      search or count in one chat
  --table, --csv, --json   the same result as a table, as CSV or as JSON, for a program to read
  --text                   plain lines again, when another format is the default
  --within 0               no time limit

To make one of them the default:   nj set format json     (text, table, csv or json)

More: nj version, nj help settings
Short name: type nj instead of namjai.

help settings

The commands and settings for developers and for connecting to a Namjai server. You do not need them to read WhatsApp. Exit code 0.

nj help settings
nj help settings
Terminal
For developers and for connecting to a Namjai server.

  nj wp sync [--server URL]     send the chats marked client to the server
  nj demo send [--server URL] [--seed N] [--account E164] [--device ID]
  nj setup [--store PATH] [--time-zone NAME]

An installed app reads what setup saved. A variable set in the environment wins.

  NAMJAI_WHATSAPP_STORE         path of WhatsApp's ChatStorage.sqlite on this computer
  NAMJAI_TIME_ZONE              this computer's zone as an IANA name
  NAMJAI_OUTPUT_FORMAT          text, table, csv or json; what nj set format saves
  NAMJAI_ENV                    local, ci, dev, uat or prod
  NAMJAI_SERVER                 API base URL (or --server)
  NAMJAI_OUTBOX_KEY             32 random bytes in base64, seals the outbox (secret)
  NAMJAI_OUTBOX_DIR             outbox directory (NAMJAI_STATE_DIR/outbox if unset)
  NAMJAI_STATE_DIR              directory for what is remembered between runs, and the
                                record of every wp send (sends.jsonl)
  NAMJAI_WHATSAPP_ACCOUNT       the salesperson's own WhatsApp number in E.164
  NAMJAI_WHATSAPP_CLIENT_CHATS  chats marked client, separated by commas: numbers in E.164
                                or chat IDs. Only these are sent. Empty means none
  NAMJAI_SHORTCUTS_COMMAND      Apple's shortcuts program, which wp send runs
                                (/usr/bin/shortcuts when unset)
  NAMJAI_OPEN_COMMAND           the program setup and wp send-setup open the shortcut with,
                                and remove opens the Shortcuts app with
                                (/usr/bin/open when unset)
  NAMJAI_DOWNLOAD_ADDRESS       where update finds release.json and the installer; what
                                nj set download saves. No default
  NAMJAI_INSTALLER_DEFAULTS     the file the installer left the download address in
                                (/usr/local/share/namjai/installer-defaults.env when unset)
  NAMJAI_INSTALL_COMMAND        the program update runs Apple's installer with
                                (/usr/bin/sudo when unset)
  NAMJAI_REMOVE_COMMAND         the program remove deletes the installed program with
                                (/usr/bin/sudo when unset)