Redflag/system/lettabot_cli_tools.md

description, limit

description	limit
LettaBot CLI tools for messaging, reactions, and channel management. Use via Bash when in Matrix/lettabot context.	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:

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

lettabot-message send --text "Hello from Ani!"

Send File

lettabot-message send --file /path/to/file.pdf --text "Here's the file"

Send to Specific Channel

# 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

# 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

lettabot-react add --emoji "👍"

React to Specific Message

lettabot-react add --emoji "👀" --channel discord --chat 123 --message 456

Emoji Formats

# 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.

# 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.

# 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

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

lettabot channels list
lettabot channels add telegram
lettabot channels remove discord

Skills Management

lettabot skills status
lettabot skills

Model Selection

lettabot model show
lettabot model set "anthropic/claude-sonnet-4-5-20250929"

---

Common Patterns

Send File to Current Matrix Room

lettabot-message send --file /tmp/output.pdf --text "Here's the report"

Quick Acknowledgment Reaction

lettabot-react add --emoji "✅"

Send Image with Caption

lettabot-message send --file screenshot.png --image --text "Check this out!"

Send to Different Platform

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