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.
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
1
CLI
Add a job with
--command. Its stdout is delivered as-is — no --message, no agent, no tokens.2
Python
Set
command on a ScheduleJob. When command is present, the job takes the model-free path.How It Works
The executor checks for acommand before resolving any agent — a command job never touches the model.
Choosing the Right Mode
A scheduled job runs in one of three modes depending on which fields are set.pre_run is a gate (a cheap check that still runs the model); command is an action (a shell command that runs instead of the model).
Configuration Options
ScheduleJob fields
command is persisted only when set; command_timeout is persisted only when a command is configured and the timeout differs from the default 60.0. Agent-only jobs are unchanged on disk.
Common Patterns
Disk watch
Report free space on the root filesystem every hour.Health-check curl
Poll a health endpoint and post the raw response. Use--no-continuable so a reply starts a fresh session instead of resuming.
Uptime heartbeat
Post a lightweight heartbeat so you know the host is alive.Best Practices
Bound every command with command_timeout
Bound every command with command_timeout
The default
command_timeout=60.0 kills a hung command with its process group on POSIX. Lower it to match a fast watchdog so a stuck command cannot stall the ticker.Keep output under 8,000 characters
Keep output under 8,000 characters
stdout is capped at 8,000 characters before delivery. Trim chatty commands with
head, tail, or a filter so the channel gets a clean, complete message.Use --no-continuable for pure alerts
Use --no-continuable for pure alerts
A command action is a notification, not a conversation. Add
--no-continuable so a reply in the channel starts a fresh session instead of trying to resume a job that has no agent context.Command jobs are a trusted, human-only surface
Command jobs are a trusted, human-only surface
command runs an arbitrary host shell command. It is not accepted by the agent-callable schedule_add tool — only a human author via CLI, YAML, or Python can persist one. This prevents a prompt-injected agent from persisting arbitrary shell commands on the host.Related
Pre-Run Gate
The go/no-go gate — cheap check that still runs the model turn
Scheduler Delivery
Push scheduled results to Telegram/Discord/Slack/WhatsApp
Schedule CLI
CLI surface — where
--command and --command-timeout are configured