> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduler CLI

> Schedule agents to run continuously 24/7 at regular intervals

The Scheduler CLI enables 24/7 autonomous agent operations by running agents at regular intervals.

## Quick Start

### With Direct Prompt (No YAML needed)

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Schedule with a simple prompt
praisonai schedule "Check AI news and summarize" --interval hourly
```

### With agents.yaml

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Schedule using agents.yaml configuration
praisonai schedule agents.yaml
```

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai praisonaiagents
export OPENAI_API_KEY=your_key_here
```

## PM2-Style Daemon Commands

### Start Scheduler

#### With a Task Prompt

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start as background daemon
praisonai schedule start <name> "Your task" --interval hourly

# With all options
praisonai schedule start my-agent "Monitor logs" \
  --interval "*/30m" \
  --timeout 120 \
  --max-cost 2.00 \
  --max-retries 3

# Examples
praisonai schedule start news-bot "Check AI news" --interval hourly
praisonai schedule start health-check "Monitor system" --interval "*/15m"
praisonai schedule start test-agent "Count to 5" --interval "*/10s"
```

#### With a Recipe

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Schedule a recipe
praisonai schedule start news-monitor --recipe news-analyzer --interval hourly

# Recipe with custom interval
praisonai schedule start daily-report --recipe report-generator --interval daily

# Recipe with all options
praisonai schedule start my-scheduler \
    --recipe my-recipe \
    --interval "*/6h" \
    --timeout 600 \
    --max-cost 2.00 \
    --max-retries 3
```

### List Schedulers

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Show all running schedulers
praisonai schedule list

# Output example:
# Name                 Status     PID      Interval     Task
# ================================================================
# news-bot             🟢 running  12345    hourly       Check AI news
# health-check         🟢 running  12346    */15m        Monitor system
# 
# Total: 2 scheduler(s)
```

### View Logs

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# View last 50 lines
praisonai schedule logs <name>

# Follow logs in real-time
praisonai schedule logs <name> -f

# Examples
praisonai schedule logs news-bot
praisonai schedule logs news-bot --follow
```

### Stop Scheduler

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Graceful shutdown
praisonai schedule stop <name>

# Example
praisonai schedule stop news-bot
```

### Restart Scheduler

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Restart with same configuration
praisonai schedule restart <name>

# Example
praisonai schedule restart news-bot
```

### Delete Scheduler

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Remove from list (must be stopped first)
praisonai schedule delete <name>

# Example
praisonai schedule delete news-bot
```

### Describe Scheduler

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Show detailed information
praisonai schedule describe <name>

# Shows: PID, status, uptime, executions, cost, config, logs path
```

## Legacy Foreground Mode

For quick testing or one-off runs, use foreground mode:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Direct prompt (runs in foreground)
praisonai schedule "Your task" --interval hourly

# YAML mode (runs in foreground)
praisonai schedule agents.yaml
```

**YAML Configuration Example:**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai

agents:
  - name: "AI News Monitor"
    role: "Technology News Analyst"
    goal: "Monitor and summarize AI news"
    instructions: "Search for latest AI developments"
    tools:
      - search_tool
    verbose: true

task: "Search for latest AI news and provide top 3 stories"

schedule:
  interval: "hourly"
  max_retries: 3
  run_immediately: true
  timeout: 60
  max_cost: 1.00
```

**Run YAML in foreground:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule agents.yaml
```

Press `Ctrl+C` to stop. Shows final statistics:

```
Execution stats - Total: 12, Success: 11, Failed: 1
Total cost: $0.0056
Runtime: 3600.5s
```

## Storage Locations

* **Schedule data:** `~/.praisonai/config.yaml` (under the `schedules` key)
* **Log files:** `~/.praisonai/logs/*.log`

<Note>
  Schedules are stored in the same `config.yaml` used by agents and server configuration. Legacy `jobs.json` data is auto-migrated on first use.
</Note>

## Features

✅ **PM2-style daemon management** - No nohup needed\
✅ **Process persistence** - State saved to disk\
✅ **Easy lifecycle control** - start/stop/restart/list\
✅ **Centralized logging** - Auto-rotation, follow mode\
✅ **Graceful shutdown** - SIGTERM with SIGKILL fallback\
✅ **Cost monitoring** - Budget limits with \$1.00 default\
✅ **Timeout protection** - Prevent runaway executions\
✅ **Auto cleanup** - Dead processes removed automatically

## Schedule Intervals

| Format   | Interval | Description               |
| -------- | -------- | ------------------------- |
| `hourly` | 3600s    | Every hour                |
| `daily`  | 86400s   | Every 24 hours            |
| `*/30m`  | 1800s    | Every 30 minutes          |
| `*/6h`   | 21600s   | Every 6 hours             |
| `*/5s`   | 5s       | Every 5 seconds (testing) |
| `3600`   | 3600s    | Custom seconds            |

## Examples

### Example 1: Simple Prompt Scheduling

**Quick news check every hour:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule "Search for latest AI news and summarize top 3 stories" --interval hourly --verbose
```

**System monitoring every 15 minutes:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule "Check system health and disk space" --interval "*/15m"
```

