Project Commands

Five commands operate on a project rather than on a running server: scaffold one, build it to static files, print its schema, check a config before you ship it, and write the types for a TypeScript config.

sovrium init

Scaffold a new project into the given directory, or into the current one when no directory is passed. Every scaffold writes an app.yaml, a CLAUDE.md written for that template's domain, and a public/ directory for static assets.

sovrium init ./my-app                          # blank starter
sovrium init ./my-app --template crm --name acme-crm
sovrium init ./my-app --template sovrium/crm-template#v2

Bundled templates: hello-world, landing-page, crm, api-only, intranet, mcp-server, blog, docs-site, projects, helpdesk, content-calendar, people, events, assets, expenses, company-os, automation-recipes, knowledge-base. An unknown name exits 1 and prints the list.

--template also accepts a GitHub repository in any of the forms owner/repo, gh:owner/repo, or https://github.com/owner/repo, each with an optional #ref naming a branch, tag or SHA. Only github.com is supported.

--typescript writes an app.ts instead of an app.yaml, alongside the sovrium.d.ts and tsconfig.json that make it check. It refuses to combine with --template: a template ships its own app.yaml, and Sovrium resolves app.yaml before app.ts, so the generated config would be permanently shadowed. Scaffold the template first, then convert its config by hand.

sovrium build

Generate a static site — HTML, CSS and assets — from your configuration, ready for any static host.

sovrium build app.yaml

SOVRIUM_DEPLOYMENT=github-pages sovrium build app.yaml

SOVRIUM_OUTPUT_DIR=./public \
  SOVRIUM_BASE_URL=https://example.com \
  SOVRIUM_GENERATE_SITEMAP=true \
  SOVRIUM_GENERATE_ROBOTS=true \
  sovrium build app.yaml

Build options come from SOVRIUM_* environment variables, not flags — see Environment Variables for the full set. Output goes to SOVRIUM_OUTPUT_DIR when set; otherwise to a dist/ directory beside the config file.

sovrium schema

Print the JSON Schema (Draft 2020-12) for the app configuration to stdout, or write it to a file.

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

The document is self-contained, with a top-level $schema declaration, so any JSON-Schema-aware editor or validator consumes it as-is. See JSON Schema for how to wire it into an editor.

sovrium validate

Decode a config file against AppSchema and report what is wrong. Accepts .json, .yaml, .yml and .ts, resolving $ref includes first.

sovrium validate app.yaml
sovrium validate app.ts

Prints Valid configuration: <name> and exits 0, or a tree of errors and exits 1. Run it in CI ahead of a deploy — the same schema the server decodes at boot. Full behaviour on Validating a Config.

sovrium types

Write the TypeScript authoring surface into a directory, so a config can be authored as app.ts with no package.json, no node_modules and no install step.

sovrium types
sovrium types --output ./config

Two files land. sovrium.d.ts declares the bare sovrium module and is rewritten on every run, because it describes the schema of the binary that wrote it. tsconfig.json puts that declaration in the TypeScript program and is written only when absent: once a project has one it is yours, and replacing it is not an acceptable side effect of asking for types. When one already exists the command says so, and names the single thing that has to stay true of it. sovrium.d.ts must remain in the TypeScript program.

Re-run it after upgrading the binary. See TypeScript Configs for the authoring model.

Related Pages

• CLI Overview — config resolution and the full command surface.
• Lifecycle Commands — start, stop, restart, reload.
• Templates & Examples — what each bundled template contains.
• Validating a Config — reading the errors validate prints.
• TypeScript Configs — authoring app.ts with zero npm.