primitree check

primitree check [--config <path>] [--source <name>] [--format text|json]
primitree check <variables.json | tokens-dir>

The first form reads ./primitree.config.ts by default. --config names one exact config file. --source selects a source when the file contains several sources. --format json writes one JSON report.

The source config names a local DTCG file, one to four layers, allowed value forms and references, and owners. Paths start from the config file directory.

Install the CLI in the project before importing its config helper:

npm install -D @primitree/cli@next

import { defineConfig } from '@primitree/cli/config'

export default defineConfig({
  schemaVersion: 1,
  sources: {
    brand: {
      type: 'dtcg',
      file: './tokens.json',
      architecture: {
        layers: [
          { id: 'base', roots: ['color'], values: 'literal' },
          {
            id: 'meaning',
            roots: ['semantic'],
            values: 'reference',
            references: ['base'],
          },
        ],
      },
      ownership: { default: ['design-systems'] },
    },
  },
})

Configured source files must contain valid UTF-8 and be 10 MiB or smaller. Output-path validation records the identity of each existing regular source file it inspects. Primitree compares that identity with the file it opens. During the bounded read, it rejects changes to the opened file or configured path.

The older <path> form can point to:

• a variables.json export
• a built design-tokens/ directory

Usage

primitree check variables.json
primitree check design-tokens
primitree check . # initialized repository root

Positional input rules

A variables JSON file must be 20 MiB or smaller. In a built token source, tokens.resolver.json and each *.tokens.json file must be 20 MiB or smaller, and their combined size cannot exceed 256 MiB. The combined limit includes the Resolver. A source can contain at most 1,000 token files, 100,000 directory entries, and 64 nested directory levels.

Built sources support nested token files. Resolver references use paths relative to the directory containing tokens.resolver.json.

Every positional JSON file must contain valid UTF-8. The variables input must be a regular file. A built source accepts directories and regular files; the check rejects symbolic links and special nodes. A built-source warning appears when a token has no effective type. A token's own $type, an inherited group $type, or a type reached through a whole-token alias counts as an effective type.

Checks

Configured DTCG source

• Reference targets, cycles, and token types
• Exact layer roots
• Literal and reference rules
• Allowed reference layers
• Owner rules

Older variables export

• Supported export shape
• Alias graph cycles and dangling targets
• Per-mode value resolution

Built directory

• DTCG Resolver version
• Each declared context permutation merges
• Token references resolve

The command exits with code 0 after a passing check, code 1 for findings, and code 2 for command, config, or input errors.