Skip to main content
View as Markdown

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.

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.

sovrium start app.yaml

sovrium stop

Stop the running Sovrium server.

sovrium stop

sovrium restart

Restart the running server, optionally with a new config file.

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.

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 <name> to start from a template and --name <name> to set the app name.

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.

sovrium build app.yaml

sovrium schema

Print the JSON Schema (Draft-07) for the Sovrium app configuration to stdout. Use --output <path> to write to a file instead.

sovrium schema
sovrium schema --output app.schema.json

sovrium validate <config>

Validate a configuration file against the Sovrium AppSchema. Returns exit code 0 if valid, 1 if invalid with error details.

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.

sovrium agents list

sovrium agents install <name>

Install an embedded agent template into .claude/agents/<name>.md. add is an alias of install. By default the agent is written under the current directory; pass --target <dir> to choose another project root. The command refuses to overwrite an existing agent file unless --force is supplied.

sovrium agents install crud-editor
sovrium agents add crud-editor --target ./my-project --force

sovrium admin create <email>

Provision an admin user against the database without standing up a full schema. The password is taken from --password <value> 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 <path>, then APP_SCHEMA, then a minimal built-in default — so the bare sovrium admin create <email> flow works with no config file. If the admin already exists, no changes are made.

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

# 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) 
sovrium update
sovrium update --help

sovrium --help

Display the help message with a summary of commands, options, and examples.

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 <path> Write output to a file instead of stdout (schema command only).
--template <name> Project template to scaffold from (init command).
--name <name> App name to set when scaffolding (init command).
--target <dir> Install destination, defaults to the current directory (agents install command).
--config <path> Config file used to resolve the database schema (admin create command).
--password <value> 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.

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.

# 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

Watch Mode

Watch mode monitors your config file and automatically reloads the server when changes are detected.

# Start with file watching
sovrium start app.yaml --watch

# Edit app.yaml in another terminal...
# Server reloads automatically

Examples

Common CLI usage patterns.

sovrium start

# 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

# 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

# Print JSON Schema to stdout
sovrium schema

# Write JSON Schema to a file
sovrium schema --output app.schema.json

sovrium validate <config>

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