imessage-cli

module
v0.0.0-...-f6fa6ab Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 9, 2026 License: MIT

README

iMessage CLI

A command-line tool for reading and sending iMessages on macOS.

Features

  • List conversations - View recent iMessage conversations
  • Read messages - Read messages from any conversation
  • Send messages - Send iMessages from the command line
  • Interactive chat - Real-time chat mode with a contact
  • Search - Search through your message history
  • TUI - Full terminal user interface with live updates

Requirements

  • macOS (uses the Messages app and iMessage database)
  • Go 1.21 or later
  • Full Disk Access permission for Terminal/your terminal emulator

Building

cd go
go mod download
go build -o imessage ./cmd/imessage

Installation

# Build and install to your GOPATH/bin
go install ./cmd/imessage

# Or build locally
go build -o imessage ./cmd/imessage

Usage

List recent conversations
imessage list
imessage ls
imessage l
Read messages from a conversation
# By conversation number from list
imessage read 1

# By phone number
imessage read "+1234567890"

# Specify number of messages
imessage read 1 -n 50
Send a message
imessage send "+1234567890" "Hello from the command line!"

# Skip confirmation
imessage send "+1234567890" "Hi" -y
Interactive chat mode
imessage chat 1
imessage chat "+1234567890"
Search messages
imessage search "meeting"
imessage search "project" -n 50
Launch TUI (Terminal User Interface)
imessage tui
imessage ui
imessage watch
Check status
imessage status

TUI Controls

Key Action
↑/↓ or j/k Navigate/scroll
Enter Select conversation
Tab Switch between panels
h/← Go back to conversations
l/→ Go to messages
i Start typing a message
r Refresh
g Go to top (messages)
G Go to bottom (messages)
q Quit

Permissions

This tool requires access to:

  1. iMessage Database (~/Library/Messages/chat.db) - Grant Full Disk Access to your terminal
  2. Contacts Database (~/Library/Application Support/AddressBook/) - For resolving contact names
  3. Messages App - Via AppleScript for sending messages

To grant Full Disk Access:

  1. Open System Preferences → Security & Privacy → Privacy
  2. Select "Full Disk Access"
  3. Add your terminal application (Terminal.app, iTerm2, etc.)

Project Structure

go/
├── cmd/
│   └── imessage/
│       └── main.go           # Entry point
├── internal/
│   ├── cli/
│   │   └── cli.go            # CLI commands
│   ├── database/
│   │   ├── database.go       # iMessage database operations
│   │   └── contacts.go       # Contact resolution
│   ├── sender/
│   │   └── sender.go         # AppleScript message sending
│   ├── tui/
│   │   └── tui.go            # Terminal user interface
│   └── watcher/
│       └── watcher.go        # Real-time message watching
├── go.mod
├── go.sum
└── README.md

Dependencies

Differences from Python Version

This Go version is a complete rewrite with:

  • Single binary distribution (no Python dependency)
  • Faster startup time
  • Native concurrency with goroutines
  • Uses tview instead of curses for the TUI

License

Same license as the parent project.

Directories

Path Synopsis
cmd
imessage command
internal
cli
Package cli provides the command-line interface for iMessage CLI.
Package cli provides the command-line interface for iMessage CLI.
database
Package database provides contact resolution functionality.
Package database provides contact resolution functionality.
sender
Package sender provides functionality for sending iMessages using AppleScript.
Package sender provides functionality for sending iMessages using AppleScript.
tui
Package tui provides image rendering for terminal display using half-block characters.
Package tui provides image rendering for terminal display using half-block characters.
watcher
Package watcher provides real-time message watching functionality.
Package watcher provides real-time message watching functionality.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL