### Install imsg with Homebrew or build from source

Source: https://context7.com/openclaw/imsg/llms.txt

Install imsg using Homebrew for the recommended approach or build it from source by cloning the repository and running make. Optional dependencies like ffmpeg for attachment conversion and jq for pretty-printing JSON can also be installed.

```bash
# Homebrew
brew install steipete/tap/imsg
imsg --version

# Build from source
git clone https://github.com/steipete/imsg.git
cd imsg
make build
./bin/imsg --help

# Optional: ffmpeg for attachment conversion
brew install ffmpeg

# Optional: jq for pretty-printing NDJSON
brew install jq
```

--------------------------------

### Install imsg with Homebrew

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Use Homebrew for the recommended installation path. This command downloads the universal binary, adds it to your PATH, and manages updates.

```bash
brew install steipete/tap/imsg
```

--------------------------------

### Install imsg and check version

Source: https://github.com/openclaw/imsg/blob/main/docs/quickstart.md

Installs the imsg tool using Homebrew and verifies the installation by checking its version. Ensure you have Homebrew installed.

```bash
brew install steipete/tap/imsg
imsg --version
```

--------------------------------

### Verify imsg installation

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Check if imsg is installed correctly by running the --version command and a sample command like 'chats'. If you encounter permission errors, refer to the Permissions section.

```bash
imsg --version
```

```bash
imsg chats --limit 3
```

--------------------------------

### IMsg Command Examples

Source: https://github.com/openclaw/imsg/blob/main/docs/json.md

Examples of using the imsg command with the --json flag to output NDJSON, piped to jq for processing.

```APIDOC
## IMsg Command Examples

Every read command supports `--json`. Output is **newline-delimited JSON (NDJSON)**: one self-contained JSON object per line. This shape works equally well for streaming consumers and for batch readers that pipe through `jq -s` to materialize an array.

```bash
imsg chats --json | jq -s
imsg history --chat-id 42 --json | jq -s
imsg watch --chat-id 42 --json
```

Human progress, prompts, and warnings are written to **stderr**, not stdout. Stdout is reserved for parseable JSON so pipelines stay clean.
```

--------------------------------

### Check imsg version and Homebrew installation

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Use these commands to determine the currently active imsg binary and check installed versions via Homebrew. This helps diagnose issues where imsg reports a different version than expected from Homebrew.

```bash
which imsg
```

```bash
brew list --versions imsg
```

--------------------------------

### Request chats.list

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example of a JSON-RPC 2.0 request to list chats with a specified limit.

```json
{"jsonrpc":"2.0","id":"1","method":"chats.list","params":{"limit":10}}
```

--------------------------------

### Pick a Target Chat

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Lists the latest 10 chats and sets an environment variable for the target chat GUID. Requires `jq` for JSON parsing.

```bash
imsg chats --limit 10 --json | jq -r '.[] | "\(.guid)\t\(.name // .identifier)"'
export CHAT='iMessage;-;+15551234567'    # paste guid from above
```

--------------------------------

### Subscribe to a chat

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example JSON-RPC 2.0 request to subscribe to message updates for a specific chat ID.

```json
{"jsonrpc":"2.0","id":"2","method":"watch.subscribe","params":{"chat_id":1}}
```

--------------------------------

### Watch Typing Events

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Starts a background process to watch for typing events and emits JSON objects for started-typing and stopped-typing. The process is killed afterwards.

```bash
imsg watch --bb-events --json &
# from another device or simulator, type into your conversation
# you should see started-typing / stopped-typing JSON objects emit
kill %1
```

--------------------------------

### Message notification

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example JSON-RPC 2.0 notification structure for a new message within a subscription.

```json
{"jsonrpc":"2.0","method":"message","params":{"subscription":2,"message":{...}}}
```

--------------------------------

### JSON Schema for Chat Object

Source: https://context7.com/openclaw/imsg/llms.txt

Provides an example of the JSON schema for a full chat object, detailing fields like ID, name, participants, and timestamps.

```json
{
  "id": 42,                                       # chat.ROWID — preferred routing key
  "name": "Jane Appleseed",                       # display name or handle fallback
  "display_name": "",                             # group title when set
  "contact_name": "Jane Appleseed",               # resolved from Contacts
  "identifier": "iMessage;-;+14155551212",        # portable handle
  "guid": "iMessage;-;+14155551212",              # portable GUID
  "service": "iMessage",
  "last_message_at": "2026-05-06T12:34:00Z",
  "is_group": false,
  "participants": ["+14155551212"],               # external handles only
  "account_id": "E:you@example.com",             # routing diagnostic (read-only)
  "account_login": "you@example.com",            # routing diagnostic (read-only)
  "last_addressed_handle": "+14155551212"        # routing diagnostic (read-only)
}
```

--------------------------------

### Full Message Object Example with Attachments

Source: https://context7.com/openclaw/imsg/llms.txt

This JSON object represents a full message, including details about any attachments. It shows the structure for filenames, transfer names, MIME types, sizes, and paths.

