xcaffold validate

Check .xcaf syntax and schema, cross-references, and structural invariants.

Performs a dry-run validation of your .xcaf configuration. It checks for syntax errors, broken references, policy violations, and structural invariants without writing any files to the provider directories.

Usage

Shell

xcaffold validate [flags]

Flags

Flag	Short	Type	Default	Description
`--target`		`string`	`""`	Validate field support for a specific provider target. When set, runs field-level fidelity checks and returns a non-zero exit code on any field error.
`--var-file`		`string`	`""`	Load variables from a custom file instead of the default `xcaf/project.vars`.
`--global`	`-g`	`bool`	`false`	Operate on the user-wide global configuration (`~/.xcaffold/xcaf/global.xcaf`). Inherited from the root command.

Behavior

Validation Tiers

Syntax and Schema: Checks that all .xcaf files are valid YAML and adhere to the latest schema version (e.g., version: "1.0").
Cross-References: Ensures that all resource links (e.g., an agent referencing a skill) resolve to valid resource IDs. Unresolved cross-references are reported as non-fatal warnings and do not cause a non-zero exit code.
Directory Integrity: Validates that all referenced supporting files (scripts, references, artifacts) exist on the filesystem. Checked separately for skill directories and hook directories.
Structural Checks: Runs invariant checks. The only structural check is: warning if an agent has the Bash tool enabled without a PreToolUse hook for command validation.
Policy Evaluation: Compiles the project and evaluates all project and global policies against the compiled output. When --target is set, runs once for that target. When --target is omitted, runs once per target declared in project.xcaf's targets: list and aggregates findings across all targets. If --target is omitted and no targets are declared in project.xcaf, validate exits with an error. The policies line appears in output only when at least one policy is evaluated or at least one violation is found.
Field Validation: If --target is specified, checks for missing required fields or unsupported field types for that provider.

Examples

Run a full validation of the project:

Shell

xcaffold validate

Validate field support for Claude:

Shell

xcaffold validate --target claude

Load variables from a custom file:

Shell

xcaffold validate --var-file ./custom.vars

Sample Output

xcaffold-project  ·  validating 14 resources

  ✓  syntax and schema (22 files)
  ✓  skill directories
  ✓  hook directories
  ✓  policies (2 checked)

✓  Validation passed.  14 .xcaf files checked.

Errors

No targets configured

error: no targets configured; specify --target or add targets: in project.xcaf

This error fires when --target is not passed and project.xcaf has no targets: block. To resolve:

Option 1 — Add a targets: list to project.xcaf:

.xcaf

kind: project
name: my-project
targets:
  - claude
  - cursor

Option 2 — Pass --target explicitly:

Shell

xcaffold validate --target claude

Exit Codes

Code	Meaning
`0`	Success (all checks passed)
`1`	Failure (one or more errors found)

Previous← xcaffold init NextUtility →

Flags

Flag	Short	Type	Default	Description
`--target`		`string`	`""`	Validate field support for a specific provider target. When set, runs field-level fidelity checks and returns a non-zero exit code on any field error.
`--var-file`		`string`	`""`	Load variables from a custom file instead of the default `xcaf/project.vars`.
`--global`	`-g`	`bool`	`false`	Operate on the user-wide global configuration (`~/.xcaffold/xcaf/global.xcaf`). Inherited from the root command.

Behavior

Validation Tiers

Syntax and Schema: Checks that all .xcaf files are valid YAML and adhere to the latest schema version (e.g., version: "1.0").

Cross-References: Ensures that all resource links (e.g., an agent referencing a skill) resolve to valid resource IDs. Unresolved cross-references are reported as non-fatal warnings and do not cause a non-zero exit code.

Directory Integrity: Validates that all referenced supporting files (scripts, references, artifacts) exist on the filesystem. Checked separately for skill directories and hook directories.

Structural Checks: Runs invariant checks. The only structural check is: warning if an agent has the Bash tool enabled without a PreToolUse hook for command validation.

Policy Evaluation: Compiles the project and evaluates all project and global policies against the compiled output. When --target is set, runs once for that target. When --target is omitted, runs once per target declared in project.xcaf's targets: list and aggregates findings across all targets. If --target is omitted and no targets are declared in project.xcaf, validate exits with an error. The policies line appears in output only when at least one policy is evaluated or at least one violation is found.

Field Validation: If --target is specified, checks for missing required fields or unsupported field types for that provider.

Sample Output

xcaffold-project  ·  validating 14 resources

  ✓  syntax and schema (22 files)
  ✓  skill directories
  ✓  hook directories
  ✓  policies (2 checked)

✓  Validation passed.  14 .xcaf files checked.

Errors

No targets configured

error: no targets configured; specify --target or add targets: in project.xcaf

This error fires when --target is not passed and project.xcaf has no targets: block. To resolve:

Option 1 — Add a targets: list to project.xcaf:

.xcaf

kind: project
name: my-project
targets:
  - claude
  - cursor

Option 2 — Pass --target explicitly:

Shell

xcaffold validate --target claude

Code

Meaning

0

Success (all checks passed)

1

Failure (one or more errors found)