CLI Reference

The Sovrium CLI provides two commands: start a development server and build a static site. Configuration is loaded from a file or environment variable.

Usage

The CLI accepts a command followed by an optional config file path and flags.

Terminal 
sovrium [command] [config] [flags]

sovrium start app.yaml          # Start dev server
sovrium build app.yaml          # Build static site
sovrium --help                  # Show help

Commands

Sovrium has two commands. If no command is specified, start is used by default.

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.

Terminal 
sovrium start app.yaml

sovrium build

Generate a static site from your configuration. Produces HTML, CSS, and assets ready for deployment to any static hosting provider.

Terminal 
sovrium build app.yaml

sovrium --help

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

Terminal 
sovrium --help

Flags

Flags can be placed anywhere in the command.

PropertyDescription
--watch, -wWatch the config file for changes and hot-reload the server automatically. Only available with the start command.
--help, -hShow 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.

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

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

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.

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

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

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

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

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

Exit Codes

The CLI uses standard exit codes.

PropertyDescription
0 — Success
1 — Error (invalid config, missing file, unknown command)
Quick StartTypeScript API