```json
{
  "id": 9001,
  "chat_id": 42,
  "chat_identifier": "iMessage;-;+14155551212",
  "chat_guid": "iMessage;-;+14155551212",
  "chat_name": "Jane Appleseed",
  "participants": ["+14155551212"],
  "is_group": false,
  "guid": "8DF3A1B2-...",
  "reply_to_guid": "",
  "destination_caller_id": "",                   # outgoing only: which number was used
  "sender": "+14155551212",
  "sender_name": "Jane Appleseed",
  "is_from_me": false,
  "text": "here is the file",
  "created_at": "2026-05-06T11:00:00Z",
  "attachments": [
    {
      "filename": "IMG_0001.jpg",
      "transfer_name": "photo.jpg",
      "uti": "public.jpeg",
      "mime_type": "image/jpeg",
      "byte_size": 204800,
      "is_sticker": false,
      "missing": false,
      "path": "/Users/you/Library/Messages/Attachments/ab/00/IMG_0001.jpg",
      "converted_path": "/path/to/cache/IMG_0001.png",    # with --convert-attachments
      "converted_mime_type": "image/png"
    }
  ]
}
```

--------------------------------

### Response for chats.list

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example JSON-RPC 2.0 response structure for the chats.list method, indicating the presence of chat data.

```json
{"jsonrpc":"2.0","id":"1","result":{"chats":[...]}}
```

--------------------------------

### Apply Tapback Reaction with iMessage CLI

Source: https://github.com/openclaw/imsg/blob/main/README.md

Use `tapback` to add or remove reactions to messages. Specify the chat, message GUID, and reaction kind. Use `--remove` to delete a reaction.

```bash
imsg tapback --chat ... --message <guid> --kind love
```

```bash
imsg tapback --chat ... --message <guid> --kind love --remove
```

--------------------------------

### Read Converted Attachment Variants

Source: https://github.com/openclaw/imsg/blob/main/docs/attachments.md

These commands fetch attachment metadata along with converted variants for CAF audio (to M4A) and GIF images (to first-frame PNG). This feature requires ffmpeg to be installed and available in the system's PATH. If ffmpeg is not found, converted paths will be omitted.

```bash
imsg history --chat-id 42 --attachments --convert-attachments --json
```

```bash
imsg watch   --chat-id 42 --attachments --convert-attachments --json
```

--------------------------------

### Streaming JSON Output with jq

Source: https://github.com/openclaw/imsg/blob/main/docs/json.md

Use the --json flag with imsg commands to get newline-delimited JSON output. Pipe this output to `jq -s` to materialize it as a JSON array for further processing.

```bash
imsg chats --json | jq -s
```

```bash
imsg history --chat-id 42 --json | jq -s
```

```bash
imsg watch --chat-id 42 --json
```

--------------------------------

### Uninstall imsg with Homebrew

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

To remove imsg installed via Homebrew, use the uninstall command. The untap command is optional.

```bash
brew uninstall imsg
```

```bash
brew untap steipete/tap   # optional
```

--------------------------------

### Tapback Round Trip

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Applies a 'love' tapback reaction to a specified message and then removes it. Requires capturing the message GUID first.

```bash
# Capture the messageGuid of an existing message you want to react to
imsg history --chat-id 1 --limit 1 --json | jq -r '.guid'
export MSG=<paste guid>
imsg tapback --chat "$CHAT" --message "$MSG" --kind love
imsg tapback --chat "$CHAT" --message "$MSG" --kind love --remove
```

--------------------------------

### Stream attachments

Source: https://github.com/openclaw/imsg/blob/main/docs/watch.md

To include attachment metadata in the stream, use the `--attachments` flag. For automatic conversion of attachments, use `--convert-attachments`. This requires `ffmpeg` to be installed and available on the system's PATH.

```bash
imsg watch --chat-id 42 --attachments --json
```

```bash
imsg watch --chat-id 42 --attachments --convert-attachments --json
```

--------------------------------

### JSON-RPC 2.0 interface with imsg rpc

Source: https://context7.com/openclaw/imsg/llms.txt

Start `imsg rpc` to expose chats, history, watch, and send functionalities over JSON-RPC 2.0 via stdio. This is suitable for agents requiring a persistent subprocess. Requests and responses are JSON objects, one per line.

```bash
# Start the RPC server (no daemon, no port — just a subprocess)
imsg rpc
```

```json
# --- chats.list ---
# Request (write to stdin):
{"jsonrpc":"2.0","id":"1","method":"chats.list","params":{"limit":10}}
```

```json
# Response (read from stdout):
{"jsonrpc":"2.0","id":"1","result":{"chats":[...]}}
```

```json
# --- messages.history ---
{"jsonrpc":"2.0","id":"2","method":"messages.history","params":{
  "chat_id":42,"limit":20,"attachments":true,
  "start":"2026-05-01T00:00:00Z","end":"2026-05-06T00:00:00Z"}}
# Response:
{"jsonrpc":"2.0","id":"2","result":{"messages":[...]}}
```

