CLI Reference

CLI Reference

The cms command (package cms-cli, built on Typer). Every command accepts --project / -p to point at the project directory containing sardine.toml (defaults to the current directory). Missing project file exits with code 2.

cms init DIRECTORY

Scaffold a new project.

Option	Default	Meaning
--name	My Sardine CMS	Site name
--base-url	https://example.com	Canonical base URL
--languages	pt-pt,es,fr,de	Required target languages, comma-separated (EN is always the source)

cms seed [-p DIR] [--force]

Write the fictional starter content (Sardine Aerospace: 2 pages, 12 articles, 4 media assets, 5 languages) with fixed timestamps so seeded projects build deterministically. Refuses to overwrite existing content (exit 3) unless --force is given.

cms validate [-p DIR]

Run the validation ruleset over the whole content set and print N error(s), M warning(s). Non-zero exit when errors exist. Rules: required translations, unique slugs per language, media references, mandatory EN alt text, known categories (see Content Model).

cms build [-p DIR]

Validate, then build the static site into the configured output directory (default _site/). Deterministic: same content → byte-identical output (the CLI prints the artifact digest).

cms export [-p DIR] [--target NAME]

Build plus target-specific extras:

Target	Extras
generic (default)	plain static files
swa	staticwebapp.config.json (security headers, cache rules, 404 rewrite)
nginx	nginx server config with security headers, container-ready layout

cms preview [-p DIR] [--port N]

Serve the built _site/ locally (default port 8000).

cms admin create-user USERNAME [--role ROLE] [--force] [-p DIR]

Create an admin account in the project's storage — the only way to create the first account (no default credentials). Prompts for the password twice (argon2id-hashed; only the hash is stored). Roles: editor | reviewer | publisher | admin. --force replaces an existing account.

Exit codes

Code	Meaning
0	success
1	validation errors (validate/build/export)
2	sardine.toml not found
3	cms seed refused to overwrite existing content

cms dump / cms import

cms dump -p project writes the portable source of truth — portable/content.json plus portable/markdown/<article>/<lang>.md. cms import portable/ -p other-project reads it back losslessly (--replace to upsert into non-empty storage). Round-trip is byte-verified by the test suite: this is the backup, the restore path and the way to move content between instances or storage engines.