Imsg

💬 imsg — Send, read, stream iMessage & SMS

A macOS Messages.app CLI to send, read, and stream iMessage/SMS (with attachment metadata). Read-only for receives; send uses AppleScript (no private APIs).

Features

• List chats, view history, or stream new messages (watch).
• Send text and attachments via iMessage or SMS (AppleScript, no private APIs).
• Phone normalization to E.164 for reliable buddy lookup (--region, default US).
• Optional attachment metadata output (mime, name, path, missing flag).
• Filters: participants, start/end time, JSON output for tooling.
• Read-only DB access (mode=ro), no DB writes.
• Event-driven watch via filesystem events.

Requirements

• macOS 14+ with Messages.app signed in.
• Full Disk Access for your terminal to read ~/Library/Messages/chat.db.
• Automation permission for your terminal to control Messages.app (for sending).
• For SMS relay, enable “Text Message Forwarding” on your iPhone to this Mac.

Install

make build
# binary at ./bin/imsg

Commands

• imsg chats [--limit 20] [--json] — list recent conversations.
• imsg history --chat-id [--limit 50] [--attachments] [--participants +15551234567,...] [--start 2025-01-01T00:00:00Z] [--end 2025-02-01T00:00:00Z] [--json]
• imsg watch [--chat-id ] [--since-rowid ] [--debounce 250ms] [--attachments] [--participants …] [--start …] [--end …] [--json]
• imsg send --to [--text "hi"] [--file /path/img.jpg] [--service imessage|sms|auto] [--region US]

Quick samples

# list 5 chats
imsg chats --limit 5

# list chats as JSON
imsg chats --limit 5 --json

# last 10 messages in chat 1 with attachments
imsg history --chat-id 1 --limit 10 --attachments

# filter by date and emit JSON
imsg history --chat-id 1 --start 2025-01-01T00:00:00Z --json

# live stream a chat
imsg watch --chat-id 1 --attachments --debounce 250ms

# send a picture
imsg send --to "+14155551212" --text "hi" --file ~/Desktop/pic.jpg --service imessage

A