```json
# --- watch.subscribe ---
{"jsonrpc":"2.0","id":"3","method":"watch.subscribe","params":{
  "chat_id":42,"since_rowid":9000,"include_reactions":true,"debounce_ms":500}}
# Response:
{"jsonrpc":"2.0","id":"3","result":{"subscription":1}}
# Notifications arrive as messages are written:
{"jsonrpc":"2.0","method":"message","params":{"subscription":1,"message":{...}}}
```

```json
# --- watch.unsubscribe ---
{"jsonrpc":"2.0","id":"4","method":"watch.unsubscribe","params":{"subscription":1}}
{"jsonrpc":"2.0","id":"4","result":{"ok":true}}
```

```json
# --- send (returns rowid + guid when observable) ---
{"jsonrpc":"2.0","id":"5","method":"send","params":{"to":"+14155551212","text":"hi"}}
{"jsonrpc":"2.0","id":"5","result":{"ok":true,"id":1979,"guid":"8DF..."}}
```

```json
# --- send to group chat ---
{"jsonrpc":"2.0","id":"6","method":"send","params":{"chat_id":42,"text":"hello group","file":"/tmp/photo.jpg"}}
{"jsonrpc":"2.0","id":"6","result":{"ok":true,"id":1980,"guid":"9EF..."}}
```

--------------------------------

### History Read with Date Filters

Source: https://github.com/openclaw/imsg/blob/main/docs/history.md

Retrieves messages within a specified date range. Both `--start` and `--end` accept ISO 8601 format with an explicit timezone. Either bound can be omitted to fetch messages from the beginning or up to a certain point.

```bash
imsg history --chat-id 42 \
  --start 2026-05-01T00:00:00Z \
  --end   2026-05-06T00:00:00Z \
  --json
```

```bash
# Everything since May 1st.
imsg history --chat-id 42 --start 2026-05-01T00:00:00Z --json
```

```bash
# Everything before May 6th.
imsg history --chat-id 42 --end 2026-05-06T00:00:00Z --json
```

--------------------------------

### Confirm Sent Messages (JSON Mode)

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Enable JSON output mode for send confirmations, which emits `{"status":"sent"}` on success. For more detailed acknowledgments including rowid and GUID, use the JSON-RPC `send` method.

```bash
imsg send --to "+14155551212" --text "hi" --json
```

--------------------------------

### Efficiently Process Large History Output

Source: https://github.com/openclaw/imsg/blob/main/docs/history.md

For very large message histories, stream the JSON output and process it line by line using tools like `jq` to avoid buffering the entire result in memory. This example filters for inbound messages and saves them to a file.

```bash
imsg history --chat-id 42 --limit 5000 --json \
  | jq -c 'select(.is_from_me == false)' \
  > inbound.ndjson
```

--------------------------------

### Get Group Chat Details - imsg CLI

Source: https://github.com/openclaw/imsg/blob/main/docs/groups.md

Use the `imsg group` command to retrieve details about a specific chat, including its ID, identifier, GUID, name, service, group status, participants, and routing hints. This command works for both group and direct chats.

```bash
imsg group --chat-id 42
```

```bash
imsg group --chat-id 42 --json
```

--------------------------------

### Build and Run imsg from Source

Source: https://github.com/openclaw/imsg/blob/main/README.md

Build the imsg tool from its source code and run the help command. This requires having the source code locally.

```bash
make build
./bin/imsg --help
```

--------------------------------

### Build imsg from source

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Clone the repository, navigate into the directory, and run 'make build' to compile the universal release binary. The binary will be located at 'bin/imsg'.

```bash
git clone https://github.com/steipete/imsg.git
cd imsg
make build
./bin/imsg --help
```

--------------------------------

### Build and Launch imsg Helper

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Builds the imsg project and its dylib, then launches Messages.app with the helper dylib injected. Verifies the bridge status.

```bash
csrutil disable

make build && make build-dylib
imsg launch                 # kills + relaunches Messages with DYLD_INSERT
imsg status                 # expect: bridge version: v2 (v2 inbox active)
```

--------------------------------

### Build and Launch IMCore Bridge Helper

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Commands to build the helper dylib and launch Messages.app with it injected. The `imsg launch` command will refuse to proceed if SIP is enabled.

```bash
make build-dylib   # produces .build/release/imsg-bridge-helper.dylib (arm64e)
imsg launch        # launches Messages.app with the dylib injected
imsg status        # confirms the bridge is up
```

--------------------------------

### Develop imsg with make

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

For day-to-day development, use 'make imsg' with custom arguments to perform a clean debug rebuild and run the binary.

```bash
make imsg ARGS="chats --limit 5"
```

--------------------------------

### Get Nickname

Source: https://github.com/openclaw/imsg/blob/main/README.md

Retrieve the nickname associated with a given address.

```APIDOC
## nickname

### Description
Retrieve the nickname associated with a given address.

### Method
`imsg nickname`

### Parameters
#### Query Parameters
- `--address` (string) - Required - The address (phone number or email) to get the nickname for.
```

