CLI · Winter Console

The application command

The application is one process that starts every declared component and watches over it. application handles it as a whole: start it, stop it, see where each component stands and what is going to start at all.

Alias appActions start · stop · status · health · info

Why

A running application has many processes: the HTTP server with its workers, processes, daemons, the scheduler, outside programs. Looking at them one at a time — through process, daemon and ps — is awkward, and only the application’s supervisor can answer “did everything come up, and what fell over”: it knows which component runs, which waits for another attempt, and which failed and why.

application asks it. And before the start, it reads the code and the environment and shows what will start and with which settings.

bash
php call application info     # what will start
php call application start    # start it (= call run)
php call application status   # where it stands now
php call application health   # is it healthy: one line and an exit code
php call application stop     # stop it

app is the short name: php call app status.

start

Starts the application and runs until it is stopped — in the terminal, not in the background. It is the same command as run under its full name: the same development mode and options.

bash
php call application start
php call application start dev           # with the watcher
php call application start --http.port=9000

info

What starts with the application and with which configuration. The application does not have to run for this: the command reads the attributes, the components() hook and the environment.

text
[ Components ]
COMPONENT                      KIND       SOURCE               CRITICAL  RETRIES  START TIMEOUT
Http :8000                     Http       #[EnableHttp]        yes       3        60s
Chat :8001                     WebSocket  #[EnableWebSocket]   yes       3        60s
Orders                         Daemon     #[EnableDaemon]      yes       -        60s
Heartbeat                      Process    components()         no        3        60s
bridge                         Command    components()         yes       0        -
[i] 5 component(s) start with the application.
[ HTTP server ]
Address        http://0.0.0.0:8000  (#[EnableHttp])
Workers        4
Memory         256M
Timeout        30s per request
Profile        balance · 455 in flight · 910 connections · recycle at 149,130
TLS            off — plain HTTP (TLS at the proxy)
HTTP/2         off
Compression    br/gzip · level 1 · from 1K
[ Configuration ]
Async          off
Caching        enabled
Actuator       enabled · health
DEBUG          false
LOG_LEVEL      info
Column Meaning
SOURCE Where the component is declared: an attribute or the components() hook
CRITICAL Whether its failure stops the whole application
RETRIES How many times it is brought back after a crash; - — never (daemons and programs)
START TIMEOUT How long to wait for it to be ready at the start

What the parameters mean is covered in Supervision. The HTTP server block shows the server settings the way a start without options resolves them: the address from #[EnableHttp], the rest from the SERVER_* variables, all of it as the configuration class adjusts it. The parentheses after the address say where it came from: the attribute, or the configurer (ServerConfigurer) when it changed it. The Actuator line lists the endpoints it exposes (expose), and says guarded when a middleware is set.

status

Where the running application stands: its process and, for every component, what the supervisor last said about it. The components are in two lists: Boot — declared, started with the application; Adopted — not declared, started later on request (call schedule start, dispatch()), see Starting a process that is not declared. An empty Adopted list is not shown.

text
[ Application Status ]
Application ...................................... [● RUNNING]
PID            1
Host           3f2a9c1d7e40
Started        2026-10-27 09:12:03 +00:00
Uptime         2h 14m
[ Boot — started with the application ]
COMPONENT                      KIND       STATE      PID      FOR        RESTARTS
Http                           Http       RUNNING    12       2h 14m     0
Orders                         Daemon     RUNNING    14       2h 14m     0
CacheWarmup                    Process    COMPLETED  -        2h 13m     0
Heartbeat                      Process    WAITING    -        3s         2/3
    next attempt in 1s
    exit code 255
bridge                         Command    FAILED     -        40m        0
    exit code 1
[ Adopted — started on request, run once ]
COMPONENT                      KIND       STATE      PID      FOR
Scheduler                      Scheduler  RUNNING    88       1d 4h
State Meaning
STARTING Started, waiting for it to be ready
RUNNING Running
WAITING Crashed and waits for another attempt — or waits for its start level
HELD Its class already runs outside the application — waiting for that process to end
FAILED Failed: did not come up, or used up its attempts
STOPPED Stopped on request
COMPLETED Finished its work by itself

