Make one-time schedules message-first with optional delay

Changed paradigm from 'schedule a message' to 'send a message (optionally later)':

CLI Changes:
- execute-at flag now optional (defaults to 'now' for immediate delivery)
- Added 'send' and 'message' aliases to onetime command
- Updated command descriptions to focus on messaging
- Better success messages ('Message sent' vs 'Schedule created')

Usage Examples:
  # Send immediately (new!)
  letta-schedules send --agent-id xxx --message 'Hello'

  # Send later (still works)
  letta-schedules send --agent-id xxx --message 'Reminder' --execute-at 'tomorrow at 9am'

Documentation:
- Updated CLI README with send-first paradigm
- Added section on future cross-server messaging with permissions
- Updated main README to promote CLI as recommended usage

Future Vision:
- Permission tables for cross-server agent messaging
- Federated agent communication across Letta instances
- Agent-to-agent messaging across organizations

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

README.md

@@ -159,9 +159,33 @@ Same functionality using curl commands.
 LETTA_API_KEY=sk-xxx LETTA_AGENT_ID=agent-yyy python test_api.py
 ```
 
+## CLI Usage (Recommended)
+
+The easiest way to interact with letta-schedules is via the CLI:
+
+```bash
+# Send a message immediately
+letta-schedules send --agent-id agent-xxx --message "Hello!"
+
+# Send a message later
+letta-schedules send --agent-id agent-xxx --message "Reminder" --execute-at "tomorrow at 9am"
+
+# Create recurring schedule
+letta-schedules recurring create --agent-id agent-xxx --message "Daily standup" --cron "every weekday at 9am"
+
+# List schedules
+letta-schedules onetime list
+letta-schedules recurring list
+
+# View results
+letta-schedules results list
+```
+
+See [CLI Documentation](cli/README.md) for installation and full usage guide.
+
 ## API Usage
 
-Base URL: `https://your-modal-app.modal.run`
+Base URL: `https://letta--schedules-api.modal.run`
 
 ### Authentication
 

cli/README.md

@@ -1,14 +1,15 @@
 # Letta Schedules CLI
 
-A command-line interface for managing scheduled messages for Letta AI agents.
+A command-line interface for sending messages to Letta AI agents and managing schedules.
 
 ## Features
 
-- Create and manage recurring schedules with cron expressions
-- Create and manage one-time schedules
-- View execution results
-- Beautiful table output
-- Easy configuration management
+- **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
 
@@ -61,18 +62,34 @@ letta-schedules config set-url https://your-api-url.com
 letta-schedules config show
 ```
 
-### 2. Create a Recurring Schedule
+### 2. Send a Message to an Agent
+
+```bash
+# Send immediately
+letta-schedules send \
+  --agent-id agent-xxx \
+  --message "Hello! How are you doing?"
+
+# Or schedule for later
+letta-schedules send \
+  --agent-id agent-xxx \
+  --message "Reminder: Follow up on project" \
+  --execute-at "tomorrow at 9am"
+```
+
+### 3. Create a Recurring Schedule
 
 ```bash
 letta-schedules recurring create \
   --agent-id agent-xxx \
   --message "Daily check-in" \
-  --cron "0 9 * * *"
+  --cron "every weekday at 9am"
 ```
 
-### 3. List Schedules
+### 4. List Schedules
 
 ```bash
+letta-schedules onetime list
 letta-schedules recurring list
 ```
 
@@ -199,6 +216,45 @@ letta-schedules results list
 letta-schedules 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
+
+```bash
+# Send a message right now (executes within 1 minute)
+letta-schedules send \
+  --agent-id agent-xxx \
+  --message "Hey, how's the project going?"
+```
+
+### Schedule for Later
+
+```bash
+# Relative time
+letta-schedules send \
+  --agent-id agent-xxx \
+  --message "Follow up reminder" \
+  --execute-at "in 2 hours"
+
+# Specific day/time
+letta-schedules 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-schedules/config.yaml`:

cli/cmd/onetime.go

@@ -13,22 +13,30 @@ import (
 )
 
 var onetimeCmd = &cobra.Command{
-	Use:   "onetime",
-	Short: "Manage one-time schedules",
-	Long:  "Create, list, view, and delete one-time schedules for Letta agents",
+	Use:     "onetime",
+	Aliases: []string{"send", "message"},
+	Short:   "Send messages to agents",
+	Long:    "Send one-time messages to Letta agents immediately or scheduled for later",
 }
 
 var onetimeCreateCmd = &cobra.Command{
-	Use:   "create",
-	Short: "Create a new one-time schedule",
+	Use:     "create",
+	Aliases: []string{"send"},
+	Short:   "Send a message to an agent",
+	Long:    "Send a message to an agent immediately or scheduled for later",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		agentID, _ := cmd.Flags().GetString("agent-id")
 		message, _ := cmd.Flags().GetString("message")
 		role, _ := cmd.Flags().GetString("role")
 		executeAt, _ := cmd.Flags().GetString("execute-at")
 
-		if agentID == "" || message == "" || executeAt == "" {
-			return fmt.Errorf("agent-id, message, and execute-at are required")
+		if agentID == "" || message == "" {
+			return fmt.Errorf("agent-id and message are required")
+		}
+
+		// Default to "now" if no time specified
+		if executeAt == "" {
+			executeAt = "now"
 		}
 
 		// Parse natural language time to ISO 8601
@@ -56,7 +64,11 @@ var onetimeCreateCmd = &cobra.Command{
 			return fmt.Errorf("failed to create schedule: %w", err)
 		}
 
-		color.Green("✓ One-time schedule created successfully")
+		if executeAt == "now" {
+			color.Green("✓ Message sent successfully (executing immediately)")
+		} else {
+			color.Green("✓ Message scheduled successfully")
+		}
 		fmt.Printf("\nSchedule ID:  %s\n", schedule.ID)
 		fmt.Printf("Agent ID:     %s\n", schedule.AgentID)
 		fmt.Printf("Execute At:   %s\n", schedule.ExecuteAt)
@@ -181,7 +193,7 @@ func init() {
 	onetimeCreateCmd.Flags().String("agent-id", "", "Agent ID (required)")
 	onetimeCreateCmd.Flags().String("message", "", "Message to send (required)")
 	onetimeCreateCmd.Flags().String("role", "user", "Message role (default: user)")
-	onetimeCreateCmd.Flags().String("execute-at", "", "When to execute (required)\n  Examples: 'in 5 minutes', 'tomorrow at 9am', 'next monday at 3pm', '2025-11-07T10:00:00Z'")
+	onetimeCreateCmd.Flags().String("execute-at", "", "When to send (optional, defaults to now)\n  Examples: 'in 5 minutes', 'tomorrow at 9am', 'next monday at 3pm', '2025-11-07T10:00:00Z', or omit for immediate delivery")
 
 	onetimeCmd.AddCommand(onetimeListCmd)
 	onetimeCmd.AddCommand(onetimeGetCmd)