CLI · Winter Console

The schedule command

Scheduled tasks are not listed in one file — they are scattered through the code as #[Scheduled] attributes. The schedule command gathers them into a table, shows each one’s schedule and manages the scheduler itself.

Default listScheduler one per host

What is scheduled

The default action is the listing, so the command can be called with no arguments:

bash
php call schedule
php call schedule list
text
 | [================================ Schedule ================================]
| [ Scheduled Tasks ]
|	   TASK                                           TRIGGER
|	   Main\Task\Digest::sendDaily                    cron 0 9 * * *
|	   Main\Task\Cleanup::purgeTemp                   fixedRate 3600s
|	   Main\Task\Sync::pullRates                      fixedDelay 300s
| - - - - - - - - - - - - - - - - - - - - - - -
| [i] 3 task(s) defined.
| [ Scheduled Tasks ]
| [================================ Schedule ================================]

This is the only way to see the whole schedule: the attributes live next to their methods, and finding them by eye across a project gets harder the bigger it grows.

Trigger What it means
cron 0 9 * * * By the calendar — five fields, no seconds
fixedRate 3600s Every hour from the start of the previous run
fixedDelay 300s Five minutes after the previous run finished

The difference between the last two matters: fixedRate holds the frequency, fixedDelay holds the pause. In detail on the Scheduler page.

When the list is available

For the built-in scheduler, list scans the project rather than asking a running process. So it always works — and it is the way to check the schedule before a deploy, or to confirm that a new task was picked up at all. While the scheduler runs, list and status show the tasks it actually runs.

A scheduler of your own with an overridden discover() (tasks from a database, say) is visible to the console only while it runs: without it the console prints The tasks of … come from its discover().

Starting the scheduler

bash
php call schedule start        # in the terminal
php call schedule start -d     # in the background
php call schedule stop         # graceful stop
php call schedule restart      # stop and start again at once

The scheduler is one long-lived process that watches the clock and starts tasks as their times arrive. It runs the tasks themselves separately, so a long task does not push everyone else’s schedule along.

One scheduler per host

A second start will not create a second scheduler: the class is protected by a lock, like any singleton process. That is protection against double firing — otherwise, after a failed deploy or a restart, tasks would run twice.

It follows that across several servers the scheduler must run on one of them. The application scales; the scheduler does not.

Usually it is not started separately: the #[EnableScheduler] attribute on the application class brings the scheduler up together with call run. A separate start is for when the scheduler lives as its own process — in its own container or under a supervisor.

Status

bash
php call schedule status
text
 | [================================ Schedule ================================]
| [ Scheduler Status ]
|	 Scheduler ................................................... [Scheduler ● RUNNING]
| - - - - - - - - - - - - - - - - - - - - - - -
|	 PID          52190
|	 State        RUNNING
|	 Activity     IDLE
|	 Started      2026-08-14 06:40:12 +00:00
|	 Uptime       7h 55m
|	 Tasks        3
| [ Scheduler Status ]
| [================================ Schedule ================================]

Activity shows whether a task is running right now. IDLE means the scheduler is waiting for the next due time; that is the normal state almost all the time.

If the scheduler is stopped, the command says so plainly:

text
 | [ Scheduler Status ]
|	 Scheduler ................................................... [○ STOPPED]
| [i] The scheduler is not running.

Scheduler resources

bash
php call schedule status -v

The flag appends a [ Resources ] block — the user, the parent PID, CPU, memory and elapsed time of the scheduler’s process, as the operating system reports them:

text
 | - - - - - - - - - - - - - - - - - - - - - - -
| [ Resources ]
|	 User         winter
|	 PPID         1
|	 CPU          0.1 %
|	 Memory       0.4 % (28.6 MB)
|	 Elapsed      07:55:12

While the application runs

While the application runs, it starts the scheduler, not the console: start, with or without -d, asks the application to start it, and the command returns at once. stop and restart go through the application too: a stopped scheduler stays stopped until the next start, and restart is done by the application itself — not counted as a crash.

  • The scheduler is declared (#[EnableScheduler]) — it starts with its own parameters.
  • It is not — the application takes it in: no retries, never critical, running until stopped. That way it can be switched on for a couple of days and off again, without touching the application’s components.
bash
php call schedule start     # the application takes the scheduler in
php call app status           # it is in the "Adopted" list
php call schedule stop        # and the application lets it go

When the application runs in another environment (in a container, with the command run on the host), the command refuses and says to run it there: otherwise every task would fire twice. More in Starting a process that is not declared.

Every action

Command What it does
list Every task and its schedule (the default)
start Start in the terminal
start -d Start in the background
stop A graceful stop (SIGTERM)
restart Stop and start again at once
status State, PID, uptime, task count
status -v Also the CPU and memory of the scheduler’s process

Next

  • Scheduler — #[Scheduled], cron, fixedRate and fixedDelay
  • process — single processes
  • daemon — daemons and worker fleets
  • run — starting the scheduler together with the application