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.
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
php call process list | [================================ 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:
php call process main.process.ImportProcess statusDots 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
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 backgroundIn 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.
[✓] Dispatched (background): Main\Process\Import
PID 48213Starting 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:
php call process main.ChatSocket start --port=8001
php call process main.ChatSocket start --port=8001 --host=127.0.0.1 -dWithout --port the command starts nothing and says what is missing:
[!] 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
php call process main.process.Import stopA 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
php call process main.process.Import status[ Process Status ]
main.process.Import Process ● RUNNING
PID 48213
State RUNNING
Activity BUSY
Started 2026-08-14 09:12:44
Uptime 2h 14m
Concurrency 4The -v flag adds the resource usage, taken from the operating system:
php call process main.process.Import status -v[ Resources ]
User winter
PPID 1
CPU 12.4 %
Memory 3.1 % (248.6 MB)
Elapsed 02:14:31This 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.
| [ 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:
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 26srestart 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 |