Lifecycle Commands

Four commands run and control a server. stop, restart and reload all find the running process through a lock file the server writes at boot, recording its PID, port and config path — which is why none of them need you to name the config again.

sovrium start

Start the server. This is the default command, so the start word is optional when a config path is present.

sovrium start app.yaml          # explicit
sovrium app.yaml                # implicit — identical
sovrium start app.yaml --watch  # reload on config change

PORT=8080 sovrium start app.yaml

The port comes from PORT and defaults to 3000. If that port is already taken, Sovrium does not fail — it binds an OS-assigned free port and prints the real URL in the startup banner:

[SERVER] Port 3000 in use; using an OS-assigned port (see URL below).

Starting while another instance holds the lock is refused:

Error: Server already running (PID: 12345, port: 3000)

A lock left behind by a crashed process is detected (its PID no longer exists) and removed automatically, so this only blocks you when an instance really is running.

sovrium stop

Send SIGTERM to the process named in the lock file, then remove the lock.

sovrium stop

Prints Server stopped successfully. With no lock file it exits 1 with Error: No server is running (lock file not found).

sovrium restart

Stop the running server, then relaunch it detached in the background. The config path is optional — without one, the path recorded in the lock file is reused.

sovrium restart          # same config as the running instance
sovrium restart app.yaml # swap in a different config

Restart is a full process replacement: the port is reassigned and connections are dropped. Prefer reload when the only thing that changed is the configuration.

sovrium reload

Re-read the configuration of a running server without downtime. Sovrium validates the file first and only signals the process once it decodes cleanly, so an invalid edit is rejected before it can reach the live server.

sovrium reload
sovrium reload --message "Add the invoices table"

--message records an operator note against the new configuration version, which then shows up in the app's migration history.

Because configuration is code-only, there is no runtime-edited schema for a reload to conflict with — the file on disk is always the truth. An invalid file stops the reload with:

Error: Invalid configuration - <the failing path and reason>

Related Pages

• CLI Overview — config resolution and watch mode.
• Project Commands — init, build, schema, validate.
• App Metadata — the migration history a reload appends to.
• Troubleshooting — port conflicts and lock-file errors.