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.

Verified November 15, 2026

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 warning
SEVERITY  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 warning

The 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:

PrefixExamples
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

SituationExit codeError code
No finding at the --fail-on severity0
A finding at or above --fail-on (default: error)1invalid
The path is not a CMS site3not_found
A wrong flag, a missing or non-directory path2usage_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.json

No token is needed; the step reads the checkout only.

Limits

  • Regular expressions in regex knobs 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 as schema.invalid_regex and 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).

On this page