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

# Schedule

> Scheduler management for automated agent execution

The `schedule` command manages scheduled agent execution.

## Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule [OPTIONS] COMMAND [ARGS]...
```

## Commands

| Command    | Description                     |
| ---------- | ------------------------------- |
| `add`      | Add a scheduled job             |
| `start`    | Start scheduled agent execution |
| `stop`     | Stop scheduled job(s)           |
| `list`     | List scheduled jobs             |
| `logs`     | View scheduler logs             |
| `restart`  | Restart a scheduled job         |
| `delete`   | Delete a scheduled job          |
| `describe` | Show job details                |
| `stats`    | Show scheduler statistics       |

## Adding Jobs

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "job-name" \
  --schedule "cron:0 9 * * *" \
  --message "Good morning! Check tasks." \
  --agent support \
  --channel telegram \
  --channel-id 12345
```

### Options

| Option         | Short | Description                                                                                                                 |
| -------------- | ----- | --------------------------------------------------------------------------------------------------------------------------- |
| `--schedule`   | `-s`  | When to run: `hourly`, `daily`, `*/30m`, `cron:...`, `at:...`, `in 20 minutes`                                              |
| `--message`    | `-m`  | Prompt text to deliver                                                                                                      |
| `--agent`      | `-a`  | Agent ID to execute this job (default: first registered)                                                                    |
| `--deliver`    | `-d`  | Delivery token: `origin`, `telegram`, `all`, or `platform:chat_id[:thread_id]`                                              |
| `--pre-run`    |       | Cheap pre-run gate command: exit 0 + output → run (output seeds the prompt); non-zero → skip (no model tokens, no delivery) |
| `--condition`  |       | Natural-language / expression alias for the pre-run gate (advisory)                                                         |
| `--channel`    |       | \[Legacy] Delivery platform: `telegram`, `discord`, `slack`, `whatsapp`                                                     |
| `--channel-id` |       | \[Legacy] Target chat/channel ID                                                                                            |
| `--session-id` |       | Session ID to preserve conversation context                                                                                 |
| `--json`       |       | Output JSON                                                                                                                 |

## Examples

### Add a daily reminder bound to a specific agent

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "morning-hello" -s daily -m "say hello" --agent support
```

### Deliver via home channel

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "news" -s daily -m "summarise AI news" --deliver telegram
```

Run `/sethome` in the target chat first.

### Fan-out to all home channels

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "ops-digest" -s "cron:0 * * * *" -m "incident digest" --deliver all
```

### Deliver back to origin chat

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "stretch" -s "*/2h" -m "time to stretch" \
  --deliver origin --channel telegram --channel-id 12345
```

`origin` requires `--channel` and `--channel-id` so the executor can resolve the creating chat.

### Add with delivery target \[Legacy]

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "tg-reminder" \
  -s "cron:0 9 * * *" \
  -m "check email" \
  --agent support \
  --channel telegram \
  --channel-id 12345
```

### Start scheduler

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule start
```

### List scheduled jobs

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule list
praisonai schedule list --json
```

### View logs

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule logs
praisonai schedule logs --tail 100 --follow
```

### Stop a job

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule stop job-123
praisonai schedule stop all
```

### Delete a job

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule delete job-123 --yes
```

### Skip the model turn when there are no new emails

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "inbox-watch" \
  -s "*/5m" \
  -m "Summarise new emails" \
  --pre-run "scripts/new_mail.sh" \
  --deliver telegram
```

`--pre-run` runs `scripts/new_mail.sh` before each tick. Exit 0 + stdout → agent runs with that stdout appended to the message. Non-zero exit → tick is skipped, no tokens spent, no Telegram ping.

<Note>
  `--pre-run` is a trusted, human-configured surface — it is not accepted by the agent-callable `schedule_add` tool, which prevents a prompt-injected agent from persisting arbitrary shell commands on the host. Configure `--pre-run` only via the CLI, YAML, or Python.
</Note>

## See Also

* [Proactive Delivery](/docs/features/proactive-delivery) - Home channels and delivery tokens
* [Scheduler](/docs/cli/scheduler) - Scheduler details
* [Background](/docs/cli/background) - Background tasks