Skip to main content
View as Markdown

CLI Overview

The Sovrium CLI is the whole product surface of the self-hosted binary: it runs your app, manages its lifecycle, scaffolds and validates projects, and provisions the secrets and admin account a deployment needs.

Every invocation is a command, an optional config path, and flags. Anything else — ports, database, storage, AI — comes from the environment, never from a flag.

>_ terminal
sovrium [command] [config] [flags]

If the first positional argument looks like a config file (it ends in .json, .yaml, .yml, .ts, .mts, or contains a /), start is assumed. sovrium app.yaml and sovrium start app.yaml are the same command.

Commands

Four groups, documented on their own pages. sovrium --help prints the same list.

Command Group What it does
sovrium start [config] Lifecycle Run the server (default command)
sovrium stop Lifecycle Stop the running server
sovrium restart [config] Lifecycle Stop, then relaunch in the background
sovrium reload Lifecycle Re-read the config with no downtime
sovrium init [dir] Project Scaffold a new project
sovrium build [config] Project Generate a static site
sovrium schema Project Print the JSON Schema
sovrium validate <config> Project Check a config against AppSchema
sovrium design-system [config] Validation & Schema Export the design system for an agent
sovrium admin create <email> Admin & Maintenance Provision an admin user
sovrium secret generate Admin & Maintenance Print fresh secrets as .env lines
sovrium secret adopt Admin & Maintenance Persist the encryption key in use
sovrium update Admin & Maintenance Update the binary
sovrium --help Flags & Exit Codes Print the command summary and exit

Flags

Moved to Global Flags & Exit Codes.

Configuration Sources

Configuration is resolved in a fixed order, and the first source that answers wins:

  1. The config path argument — sovrium start app.yaml.
  2. APP_SCHEMA_FILE — a path, for when a config is too large to pass inline.
  3. APP_SCHEMA — the config itself, as inline JSON, inline YAML, or an http(s) URL to fetch.
  4. Nothing — the command fails with Error: No configuration provided.
>_ terminal
# From a file (any supported format)
sovrium start app.yaml
sovrium start config.json
sovrium start app.ts

# Inline JSON
APP_SCHEMA='{"name":"my-app"}' sovrium start

# Inline YAML
APP_SCHEMA='name: my-app' sovrium start

# Fetched over HTTP at boot
APP_SCHEMA='https://example.com/app.yaml' sovrium start

Supported file extensions are .json, .yaml, .yml, .ts and .mts. The format is detected by extension, not by content, so a YAML document saved as .txt is rejected rather than sniffed.

Watch Mode

--watch (or -w) makes start watch the config file and reload the server when it changes. It is the only flag that changes how start runs.

>_ terminal
sovrium start app.yaml --watch

Examples

Per-command examples live with each command — see Lifecycle, Project, and Admin & Maintenance.

Exit Codes

Moved to Global Flags & Exit Codes.

Last updated August 28, 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