The messages command gives you access to your Messages.app data right from the terminal. This page covers all the available commands and options.

Quick reference¶

# Show help
messages
messages --help

# List chats
messages chats
messages chats --search "john"

# List contacts
messages contacts
messages contacts --search "john"

# List messages from a chat
messages --chat 42
messages --chat "Mom"
messages --with "John Doe"

# List unread messages
messages --unread

# Search messages
messages --search "dinner"
messages --with "John Doe" --search "dinner"
messages --with "John Doe" --search "dinner" --since 2025-07-15

Global options¶

These options work with any command:

Listing messages¶

When you provide message options directly to messages, it lists messages from a conversation. Use --chat or --with to specify the conversation, and --search to search within messages.

messages [OPTIONS]

Examples:

# Get the last 50 messages from chat ID 42
messages --chat 42

# Get messages by chat display name
messages --chat "Mom"

# Get messages with a contact (exact name match)
messages --with "John Doe"

# Search all messages
messages --search "dinner"

# Search within a conversation
messages --with "John Doe" --search "dinner"

# Search including unknown senders
messages --search "offer" --include-unknown-senders

# Messages from the last week
messages --chat 42 --since 2025-01-01

# Date range
messages --chat 42 --since 2025-01-01 --before 2025-01-15

# Only show messages with attachments
messages --chat 42 --with-attachments

# Show unread messages (excludes spam/unknown senders by default)
messages --unread

# Show all unread messages including spam
messages --unread --include-unknown-senders

# Unread messages from a specific chat
messages --unread --chat 42

# Get JSON for scripting
messages --chat 42 --json | jq '.[] | select(.is_from_me == false)'

What the output looks like:

[January 15, 2025]
Mom (10:30am): Hey, are you free for lunch?
me (10:31am): Sure! Where? [❤️ 1, 👍 1]
Mom (10:32am): How about Main St? (edited)

With --with-attachments:

[January 15, 2025]
Mom (10:33am): Check out this photo!
  [image: ~/Library/Messages/Attachments/ab/cd/photo.jpg]

chats¶

Lists your conversations, ordered by most recent activity.

messages chats [OPTIONS]

Examples:

# Show your 20 most recent conversations
messages chats

# Search for chats by name
messages chats --search "john"

# Show your 10 most recent conversations
messages chats --limit 10

# Only iMessage conversations
messages chats --service imessage

# Get JSON for scripting
messages chats --json | jq '.[0]'

What the output looks like:

42 Mom (iMessage) - 1,247 messages
15 Work Group (iMessage) - 892 messages

The number at the start is the chat ID, which you can use with --chat.

contacts¶

Lists contacts from your macOS Contacts.app.

messages contacts [OPTIONS]

Examples:

# List contacts
messages contacts

# Search for contacts by name
messages contacts --search "john"

# Get JSON for scripting
messages contacts --json

What the output looks like:

John Doe
John Smith
Debbie Johnson

Output formats¶

By default, commands output plain text that's easy to read and pipe to other tools. If you need machine-readable output, use --json:

messages --chat 42 --json | jq '.[] | select(.is_from_me == false)'

Error messages¶

If something goes wrong, you'll get one of these errors: