diff --git a/README.md b/README.md index a2f554d..3b4a4e1 100644 --- a/README.md +++ b/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 diff --git a/cli/README.md b/cli/README.md index be24c75..e1cb5d0 100644 --- a/cli/README.md +++ b/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 ``` +## 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`: diff --git a/cli/cmd/onetime.go b/cli/cmd/onetime.go index 369b7bf..1282d7b 100644 --- a/cli/cmd/onetime.go +++ b/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)