268 lines
7.0 KiB
Markdown
268 lines
7.0 KiB
Markdown
---
|
|
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
|