# 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.

```bash
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:

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

Starting while another instance holds the lock is refused:

```text
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.

```bash
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.

```bash
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.

```bash
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:

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

:::callout
**Reload changes config, not code.** A new Sovrium version still needs `restart` (or a redeploy). `reload` re-reads your `app.yaml`; it does not swap the binary.
:::

## Related Pages

- [CLI Overview](/en/docs/cli) — config resolution and watch mode.
- [Project Commands](/en/docs/cli-project) — `init`, `build`, `schema`, `validate`.
- [App Metadata](/en/docs/app-metadata) — the migration history a `reload` appends to.
- [Troubleshooting](/en/docs/troubleshooting) — port conflicts and lock-file errors.