--------------------------------

### Get Account Information

Source: https://github.com/openclaw/imsg/blob/main/README.md

Display the active iMessage account and its aliases.

```APIDOC
## account

### Description
Display the active iMessage account and its aliases.

### Method
`imsg account`
```

--------------------------------

### Tag and push a new release version

Source: https://github.com/openclaw/imsg/blob/main/docs/RELEASING.md

Create an annotated Git tag for the new release version and push it to the origin repository. This marks the release point in the project's history.

```bash
git tag -a vX.Y.Z -m "vX.Y.Z"

```

```bash
git push origin vX.Y.Z

```

--------------------------------

### Generate Fish Completions

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Fish automatically picks up new completions when launched if they are placed in `~/.config/fish/completions/`.

```bash
imsg completions fish > ~/.config/fish/completions/imsg.fish
```

--------------------------------

### Whois Lookup

Source: https://github.com/openclaw/imsg/blob/main/README.md

Perform a lookup for a given address to get associated iMessage information.

```APIDOC
## whois

### Description
Perform a lookup for a given address to get associated iMessage information.

### Method
`imsg whois`

### Parameters
#### Query Parameters
- `--address` (string) - Required - The address (phone number or email) to look up.
- `--type` (string) - Required - The type of address ('phone' or 'email').
```

--------------------------------

### Watch Live dylib Events with JSON Output

Source: https://context7.com/openclaw/imsg/llms.txt

Merges live dylib events with watch output, including typing indicators from IMCore, and provides JSON formatted output.

```bash
# Live dylib events merged with watch output (typing indicators from IMCore)
imsg watch --bb-events --json
```

--------------------------------

### Development Commands for iMessage CLI

Source: https://github.com/openclaw/imsg/blob/main/README.md

Standard development commands including linting, testing, and building the project. `make test` applies a SQLite.swift patch.

```bash
make lint
```

```bash
make test
```

```bash
make build
```

--------------------------------

### Create a GitHub release

Source: https://github.com/openclaw/imsg/blob/main/docs/RELEASING.md

Create a new release on GitHub using the 'gh' CLI, associating the tagged version with the release notes and the built macOS archive. This makes the release available for download.

```bash
gh release create vX.Y.Z /tmp/imsg-macos.zip -t "vX.Y.Z" -F /tmp/release-notes.txt

```

--------------------------------

### Build and Inject Helper dylib for Messages.app

Source: https://context7.com/openclaw/imsg/llms.txt

Builds a helper dylib and injects it into Messages.app. Requires SIP to be disabled. Use `imsg status` to confirm the bridge is up.

```bash
# Build and inject helper dylib (requires SIP disabled)
make build-dylib
imsg launch              # injects dylib into Messages.app
```

```bash
imsg status              # confirm bridge is up (read-only, safe anywhere)
```

```bash
imsg status --json       # machine-readable bridge status
```

--------------------------------

### Filter chat list by group status

Source: https://github.com/openclaw/imsg/blob/main/docs/chats.md

Filters the JSON output of `imsg chats` to show only group conversations. Requires `jq` to be installed.

```bash
imsg chats --json | jq -s 'map(select(.is_group == true))'
```

--------------------------------

### Create Chat and Manage Members

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Creates a new chat, adds members, renames it, sets a photo, removes a member, and leaves the chat. `chat-create` is iMessage-only.

```bash
imsg chat-create --addresses '+15551111111,+15552222222' \
  --name 'imsg test' --text 'hello' --json
# Capture the new chatGuid from the JSON output:
export GROUP=<paste chatGuid>
imsg chat-add-member --chat "$GROUP" --address +15553333333
imsg chat-name --chat "$GROUP" --name 'imsg test renamed'
imsg chat-photo --chat "$GROUP" --file ~/Pictures/test.jpg
imsg chat-remove-member --chat "$GROUP" --address +15553333333
imsg chat-leave --chat "$GROUP"
```

--------------------------------

### Filter chat list by service

Source: https://github.com/openclaw/imsg/blob/main/docs/chats.md

Filters the JSON output of `imsg chats` to show only conversations from a specific service, such as 'SMS'. Requires `jq` to be installed.

```bash
imsg chats --json | jq -s 'map(select(.service == "SMS"))'
```

--------------------------------

### Edit, Unsend, or Delete Messages (macOS 13+)

Source: https://context7.com/openclaw/imsg/llms.txt

Allows editing, unsending, or deleting messages using their GUID on macOS 13 (Ventura) and later.

```bash
# Message mutation (macOS 13+)
imsg edit --chat 'iMessage;-;+14155551212' --message <guid> --new-text "actually..."
```

```bash
imsg unsend --chat 'iMessage;-;+14155551212' --message <guid>
```

```bash
imsg delete-message --chat 'iMessage;-;+14155551212' --message <guid>
```

--------------------------------

### Check chat.db existence

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Verify if the chat.db file exists. If it's missing, Messages.app needs to be opened to complete sign-in and database creation.

