Docs / Operate

Scheduled requests

A schedule runs a request by itself, on time, through the operating system's own scheduler. It may send its result only to the people you approved when you set it up.

How a schedule runs

ivralo keeps no daemon for schedules. ivralo schedule add registers a task with the operating system's scheduler, and that task calls ivralo schedule run <name> at the time you gave. The run is the same unattended run ivralo ask makes in a pipe: nothing that would need a person's yes is granted.

Platform	Scheduler	Where the task is
Linux, macOS	cron	One line in your crontab, tagged `# ivralo:<name>`
Windows	Task Scheduler	The task `ivralo\<name>`, made with `schtasks`

On macOS the task is a cron line too; ivralo does not write launchd jobs. The rest of your crontab is left alone.

Adding a schedule

ivralo schedule add sales-report --every "weekly mon 09:00" \
  --mail-to ali@example.com \
  "produce the weekly sales report from sales.xlsx and e-mail it to ali@example.com"

The name is lowercase letters, digits and hyphens. A schedule with that name already there is replaced only after a yes, or with --yes.

--every takes a small grammar on purpose. Every other shape belongs to the operating system's scheduler, and a task you register there by hand can still call ivralo schedule run <name>.

`--every`	Runs
`daily HH:MM`	Every day at that time
`weekdays HH:MM`	Monday to Friday
`weekly <mon..sun> HH:MM`	Once a week; `mon 09:00` works too
`monthly <1-31> HH:MM`	Once a month, on that day
`hourly`	Every hour; the finest step

Trying it before trusting the clock

ivralo schedule run sales-report

run does exactly what the task will do and prints the same JSON object a pipeline prints (ok, reply, files, run_id, seconds, ...). It exits 1 when the run failed. Each run also leaves that object as one file under .ivralo/schedules/<name>/ in the workspace.

What a schedule may send

An unattended run cannot answer the send dialog. So --mail-to is the only way an unattended run sends mail, and the approval happens once, when you create the schedule:

the recipients are checked against IVRALO_MAIL_ALLOWED then, and mail must be configured (IVRALO_MAIL), or add refuses;
at run time the run sends to exactly those addresses and refuses any other, including one the model came up with;
a schedule without --mail-to cannot send mail at all.

--notify is the same for short messages: the schedule may post to the configured Telegram chat or Slack webhook. The chat is fixed by configuration, so the flag is the approval. Neither pre-approval ever reaches an interactive session, a plain ivralo ask or a job, which keep asking every time. See Email and chat.

Keeping jobs flowing: `--jobs`

A schedule made with --jobs takes no request. Its task runs ivralo jobs run for the workspace you made it in, so the next queued job starts each time, runs to its end, and the task exits:

ivralo schedule add jobs --every hourly --jobs

The task pins that workspace (IVRALO_WORKSPACE), so it starts that workspace's jobs whatever directory it runs from. It takes no --mail-to or --notify: the jobs it starts run unattended, and a send in one of them parks for a person. It writes no JSON run log; what each run printed is in task.log.

The commands

Command	Does
`ivralo schedule` (or `schedule list`)	Every schedule: when it runs, whom it may mail, whether the OS still has the task, the last run
`ivralo schedule add <name> --every "<when>" "<request>"`	Register it with the OS and remember it
`ivralo schedule run <name>`	Run it now, unattended: what the task calls
`ivralo schedule log <name>`	The last runs: when, ok or failed, seconds, files, the reply's first line (`--limit`, 10 by default)
`ivralo schedule remove <name>`	Unregister the task and forget the schedule; its logs stay. Asks first, or `--yes`.

Where things are

schedules.json in the ivralo home holds every schedule (IVRALO_SCHEDULES moves it).
.ivralo/schedules/<name>/ in the workspace holds one JSON file per run, plus task.log with whatever the command printed. It is the first place to look when a run did nothing.
The task calls the install's own ivralo by absolute path, because cron's PATH is minimal, and starts from the home. schedule add refuses, registering nothing, when no ivralo executable can be found.

ivralo doctor has a schedules section: each schedule, whether the OS still has its task, and how the last run went.

What can go wrong

The model is not up at the scheduled time. The run fails into its log, and ivralo doctor says why. Make sure the model server starts with the machine.
The install moved. The task's command line is absolute. After reinstalling ivralo somewhere else, run ivralo schedule add ... --yes again.
The run did nothing. Read task.log under .ivralo/schedules/<name>/. A run that started has a run_id in its JSON file; ivralo trace <run_id> shows every call it made.