Letta Switchboard CLI #

A command-line interface for sending messages to Letta AI agents and managing schedules.

Features #

• Send messages to agents - Immediately or scheduled for later
• Natural language scheduling - "in 5 minutes", "tomorrow at 9am", "every weekday"
• Recurring schedules - Daily check-ins, weekly summaries, custom patterns
• View execution results - Track message delivery and run IDs
• Beautiful output - Clean tables and colored success messages
• Easy configuration - One-time API key setup

Installation #

From Source #

# Clone the repository
cd cli

# Build the binary
go build -o letta-switchboard

# Move to your PATH (optional)
sudo mv letta-switchboard /usr/local/bin/

Using Go Install #

go install github.com/letta/letta-switchboard-cli@latest

Cross-Platform Build #

# macOS
GOOS=darwin GOARCH=amd64 go build -o letta-switchboard-darwin-amd64
GOOS=darwin GOARCH=arm64 go build -o letta-switchboard-darwin-arm64

# Linux
GOOS=linux GOARCH=amd64 go build -o letta-switchboard-linux-amd64
GOOS=linux GOARCH=arm64 go build -o letta-switchboard-linux-arm64

# Windows
GOOS=windows GOARCH=amd64 go build -o letta-switchboard-windows-amd64.exe

Quick Start #

1. Configure API Credentials #

# Set your Letta API key
letta-switchboard config set-api-key sk-xxx...

# Set the API URL (optional, defaults to Modal deployment)
letta-switchboard config set-url https://your-api-url.com

# View current configuration
letta-switchboard config show

2. Send a Message to an Agent #

# Send immediately
letta-switchboard send \
  --agent-id agent-xxx \
  --message "Hello! How are you doing?"

# Or schedule for later
letta-switchboard send \
  --agent-id agent-xxx \
  --message "Reminder: Follow up on project" \
  --execute-at "tomorrow at 9am"

3. Create a Recurring Schedule #

letta-switchboard recurring create \
  --agent-id agent-xxx \
  --message "Daily check-in" \
  --cron "every weekday at 9am"

4. List Schedules #

letta-switchboard onetime list
letta-switchboard recurring list

Natural Language Support #

The CLI supports natural language input for both time expressions and cron schedules, making it easy to create schedules without memorizing syntax!

One-Time Schedules (Timestamps) #

# Relative time
--execute-at "in 5 minutes"
--execute-at "in 2 hours"
--execute-at "in 3 days"

# Tomorrow
--execute-at "tomorrow at 9am"
--execute-at "tomorrow at 14:30"

# Next weekday
--execute-at "next monday at 3pm"
--execute-at "next friday at 10:00"

# ISO 8601 (still supported)
--execute-at "2025-11-12T19:30:00Z"

Recurring Schedules (Cron Expressions) #

# Minutes
--cron "every 5 minutes"
--cron "every 30 minutes"

# Hourly/Daily
--cron "every hour"
--cron "daily at 9am"
--cron "daily at 14:30"

# Weekdays
--cron "every monday"
--cron "every friday at 3pm"
--cron "every weekday"     # Mon-Fri at 9am
--cron "every weekend"     # Sat-Sun at 9am

# Weekly/Monthly
--cron "weekly"            # Every Monday at 9am
--cron "monthly"           # 1st of month at 9am

# Traditional cron (still supported)
--cron "*/5 * * * *"       # Every 5 minutes
--cron "0 9 * * 1-5"       # Weekdays at 9am

Usage #

Configuration Commands #

# Set API key
letta-switchboard config set-api-key <key>

# Set base URL
letta-switchboard config set-url <url>

# Show configuration
letta-switchboard config show

Recurring Schedules #

# Create a recurring schedule
letta-switchboard recurring create \
  --agent-id <agent-id> \
  --message "Your message" \
  --cron "0 9 * * *" \
  --role user

# List all recurring schedules
letta-switchboard recurring list

# Get details of a specific schedule
letta-switchboard recurring get <schedule-id>

# Delete a schedule
letta-switchboard recurring delete <schedule-id>

Cron Expression Examples #

• 0 9 * * * - Every day at 9:00 AM
• 0 */6 * * * - Every 6 hours
• 0 0 * * 1 - Every Monday at midnight
• */30 * * * * - Every 30 minutes

One-Time Schedules #

# Create a one-time schedule
letta-switchboard onetime create \
  --agent-id <agent-id> \
  --message "Reminder message" \
  --execute-at "2025-11-07T10:00:00Z" \
  --role user

# List all one-time schedules
letta-switchboard onetime list

# Get details of a specific schedule
letta-switchboard onetime get <schedule-id>

# Delete a schedule
letta-switchboard onetime delete <schedule-id>

Execution Results #

# List all execution results
letta-switchboard results list

# Get result for a specific schedule
letta-switchboard results get <schedule-id>

Sending Messages (One-Time Schedules) #

The send (alias: onetime create) command allows you to send messages to agents immediately or scheduled for later.

Send Immediately #

# Send a message right now (executes within 1 minute)
letta-switchboard send \
  --agent-id agent-xxx \
  --message "Hey, how's the project going?"

Schedule for Later #

# Relative time
letta-switchboard send \
  --agent-id agent-xxx \
  --message "Follow up reminder" \
  --execute-at "in 2 hours"

# Specific day/time
letta-switchboard send \
  --agent-id agent-xxx \
  --message "Weekly summary time!" \
  --execute-at "next monday at 10am"

Future: Cross-Server Messaging #

Coming soon: Permission system to allow messaging agents across different Letta servers.

This will enable:

• Send messages to agents on any Letta instance (cloud or self-hosted)
• Permission tables to control who can message which agents
• Cross-organization agent communication
• Federated agent networks

Configuration #

The CLI stores configuration in ~/.letta-switchboard/config.yaml:

api_key: sk-xxx...
base_url: https://letta--schedules-api.modal.run

Examples #

Daily Agent Check-in #

letta-switchboard recurring create \
  --agent-id agent-123 \
  --message "Good morning! Please provide a daily summary." \
  --cron "0 9 * * *"

Hourly Status Update #

letta-switchboard recurring create \
  --agent-id agent-123 \
  --message "Status update please" \
  --cron "0 * * * *"

One-Time Reminder #

letta-switchboard onetime create \
  --agent-id agent-123 \
  --message "Meeting in 1 hour" \
  --execute-at "2025-11-07T14:00:00Z"

Development #

Prerequisites #

• Go 1.21+

Build #

go build -o letta-switchboard

Run Tests #

go test ./...

Update Dependencies #

go mod tidy

License #

MIT