# CLI Reference The Sovrium CLI runs your application and manages its lifecycle: start and stop the server, hot-reload config without downtime, build a static site, scaffold a project, print the JSON Schema, and validate a config file. Configuration is loaded from a file or environment variable. ## Usage The CLI accepts a command followed by an optional config file path and flags. ```bash sovrium [command] [config] [flags] sovrium start app.yaml # Start the server (default command) sovrium stop # Stop the running server sovrium restart app.yaml # Restart the running server sovrium reload # Hot-reload config without downtime sovrium build app.yaml # Build static site sovrium init ./my-app # Scaffold a new project sovrium schema # Print JSON Schema sovrium validate app.yaml # Validate config sovrium --help # Show help ``` ## Commands The most common commands are below. If no command is specified, `start` is used by default. The CLI also exposes commands to extend a project (`agents`), operate it (`admin`, `secret`), and keep the binary current (`update`) — all documented below. Run `sovrium --help` for the full list. ### `sovrium start` Start a development server that serves your application. This is the default command — running `sovrium app.yaml` is equivalent to `sovrium start app.yaml`. ```bash sovrium start app.yaml ``` ### `sovrium stop` Stop the running Sovrium server. ```bash sovrium stop ``` ### `sovrium restart` Restart the running server, optionally with a new config file. ```bash sovrium restart app.yaml ``` ### `sovrium reload` Hot-reload the configuration of a running server without downtime. The reload first probes the live app's drift posture; if the live schema has drifted from the file (edited at runtime via the admin API or MCP), the reload is refused unless `--force` is passed. See [App Metadata](/en/docs/app-metadata#schema-drift-detection). ```bash sovrium reload sovrium reload --force # overwrite a drifted live schema with the file ``` ### `sovrium init` Scaffold a new project in the given directory (or the current directory). Use `--template ` to start from a template and `--name ` to set the app name. ```bash sovrium init ./my-app --template blog ``` ### `sovrium build` Generate a static site from your configuration. Produces HTML, CSS, and assets ready for deployment to any static hosting provider. ```bash sovrium build app.yaml ``` ### `sovrium schema` Print the JSON Schema (Draft-07) for the Sovrium app configuration to stdout. Use `--output ` to write to a file instead. ```bash sovrium schema sovrium schema --output app.schema.json ``` ### `sovrium validate ` Validate a configuration file against the Sovrium AppSchema. Returns exit code 0 if valid, 1 if invalid with error details. ```bash sovrium validate app.yaml ``` ### `sovrium agents list` List the agent templates embedded in the binary. These are Claude Code subagent definitions you can install into a project's `.claude/agents/` directory. ```bash sovrium agents list ``` ### `sovrium agents install ` Install an embedded agent template into `.claude/agents/.md`. `add` is an alias of `install`. By default the agent is written under the current directory; pass `--target ` to choose another project root. The command refuses to overwrite an existing agent file unless `--force` is supplied. ```bash sovrium agents install crm-editor sovrium agents add crm-editor --target ./my-project --force ``` ### `sovrium admin create ` Provision an admin user against the database without standing up a full schema. The password is taken from `--password ` when supplied (useful for CI/scripting); otherwise you are prompted interactively with echo disabled. Running without `--password` in a non-interactive shell (no TTY) is an error. The database schema is resolved in this order: an explicit `--config `, then `APP_SCHEMA`, then a minimal built-in default — so the bare `sovrium admin create ` flow works with no config file. If the admin already exists, no changes are made. ```bash # Prompt for the password interactively sovrium admin create me@example.com # Supply the password (CI / scripting) sovrium admin create me@example.com --password 's3cret-pass' # Resolve the schema from a specific config sovrium admin create me@example.com --config app.yaml ``` ### `sovrium secret generate` Print freshly-generated, cryptographically random secrets as `.env`-ready lines. Each secret is a 256-bit (64 hex character) value. With no scope, both `AUTH_SECRET` and `SOVRIUM_ENCRYPTION_KEY` are printed. Pass a scope to print a subset. | Scope | Output | | ------------ | ---------------------------------------- | | _(none)_ | `AUTH_SECRET` + `SOVRIUM_ENCRYPTION_KEY` | | `all` | Both (explicit) | | `auth` | `AUTH_SECRET` only | | `encryption` | `SOVRIUM_ENCRYPTION_KEY` only | The generated `.env` lines are written to stdout (so redirects work cleanly); informational notes go to stderr. ```bash # Both secrets sovrium secret generate # Append a fresh AUTH_SECRET to your .env sovrium secret generate auth >> .env # Encryption key only sovrium secret generate encryption ``` ### `sovrium update` Update Sovrium to the latest version. The behavior depends on how Sovrium was installed: | Install method | Behavior | | -------------- | -------------------------------------------------------- | | `binary` | Self-replaces from GitHub Releases (Unix) | | `homebrew` | Delegates to `brew upgrade sovrium/tap/sovrium` | | `scoop` | Delegates to `scoop update sovrium` | | `docker` | Prints the `docker pull` instruction | | `npm` | Prints a deprecation notice (the npm package is retired) | ```bash sovrium update sovrium update --help ``` ### `sovrium --help` Display the help message with a summary of commands, options, and examples. ```bash sovrium --help ``` ## Flags Flags can be placed anywhere in the command. | Flag | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------- | | `--watch, -w` | Watch the config file for changes and hot-reload the server automatically. Only available with the `start` command. | | `--version, -V` | Show the Sovrium version number and exit. | | `--output ` | Write output to a file instead of stdout (`schema` command only). | | `--template ` | Project template to scaffold from (`init` command). | | `--name ` | App name to set when scaffolding (`init` command). | | `--target ` | Install destination, defaults to the current directory (`agents install` command). | | `--config ` | Config file used to resolve the database schema (`admin create` command). | | `--password ` | Admin password; if omitted you are prompted interactively (`admin create` command). | | `--force` | Overwrite existing files or a drifted live schema (`init`, `reload`, `agents install`). | | `--help, -h` | Show the help message and exit. | ## Configuration Sources Sovrium can load configuration from a file path or from the `APP_SCHEMA` environment variable. A file path takes precedence when both are provided. ### File path Pass a path to a JSON or YAML configuration file as the second argument. ```bash sovrium start app.yaml sovrium build config.json ``` ### Environment variable Set the `APP_SCHEMA` variable to provide configuration without a file. Supports inline JSON, inline YAML, or a remote URL. ```bash # Inline JSON APP_SCHEMA='{"name":"my-app"}' sovrium start # Inline YAML APP_SCHEMA='name: my-app' sovrium start # Remote URL APP_SCHEMA='https://example.com/app.yaml' sovrium start ``` :::callout **YAML or JSON.** Sovrium supports both `.yaml`/`.yml` and `.json` files. YAML is recommended for readability. ::: ## Watch Mode Watch mode monitors your config file and automatically reloads the server when changes are detected. ```bash # Start with file watching sovrium start app.yaml --watch # Edit app.yaml in another terminal... # Server reloads automatically ``` :::callout **Error recovery.** If the updated config file is invalid, the reload fails gracefully and the previous server continues running. Fix the config and save to retry. ::: ## Examples Common CLI usage patterns. ### `sovrium start` ```bash # Start from a JSON file sovrium start app.json # Start from a YAML file sovrium start app.yaml # Implicit start (default command) sovrium app.yaml # Start with watch mode (hot reload) sovrium start app.yaml --watch sovrium start app.yaml -w # Start on a custom port PORT=8080 sovrium start app.yaml ``` ### `sovrium build` ```bash # Basic static build sovrium build app.yaml # Build for GitHub Pages SOVRIUM_DEPLOYMENT=github-pages sovrium build app.yaml # Build with sitemap and custom output SOVRIUM_OUTPUT_DIR=./public \ SOVRIUM_BASE_URL=https://example.com \ SOVRIUM_GENERATE_SITEMAP=true \ SOVRIUM_GENERATE_ROBOTS=true \ sovrium build app.yaml ``` ### `sovrium schema` ```bash # Print JSON Schema to stdout sovrium schema # Write JSON Schema to a file sovrium schema --output app.schema.json ``` ### `sovrium validate ` ```bash # Validate a YAML config sovrium validate app.yaml # Validate a JSON config sovrium validate config.json ``` ## Exit Codes The CLI uses standard exit codes. | Code | Meaning | | ---- | ----------------------------------------------------- | | `0` | Success | | `1` | Error (invalid config, missing file, unknown command) | ## Related Pages - [Configuration Files](/en/docs/configuration-files) — YAML, JSON, TypeScript, and `$ref` multi-file configs. - [Environment Variables](/en/docs/env-vars) — `APP_SCHEMA`, `PORT`, `DATABASE_URL`, and build vars. - [App Metadata](/en/docs/app-metadata) — the version ledger and drift detection that `reload` respects.