```bash
ls -la ~/Library/Messages/chat.db
```

--------------------------------

### Manage Chats: Create, Add/Remove Members, Leave, Rename, Mark Read

Source: https://context7.com/openclaw/imsg/llms.txt

Commands for managing chats, including creating new chats, adding or removing members, leaving a chat, renaming it, and marking it as read.

```bash
# Chat management
imsg chat-create --addresses '+14155551111,+14155552222' --name 'Crew' --text 'gm'
```

```bash
imsg chat-add-member --chat 'iMessage;+;chat0000' --address +14155553333
```

```bash
imsg chat-remove-member --chat 'iMessage;+;chat0000' --address +14155553333
```

```bash
imsg chat-leave --chat 'iMessage;+;chat0000'
```

```bash
imsg chat-name --chat 'iMessage;+;chat0000' --name 'Renamed'
```

```bash
imsg chat-mark --chat 'iMessage;+;chat0000' --read
```

--------------------------------

### Check chat.db accessibility with sqlite3

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Use this command to verify if sqlite3 can access the chat database. If this fails but imsg works, the parent process of imsg is missing Full Disk Access. If both fail, Full Disk Access needs to be fixed.

```bash
sqlite3 ~/Library/Messages/chat.db 'pragma quick_check;'
```

--------------------------------

### Edit and Unsend Messages (macOS 13+)

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Sends a message, captures its GUID, edits it to a new version, and then unsends it. This functionality requires macOS 13 or later.

```bash
imsg send-rich --chat "$CHAT" --text "rough draft"
# Capture the new guid:
imsg history --chat-id 1 --limit 1 --json | jq -r '.guid'
export MSG=<paste guid>
imsg edit --chat "$CHAT" --message "$MSG" --new-text "polished version"
imsg unsend --chat "$CHAT" --message "$MSG"
```

--------------------------------

### Launch Messages with Custom Dylib or Kill Process

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Commands to launch Messages.app with a custom dylib injected or to simply quit Messages without relaunching. The `--kill-only` option is useful for tearing down a stale injection.

```bash
imsg launch --dylib /path/to/custom.dylib
```

```bash
imsg launch --kill-only           # quit Messages without launching
```

```bash
imsg launch --json                # machine-readable launch result
```

--------------------------------

### Verify macOS build signing and entitlements

Source: https://github.com/openclaw/imsg/blob/main/docs/RELEASING.md

After unzipping the macOS release archive, verify the code signing and entitlements of the imsg executable. This ensures the application is properly signed and notarized.

```bash
unzip -q /tmp/imsg-macos.zip -d /tmp/imsg-check

```

```bash
codesign -d --entitlements :- /tmp/imsg-check/imsg

```

```bash
spctl -a -t exec -vv /tmp/imsg-check/imsg

```

--------------------------------

### Send Rich Messages with Effects and Inline Replies

Source: https://context7.com/openclaw/imsg/llms.txt

Sends rich messages with iMessage effects and supports inline replies using a message GUID. Requires the bridge.

```bash
# Rich send with iMessage effect and inline reply (bridge required)
imsg send-rich --chat 'iMessage;-;+14155551212' --text "boom" \
  --effect com.apple.MobileSMS.expressivesend.impact \
  --reply-to <messageGuid>
```

--------------------------------

### Send Standard Tapbacks (Reactions)

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Apply standard tapbacks (reactions) to messages in a chat using the `imsg react` command. Supports 'love', 'like', 'dislike', 'laugh', 'emphasis', and 'question'.

```bash
imsg react --chat-id 42 --reaction love
```

```bash
imsg react --chat-id 42 --reaction like
```

```bash
imsg react --chat-id 42 --reaction dislike
```

```bash
imsg react --chat-id 42 --reaction laugh
```

```bash
imsg react --chat-id 42 --reaction emphasis
```

```bash
imsg react --chat-id 42 --reaction question
```

--------------------------------

### Generate Zsh Completions

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

For Zsh, generate completions into `~/.zsh/completions/` and ensure this directory is on your `fpath` and `compinit` is called in your `~/.zshrc`.

```bash
mkdir -p ~/.zsh/completions
imsg completions zsh > ~/.zsh/completions/_imsg
```

```zsh
fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit
```

--------------------------------

### Mark Chat as Read

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Commands to mark a chat as read for a specific handle, optionally specifying chat ID, identifier, or GUID. This is useful for programmatic agents to clear unread counters without UI interaction.

```bash
imsg read --to "+14155551212"
```

```bash
imsg read --to "+14155551212" --chat-id 42
```

```bash
imsg read --to "+14155551212" --chat-identifier "iMessage;+;chat..."
```

```bash
imsg read --to "+14155551212" --chat-guid "iMessage;+;chat..."
```

--------------------------------

### Send Files and Audio

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Attach files or audio messages to your outgoing messages. Files are staged in `~/Library/Messages/Attachments/imsg/` before sending. Audio files are sent as audio messages.

