Skip to main content
View as Markdown

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, types Write the JSON Schema to a file; for types, the directory to write into.
--typescript init Scaffold a typed app.ts instead of app.yaml. Refuses --template.
--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.

>_ terminal
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:

code
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:

>_ terminal
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.

Last updated September 1, 2026

Edit this pageReport an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.

Built with Sovrium