> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/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
# Note: Async daemons (schedule start) now correctly persist executions and cost to disk (PR #1857)
```

## 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
...
Run cost: $0.0034 (model=gpt-4o-mini, in=2100, out=480). Total: $0.0034 / $0.5
...
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.

  **Budget & timeout (PR #1771):** `AsyncAgentScheduler` now accepts `timeout` (per-run seconds) and `max_cost` (total USD cap) in its constructor — see [Async Agent Scheduler](/docs/features/async-agent-scheduler) for the full pattern.

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

  **Async-only agents ([PR #2147](https://github.com/MervinPraison/PraisonAI/pull/2147)):** The sync `AgentScheduler` now accepts agents that expose only `astart()` (not `start()`). Dispatch logic is shared between sync and async schedulers via `praisonai.scheduler._dispatch.adispatch_agent`. Both schedulers prefer `astart()` when present and fall back to `start()` in a worker thread.

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

  agent = Agent(
      name="NewsChecker",
      instructions="Check the latest AI news",
  )

  # Sync scheduler now runs agents that only expose astart()
  scheduler = AgentScheduler(agent=agent, task="Summarise top 3 AI stories")
  scheduler.start("hourly", max_retries=3, run_immediately=True)
  ```
</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
* **💰 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

<Note>
  **Real cost tracking ([PR #2171](https://github.com/MervinPraison/PraisonAI/pull/2171)):** `--max-cost` is now enforced against the real per-token spend pulled from each agent response. Previously the scheduler added a fixed `$0.0001` per run, so the default `$1.00` brake required \~10,000 executions to trip. Set `--max-cost` to your actual budget, and ensure your model is in `DEFAULT_PRICING` (or register it — see [Cost Tracking](/docs/cli/cost-tracking#custom-pricing)) so runs aren't silently priced at \$0.
</Note>

## 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]
Run cost: $0.0034 (model=gpt-4o-mini, in=2100, out=480). Total: $0.0034 / $1.0
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_async()
# Returns:
{
    "is_running": True,
    "total_executions": 10,
    "successful_executions": 9,
    "failed_executions": 1,
    "success_rate": 90.0,
    "total_cost_usd": 0.0234,
    "remaining_budget": 0.9766,
    "runtime_seconds": 3601.5,
    "cost_per_execution": 0.0023,
}
```

<Note>
  **Stats parity (PR #1857):** Both `AgentScheduler` and `AsyncAgentScheduler` now return the same stats shape via a shared `_BaseAgentScheduler._build_stats()` helper. Keys: `is_running`, `total_executions`, `successful_executions`, `failed_executions`, `success_rate`, `total_cost_usd`, `remaining_budget`, `runtime_seconds`, `cost_per_execution`. Use `await scheduler.get_stats_async()` in async code, `scheduler.get_stats()` in sync code.
</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.
- Sync and async schedulers now share the same `backoff_delay()` implementation as of [PR #1673](https://github.com/MervinPraison/PraisonAI/pull/1673), not just the same formula.

`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

### Interruptible backoff (PR #1673)

Calling `scheduler.stop()` during a retry backoff window now returns within milliseconds. Previously a stop signal could wait out the full backoff delay (up to ~300s).

### Cross-platform timeout (PR #1741)

Execution timeouts now work on all platforms including Windows and can run safely in worker threads (FastAPI background tasks, the bot adapter, Streamlit). Previously timeouts were Unix/Linux/Mac only and failed in worker thread contexts.

```python
import signal
from praisonai.scheduler import AgentScheduler

scheduler = AgentScheduler(agent, "Monitor logs")
scheduler.start("hourly", max_retries=3)

# Set up signal handler
def handle_sigint(signum, frame):
    print("Ctrl+C pressed - stopping scheduler...")
    scheduler.stop()  # Returns immediately, even during backoff
    exit(0)

signal.signal(signal.SIGINT, handle_sigint)
````

### CLI Commands

Use the daemon management commands:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
* [Scheduled Run Policy](/docs/features/scheduled-run-policy) - Programmatic tool scoping, prompt scanning, and output auditing for unattended runs (no CLI flag — configure via `RunPolicy` in Python)
* [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