> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ocx validate

> Reference for the ocx validate command — validate a registry source without building

## Usage

```bash theme={null}
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

```bash theme={null}
ocx validate
```

### Validate from a Specific Directory

```bash theme={null}
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:

```bash theme={null}
ocx validate
if [ $? -ne 0 ]; then
  echo "Validation failed"
  exit 1
fi
```

### Skip Duplicate Target Validation

```bash theme={null}
ocx validate --no-duplicate-targets
```

### JSON Output for Scripting

```bash theme={null}
ocx validate --json
```

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

### Quiet Mode

```bash theme={null}
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

```bash theme={null}
$ 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**:

```bash theme={null}
$ 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**:

```bash theme={null}
$ 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:

```bash theme={null}
$ 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

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

## See Also

* [ocx build](/docs/cli/build) — Build a registry from source (includes validation).
* [Creating Registries](/docs/registries/create) — Full guide for registry authors.
* [Registry Protocol](/docs/registries/protocol) — Technical specification for registry HTTP APIs.
* [CLI Reference](/docs/cli/commands) — All commands.