imessage

Send and read iMessage and SMS messages via the imsg CLI on macOS.

Updated Dec 7, 2025

Search Tags:#messaging #cli #macos #sms #imessage #imsg #send text

Ready to run

npx skills add https://github.com/harlanljones/dotfiles --skill imessage-harlanljones

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: imessage
Source: https://github.com/harlanljones/dotfiles/tree/main/dot_hermes/skills/apple/imessage
Command: npx skills add https://github.com/harlanljones/dotfiles --skill imessage-harlanljones

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires imsg.

What problem does it solve? It lets you read chat history and send iMessage or SMS texts from the terminal on macOS without opening Messages.app manually. ## Core Features & Use Cases - List and Inspect Chats: Enumerate recent conversations with `imsg chats` and view message history by chat ID, including attachment info. - Send Messages with Attachments: Send text and files to phone numbers or Apple IDs, with control over iMessage versus SMS delivery. - Watch for Incoming Messages: Monitor a conversation in real time using `imsg watch`. - Use Case: A user asks to text a family member; the assistant finds the contact's chat, confirms the recipient and message content, then sends the text via the appropriate service. ## Quick Start Ask the assistant to send a text message to a specific contact or phone number, and it will confirm the recipient and content before sending via imsg.

Frequently Asked Questions about imessage

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I send an iMessage from the terminal on macOS?▼

Use the imsg CLI with the send command, specifying the recipient phone number or Apple ID and the message text. You can attach files with the file flag and force iMessage or SMS delivery with the service flag.

How do I read iMessage history from the command line?▼

Run imsg chats to list recent conversations, then use imsg history with a chat ID to view messages. Add the attachments flag to include attachment information and the json flag for structured output.

What permissions does imsg need on macOS?▼

imsg requires Full Disk Access for the terminal, granted in System Settings under Privacy, plus Automation permission for Messages.app when first prompted. Messages.app must also be signed in to an Apple ID.

Can I force SMS instead of iMessage when sending a text?▼

Yes, pass the service flag with the value sms to force SMS delivery, or imessage to force iMessage. The default auto mode lets Messages.app decide based on the recipient.

What are the limitations of sending messages with imsg?▼

imsg only works on macOS with Messages.app configured and cannot manage group chat membership. Bulk messaging is discouraged, and recipients and content should always be confirmed before sending.