ocx validate

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

Argument	Required	Description
`path`	No	Registry source directory (default: current directory)

Flags

Flag	Shorthand	Default	Description
`--cwd <path>`		Current directory	Working directory
`--json`		`false`	Output as JSON (both success and failure)
`--quiet`	`-q`	`false`	Suppress all output (including errors)
`--no-duplicate-targets`			Skip 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:

Schema Validation — Validates the manifest structure and required fields
File Existence — Ensures all referenced files exist in the source directory
Circular Dependencies — Detects circular dependencies between components
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

Error	Cause	Solution
Schema validation failed	Invalid manifest structure (`registry.jsonc` or `registry.json`)	Check error messages for specific schema violations
File not found	Referenced file missing from source	Ensure all files in manifest exist in `files/` directory
Circular dependency detected	Components depend on each other	Review component dependencies and remove cycles
Duplicate target paths	Multiple components write to same path	Update target paths to be unique

Getting Started

Profiles

CLI

Registries

Reference

Guides

Integrations

Enterprise

Security

Usage

Description

Arguments

Flags

Examples

Validate Registry in Current Directory

Validate from a Specific Directory

CI/CD Integration

Skip Duplicate Target Validation

JSON Output for Scripting

Quiet Mode

Output

Success

Validation Failure

Runtime / Tool Failure (JSON)

Validation Checks

Source Structure

Errors

See Also

​Usage

​Description

​Arguments

​Flags

​Examples

​Validate Registry in Current Directory

​Validate from a Specific Directory

​CI/CD Integration

​Skip Duplicate Target Validation

​JSON Output for Scripting

​Quiet Mode

​Output

​Success

​Validation Failure

​Runtime / Tool Failure (JSON)

​Validation Checks

​Source Structure

​Errors

​See Also

Usage

Description

Arguments

Flags

Examples

Validate Registry in Current Directory

Validate from a Specific Directory

CI/CD Integration

Skip Duplicate Target Validation

JSON Output for Scripting

Quiet Mode

Output

Success

Validation Failure

Runtime / Tool Failure (JSON)

Validation Checks

Source Structure

Errors

See Also