```bash
imsg send --to "+14155551212" --text "see attached" --file ~/Desktop/note.pdf
```

```bash
imsg send --to "Jane Appleseed" --file ~/Desktop/voice.m4a
```

```bash
imsg send --chat-id 42 --file ~/Desktop/screenshot.png
```

--------------------------------

### Generate Shell Completions

Source: https://github.com/openclaw/imsg/blob/main/README.md

Generate command-line completion scripts for various shells (zsh, llm). This helps in using the imsg CLI more efficiently.

```bash
imsg completions zsh
```

```bash
imsg completions llm
```

--------------------------------

### Stream New Messages

Source: https://github.com/openclaw/imsg/blob/main/README.md

Monitor a chat for new incoming messages in real-time. Options include specifying a starting row ID, including attachments and reactions, and setting a debounce interval. JSON output is available.

```bash
imsg watch --chat-id 42 --json
```

```bash
imsg watch --chat-id 42 --since-rowid 9000 --attachments --reactions --debounce 250ms --json
```

--------------------------------

### Mutate Messages with iMessage CLI (macOS 13+)

Source: https://github.com/openclaw/imsg/blob/main/README.md

Edit, unsend, delete, or notify for messages using the mutate commands. Requires macOS 13+ and availability surfaced in `imsg status`. Use the message GUID to target specific messages.

```bash
imsg edit --chat ... --message <guid> --new-text "actually..."
```

```bash
imsg unsend --chat ... --message <guid>
```

```bash
imsg delete-message --chat ... --message <guid>
```

```bash
imsg notify-anyways --chat ... --message <guid>
```

--------------------------------

### Generate Bash Completions

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

To enable tab-completion for `imsg` in Bash, redirect the output to a file in `~/.bash_completion.d/` or a system-wide directory.

```bash
imsg completions bash > ~/.bash_completion.d/imsg
```

```bash
sudo imsg completions bash > /usr/local/etc/bash_completion.d/imsg
```

--------------------------------

### Generate LLM Markdown Reference

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Generate a Markdown CLI reference for `imsg` commands, flags, and arguments. This is useful for embedding in LLM prompts or tool documentation.

```bash
imsg completions llm
```

```bash
imsg completions llm > /tmp/imsg-help.md
```

--------------------------------

### Manage Chats with iMessage CLI

Source: https://github.com/openclaw/imsg/blob/main/README.md

Commands for creating, renaming, updating photos, adding/removing members, leaving, deleting, and marking chats. `chat-create` currently only supports iMessage chats.

```bash
imsg chat-create --addresses '+15551111111,+15552222222' --name 'Crew' --text 'gm'
```

```bash
imsg chat-name --chat ... --name 'Renamed'
```

```bash
imsg chat-photo --chat ... --file ~/Downloads/g.jpg     # set
```

```bash
imsg chat-photo --chat ...                              # clear
```

```bash
imsg chat-add-member --chat ... --address +15553333333
```

```bash
imsg chat-remove-member --chat ... --address +15553333333
```

```bash
imsg chat-leave --chat ...
```

```bash
imsg chat-delete --chat ...
```

```bash
imsg chat-mark --chat ... --read     # or --unread
```

--------------------------------

### Send messages and files with imsg send

Source: https://context7.com/openclaw/imsg/llms.txt

Use `imsg send` to send text messages and files via Messages.app. You can specify recipients by phone number, email, or contact name, and target specific chats using chat ID, identifier, or GUID. Files are automatically staged.

```bash
# Direct send by phone (E.164 preferred), email, or contact name
imsg send --to "+14155551212" --text "hi"
imsg send --to "jane@example.com" --text "hi"
imsg send --to "Jane Appleseed" --text "hi"
```

```bash
# Force service
imsg send --to "+14155551212" --text "hi" --service imessage
imsg send --to "+14155551212" --text "hi" --service sms
imsg send --to "+14155551212" --text "hi" --service auto   # default
```

```bash
# Local phone number with region
imsg send --to "415-555-1212" --text "hi" --region US
```

```bash
# Send to a group by chat-id (preferred), identifier, or guid
imsg send --chat-id 42 --text "same thread"
imsg send --chat-identifier "iMessage;+;chat1234567890" --text "hi"
imsg send --chat-guid "iMessage;+;chat1234567890" --text "hi"
```

```bash
# Send a file (auto-staged under ~/Library/Messages/Attachments/imsg/)
imsg send --to "+14155551212" --file ~/Desktop/note.pdf
imsg send --to "Jane Appleseed" --text "see attached" --file ~/Desktop/voice.m4a
imsg send --chat-id 42 --file ~/Desktop/screenshot.png
```

```bash
# JSON output: {"status":"sent"}
imsg send --to "+14155551212" --text "hi" --json
```

--------------------------------

### Send to Group Chat - imsg CLI

Source: https://github.com/openclaw/imsg/blob/main/docs/groups.md

Use the `--chat-id`, `--chat-identifier`, or `--chat-guid` flags to send messages to a group chat. The `--chat-id` is preferred for local database stability, while `--chat-identifier` and `--chat-guid` are portable.

