iMessage CLI

iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.

imsg is a Swift-based CLI for Apple's Messages.app by Peter Steinberger (steipete). It provides programmatic access to iMessage and SMS — list chats, view message history with attachment metadata, stream new messages in real-time via filesystem events, and send texts and files via AppleScript. No private APIs, no jailbreak required. The architecture is clean: reading uses direct SQLite access to `~/Library/Messages/chat.db` in read-only mode (no database modifications), while sending uses AppleScript to drive Messages.app (the safe, Apple-sanctioned approach). This separation means reads are instant and don't require Messages.app to be open, while sends are reliable because they go through the same path as manual message composition. Key features include phone number normalization to E.164 format for reliable contact matching, optional attachment metadata output (MIME type, filename, path, missing flag), participant and date range filters, and JSON output for every command. The `watch` command uses macOS filesystem events (FSEvents) to detect new messages with minimal latency and configurable debounce. For OpenClaw users, imsg is the simplest path to iMessage integration on macOS. Unlike BlueBubbles (which requires a server and tunnel), imsg runs locally and directly. The trade-off: it only works on the Mac where Messages.app is signed in, and there's no remote access. For SMS relay, you need to enable 'Text Message Forwarding' on your iPhone. Security requires two system permissions: Full Disk Access (to read chat.db) and Automation permission (to control Messages.app for sending). Both are granted through System Settings > Privacy & Security. Best suited for: macOS users who want local iMessage automation, OpenClaw users wanting simple iMessage without a server setup, developers building iMessage workflows on macOS, anyone who prefers direct local access over BlueBubbles' server architecture.

Tags: imessage, sms, messaging, apple, macos

Category: Messaging

Use Cases

  • Read and reply to iMessages via AI assistant on macOS
  • Real-time message monitoring with the watch command
  • Send notifications to yourself or contacts via iMessage
  • Export message history for specific conversations
  • Automated message forwarding between iMessage and other channels
  • Chat history search by participant, date range, or content

Tips

  • Grant Full Disk Access proactively: System Settings → Privacy & Security → Full Disk Access → add Terminal
  • Use `--json` for all commands when integrating with OpenClaw
  • The watch command is great for real-time message monitoring: `imsg watch --json --debounce 250ms`
  • Use `--region` flag for non-US phone numbers: `imsg send --to '+919999999999' --region IN`
  • Filter by participant: `imsg history --chat-id 1 --participants +15551234567`
  • For SMS support, enable Text Message Forwarding: iPhone → Settings → Messages → Text Message Forwarding
  • Combine with cron for periodic message checks without the watch command

Known Issues & Gotchas

  • Requires Full Disk Access permission for your terminal — without it, chat.db is inaccessible
  • Requires Automation permission for Messages.app — needed for sending only
  • macOS 14+ (Sonoma) required — won't work on older macOS versions
  • Only works locally on the Mac where Messages.app is signed in — no remote access
  • SMS relay requires 'Text Message Forwarding' enabled on iPhone → this Mac
  • Send uses AppleScript — Messages.app must be running (but can be in background)
  • Attachment paths are shown as metadata only — files aren't copied or moved
  • Phone numbers default to US region — use --region for other countries

Alternatives

  • BlueBubbles
  • AirMessage
  • Shortcuts.app (macOS)
  • osascript (raw AppleScript)

Community Feedback

A Console App for Sending and Receiving iMessages. The work is based on steipete's imsg, and is a spiritual successor to things like CamHenlin's imessageclient.

— Hacker News

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.

— GitHub

Deep Dive into iMessage — Behind the Making of an Agent Skill. Open System Settings → Privacy & Security → Full Disk Access to grant terminal read access.

— Fat Bob Man Blog

imsg is a CLI tool for macOS that lets you programmatically interact with iMessage/SMS via the Messages.app. It enables developers to list chats, view history, and send messages.

— MCP Hub

Configuration Examples

Install and grant permissions

# Install via Homebrew
brew install steipete/tap/imsg

# Grant permissions:
# 1. System Settings → Privacy & Security → Full Disk Access → add Terminal
# 2. System Settings → Privacy & Security → Automation → Terminal → Messages.app

Common operations

# List recent chats
imsg chats --limit 10 --json

# View message history
imsg history --chat-id 1 --limit 20 --attachments --json

# Send a message
imsg send --to "+14155551212" --text "Hello from OpenClaw!" --service imessage

# Send with attachment
imsg send --to "+14155551212" --text "Check this out" --file ~/Desktop/photo.jpg

Real-time monitoring

# Watch for new messages across all chats
imsg watch --json --debounce 250ms

# Watch a specific chat with attachments
imsg watch --chat-id 5 --attachments --json

Installation

brew install steipete/tap/imsg

Homepage: https://imsg.to

Source: bundled