Formats and spreadsheets

Every nj wp command except the health check can print the same answer four ways. Text is for reading; table, CSV and JSON carry every detail, for a spreadsheet or another program.

nj wp waiting
Terminal
     18m  Laura Kim · unread
          them: Hi, is the Tokyo tour in April still available?
     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
5 people waiting for your answer in the last 7d. For longer: nj wp waiting --within 30d

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.

What the columns mean

Table, CSV and JSON carry the same columns. The chat lists (waiting, unanswered, new, find, archived, labelled) have these:

ColumnMeaning
chat_idWhatsApp's own name for the chat: the number, then @s.whatsapp.net for a person; for a group, numbers, then @g.us.
nameThe contact or group name.
kinddirect for a one-to-one chat, group for a group.
unreadHow many messages are unread.
archivedtrue if you archived the chat, otherwise false.
last_atDate and time of the last message, with your time zone's offset.
last_fromWho sent the last message: them, or me for you.
minutes_since_lastMinutes since the last message.
last_kindWhat the last message was: text, audio, picture, document and so on.
last_textThe text of the last message.

The other commands have their own columns:

CommandColumnsMeaning
read, searchat, chat_id, chat_name, from, kind, textOne row per message: its date and time, the chat, who sent it (their number with +, or me for you), what kind of message, and its text.
callsat, direction, missed, video, seconds, who, who_idsOne row per call: when, incoming or outgoing, true if missed, true if a video call, how many seconds it lasted, the name and the number.
new-customerschat_id, name, first_at, messagesThe chat, the name, the date and time of the first message on this Mac, and how many messages the chat has.
countkind, messagesOne row per kind of message (text, audio, document and so on) and how many there are.
labelslabel, chatsOne row per label and how many chats are under it.

Save a list and open it in a spreadsheet

The > sends the answer into a file instead of the screen. This saves the file waiting.csv in your home folder (~ means your home folder):

nj wp waiting --csv > ~/waiting.csv

Nothing is printed when it works. The file is plain text in UTF-8, with no direction marks. Numbers reads UTF-8. If a spreadsheet app shows wrong letters for Hebrew or Arabic, use its import command and choose Unicode (UTF-8) as the file's encoding. How spreadsheet apps show Hebrew was not tested for this guide. To open the file in the app your Mac uses for CSV files:

open ~/waiting.csv

Or find waiting.csv in your home folder in Finder and double-click it. Running the command again replaces the file with a fresh list.

The file holds real names and messages: treat it like the chats themselves. Other accounts on this Mac can read it unless you make it private. This makes it readable by you alone, and it stays private when the command above replaces it later:

chmod 600 ~/waiting.csv

Make a format the default

nj set format csv

You undo this a few lines below, with nj set format text.

Terminal
Saved. Every nj wp list now prints csv unless you add --text, --table, --csv or --json.

From then on, these commands print CSV until you change it back: find, read, search, new, waiting, unanswered, archived, count, calls, new-customers, labels and labelled. The saved format changes these lists only. It does not change nj setup, the health check (nj wp doctor) or nj version. --text brings the normal lines back for one command.

Try it with your labels. The plain command now prints CSV:

nj wp labels
Terminal
label,chats
Quote sent,2
VIP,2

With --text, the same command prints the normal lines, this one time:

nj wp labels --text
Terminal
Quote sent · 2 chats
VIP · 2 chats

To go back to the normal lines for good:

nj set format text
Terminal
Saved. Every nj wp list now prints text unless you add --text, --table, --csv or --json.

The choices are text, table, csv and json. Anything else is refused:

Terminal: nj set format pdf
nj set format: must be text, table, csv or json, got "pdf"
See: nj help

More than one word is refused too: nj set format: takes one word, got "text extra", then See: nj help, exit code 2. A format that is accepted prints Saved. and the format every list now prints, as above.

Hebrew and Arabic

Names and messages in Hebrew or Arabic come out whole and readable. In the text and table formats, Namjai wraps each right-to-left name or message in invisible direction marks, so Terminal shows it right to left without mixing it into the English around it. CSV and JSON carry the text exactly as it is in WhatsApp, in UTF-8, with no direction marks. You can search and read by a Hebrew name too:

nj wp read אורי
Terminal
Chat with ⁨אורי מזרחי⁩‎

Nov 13 01:25  ⁨אורי מזרחי⁩‎: ⁨אני צריך הצעה לחבילה ליוון לשבוע⁩‎
Nov 15 07:25  You: ⁨שלחתי לך שתי אפשרויות, מה דעתך?⁩‎
2 messages