```bash
imsg send --chat-id 42 --text "hi"
```

```bash
imsg send --chat-identifier "iMessage;+;chat1234567890" --text "hi"
```

```bash
imsg send --chat-guid "iMessage;+;chat1234567890" --text "hi"
```

--------------------------------

### Standard Tapbacks (Reactions)

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Send standard tapbacks (reactions) to messages in a chat.

```APIDOC
## Standard Tapbacks

### Description
Send standard tapbacks (reactions) to messages.

### Method
`imsg react`

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--chat-id` (integer) - Required - The ID of the chat containing the message to react to.
- `--reaction` (string) - Required - The type of reaction to send (e.g., `love`, `like`, `dislike`, `laugh`, `emphasis`, `question`).

### Request Example
```bash
imsg react --chat-id 42 --reaction love
imsg react --chat-id 42 --reaction like
imsg react --chat-id 42 --reaction dislike
imsg react --chat-id 42 --reaction laugh
imsg react --chat-id 42 --reaction emphasis
imsg react --chat-id 42 --reaction question
```

**Note:** Only standard tapbacks are supported. Custom emoji tapbacks are not supported.
```

--------------------------------

### Stream New Messages Live with Reactions

Source: https://github.com/openclaw/imsg/blob/main/docs/index.md

Continuously stream new messages for a given chat ID as they arrive. This command also includes reactions (tapbacks) in the output. The `--json` flag ensures parseable output.

```bash
# Stream new messages live, including tapbacks.
imsg watch --chat-id 42 --reactions --json
```

--------------------------------

### Sending Files and Audio

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Attach files and audio messages to your outgoing messages.

```APIDOC
## Files and Audio

### Description
Send messages with attached files or audio recordings.

### Method
`imsg send`

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--to` (string) - Optional - Recipient for direct send.
- `--chat-id` (integer) - Optional - Group chat ID for group send.
- `--chat-identifier` (string) - Optional - Group chat identifier for group send.
- `--chat-guid` (string) - Optional - Group chat GUID for group send.
- `--text` (string) - Optional - The message content.
- `--file` (string) - Required - The path to the file to attach (e.g., `~/Desktop/note.pdf`, `~/Desktop/voice.m4a`).

### Request Example
```bash
imsg send --to "+14155551212" --text "see attached" --file ~/Desktop/note.pdf
imsg send --to "Jane Appleseed" --file ~/Desktop/voice.m4a
imsg send --chat-id 42 --file ~/Desktop/screenshot.png
```

**Note:** Files are staged under `~/Library/Messages/Attachments/imsg/` before sending.
```

--------------------------------

### Watch Live iMessage Events

Source: https://github.com/openclaw/imsg/blob/main/README.md

Monitor live events like typing indicators using `watch --bb-events`. Use `--json` for structured event output.

```bash
imsg watch --bb-events                                  # merge dylib events into stdout
```

```bash
imsg watch --bb-events --json                           # one JSON object per event
```

--------------------------------

### Send Attachment with iMessage CLI

Source: https://github.com/openclaw/imsg/blob/main/README.md

Use `send-attachment` to send files or audio messages. Specify the chat and the file path. Use the `--audio` flag for audio files.

```bash
imsg send-attachment --chat ... --file ~/Pictures/img.jpg
```

```bash
imsg send-attachment --chat ... --file ~/audio.caf --audio
```

--------------------------------

### Update GitHub release notes

Source: https://github.com/openclaw/imsg/blob/main/docs/RELEASING.md

If necessary, edit the existing GitHub release to update its notes. This command allows for manual adjustments to the release description after the initial creation.

```bash
gh release edit vX.Y.Z --notes-file /tmp/release-notes.txt

```

--------------------------------

### Send message and receive verification

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Demonstrates sending a message via the RPC interface and the expected response, including success status and identifiers.

```json
{"jsonrpc":"2.0","id":"3","method":"send","params":{"to":"+14155551212","text":"hi"}}
```

```json
{"jsonrpc":"2.0","id":"3","result":{"ok":true,"id":1979,"guid":"8DF..."}}
```

--------------------------------

### Generate Shell Completions for imsg

Source: https://context7.com/openclaw/imsg/llms.txt

Generates shell tab-completion scripts for Bash, Zsh, and Fish. Also generates a Markdown CLI reference for LLM integration.

```bash
# Bash
imsg completions bash > ~/.bash_completion.d/imsg
```

```bash
# Zsh
mkdir -p ~/.zsh/completions
imsg completions zsh > ~/.zsh/completions/_imsg
# Add to ~/.zshrc:
# fpath=(~/.zsh/completions $fpath)
# autoload -U compinit && compinit
```

```bash
# Fish
imsg completions fish > ~/.config/fish/completions/imsg.fish
```

```bash
# LLM reference — embed in agent system prompt for accurate in-context help
imsg completions llm > /tmp/imsg-help.md
```

--------------------------------

### Send Standard Tapbacks

