Skip to main content

​
Usage

ocx validate [path] [options]

​
Description

Validate a registry source without building it. This command performs comprehensive validation checks on the registry manifest (registry.jsonc or registry.json) including schema validation, file existence checks, circular dependency detection, and duplicate target detection. Intended for registry authors who want to verify their registry before building or deploying. Unlike ocx build --dry-run, this command focuses exclusively on validation and provides detailed error reporting without attempting to generate output files.

​
Arguments

ArgumentRequiredDescription
pathNoRegistry source directory (default: current directory)

​
Flags

FlagShorthandDefaultDescription
--cwd <path>Current directoryWorking directory
--jsonfalseOutput as JSON (both success and failure)
--quiet-qfalseSuppress all output (including errors)
--no-duplicate-targetsSkip duplicate target validation

​
Examples

​
Validate Registry in Current Directory

ocx validate

​
Validate from a Specific Directory

ocx validate ./my-registry

​
CI/CD Integration

ocx validate uses distinct exit codes so CI can tell validation failures apart from runtime/tool failures:
  • 0 — registry is valid
  • 78 — configuration or validation failed (CONFIG_ERROR or VALIDATION_FAILED)
  • other non-zero codes — runtime/tool failures (for example missing manifest/source directory, I/O, or internal errors)
Referenced files missing under files/ are validation failures and return 78. Example shell gate: 
ocx validate
if [ $? -ne 0 ]; then
  echo "Validation failed"
  exit 1
fi

​
Skip Duplicate Target Validation

ocx validate --no-duplicate-targets

​
JSON Output for Scripting

ocx validate --json
JSON output is provided for both success and failure cases, making it suitable for automated tooling.

​
Quiet Mode

ocx validate --quiet
Suppresses all output (including errors). Check the exit code to determine outcome (0 for valid, 78 for configuration/validation failures—including missing referenced files under files/—and other non-zero for runtime/tool failures). Note: When using --json and --quiet together, JSON output takes precedence.

​
Output

​
Success

$ ocx validate
✓ Registry source is valid

$ ocx validate --json
{
  "success": true,
  "data": {
    "valid": true,
    "errors": [],
    "summary": {
      "valid": true,
      "totalErrors": 0,
      "schemaErrors": 0,
      "sourceFileErrors": 0,
      "circularDependencyErrors": 0,
      "duplicateTargetErrors": 0,
      "otherErrors": 0
    }
  }
}

​
Validation Failure

Human-readable output: 
$ ocx validate
Registry validation failed
  Schema validation error: Missing required field 'name'
  File not found: files/agents/missing-agent.md
  Circular dependency detected: component-a -> component-b -> component-a
JSON output: 
$ ocx validate --json
{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Registry validation failed",
    "details": {
      "valid": false,
      "errors": [
        "Schema validation error: Missing required field 'name'",
        "File not found: files/agents/missing-agent.md",
        "Circular dependency detected: component-a -> component-b -> component-a"
      ],
      "summary": {
        "valid": false,
        "totalErrors": 3,
        "schemaErrors": 1,
        "sourceFileErrors": 1,
        "circularDependencyErrors": 1,
        "duplicateTargetErrors": 0,
        "otherErrors": 0
      }
    }
  },
  "exitCode": 78,
  "meta": {
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}

​
Runtime / Tool Failure (JSON)

Runtime failures (for example missing manifest file, I/O failures, or internal errors) use the standard failure envelope with non-validation error codes: 
$ ocx validate ./missing --json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No registry.jsonc or registry.json found in source directory"
  },
  "exitCode": 66,
  "meta": {
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}

​
Validation Checks

The validate command performs the following checks:
  1. Schema Validation — Validates the manifest structure and required fields
  2. File Existence — Ensures all referenced files exist in the source directory
  3. Circular Dependencies — Detects circular dependencies between components
  4. Duplicate Targets — Identifies components that write to the same target paths

​
Source Structure

The validate command expects a manifest file in the source directory (registry.jsonc preferred, registry.json also supported): 
my-registry/
  registry.jsonc        # Preferred registry manifest
  # or registry.json    # Supported fallback manifest
  files/
    agents/
      my-agent.md       # Agent definition
    plugins/
      my-plugin.ts      # Plugin file
    skills/
      my-skill/
        SKILL.md        # Skill definition

​
Errors

ErrorCauseSolution
Schema validation failedInvalid manifest structure (registry.jsonc or registry.json)Check error messages for specific schema violations
File not foundReferenced file missing from sourceEnsure all files in manifest exist in files/ directory
Circular dependency detectedComponents depend on each otherReview component dependencies and remove cycles
Duplicate target pathsMultiple components write to same pathUpdate target paths to be unique

​
See Also