CLI Reference

The Sovrium CLI provides four commands: start a development server, build a static site, 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.

Terminal
sovrium [command] [config] [flags]

sovrium start app.yaml          # Start dev server
sovrium build app.yaml          # Build static site
sovrium schema                  # Print JSON Schema
sovrium validate app.yaml       # Validate config
sovrium --help                  # Show help

Commands

Sovrium has four 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 schema

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

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

Terminal
sovrium validate 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.
--version, -VShow the Sovrium version number and exit.
--output <path>Write output to a file instead of stdout (schema command only).
--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

sovrium schema

Terminal
# Print JSON Schema to stdout
sovrium schema

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

sovrium validate <config>

Terminal
# Validate a YAML config
sovrium validate app.yaml

# Validate a JSON config
sovrium validate config.json

Exit Codes

The CLI uses standard exit codes.

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