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.
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.
| Option | Default | Accepted values | What it does |
|---|---|---|---|
--store path | ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite | the place of WhatsApp's ChatStorage.sqlite | Use a WhatsApp chat file in another place. |
--time-zone name | the Mac's own time zone | a zone name such as Asia/Bangkok or Europe/London | Use this time zone for every date and time. |
| Message | Cause | Exit 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 read | 1 |
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 | The --time-zone you typed is not a known zone name; the sample below shows it | 2 |
WhatsApp is not on this computer yet. and three steps | There is no WhatsApp chat file at that place | 1 |
macOS did not let this program read WhatsApp's chats. and three steps | Terminal has no Full Disk Access | 1 |
nj setup: and a reason | The settings file cannot be read or written, or another error opening the file | 1 |
nj setup: does not take words, got "extra" | Words after setup | 2 |
nj setup: --bogus is not an option of this command; it takes --store, --time-zone | An option it does not take | 2 |
nj setup: --time-zone needs a value | An option with no value after it | 2 |
nj setupStep 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.
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.
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:
| Line | What it checks | What makes it FAIL |
|---|---|---|
the settings to read WhatsApp are set | That NAMJAI_WHATSAPP_STORE and NAMJAI_TIME_ZONE are set and the zone is a real one | A missing or wrong setting; the line gives the reason. The four store lines are then skipped. |
the WhatsApp store opens read-only | That WhatsApp's chat file exists and opens | The 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 uses | That WhatsApp's file still has every part Namjai reads | A WhatsApp update changed the file; the line says missing and names each part. |
the store answers a count | Counts chats and messages | The file cannot be read; otherwise it shows 10 chats, 24 messages, with the real numbers. |
the store has a recent message | How old the newest message is, such as the newest is 1h 19m old | The file holds no message: it holds no message. An old message does not fail. |
sending WhatsApp messages | Whether 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 that | Never; sending is optional, so the line says ok either way and its words say which. |
-- sending chats to Namjai | Shown when no server is set: not set up; reading WhatsApp on this computer does not need it | Never; -- is not a failure. |
the settings to send to Namjai are set | Shown when a server is set: every setting nj wp sync needs; then yes, 0 chats marked client | A missing or wrong setting. The next three lines are then skipped. |
the state directory can be written | That NAMJAI_STATE_DIR can be made and written | The folder cannot be made or written; the line gives the reason. |
the outbox opens | That the outbox opens with its key; then yes, 0 items waiting to be sent | The outbox cannot be opened or read. |
the Namjai server answers | Asks the server's /healthz address | No answer (the line gives the reason), or an answer other than 200 OK. |
nj wp doctorok 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:
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:
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.
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 jsonSaved. Every nj wp list now prints json unless you add --text, --table, --csv or --json.
nj set format: must be text, table, csv or json, got "pdf" See: nj help
nj set format textSaved. Every nj wp list now prints text unless you add --text, --table, --csv or --json.
update
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.
| Message | Cause | Exit code |
|---|---|---|
nj update: NAMJAI_DOWNLOAD_ADDRESS must be an https address, got the address. Fix it with: nj set download ADDRESS | The 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 reason | The address did not answer, or did not hold a release.json | 1 |
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 installed | The file changed on the way, or on the server | 1 |
nj update: the installer did not finish, the reason and the version you still have | The password was refused three times, or the installer failed | 1 |
nj update: the installer finished, but and what version says | The installer ran, but the program in /usr/local/bin still says the old version | 1 |
nj update: no download address is set. Install the newest installer from the Namjai guide, or run: nj set download ADDRESS
| Option | What it does |
|---|---|
--check | Only says whether a newer version is there. Downloads and installs nothing; exit code 0 either way |
nj update --checknamjai 0.2.14 is available, you have 0.2.13. To install it: nj update
nj updateDownloaded 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 versionnamjai 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
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/namjaiSaved. nj update now looks for the newest version at https://guide.example.com/namjai
remove
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.
| Option | What it does |
|---|---|
--dry-run | Prints what would be removed and removes nothing |
--yes | Removes 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-runThis 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 --yesThis 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 versionnamjai 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 wpNamjai 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 settingsFor 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)