imsg

# imsg `imsg` reads `~/Library/Messages/chat.db` directly and sends through Messages.app automation. Reading is local and safe. **Sending, reacting, marking read, typing indicators, and any chat mutation require an explicit user request** — confirm recipient, service, and content in your final summary. ## Ground rules - Every read command supports `--json` and emits **NDJSON** (one object per line). Pipe to `jq -s` to get an array. Stdout carries only JSON; progress and warnings go to stderr. - Two capability tiers: - **Standard** (normal permissions): `chats`, `group`, `history`, `watch`, `search`, `send`, `react`, `nickname --local`, `account --local`, `whois --local`. - **Bridge** (SIP disabled + `imsg launch` dylib injection): `send-rich`, `send-multipart`, `send-attachment`, `send-sticker`, `tapback`, `poll`, `edit`, `unsend`, `delete-message`, `read`, `typing`, `notify-anyways`, `chat-*`, `name-photo`, and default-mode `account`/`whois`/`nickname`. - Check availability with `imsg status --json` before using bridge commands. Stickers additionally require `send.sticker` in `rpc_methods` and `selectors.stickerSend`; attaching one requires `selectors.stickerAttach`. If the bridge is down, use a standard command only when it preserves the requested semantics; otherwise stop and explain. Never turn a reply/effect/subject into a plain send or a GUID-targeted tapback into `react`, and never suggest disabling SIP unprompted. - Full command and flag reference: `imsg completions llm`. ## Preconditions ```bash imsg status --json # feature availability + setup hints sqlite3 ~/Library/Messages/chat.db 'pragma quick_check;' # fails => terminal lacks Full Disk Access ``` ## Reading Resolve a person visible in the Messages.app UI from `chats`, not `search`. The UI name usually surfaces as `contact_name` (Contacts permission); it does not appear in `imsg search` results, raw `message.text`, or the DB `handle` table. **No search hits is not proof the contact doesn't exist.** ```bash imsg chats --limit 200 --json | jq -s '.[] | select((.contact_name // .display_name // .name // .identifier // "" | ascii_downcase) | contains("beatrix"))' imsg chats --unread-only --json | jq -s ``` Then inspect and read the chat by rowid: ```bash imsg group --chat-id ID --json # identity + participants; check before automating imsg history --chat-id ID --limit 50 --json | jq -s imsg history --chat-id ID --start 2025-01-01T00:00:00Z --end 2025-02-01T00:00:00Z --json imsg stats --chat-id ID --time-zone UTC --media --json # logical message + media totals imsg scheduled list --json # future Send Later rows; read-only imsg chat-background status --chat-id ID --json # inspect local background state; read-only imsg name-photo status --chat GUID --json # read-only Share Name & Photo eligibility ``` - Chat `id` is the `chat.db` rowid: stable on one machine, the preferred `--chat-id` handle. `identifier` and `guid` are portable across machines. - `--start` is inclusive, `--end` exclusive; both take ISO8601. Use absolute timestamps for date-scoped questions. - `--attachments` adds attachment metadata; `--convert-attachments` converts CAF→M4A / GIF→PNG for model consumption. - `imsg search --query "pizza tonight" --json` searches message bodies only (`--match contains` default, `exact` available). - `imsg stats [--chat-id ID] [--time-zone IANA] [--media] --json` aggregates logical messages by chat, inbound sender, service, and local date; no bridge required. - Chat-list JSON includes `unread_count`. Inbound message payloads include `is_read` and, when read, `date_read`; outbound payloads omit both. - SIP-free lookups: `imsg whois --address "+15551234567" --type phone --local`, `imsg nickname --address "+15551234567" --local --json`, `imsg account --local --json`. Note `nickname --local` returns *your* AddressBook label for the handle; the iMessage-shared nickname needs default-mode `nickname` via the bridge. - Direct `sqlite3` queries are a last resort; the `handle` table lacks the resolved names `imsg chats` provides. ## Streaming ```bash imsg watch --chat-id ID --json # filesystem events with polling fallback imsg watch --since-rowid N --json # resume from a message id cursor ``` Message `id` doubles as the watch cursor: persist the last-seen id and pass it back via `--since-rowid`. Add `--reactions` for tapback add/remove events and `--attachments` for attachment metadata. ## Sending (explicit request only) ```bash imsg send --to "+15551234567" --text "message" --service auto imsg send --chat-id ID --text "message" # prefer for groups: no address ambiguity imsg send --to "+15551234567" --file ~/Desktop/pic.jpg imsg name-photo share --chat GUID # shares YOUR Name & Photo; explicit request only ``` - `--service auto` prefers iMessage and falls back to SMS for text-only phone sends; `--no-sms-fallback` disables that. - `imsg react --chat-id ID --reaction like` (AppleScript) only targets the **most recent incoming message** and needs Accessibility permission. To react to a specific message by GUID, use bridge `tapback`. - `name-photo share` is not a vCard send. It discloses the local Messages Name & Photo to every participant in the selected chat; confirm the destination and explicit user intent before invoking it. ## Bridge extras Only after `imsg status` confirms the bridge is loaded (`imsg launch` injects it; refuses when SIP is on; macOS 26 entitlement gates can block features even with SIP off): ```bash imsg send-rich --chat 'iMessage;-;+15551234567' --text 'hi' --reply-to MSG_GUID # replies, effects, subjects imsg send-sticker --chat GUID --file ~/Pictures/sticker.png --attach-to MSG_GUID --target-part 0 imsg send-rich --chat 'iMessage;-;+15551234567' --url https://imsg.sh imsg poll send --chat GUID --question 'Dinner?' --option 'Pizza' --option 'Sushi' --comment 'Vote by 5pm' imsg poll unvote --chat GUID --poll POLL_GUID --option-index 1 imsg edit --chat GUID --message MSG_GUID --new-text 'updated' # macOS 13+ imsg chat-create --addresses '+15551234567,+15559876543' --name 'Crew' ``` `poll send` echoes `--question` as a best-effort plain caption after the Polls balloon; `--comment` overrides that caption. Do not retry automatically when only the caption fails: the poll may already be delivered. `history` and `watch` backfill a title-less inbound native poll's `poll.question` from its clean caption row. Destructive bridge commands — `unsend`, `delete-message`, `chat-delete`, `chat-leave`, `chat-remove-member` — need per-action user confirmation. ## Verification For repo edits: ```bash make test make build ./bin/imsg chats --limit 3 --json | jq -s # live read proof against the local DB ```