---

name: nanomsg description: Read and send iMessage or SMS with the nanomsg CLI. Use when working on a Mac where nanomsg is installed and you need terminal access to Messages data or sending.

nanomsg CLI

Always use --json — output is human-readable text by default, but agents need structured JSON.

Read

nanomsg chats --json --limit 20
nanomsg chats --json --unread
nanomsg unread --json --limit 20
nanomsg unread --json --chat-id 207
nanomsg history --json --chat-id 207 --limit 20
nanomsg history --json --chat-id 207 --since "2026-02-13"
nanomsg search --json "query" --limit 20
nanomsg search --json "query" --chat-id 207
nanomsg search --json "query" --from "Alice"
nanomsg contacts --json

Attributing senders

Every message has a senderDisplayName field — always present, "You" for outgoing, otherwise the resolved contact name (or raw handle). Read it per message. In group chats (isGroup: true on the chat/unread group) the chat's name is not the sender of any given message, so never attribute a message to the chat name — use each message's senderDisplayName.

Write

nanomsg send --json --to "+1234567890" --text "Hello"
nanomsg send --json --chat-id 207 --text "Hello"

Workflow

1. Run chats --json first to identify target chat IDs.
2. Use history --json for context before replying.
3. Use search --json --from when sender context matters.
4. Ask for confirmation before sending messages.