CLI · Winter Console

The process command

Processes can be started from more than code. The process command finds every process class in the project, shows which of them are running right now, and lets you start, stop and inspect any of them — without touching the application.

Actions list · start · stop · restart · statusDaemons a separate command

Why

A process is a unit of work outside a request: an import, a mailing, a recalculation. It needs operational actions the application’s code does not have: see whether it is running right now, start it by hand after a failure, stop it before a deploy, work out why it is eating the CPU.

The process command gives exactly that. What processes are and how to write them is on the Processes page.

What the project has

bash
php call process list
text
 | [================================ Process ================================]
| [ Available Processes ]
|	 [P] Main.Process.ImportProcess ..................... [● RUNNING] [BUSY] 12s
|	 [P] Main.Process.ReportProcess ..................... [○ STOPPED]
|	 [P] Main.Process.CleanupProcess ................... [● RUNNING] [idle] 3h 4m
| - - - - - - - - - - - - - - - - - - - - - - -
| [i] 3 defined, 2 running.
| [ Available Processes ]
| [================================ Process ================================]

The list is collected by scanning the project, so processes need no registration anywhere — it is enough for the class to extend Process. Daemons do not appear in this list: they have their own command.

Marker Meaning
● / ○ Running / stopped
[BUSY] Currently doing useful work
[idle] Started but idling

The class name

The class is given in dot notation — the same way as in make and script:

bash
php call process main.process.ImportProcess status

Dots become namespace separators and the first letter of each segment is capitalised: main.process.ImportProcess → Main\Process\ImportProcess. The command leaves the other letters alone, so type the class name in its own case: main.process.importprocess becomes Main\Process\Importprocess, and the command finds no such class.

Starting

bash
php call process main.process.Import              # foreground
php call process main.process.Import start        # the same thing
php call process main.process.Import start -d     # in the background

In the foreground — the process occupies the terminal, writes into it and finishes on its own. That is convenient for debugging: you see the output and Ctrl+C stops it.

In the background (-d) — the command detaches the process and returns control, printing the PID. The terminal can be closed.

text
[✓] Dispatched (background): Main\Process\Import
  PID          48213

Starting it again does not create a second process

If the process is already running, the command says so and starts nothing:

[!] Already running [PID:48213] (2026-08-14 09:12:44).

This is the same locking mechanism that protects a process from being started concurrently from inside the application — a lock file in .winter/runnable.

WebSocket: a port is required

A WebSocket server is a process too, but it will not start without a port. The port and, if needed, the interface are passed as options:

bash
php call process main.ChatSocket start --port=8001
php call process main.ChatSocket start --port=8001 --host=127.0.0.1 -d

Without --port the command starts nothing and says what is missing:

text
[!] A WebSocket needs a port: --port=8001 [--host=0.0.0.0].

The exception is a socket declared among the application’s components (#[EnableWebSocket]) while that application runs on this same host: start without --port asks the application to start it, and it gets its declared port.

status and stop work as for any process — they need no port. restart of a socket started on its own, however, is refused: the port it was started with is not known here, and the command will not stop what it could not start again. Restart such a socket in two steps — stop, then start --port=…. A socket the running application manages is restarted by restart as usual, with its port.

Stopping

bash
php call process main.process.Import stop

A SIGTERM is sent — the graceful-shutdown signal. The process gets the chance to finish its current iteration, close its connections and exit on its own. It does not die instantly, and that is right: an unfinished write to the database is worse than a second of delay.

Status

bash
php call process main.process.Import status
text
[ Process Status ]
main.process.Import        Process ● RUNNING
PID          48213
State        RUNNING
Activity     BUSY
Started      2026-08-14 09:12:44
Uptime       2h 14m
Concurrency  4

The -v flag adds the resource usage, taken from the operating system:

bash
php call process main.process.Import status -v
text
[ Resources ]
User         winter
PPID         1
CPU          12.4 %
Memory       3.1 % (248.6 MB)
Elapsed      02:14:31

This is the first place to look when a process “hangs”: Activity shows whether it is working or idling, and CPU and Memory show what it ran into.

While the application runs

While the application runs, it starts the process, not the console: start, with or without -d, asks the application to start the process, and the command returns at once.

text
 | [ Available Processes (application) ]
|	 [P] Main.Process.Import ..................... [● RUNNING] [idle] [boot] 2h 14m
|	 [P] Main.Process.Export ..................... [● RUNNING] [BUSY] [adopted] 3m
Tag Meaning
(application) The application runs — it does the starting
[boot] Declared among the application’s components — starts with its own parameters
[adopted] Not declared — the application took it in for one run: no retries, never critical
○ STOPPED / ✕ FAILED A component of the application stopped on request / could not run

For a component that is down, status shows when it went down and who manages it; there is no PID in that state:

text
  main.process.Import ............. [○ STOPPED]
PID          —
State        STOPPED — on request
Managed by   application [PID 1]
Stopped at   2026-10-27 09:08:31 +00:00
Down for     2m 26s

restart stops it and starts it again at once; while the application runs, the application does it, and it does not count as a crash.

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. More in Controlling a running component.

Every action

Command What it does
list Every process in the project with its current state
<Class> Start in the foreground
<Class> start The same, explicitly
<Class> start -d Start in the background
<Class> stop Graceful stop (SIGTERM)
<Class> restart Stop and start again at once
<Class> status State, PID, uptime
<Class> status -v Plus resource usage
<Socket> start --port=N [--host=…] [-d] Start a WebSocket server — the port is required, except for a declared socket while the application runs

Next

  • Processes — how to write processes
  • WebSocket — a WebSocket server as a process
  • daemon — the same for daemons and their workers
  • schedule — scheduled tasks
  • run — starting processes together with the application