Validate a site
Check a site's CMS schema and content from the command line, before you push and in CI, with the same rules the editor runs.
The editor validates the page you have open. nrc cms validate validates
the whole site from a checkout of its repository: every schema file,
every content file against its collection, and the links between them.
It needs no sign-in and sends nothing anywhere, so it runs on your
machine before a push and in the site's CI on every pull request.
nrc cms validate # the site in the current directory
nrc cms validate ./site # or a path
nrc cms validate --only schema # schema files alone
nrc cms validate --fail-on warningSEVERITY FILE PATH RULE MESSAGE
error src/content/pages/about.md seats content.required Seats is required.
error src/content/pages/about.md hero links.missing_asset points at /images/missing.png, which the repository does not have (looked for public/images/missing.png)
warning src/content/pages/index.md blocks[0].link links.unresolved_link links to /about/, which no content file produces
error .norcube/cms/collections/pages.yml fields.tier schema.default_not_option default "enterprise" of "Tier" is not one of its options
9 content files, 4 schema files: 3 errors, 1 warningThe last line goes to stderr; the table (or -o json) is the result.
The CLI is on the CLI page; the command's flags are in the
reference.
What is checked
Three groups run, all by default; --only schema, --only content and
--only links narrow the run (repeatable).
schema: .norcube/cms/ loads and makes sense on its own. YAML
parses, every $ref names a block or an input, every field has key,
type and label, the type is one the editor renders and the knobs
are ones that type reads, select defaults are options, bounds are
ordered, regexes compile, visibleIf and computed.from paths name
fields in their scope, storage: names and defaultStorage are
declared, the preview, redirects and variables blocks are
consistent, and no two collections claim one directory without literal
match names to tell them apart.
content: every content file against its collection, with the
editor's rules. Required fields, value shapes (a number where the
schema says text, a select value that is no longer an option), the
discriminator of each multi-shape array item, array bounds, regex,
minLength and maxLength, min and max, uniqueOn, custom
validators, keys the schema does not declare (per extraKeysPolicy),
and a Markdown body in a collection that has none. Fields hidden by
hidden or by a false visibleIf are skipped, as in the editor.
links: the site as a whole. Two files that resolve to one URL, site
links that no content file produces and no knownPaths entry covers,
images and files that do not exist in the repository, reference fields
whose target is gone, and identity sidecars under .norcube/cms/meta
whose content file no longer exists.
The groups build on the same schema reference the editor uses; a finding here is a finding the editor would show.
Findings and rules
Every finding names the file, the field path inside it
(blocks[2].heading), a severity and a rule id:
| Prefix | Examples |
|---|---|
schema. | schema.unresolved_ref, schema.unknown_knob, schema.default_not_option |
content. | content.required, content.shape, content.item_type_unknown, content.extra_keys |
links. | links.unresolved_link, links.missing_asset, links.unresolved_reference |
Rule ids are frozen: a released id is never renamed or reused, so a script can match on them. The full list is in the cms-schema module, which also holds the checks themselves; the CLI and the CMS service share it.
Errors are findings the site should not ship with: the editor would
refuse the value, the build would break, or a link provably points at
nothing. Warnings are worth a look but break nothing by themselves,
for example a link to a route the site serves from code (add it to
knownPaths in config.yml to silence it).
Exit codes and CI
| Situation | Exit code | Error code |
|---|---|---|
No finding at the --fail-on severity | 0 | |
A finding at or above --fail-on (default: error) | 1 | invalid |
| The path is not a CMS site | 3 | not_found |
| A wrong flag, a missing or non-directory path | 2 | usage_error |
--fail-on warning fails on any finding, --fail-on none only reports.
With -o json the report is {schemaVersion, path, findings[], summary{files, schemaFiles, errors, warnings}}, printed even when the
command fails, so CI keeps it as an artifact; --query works on it.
A GitHub Actions step, with the CLI installed through the install script:
- name: Validate the CMS site
run: |
curl -fsSL https://raw.githubusercontent.com/norcubeplatform/cli/main/install.sh | sh
nrc cms validate --fail-on error -o json > cms-validate.json
- uses: actions/upload-artifact@v4
if: always()
with:
name: cms-validate
path: cms-validate.jsonNo token is needed; the step reads the checkout only.
Limits
- Regular expressions in
regexknobs are evaluated by the editor in JavaScript and by the CLI with Go's RE2 engine. A pattern RE2 cannot compile (lookaround, backreferences) is reported asschema.invalid_regexand skipped in the content checks. Keep patterns to the common subset for sites checked in CI. - Links are judged against the files in the checkout. A page that only exists on another branch is reported as an unresolved link until the branches meet.
- Site-specific contracts, such as an Astro Zod schema stricter than the
CMS schema, stay with the site's own checks (
astro check).
AI schema generation
The CMS scans your repo, observes what's actually in your frontmatter, and asks an LLM to draft a working schema you can use immediately — full bootstrap or single-block.
Page editor
The schema-driven content editor — the field form, content blocks, rich text, validation, and the Save vs Publish split.