imessage-ts/CLI_USAGE.md

TypeScript library for interacting with iMessage on macOS - send messages, monitor chats, and automate responses

# iMessage SDK CLI Usage Guide

## Installation

```bash
npm install -g imessage-ts
# or
npm install imessage-ts
```

## Commands

### 1. Run HTTP Server

Start an HTTP server to interact with iMessage via a REST API.

```bash
npx imessage-ts run-server [options]
```

#### Options:
- `-p, --port <number>` - Server port (default: 3000)
- `-w, --webhook <url>` - Webhook URL to send events to
- `--whitelist <handles...>` - Whitelisted senders (space-separated)
- `--auto-respond` - Enable auto-responder for whitelisted senders
- `--api-key <key>` - API key for authentication (optional)
- `--config <path>` - Path to JSON config file
- `--temp-attachments-dir <path>` - Directory for temporary attachments (optional)

#### Example:
```bash
# Basic server
npx imessage-ts run-server

# Server with webhook and auto-responder
npx imessage-ts run-server --port 8080 --webhook https://myapp.com/webhook --auto-respond --whitelist +1234567890 +0987654321

# Server with API key authentication
npx imessage-ts run-server --api-key my-secret-key

# Server with custom temporary attachments directory
npx imessage-ts run-server --temp-attachments-dir "$HOME/Desktop/imessage-attachments"

# Server with config file
npx imessage-ts run-server --config ./imessage-config.json
```

#### Config File Format:
```json
{
  "port": 8080,
  "webhookUrl": "https://myapp.com/webhook",
  "whitelistedSenders": ["+1234567890", "+0987654321"],
  "autoRespond": true,
  "apiKey": "my-secret-key",
  "tempAttachmentsDir": "/Users/username/Desktop/imessage-attachments",
  "wittyResponses": [
    "Custom auto-response 1",
    "Custom auto-response 2"
  ]
}
```

#### API Authentication:
When an API key is configured, all API requests (except `/health`) must include it:
- Header: `x-api-key: your-api-key`
- Query parameter: `?apiKey=your-api-key`

Example:
```bash
# With header
curl -H "x-api-key: my-secret-key" http://localhost:3000/conversations

# With query parameter
curl http://localhost:3000/conversations?apiKey=my-secret-key
```

### 2. Send Message

Send a message from the command line.

```bash
# Send a simple text message
imessage-ts send -t "+1234567890" -m "Hello from CLI!"

# Send via SMS instead of iMessage
imessage-ts send -t "+1234567890" -m "SMS message" -s SMS

# Send with attachment
imessage-ts send -t "user@example.com" -m "Check this out!" -a /path/to/image.jpg
```

**Options:**
- `-t, --to <recipient>` - Recipient phone number or email (required)
- `-m, --message <text>` - Message text (required)
- `-s, --service <type>` - Service type: iMessage or SMS (default: iMessage)
- `-a, --attachment <path>` - Path to attachment file

### 3. List Conversations

List recent conversations.

```bash
# List 10 most recent conversations
imessage-ts list-conversations

# List 25 conversations
imessage-ts list-conversations --limit 25
```

**Options:**
- `-l, --limit <number>` - Number of conversations to show (default: 10)

### 4. Watch Messages

Watch for new messages in real-time.

```bash
# Watch and display messages
imessage-ts watch

# Output as JSON (useful for piping to other tools)
imessage-ts watch --json | jq '.'
```

**Options:**
- `--json` - Output messages as JSON

## HTTP Server API

When running the server, the following endpoints are available:

### Health Check
```
GET /health
```
No authentication required. Returns server status.

### Send Message
```
POST /send
Headers: x-api-key: your-api-key (if configured)
Content-Type: application/json

{
  "to": "+1234567890",
  "text": "Hello from the API!",
  "service": "iMessage" // or "SMS"
}
```

### Send Image
```
POST /send-image
Headers: x-api-key: your-api-key (if configured)
Content-Type: application/json

{
  "to": "+1234567890",
  "imagePath": "/path/to/image.jpg",
  "text": "Check out this image!" // optional
}
```

### React to Message