Schedule - PraisonAI

The schedule command manages scheduled agent execution.

See also: Gateway Schedules — when running the gateway, a schedules: block in gateway.yaml loads at boot, so you don’t need praisonai schedule to run recurring agent → channel deliveries.

Usage

praisonai schedule [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
`add`	Add a scheduled job (supports `--once` for auto-removal after one fire)
`start`	Start scheduled agent execution
`run`	Poll and fire store-backed jobs in the foreground (no gateway required)
`stop`	Stop scheduled job(s)
`list`	List scheduled jobs (merges store-backed jobs and daemon schedulers)
`runs`	Show past run history for a store-backed schedule
`pause`	Pause a store-backed schedule (stops firing, keeps it)
`resume`	Resume a paused store-backed schedule
`update`	Update a store-backed schedule’s cadence / message
`remove`	Remove a store-backed schedule (run history is retained)
`logs`	View scheduler logs
`restart`	Restart a scheduled job
`delete`	Delete a scheduled job — now finds store jobs first, falls back to daemon
`describe`	Show job details — now prefers store, falls back to daemon
`stats`	Show scheduler statistics
`blueprint`	Create a job from a blueprint template
`blueprint-list`	List available blueprints
`suggestions`	List pending automation suggestions
`suggestion-accept`	Accept a suggestion and create the job
`suggestion-dismiss`	Dismiss a suggestion
`suggestion-propose`	Propose a blueprint as a suggestion

Adding Jobs

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`, `weekly`, `*/30m`, `cron:...`, `at:...`, `in 20 minutes`, `at 9am`, `every day at 9am`, `weekdays at 9am`, `every monday 9am`, `every mon,wed,fri at 9am`. Naive `at:` / `cron:` times resolve per Timezones.
`--tz`		IANA timezone for `cron:` or naive one-shot `at:` times (e.g. `America/New_York`). See Timezones.
`--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]`. See Scheduler Delivery for the full token grammar and Python/YAML equivalents.
`--continuable / --no-continuable`		Default `--continuable`. Seed a resumable session on delivery so a reply resumes the job with context. Use `--no-continuable` for fire-and-forget notifications (pure alerts). Applied only when a delivery target is configured.
`--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)
`--command` / `--script`		No-LLM action: run this shell command on schedule and deliver its stdout verbatim (no agent, no model turn).
`--command-timeout`		Max seconds the `--command` may run before it is killed (default `60`).
`--backend`		External coding-CLI backend action: run the message as one headless turn via a registered backend (see `praisonai backends`), e.g. `claude-code`, `codex-cli`. No native agent, no in-process model turn. Mutually exclusive with `--command`.
`--monitor-url`		Run the agent only when the response body at this public HTTP(S) URL changes. Mutually exclusive with `--monitor-command`, `--pre-run`, `--command`, `--backend`. Trusted human-only surface — not exposed to the LLM.
`--monitor-command`		Run the agent only when this shell command’s stdout changes. Mutually exclusive with `--monitor-url`, `--pre-run`, `--command`, `--backend`. Trusted human-only surface — not exposed to the LLM.
`--backend-cwd`		Working directory for the `--backend` turn (default: the scheduler process cwd).
`--backend-timeout`		Max seconds the `--backend` turn may run (default: the backend’s own timeout, `300s`).
`--model`		Pin this job to a specific model (e.g. `openai/gpt-4o-mini`). Snapshotted so unattended runs stay stable and drift fails closed.
`--pin / --no-pin`		Default `--pin`. Enforce the model snapshot so drift fails closed (only takes effect once `--model` captures one). `--no-pin` follows whatever the default becomes.
`--once`		One-shot job: auto-remove after its single fire (maps to `delete_after_run`). Ideal for `at:` / `in ...` reminders so a spent job does not linger in listings.
`--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

praisonai schedule add "morning-hello" -s daily -m "say hello" --agent support

Add a weekly digest

praisonai schedule add "weekly-digest" -s weekly -m "Summarise the week's activity" --deliver telegram

weekly runs every 7 days (604800 seconds).

Natural-language schedules

Plain English clock times and day names work anywhere --schedule is accepted.

# Weekday standup — Mon–Fri at 09:00
praisonai schedule add "standup" -s "weekdays at 9am" -m "post the standup summary"

# One-shot reminder — fires once at the next 17:00, then auto-removes
praisonai schedule add "eod" -s "at 5pm" -m "wrap up the day" --once

# Specific weekdays — Mon, Wed, Fri at 09:00
praisonai schedule add "reports" -s "every mon,wed,fri at 9am" -m "send the report"

A bare clock time (at 5pm) is a one-shot at the next matching local time; any recurring form (every …, daily …, or a day-of-week name) becomes a cron schedule. See Async Agent Scheduler → Natural language for the full grammar.

Timezones and portability

A naive at: timestamp is stored with the resolved zone attached (per-date DST-correct). Adding praisonai schedule add "x" -s "at:2026-07-01T09:00:00" in Europe/London stores 2026-07-01T09:00:00+01:00; the same command on a December date stores +00:00. Because the stored value carries the offset, the job fires at the same wall-clock time on any runner — you do not need to include an offset in the input unless you want to override the resolved zone. Set a process-wide default with PRAISONAI_SCHEDULE_TIMEZONE. It resolves after any explicit tz/-s offset but before the machine’s local zone, and an unknown zone name is now rejected at add time:

# Store an aware string derived from a chosen zone
PRAISONAI_SCHEDULE_TIMEZONE=Europe/London \
  praisonai schedule add "brief" -s "at:2026-07-01T09:00:00" -m "morning brief"

# Unknown zone → ValueError at add time, not a silent never-fires job
PRAISONAI_SCHEDULE_TIMEZONE=Not/A/Zone \
  praisonai schedule add "x" -s "at:2026-07-01T09:00:00"

See Schedule Tools → Timezones for the full precedence ladder.

Fire-and-forget alert

praisonai schedule add "backup-alert" -s "cron:0 3 * * *" -m "Backup ok" \
  --deliver "slack:C012345" \
  --no-continuable

A reply in #C012345 lands as a brand-new turn instead of resuming the maintenance job’s conversation. Without --no-continuable, a delivered result is continuable by default — a reply resumes the job’s conversation with the brief in context.

Deliver via home channel

praisonai schedule add "news" -s daily -m "summarise AI news" --deliver telegram

Set the platform’s home channel first — either by exporting TELEGRAM_HOME_CHANNEL=<chat_id> before you run this command, or by adding an explicit --deliver telegram:<chat_id> argument. See Scheduler Delivery for the full precedence ladder.

Deliver into a thread

Append a third :thread_id segment to thread the outbound message — a Slack thread ts, a Telegram forum topic id, or a Discord thread id:

praisonai schedule add "standup" -s "cron:0 9 * * 1-5" -m "post the standup summary" \
  --deliver slack:C0123456:1728987654.001234

The router preserves the thread segment end-to-end, so the message lands in the Slack thread rooted at message ts 1728987654.001234. Adapters without thread support silently ignore the segment. See Scheduler Delivery → Thread semantics.

Fire-and-forget notice

praisonai schedule add "backup-notice" -s daily \
  -m "post the backup-complete notice" \
  --deliver slack:C0123456 \
  --no-continuable

--no-continuable opts out of session seeding, so a reply starts a fresh session instead of resuming the job. See Continuable Delivery.

Fan-out to all home channels

praisonai schedule add "ops-digest" -s "cron:0 * * * *" -m "incident digest" --deliver all

Deliver back to origin chat

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.

Blueprints & Suggestions

Create jobs from reusable templates, or accept consent-first suggestions — the same engine that powers the /automations and /blueprint chat commands. See Automation Suggestions for the concepts.

`blueprint`

Create a schedule from a blueprint template.

Option	Description
`--hour`	Delivery hour (0-23)
`--minute`	Delivery minute (0-59)
`--weekdays`	Days: `mon-fri`, `daily`, `weekends`, or a single day
`--focus`	Focus area
`--interval`	Interval in minutes (for interval-based blueprints)
`--keywords`	Priority keywords (for `important-mail`)
`--deliver` / `-d`	Delivery target
`--agent` / `-a`	Agent ID
`--json`	Output JSON

`blueprint-list`

List available blueprints (built-in + user YAML).

Option	Description
`--category` / `-c`	Filter by category
`--json`	Output JSON

`suggestions`

List pending automation suggestions.

Option	Description
`--json`	Output JSON

`suggestion-accept`

Accept a suggestion and create the schedule job.

Argument / Option	Description
`<id>`	Suggestion ID to accept
`--deliver` / `-d`	Override delivery target

`suggestion-dismiss`

Dismiss a suggestion without creating a job.

Argument	Description
`<id>`	Suggestion ID to dismiss

`suggestion-propose`

Propose a blueprint as a suggestion (manual/CLI trigger).

Option	Description
`--reason` / `-r`	Why this is being suggested
`--hour`	Delivery hour (0-23)
`--minute`	Delivery minute (0-59)
`--weekdays`	Days: `mon-fri`, `daily`, `weekends`, or a single day
`--focus`	Focus area
`--interval`	Interval in minutes
`--keywords`	Priority keywords (for `important-mail`)
`--deliver` / `-d`	Suggested delivery target

Examples

praisonai schedule blueprint morning-brief \
  --hour 8 --weekdays mon-fri --deliver telegram

praisonai schedule suggestions
# copy the [sug_...] id from the output, then:
praisonai schedule suggestion-accept sug_abc123 --deliver telegram

Add with delivery target [Legacy]

praisonai schedule add "tg-reminder" \
  -s "cron:0 9 * * *" \
  -m "check email" \
  --agent support \
  --channel telegram \
  --channel-id 12345

Start scheduler

praisonai schedule start

schedule start runs the agents.yaml engine (daemon scheduler). It does not poll store-backed jobs created by schedule add — use schedule run for those.

Run the store poller standalone (no gateway)

praisonai schedule add "brief" -s daily -m "morning brief" --deliver telegram
praisonai schedule run          # foreground: polls + fires store jobs (Ctrl-C to stop)
praisonai schedule run --poll 5 # poll every 5 seconds instead of the default 15s

schedule run hosts the store poller in the foreground — no messaging gateway or UI host required. Use it when you added jobs via schedule add and just want them to fire from a plain terminal or a systemd unit.

Firing goes through the same lease-based claim_due_jobs, so schedule run cannot double-fire a job when a gateway is also running (at-most-once claim).

Requires the bot extras. If praisonai_bot isn’t installed, schedule run exits with code 4: Schedule executor unavailable; cannot run the poller. Install the bot extras (praisonai_bot) to execute scheduled jobs.

Flags

Option	Short	Type	Default	Description
`--poll`	`-p`	`float`	`15.0`	Seconds between store polls

The CLI maps --poll to ScheduleLoop.run_forever(poll_seconds=…), the foreground counterpart to ScheduleLoop.start().

List scheduled jobs

list merges store-backed jobs (created with schedule add) and daemon schedulers in one view. Store jobs are tagged [store].

praisonai schedule list
praisonai schedule list --json

Store jobs print as [store] <name> (id: <id>) [enabled|paused] — <cadence> — last run: <ts>:

Store schedules (1):
  [store] morning-brief (id: sch_a1b2c3) [enabled] — cron: 0 8 * * 1-5 — last run: 2026-03-01 08:00

list --json returns a single document splitting the two sources:

{"store": [...], "daemon": [...]}

View logs

praisonai schedule logs
praisonai schedule logs --tail 100 --follow

Stop a job

praisonai schedule stop job-123
praisonai schedule stop all

Delete a job

delete finds store jobs first (by id, then by name) and removes them; it falls back to the daemon PID handler for legacy jobs.

praisonai schedule delete morning-brief --yes
praisonai schedule delete sch_a1b2c3 --yes

Skip the model turn when there are no new emails

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.

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

No-LLM command action

praisonai schedule add "disk-watch" -s hourly --command "df -h /" --deliver telegram:-100123
praisonai schedule add "uptime" -s "*/5m" --command "uptime" --deliver slack:C012345 --no-continuable

--command runs the shell command on schedule and delivers its stdout verbatim — model-free, so there is no agent turn, no tokens, and no --message needed. --command and --script are aliases for the same flag. See Scheduler Command Action for the full feature page.

--command is a trusted, human-only surface (like --pre-run) — it is NOT part of the LLM-callable schedule_add tool, so a prompt-injected agent cannot persist arbitrary shell commands. Configure --command only via the CLI, YAML, or Python.

Backend action

praisonai schedule add "nightly-refactor" \
  -s "cron:0 2 * * *" \
  -m "tidy utils.py, run tests" \
  --backend claude-code \
  --backend-cwd ~/proj \
  --deliver telegram

--backend runs the message as one headless turn through a registered CLI backend (see praisonai backends) — no native agent, no in-process model turn. It is mutually exclusive with --command. See Scheduler Backend Action for the full feature page.

--backend is a trusted, human-only surface (like --command and --pre-run) — it is NOT part of the LLM-callable schedule_add tool, so a prompt-injected agent cannot persist arbitrary backend jobs. Configure --backend only via the CLI, YAML, or Python.

Wake only when a page changes

praisonai schedule add "price-watch" \
  -s "*/15m" \
  -m "Summarise the change" \
  --monitor-url "https://example.com/api/price" \
  --deliver telegram

--monitor-url probes the URL on every tick, hashes the response, and only runs the agent when the hash changed. An unchanged source records no_change — zero tokens, no delivery. See Scheduler Monitor for the full feature page and reliability guarantees.

Wake only when a shell command’s stdout changes

praisonai schedule add "unread-watch" \
  -s "*/5m" \
  --monitor-command "curl -sf https://api.example.com/unread | jq '.count'" \
  -m "Summarise what changed" \
  --deliver telegram

--monitor-command is the stateful sibling of --pre-run: it remembers the last-seen hash across ticks and only runs the agent when the source moves.

--monitor-url and --monitor-command are mutually exclusive with each other, and with --pre-run, --command, and --backend. Like --pre-run and --command, they are trusted human-only surfaces — the LLM-callable schedule_add tool cannot set them, so a prompt-injected agent cannot persist an arbitrary monitor.

Validation errors:

--command and --backend together → --command and --backend are mutually exclusive: a job runs exactly one model-free action. Configure one or the other.
Invalid timeout → --backend-timeout must be a finite, non-negative number of seconds.
Missing praisonai-code → CLI backend '<id>' unavailable: <e>. Backend jobs require the praisonai-code package (pip install praisonai-code).
A duplicate schedule name now exits non-zero (previously it substring-matched Error and could misclassify).

Pin a scheduled job to a specific model

praisonai schedule add "daily-brief" \
  -s "cron:0 9 * * *" \
  -m "summarise the day" \
  --model "openai/gpt-4o-mini"

--model snapshots the model onto the job so unattended runs stay on it — and fail closed if the default drifts. --no-pin follows whatever the default becomes:

praisonai schedule add "flex-brief" -s daily -m "summarise" --no-pin

See Scheduler Model Pin for the full feature page.

Managing store-backed schedules

A store-backed schedule is a job authored by schedule add, persisted in ~/.praisonai/config.yaml, and managed from the CLI without hand-editing YAML. list, delete, and describe are now unified across store and daemon jobs, and five subcommands manage the store surface end to end. The agent-callable equivalents live in Schedule Tools.

Which command should I use?

Store subcommands and daemon subcommands overlap, so pick by how the job was created. Store-backed jobs (created with schedule add) manage state via pause / resume / update / remove — but they must be actively fired by a running poller. Pick how they fire:

Add a one-shot reminder

# One-shot reminder that auto-cleans after firing
praisonai schedule add "standup-ping" \
  --schedule "in 20 minutes" \
  --message "Time for standup" \
  --deliver telegram --once

Pause and resume

# Pause and resume without losing state
praisonai schedule pause morning-brief
praisonai schedule resume morning-brief

Update cadence or message

# Change cadence without remove + re-add
praisonai schedule update morning-brief -s "cron:0 8 * * 1-5"

# Change only the message
praisonai schedule update morning-brief -m "Send the updated morning brief"

update clears last_run_at when the cadence changes so the new schedule runs fresh — this avoids the “updated one-shot never fires” trap.

Show past runs

# Show past runs (status, duration, delivered, error)
praisonai schedule runs morning-brief --limit 10
praisonai schedule runs morning-brief --json

Remove a store-backed schedule

# Remove by id or name (id resolves first, so duplicate names are safe)
praisonai schedule remove morning-brief --yes

remove retains run history — query it any time with praisonai schedule runs <name|id>.

​Usage

​Commands

​Adding Jobs

​Options

​Examples

​Add a daily reminder bound to a specific agent

​Add a weekly digest

​Natural-language schedules

​Timezones and portability

​Fire-and-forget alert

​Deliver via home channel

​Deliver into a thread

​Fire-and-forget notice

​Fan-out to all home channels

​Deliver back to origin chat

​Blueprints & Suggestions

​blueprint

​blueprint-list

​suggestions

​suggestion-accept

​suggestion-dismiss

​suggestion-propose

​Examples

​Add with delivery target [Legacy]

​Start scheduler

​Run the store poller standalone (no gateway)

​List scheduled jobs

​View logs

​Stop a job

​Delete a job

​Skip the model turn when there are no new emails

​No-LLM command action

​Backend action

​Wake only when a page changes

​Wake only when a shell command’s stdout changes

​Pin a scheduled job to a specific model

​Managing store-backed schedules

​Which command should I use?

​Add a one-shot reminder

​Pause and resume

​Update cadence or message

​Show past runs

​Remove a store-backed schedule

​See Also

Usage

Commands

Adding Jobs

Options

Examples

Add a daily reminder bound to a specific agent

Add a weekly digest

Natural-language schedules

Timezones and portability

Fire-and-forget alert

Deliver via home channel

Deliver into a thread

Fire-and-forget notice

Fan-out to all home channels

Deliver back to origin chat

Blueprints & Suggestions

`blueprint`

`blueprint-list`

`suggestions`

`suggestion-accept`

`suggestion-dismiss`

`suggestion-propose`

Examples

Add with delivery target [Legacy]

Start scheduler

Run the store poller standalone (no gateway)

List scheduled jobs

View logs

Stop a job

Delete a job

Skip the model turn when there are no new emails

No-LLM command action

Backend action

Wake only when a page changes

Wake only when a shell command’s stdout changes

Pin a scheduled job to a specific model

Managing store-backed schedules

Which command should I use?

Add a one-shot reminder

Pause and resume

Update cadence or message

Show past runs

Remove a store-backed schedule

See Also