FOR is how long the component has been in its current state; RESTARTS is the restarts within the last 30 minutes out of those allowed (adopted ones have no such column: they are never restarted). An adopted component that finished its work or was stopped leaves the list. Below the line — the reason for the last crash or failure.

When components have a priority set, info and status show a PRIORITY column, and a component waiting for its level at start says below the line what it waits for: waits for High to be ready or waits for onStarting. An outside program’s START TIMEOUT is - until it has a readiness check: it is ready as soon as it runs.

When the application runs in another environment that shares the project folder (and its .winter/) — in a container, say, while the command runs on the host — status says so: Runs on another host sharing this project folder (a container?) — ask it there. A PID of another machine means nothing here. Run the command there:

bash
docker compose exec server php call app status

health

What it is. The application’s health check for a container: one line and an exit code — 0 when it is healthy, 1 when it is not.

The problem. status writes a table for a person and always exits 0. Docker, Kubernetes and load balancers read the exit code only — from status they cannot tell a running application from one whose database is down.

The solution. health answers one question — does everything the application stands on run — in the language a container’s check understands.

bash
php call app health
# healthy: 4 component(s) up
What it sees Code Line
Every critical component runs (a process whose work is done, and HELD, count) 0 healthy: 4 component(s) up
A non-critical component failed, a component was stopped on request 0 healthy, degraded: report failed
A critical component is still starting, or waits for its restart 1 unhealthy: postgres restarting (1 of 3)
The supervisor has been silent for more than 30 seconds 1 unhealthy: no report from the supervisor for 45s
The application does not run 1 unhealthy: not running

The supervisor reports every few seconds, even when nothing changes. Silence for more than 30 seconds means it hangs itself — though its last report had every component running. Adopted components do not count: they run once. A healthy line goes to stdout, an unhealthy one to stderr.

health asks nothing over the network — it reads what the supervisor publishes anyway — so it works in any application, with HTTP or without, and answers in a fraction of a second.

In Docker

docker-compose.yml
services:
server:
  healthcheck:
    test: ["CMD", "php", "call", "application", "health"]
    interval: 30s
    timeout: 5s
    start_period: 60s
    start_interval: 5s
    retries: 3

call cfg docker writes it into a new project’s docker-compose.yml itself.

  • start_period — a grace time after the container starts: failed checks in it do not count, and the container is starting. A first start creates the databases’ data and runs the migrations, and all that time health honestly answers “not ready yet”. A check that passes earlier makes the container healthy at once. 60 seconds is a service’s time to become ready (startTimeout): a critical service not ready by then stops the application anyway.
  • start_interval — how often to check in the grace time: every 5 seconds, not every 30. An ordinary restart is healthy in ~5 seconds — what waits for it (depends_on: condition: service_healthy) starts sooner, a rolling update in Swarm goes faster. It needs Docker Compose 2.20+ and Docker Engine 25+.
  • retries — how many failures in a row make the container unhealthy. The supervisor’s restart of one component takes seconds — it rarely comes to three failures in a row.

The check itself restarts nothing in compose: it gives a healthy/unhealthy status, which depends_on: condition: service_healthy, Swarm, load balancers and monitoring read. The components inside the container are restarted by the supervisor anyway.

HTTP — through the actuator too

health sees what the supervisor knows: the HTTP process is alive and ready. Whether its workers answer, it does not check. For that — an HTTP check through #[EnableActuator]: curl -f localhost:8000/actuator/health. The two checks complement each other; in Kubernetes call app health works as an exec probe.

stop

Stops the application the same way Ctrl+C or stopping the container does — with SIGTERM to its process — and waits for it to end. The components stop cleanly: a daemon, for instance, lets its workers finish what they are doing.

bash
php call application stop
php call application stop --timeout=120          # wait longer
php call application stop --timeout=30 --force   # not done by then — SIGKILL
Option What it sets Default
--timeout= How many seconds to wait for it to stop 60
--force When the time is up — SIGKILL to the application and all its components off

Without --force, when the time is up the command only says the application is still running — usually a component is finishing what it started.

To stop a single component and leave the rest alone, use call process <Class> stop or call daemon <Class> stop: see Controlling a running component.

Next