> ## 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 Command Action
> Run a shell command on schedule and deliver its stdout verbatim — no agent, no model turn
Attach a `command` to a scheduled job to run a shell command on its schedule and deliver the raw stdout to your channel — no agent is resolved and no model turn is taken.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Tick[⏰ Schedule fires] --> Cmd[💻 Run shell command]
Cmd --> Out[📤 stdout]
Out --> Deliver[✅ Deliver verbatim to channel]
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Tick input
class Cmd,Out process
class Deliver output
```
A command job is a model-free *action*: cheap, deterministic, and token-free — ideal for watchdogs like `df -h`, `uptime`, or a health-check `curl`.
## Quick Start
Add a job with `--command`. Its stdout is delivered as-is — no `--message`, no agent, no tokens.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai schedule add "disk-watch" -s hourly \
--command "df -h /" \
--deliver telegram:-100123
```
Set `command` on a `ScheduleJob`. When `command` is present, the job takes the model-free path.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.scheduler import ScheduleJob, Schedule, DeliveryTarget
job = ScheduleJob(
name="disk-watch",
schedule=Schedule(kind="every", every_seconds=3600),
command="df -h /",
command_timeout=30,
delivery=DeliveryTarget.parse("telegram:-100123"),
)
```
***
## How It Works
The executor checks for a `command` **before** resolving any agent — a command job never touches the model.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant Cron as ⏰ Cron
participant Exec as Executor
participant Shell as 💻 Shell command
participant Target as DeliveryTarget
participant Chat as 💬 Chat
Cron->>Exec: Tick due
alt job has command
Exec->>Shell: asyncio.to_thread(run command)
Shell-->>Exec: stdout + exit code
Exec->>Target: deliver stdout verbatim
Target->>Chat: message posted
else no command (agent path)
Exec->>Exec: resolve agent → model turn
end
```
| Detail | Behaviour |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **No model turn** | No agent is resolved; zero tokens are spent. |
| **Off the event loop** | The command runs via `asyncio.to_thread`, so a slow command never blocks other ticks. |
| **Bounded runtime** | The command is killed after `command_timeout` seconds; a timeout returns the conventional `124` code and records the tick as `failed`. |
| **Process-group kill** | On POSIX the command runs in its own session, so a timeout kills the whole process group (shell + children) rather than orphaning them. |
| **Exit codes surface** | A non-zero exit is **not** silently dropped — the delivered text is prefixed `[exit N]