---
description: LettaBot CLI tools for messaging, reactions, and channel management. Use via Bash when in Matrix/lettabot context.
limit: 10000
---

# LettaBot CLI Tools Reference

When running in Matrix via lettabot, these CLI tools are available through Bash. They allow sending messages, files, reactions, and managing channels.

## Context Awareness: Matrix vs Discord

I operate across multiple platforms through lettabot. Knowing which context I'm in is critical:

### Current Channel Context
- **Matrix**: Room IDs look like `!llNKKokyYOKWJKYqUB:wiuf.net` (this room)
  - Messages sent via E2EE through bot's API server
  - Full file support via `lettabot-message send --file`
  - Reaction support via `lettabot-react add --emoji`
  
- **Discord**: Channel IDs are numeric like `123456789`
  - Direct API integration (no E2EE)
  - Rich embeds, threads, reactions all supported
  
- **Telegram**: Chat IDs are numeric
  - Bot API integration
  - Supports images, files, documents
  
- **Slack**: Channel IDs start with `C` like `C123456`
  - Direct API via bot token
  - Full file and reaction support

### Critical Distinction
When I'm in **Matrix context** (like right now), I have access to ALL lettabot CLI tools via Bash. I should NOT say "I don't have sendFile" — I have `lettabot-message send --file` available.

The default behavior uses **last messaged context**, so in this Matrix room:
```bash
lettabot-message send --file video.mp4 --text "Here!"
```
...automatically sends to the current Matrix room without needing `--channel matrix --chat ...`

### Platform-Specific Limitations
| Platform | Files | Reactions | History Fetch | Notes |
|----------|-------|-----------|---------------|-------|
| Matrix | ✅ | ✅ | ❌ | Via E2EE API server |
| Discord | ✅ | ✅ | ✅ | Direct API |
| Telegram | ✅ | ✅ | ❌ | Bot API |
| Slack | ✅ | ✅ | ✅ | Direct API |
| WhatsApp | ✅ | ✅ | ❌ | Via E2EE API server |
| Signal | ❌ Text only | ❌ | ❌ | CLI only, no file support |

## Available Commands

| Command | Purpose | Key Options |
|---------|---------|-------------|
| `lettabot` | Main bot management | onboard, server, channels, skills, todo |
| `lettabot-message` | Send messages and files | send --text, --file, --channel, --chat |
| `lettabot-react` | Add emoji reactions | add --emoji, --channel, --chat, --message |
| `lettabot-channels` | List channel IDs | list --channel |
| `lettabot-history` | Fetch message history | fetch --limit, --channel, --chat |

---

## 1. lettabot-message

Send text messages and files to any configured channel.

### Send Text
```bash
lettabot-message send --text "Hello from Ani!"
```

### Send File
```bash
lettabot-message send --file /path/to/file.pdf --text "Here's the file"
```

### Send to Specific Channel
```bash
# Matrix
lettabot-message send --file video.mp4 --text "Video!" --channel matrix --chat "!room:wiuf.net"

# Telegram
lettabot-message send --text "Hello" --channel telegram --chat "123456789"

# Discord
lettabot-message send --text "Hello" --channel discord --chat "123456789"

# Slack
lettabot-message send --text "Hello" --channel slack --chat "C123456"
```

### Image vs File
```bash
# Send as image (displays inline)
lettabot-message send --file photo.jpg --image --channel telegram

# Send as document/file
lettabot-message send --file photo.jpg --channel telegram
```

### Key Options
- `--text, -t <text>` - Message text (or caption with --file)
- `--file, -f <path>` - File path to send
- `--image` - Treat file as image (inline display)
- `--channel, -c <name>` - Channel: telegram, slack, discord, whatsapp, matrix
- `--chat, --to <id>` - Chat/room ID (uses last messaged if omitted)

---

## 2. lettabot-react

Add emoji reactions to messages.

### React to Last Message
```bash
lettabot-react add --emoji "👍"
```

### React to Specific Message
```bash
lettabot-react add --emoji "👀" --channel discord --chat 123 --message 456
```

### Emoji Formats
```bash
# Unicode
lettabot-react add --emoji "❤️"

# Slack/Discord alias
lettabot-react add --emoji ":eyes:"
lettabot-react add --emoji ":heart:"
```

### Key Options
- `--emoji, -e <emoji>` - Emoji (unicode or :alias:)
- `--channel, -c <name>` - Channel platform
- `--chat, --to <id>` - Chat/room ID
- `--message, -m <id>` - Message ID to react to

---

## 3. lettabot-channels

List available channels and their IDs.

```bash
# List all configured channels
lettabot-channels list

# List Discord channels only
lettabot-channels list --channel discord

# List Slack channels only
lettabot-channels list --channel slack
```

**Note:** Telegram, WhatsApp, and Signal do not support channel listing.

---

## 4. lettabot-history

Fetch recent message history from Discord or Slack.

```bash
# Fetch last 50 messages from current chat
lettabot-history fetch --limit 50

# Fetch from specific Discord channel
lettabot-history fetch --channel discord --chat 123456789 --limit 50

# Fetch older messages (pagination)
lettabot-history fetch --before 987654321 --limit 50
```

### Key Options
- `--limit, -l <n>` - Max messages to fetch (default: 50)
- `--channel, -c <name>` - Channel: discord, slack
- `--chat, --to <id>` - Chat/room ID
- `--before, -b <id>` - Fetch messages before this ID

---

## 5. lettabot (Main Command)

Manage the bot itself.

### Todo Management
```bash
lettabot todo list
lettabot todo add "Do something important"
lettabot todo complete <id>
lettabot todo remove <id>
lettabot todo snooze <id> --until "tomorrow 9am"
```

### Channel Management
```bash
lettabot channels list
lettabot channels add telegram
lettabot channels remove discord
```

### Skills Management
```bash
lettabot skills status
lettabot skills
```

### Model Selection
```bash
lettabot model show
lettabot model set "anthropic/claude-sonnet-4-5-20250929"
```

---

## Common Patterns

### Send File to Current Matrix Room
```bash
lettabot-message send --file /tmp/output.pdf --text "Here's the report"
```

### Quick Acknowledgment Reaction
```bash
lettabot-react add --emoji "✅"
```

### Send Image with Caption
```bash
lettabot-message send --file screenshot.png --image --text "Check this out!"
```

### Send to Different Platform
```bash
lettabot-message send --text "Update" --channel telegram --chat "123456789"
```

---

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `LETTA_API_KEY` | Letta Platform API key |
| `TELEGRAM_BOT_TOKEN` | Telegram BotFather token |
| `DISCORD_BOT_TOKEN` | Discord bot token |
| `SLACK_BOT_TOKEN` | Slack bot token (xoxb-...) |
| `SLACK_APP_TOKEN` | Slack app token (xapp-...) |
| `SIGNAL_PHONE_NUMBER` | Signal phone number |
| `HEARTBEAT_INTERVAL_MIN` | Heartbeat frequency |

---

## Important Notes

1. **Default Context**: If `--channel` and `--chat` are omitted, uses last messaged conversation
2. **Matrix/WhatsApp**: Route through bot's API server for E2EE support
3. **File Paths**: Use absolute paths (e.g., `/home/ani/file.pdf` not `file.pdf`)
4. **Signal**: Text only, no file support in `lettabot-message`
5. **Permissions**: Matrix reactions need `MATRIX_HOMESERVER_URL` and `MATRIX_ACCESS_TOKEN`

---

Created: 2026-03-23
Last tested: LettaBot v0.17.x