Source: https://github.com/openclaw/imsg/blob/main/README.md

Send a standard reaction (tapback) to a message in a chat. Only reliably exposed tapbacks by Messages.app automation are supported.

```bash
imsg react --chat-id 42 --reaction like
```

--------------------------------

### Send a File via Messages

Source: https://github.com/openclaw/imsg/blob/main/docs/index.md

Send a file, such as an audio file, image, or document, through the Messages application. Specify the recipient using `--to` and the file path using `--file`.

```bash
# Send a file (image, audio, document).
imsg send --to "Jane Appleseed" --file ~/Desktop/voice.m4a
```

--------------------------------

### Create Chat

Source: https://github.com/openclaw/imsg/blob/main/README.md

Create a new iMessage chat with specified participants and an initial message.

```APIDOC
## chat-create

### Description
Create a new iMessage chat with specified participants and an initial message.

### Method
`imsg chat-create`

### Parameters
#### Query Parameters
- `--addresses` (string) - Required - Comma-separated list of participant addresses (phone numbers or emails).
- `--name` (string) - Optional - The name for the new chat.
- `--text` (string) - Optional - The initial text message to send.
```

--------------------------------

### Basic History Read

Source: https://github.com/openclaw/imsg/blob/main/docs/history.md

Reads the latest messages from a chat. Use `--json` to pipe output to tools like `jq` for further processing.

```bash
imsg history --chat-id 42 --limit 50
```

```bash
imsg history --chat-id 42 --limit 50 --json | jq -s
```

--------------------------------

### imsg rpc

Source: https://context7.com/openclaw/imsg/llms.txt

Provides a JSON-RPC 2.0 interface over stdio for long-running processes. It exposes functionalities like listing chats, retrieving message history, subscribing to message watches, and sending messages.

```APIDOC
## `imsg rpc` — JSON-RPC 2.0 over stdio

Long-running process that exposes chats, history, watch, and send over JSON-RPC 2.0 (one JSON object per line on stdin/stdout). Designed for agents that want a single persistent subprocess.

### Usage

```bash
# Start the RPC server (no daemon, no port — just a subprocess)
imsg rpc
```

### Methods

#### `chats.list`

*   **Request:**
    ```json
    {"jsonrpc":"2.0","id":"1","method":"chats.list","params":{"limit":10}}
    ```
*   **Response:**
    ```json
    {"jsonrpc":"2.0","id":"1","result":{"chats":[...]}}
    ```

#### `messages.history`

*   **Request:**
    ```json
    {"jsonrpc":"2.0","id":"2","method":"messages.history","params":{
      "chat_id":42,"limit":20,"attachments":true,
      "start":"2026-05-01T00:00:00Z","end":"2026-05-06T00:00:00Z"}}
    ```
*   **Response:**
    ```json
    {"jsonrpc":"2.0","id":"2","result":{"messages":[...]}}
    ```

#### `watch.subscribe`

*   **Request:**
    ```json
    {"jsonrpc":"2.0","id":"3","method":"watch.subscribe","params":{
      "chat_id":42,"since_rowid":9000,"include_reactions":true,"debounce_ms":500}}
    ```
*   **Response:**
    ```json
    {"jsonrpc":"2.0","id":"3","result":{"subscription":1}}
    ```
*   **Notifications:**
    ```json
    {"jsonrpc":"2.0","method":"message","params":{"subscription":1,"message":{...}}}
    ```

#### `watch.unsubscribe`

*   **Request:**
    ```json
    {"jsonrpc":"2.0","id":"4","method":"watch.unsubscribe","params":{"subscription":1}}
    ```
*   **Response:**
    ```json
    {"jsonrpc":"2.0","id":"4","result":{"ok":true}}
    ```

#### `send` (returns rowid + guid when observable)

*   **Request (Direct Message):**
    ```json
    {"jsonrpc":"2.0","id":"5","method":"send","params":{"to":"+14155551212","text":"hi"}}
    ```
*   **Response:**
    ```json
    {"jsonrpc":"2.0","id":"5","result":{"ok":true,"id":1979,"guid":"8DF..."}}
    ```
*   **Request (Group Chat):**
    ```json
    {"jsonrpc":"2.0","id":"6","method":"send","params":{"chat_id":42,"text":"hello group","file":"/tmp/photo.jpg"}}
    ```
*   **Response:**
    ```json
    {"jsonrpc":"2.0","id":"6","result":{"ok":true,"id":1980,"guid":"9EF..."}}
    ```
```

--------------------------------

### Send Attachments

Source: https://github.com/openclaw/imsg/blob/main/docs/attachments.md

Use the --file flag to send attachments. This command stages the file in a dedicated imsg directory within Messages' attachments directory for improved reliability, especially on newer macOS versions.

```bash
imsg send --to "+14155551212" --file ~/Desktop/photo.jpg
```

```bash
imsg send --to "Jane Appleseed" --file ~/Desktop/voice.m4a
```

```bash
imsg send --chat-id 42 --file ~/Desktop/note.pdf
```