Global Flags & Exit Codes

Flags may appear anywhere in the invocation — before the command, after the config path, interleaved. sovrium --watch start app.yaml and sovrium start app.yaml --watch are the same command.

Flags

Flag	Commands	Description
--watch, -w	start	Watch the config file and hot-reload on change.
--publicDir <path>	start, build	Static-asset directory to serve (or copy into the build output).
--no-publicDir	start, build	Serve no static assets. Overrides both the env var and the default.
--output <path>	schema	Write the JSON Schema to a file instead of stdout.
--template <name>	init	Bundled template name, or a GitHub repo (owner/repo[#ref]).
--name <name>	init	App name written into the scaffolded config.
--force	init	Overwrite an existing app.yaml.
--config <path>	admin create	Config used to resolve the auth settings.
--password <value>	admin create	Admin password. Omit it to be prompted, which requires a TTY.
--message <text>	reload	Operator note recorded against the new configuration version.
--version, -v	any	Print the version and exit. Always wins, wherever it appears.
--help, -h	any	Print help and exit. With a command in front, prints that command's help instead.

Static Assets

--publicDir is the one flag with a three-step fallback, shared by start and build:

1. --no-publicDir — opt out entirely; nothing else is consulted.
2. --publicDir <path> — the explicit path.
3. SOVRIUM_PUBLIC_DIR — the same thing from the environment. The literal value none is the env-var spelling of --no-publicDir.
4. Otherwise, public/ next to the config file.

The default is anchored to the config file rather than to the working directory on purpose: the same command serves the same files no matter where you run it from. With an inline APP_SCHEMA there is no config file to anchor to, so no default applies.

sovrium start app.yaml --publicDir ./assets
sovrium start app.yaml --no-publicDir
SOVRIUM_PUBLIC_DIR=none sovrium build app.yaml

Unknown Flags Are Rejected

Any --prefixed token that is not in the table above stops the command before it dispatches:

Error: Unknown flag "--wtach"

This exists because of what used to happen instead. A typo'd flag was treated as a positional argument, fell through to the implicit start, and failed with Error: No configuration provided — an accurate message about entirely the wrong problem. Now the offending token is named.

Exit Codes

Code	Meaning
0	Success
1	Failure — invalid config, missing file, unknown command or flag, refused action

Every failure path exits 1; the distinction lives in the message, not the code. That makes CI gating a one-liner:

sovrium validate app.yaml || exit 1

An unhandled failure prints an Unexpected error: banner with a link to open an issue. That banner means Sovrium itself did not anticipate the failure — worth reporting, with the message copied in.

Related Pages

• CLI Overview — commands and configuration sources.
• Project Commands — the commands most of these flags belong to.
• Environment Variables — the env-var half of the CLI's inputs.