# imsg
> Command-line interface for Apple Messages on macOS

## Summary
macOS CLI for Apple Messages providing chat listing, message history retrieval, real-time message streaming, and iMessage/SMS sending with attachment support. Uses read-only DB access and AppleScript for sending.

## Capabilities
- List recent conversations with metadata (chat ID, name, service, last message time)
- Retrieve message history with filtering by chat, date range, and participants
- Stream new messages in real-time via filesystem event watching
- Send text messages and file attachments via iMessage or SMS
- Phone number normalization to E.164 for reliable contact lookup
- Attachment metadata output including MIME type, filename, path, and missing status
- JSON output mode for all commands for scripting and agent integration
- SMS relay support when iPhone Text Message Forwarding is enabled

## When to Use
- An AI agent needs to read or send iMessages programmatically
- Monitoring incoming messages in real-time for automated responses
- Searching message history from the command line
- Sending notifications or alerts via iMessage from scripts
- Building automation workflows around Apple Messages

## When NOT to Use
- Running on non-macOS platforms
- Working without Full Disk Access permission (needed for chat.db)
- Need to interact with WhatsApp, Signal, or other non-Apple messaging services

## Usage Patterns
### List recent chats
```
imsg chats --limit 20 --json
```
Lists the 20 most recent conversations in JSON format

### View message history
```
imsg history --chat-id CHAT_ID --limit 50 --json
```
Retrieves the last 50 messages from a specific chat

### Stream new messages
```
imsg watch --json
```
Watches for and streams new incoming messages in real-time

### Send a text message
```
imsg send --to "+1234567890" --text "Hello!"
```
Sends an iMessage to the specified phone number

### Send a file attachment
```
imsg send --to "+1234567890" --file /path/to/image.png
```
Sends a file attachment via iMessage

## Input / Output
- **stdin**: Not typically used
- **stdout**: Human-readable text or JSON (with --json flag)
- **stderr**: Error and status messages

## Installation
- **source**: `git clone https://github.com/steipete/imsg && cd imsg && make build`

## Related Tools
- [wacli](/tools/wacli) (alternative): wacli provides similar messaging CLI capabilities for WhatsApp

---
Source: https://littlescripts.sh/tools/imsg