**With budget limit:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule "Analyze market trends" \
  --interval "*/30m" \
  --max-cost 0.50 \
  --timeout 120
```

### Save Configuration

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Export scheduler config to YAML
praisonai schedule save <name> [output.yaml]

# Example
praisonai schedule save news-bot news-config.yaml
```

## Command Reference

### Daemon Commands

| Command                  | Description               | Example                                      |
| ------------------------ | ------------------------- | -------------------------------------------- |
| `start <name> "task"`    | Start scheduler as daemon | `praisonai schedule start my-bot "Task"`     |
| `list`                   | List all schedulers       | `praisonai schedule list`                    |
| `logs <name> [--follow]` | View logs                 | `praisonai schedule logs my-bot --follow`    |
| `stop <name>`            | Stop scheduler            | `praisonai schedule stop my-bot`             |
| `restart <name>`         | Restart scheduler         | `praisonai schedule restart my-bot`          |
| `delete <name>`          | Remove from list          | `praisonai schedule delete my-bot`           |
| `describe <name>`        | Show details              | `praisonai schedule describe my-bot`         |
| `save <name> [file]`     | Export to YAML            | `praisonai schedule save my-bot config.yaml` |

### Options

| Option            | Type   | Description                  | Default  | Example                    |
| ----------------- | ------ | ---------------------------- | -------- | -------------------------- |
| `--interval`      | string | Schedule interval            | `hourly` | `hourly`, `*/30m`, `daily` |
| `--max-retries`   | int    | Max retry attempts           | `3`      | `3`, `5`                   |
| `--timeout`       | int    | Max execution time (seconds) | `None`   | `60`, `120`                |
| `--max-cost`      | float  | Budget limit in USD          | `$1.00`  | `1.00`, `5.00`             |
| `--verbose`, `-v` | flag   | Enable verbose logging       | `False`  | -                          |

**Notes:**

* Default budget is **\$1.00** for safety. Set to higher value or `null` in YAML to disable.
* Use `--verbose` to see detailed logs. Without it, output is clean for background running.

### Example 2: News Monitoring with YAML (Advanced)

**agents.yaml:**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai

agents:
  - name: "AI News Monitor"
    role: "Technology News Analyst"
    instructions: "Search and summarize latest AI news"
    tools:
      - search_tool

task: "Search for latest AI news and provide top 3 stories"

schedule:
  interval: "hourly"
  max_retries: 3
  run_immediately: true
```

**Run:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule agents.yaml
```

### Example 2: Data Collection (Every 30 Minutes)

**agents.yaml:**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai

agents:
  - name: "Data Collector"
    role: "Data Analyst"
    instructions: "Collect and analyze market data"
    tools:
      - search_tool

task: "Collect latest market data and identify trends"

schedule:
  interval: "*/30m"
  max_retries: 5
  run_immediately: false
```

**Run with override:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Override to run every 15 minutes instead
praisonai schedule agents.yaml --interval "*/15m"
```

### Example 3: With Budget and Timeout Limits

**agents.yaml:**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai

agents:
  - name: "Budget-Controlled Agent"
    role: "Worker"
    instructions: "Process data efficiently"
    tools:
      - search_tool

task: "Process and analyze data"

schedule:
  interval: "*/5m"
  max_retries: 3
  run_immediately: true
  timeout: 120              # Max 2 minutes per execution
  max_cost: 0.50            # Stop after $0.50 spent
```

**Run:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule agents.yaml --verbose
```

**Output:**

```
Budget limit: $0.50
Timeout per execution: 120s
...
Estimated cost this run: $0.0002, Total: $0.0002
Budget remaining: $0.4998
...
Budget limit reached: $0.5001 >= $0.50
Stopping scheduler to prevent additional costs
```

### Example 4: Testing with Short Interval

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Test with 10-second interval
praisonai schedule agents.yaml --interval "*/10s" --verbose
```

## Python API

For programmatic control, use the async-native Python API:

### Async Agent Scheduler (Recommended)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

async def main():
    # Create agent
    agent = Agent(
        name="NewsChecker",
        instructions="Check latest AI news",
    )

    # Create scheduler using canonical import
    scheduler = AgentScheduler(
        agent=agent,
        task="Search for latest AI news"
    )

    # Start (runs every hour)
    scheduler.start("hourly", max_retries=3, run_immediately=True)

    # Keep running
    try:
        import time
        time.sleep(3600)  # Run for 1 hour
    except KeyboardInterrupt:
        pass
    finally:
        scheduler.stop()
        stats = scheduler.get_stats()
        print(f"Executions: {stats['execution_count']}, Success: {stats['success_count']}")

asyncio.run(main())
```

<Note>
  **Import paths (PR #1552):**

  * **Canonical:** `from praisonai.scheduler import AgentScheduler`
  * **Deprecated** (still works, emits `DeprecationWarning`): `from praisonai.agent_scheduler import AgentScheduler`
  * **Pending deprecation** (still works, emits `PendingDeprecationWarning` — will move to `praisonai.scheduler.async_agent_scheduler` in a future release): `from praisonai.async_agent_scheduler import AsyncAgentScheduler`

  The canonical `AgentScheduler` from `praisonai.scheduler` exposes `from_yaml`, `start_from_yaml_config`, and `from_recipe`. For new applications, prefer `AsyncAgentScheduler` which provides better cancellation and fits naturally into async codebases.

  **MCP scheduling note:** The MCP server's `praisonai.schedule.list / .add / .remove` tools are now backed by `praisonaiagents.tools.schedule_tools`, so YAML/recipe scheduling works through MCP without needing to choose an import path.
</Note>

## Features

### Core Features

* **Interval-based scheduling**: Run agents at regular intervals
* **Background execution**: Runs in daemon thread, won't block terminal
* **Automatic retry**: Exponential backoff + jitter, capped at 300s, shared between sync & async
* **Graceful shutdown**: Clean stop with Ctrl+C
* **YAML configuration**: Simple configuration in agents.yaml
* **CLI overrides**: Override any setting from command line

### Safety Features

* **⏱️ Timeout Protection**: Prevent runaway executions (Unix/Linux/Mac only)
* **💰 Cost Monitoring**: Real-time cost tracking with budget limits
* **📊 Statistics Tracking**: Monitor execution success rates, costs, and runtime
* **🛡️ Budget Protection**: Auto-stops when cost limit reached
* **🔄 Retry Logic**: Exponential backoff prevents rapid failures

## Output

The scheduler provides detailed logging with cost tracking:

```
Starting agent scheduler: AI News Monitor
Task: Search for latest AI news
Schedule: hourly (3600s interval)
Timeout per execution: 60s
Budget limit: $1.00
Agent scheduler started successfully

[2025-12-22 10:00:00] Starting scheduled agent execution
Attempt 1/3
Agent execution successful on attempt 1
Result: [agent output]
Estimated cost this run: $0.0001, Total: $0.0001
Budget remaining: $0.9999
Next execution in 3600 seconds (1.0 hours)
```

### Callbacks

Both schedulers accept `on_success` and `on_failure` callbacks in the constructor.
Callbacks may be sync or async functions; a raising callback is logged and swallowed
— it will not stop the scheduler.

* `on_success(result)` — called with the agent's return value after a successful run.
* `on_failure(exc)` — called with the final `Exception` after all retries are exhausted.
  (Previously sync passed a formatted string; as of PR #1474 both sync and async
  pass the exception object.)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def success_callback(result):
    print(f"Success: {result}")

def failure_callback(exception):
    print(f"Failed: {exception}")

scheduler = AgentScheduler(
    agent=agent,
    task="Check news",
    on_success=success_callback,
    on_failure=failure_callback
)
```

### Statistics

**CLI Daemon:** Use `praisonai schedule describe <name>` for detailed stats

**Python API (AsyncAgentScheduler):**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
stats = await scheduler.get_stats()
# Returns:
{
    "is_running": True,
    "execution_count": 10,
    "success_count": 9,
    "failure_count": 1,
    "agent_name": "NewsChecker",
    "task": "Check the latest AI news"
}
```

<Note>
  **API Change:** The AsyncAgentScheduler uses simplified stats keys (`execution_count`, `success_count`, `failure_count`) and does not track cost or runtime metrics directly. Cost and runtime tracking may be handled by other system layers.
</Note>

# On stop (Ctrl+C)

🛑 Stopping scheduler...

📊 Final Statistics:
Total Executions: 5
Successful: 5
Failed: 0
Success Rate: 100.0%

✅ Agent stopped successfully

````

## Error Handling

The scheduler retries failed executions with exponential backoff + jitter:

- **Attempt 1:** Run immediately.
- **On failure:** Wait `backoff_delay(attempt)` seconds, then retry.
- Delay formula: `min(max(30, 2 ** attempt), 300)` seconds, with ±10% jitter.
- **Cap:** 300s between attempts. **Floor:** ~27s.
- Both sync (`AgentScheduler`) and async (`AsyncAgentScheduler`) use the same curve.

`max_retries` is the **total** number of attempts (including the first run).
`max_retries=3` → 1 initial attempt + up to 2 retries.

## Stopping the Scheduler

### CLI Commands
Use the daemon management commands:
```bash
# Graceful shutdown
praisonai schedule stop <name>

# Force kill if needed
praisonai schedule delete <name>
````

### Python API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Graceful async shutdown
await scheduler.stop()  # Waits up to 30s for current execution
```

### Foreground Mode

Press `Ctrl+C` to stop gracefully. The scheduler will:

1. Set stop event
2. Wait for current execution to complete
3. Log final statistics
4. Exit cleanly

## See Also

* [Async Agent Scheduler](/docs/features/async-agent-scheduler) - Python async-native scheduler API
* [Planning Mode](/docs/cli/planning) - Add planning to scheduled agents
* [Memory](/docs/cli/memory) - Enable memory for scheduled agents
* [Tools](/docs/cli/tools) - Add custom tools to agents
* [Examples](https://github.com/MervinPraison/PraisonAI/tree/main/examples/python/scheduled_agents) - Working examples