@speclynx/cli

Overlay, dereference, bundle, convert, and validate your API specs — OpenAPI, AsyncAPI, Arazzo, Overlay, and JSON Schema in one consistent toolchain, from the command line.

Note: Currently the overlay and validate commands are implemented. More commands are coming soon.

@speclynx/cli is part of the SpecLynx ecosystem, built on top of ApiDOM and ApiDOM Language Service.

Table of contents

• Installation
• Getting help
• Commands
  • overlay apply
  • overlay diff
  • validate
• License

Installation

npm install -g @speclynx/cli

Or use directly with npx:

npx @speclynx/cli overlay apply overlay.json openapi.json

Getting help

speclynx --help                  # list all commands
speclynx overlay --help          # list overlay subcommands
speclynx overlay apply --help    # show overlay apply options
speclynx overlay diff --help     # show overlay diff options
speclynx validate --help         # show validate options

Commands

overlay apply

Apply Overlay 1.x documents to API definitions.

Supported Overlay versions:

• Overlay 1.0.0
• Overlay 1.1.0

The target can be any JSON or YAML document.

speclynx overlay apply [options] <overlay> [target]

Arguments:

| Argument | Description | |----------|-------------| | <overlay> | Path to the overlay document (JSON or YAML) | | [target] | Path to the target document; if omitted, uses the overlay extends field |

Options:

| Option | Description | |--------|-------------| | --overlay <path> | Additional overlay document to apply sequentially (repeatable) | | -o, --output <file> | Write result to file instead of stdout | | -f, --format <format> | Output format: json or yaml (auto-detected from target extension) | | --strict | Fail if any action target matches zero nodes | | --verbose | Print trace information about overlay application |

Examples

Apply an overlay to an OpenAPI document:

speclynx overlay apply overlay.json openapi.json

Apply an overlay that uses the extends field to reference the target:

speclynx overlay apply overlay.yaml

Write the result to a file:

speclynx overlay apply overlay.json openapi.json -o result.json

Force YAML output regardless of target extension:

speclynx overlay apply overlay.json openapi.json -f yaml

Apply multiple overlays sequentially:

speclynx overlay apply first.json openapi.json --overlay second.json --overlay third.json

Use strict mode to catch unmatched targets:

speclynx overlay apply overlay.json openapi.json --strict

Show detailed trace of each action:

speclynx overlay apply overlay.json openapi.json --verbose

Overlay: overlay.json -> openapi.json
  [ok] update $.info (1 matches)
  Overlay was successfully applied

{ ... }

overlay diff

Generate an Overlay 1.x document from the diff of two API documents. The produced overlay, when applied to <before>, yields <after>.

speclynx overlay diff [options] <before> <after>

Arguments:

| Argument | Description | |----------|-------------| | <before> | Path to the "before" API document (JSON or YAML) | | <after> | Path to the "after" API document (JSON or YAML) |

Options:

| Option | Description | |--------|-------------| | -o, --output <file> | Write result to file instead of stdout | | -f, --format <format> | Output format: json or yaml (auto-detected from <before> extension) | | --fail-on-empty | Exit with code 1 if the documents are identical |

Examples

Generate an overlay from two OpenAPI documents:

speclynx overlay diff openapi-v1.json openapi-v2.json

Write the generated overlay to a file:

speclynx overlay diff openapi-v1.yaml openapi-v2.yaml -o migration.yaml

Force JSON output regardless of input format:

speclynx overlay diff openapi-v1.yaml openapi-v2.yaml -f json

Fail when the two documents are identical (useful in CI):

speclynx overlay diff openapi-v1.json openapi-v2.json --fail-on-empty

validate

Validate and lint an API definition, powered by the ApiDOM Language Service. The document type and version are auto-detected from its content.

Supported specifications:

• OpenAPI 2.0 (Swagger), 3.0.x, 3.1.x
• AsyncAPI 2.x
• Arazzo 1.x
• Overlay 1.x

By default, validate runs three kinds of checks:

• Semantic validation — checks the document against the meaning of its specification, not just its JSON/YAML syntax: required fields are present, values have the correct types, and objects are shaped as the spec requires.
• Reference validation — checks that every local (#/...) $ref resolves to something that actually exists.
• Semantic linting — applies style and best-practice rules on top of validation (for example, flagging an empty enum).

JSON Schema (AJV) validation is an additional opt-in layer, enabled with --json-schema-validation. It validates the document against the official JSON Schema for its specification and covers OpenAPI 2/3.0/3.1, AsyncAPI 2.x, Arazzo, and Overlay.

speclynx validate [options] <uri>

Arguments:

| Argument | Description | |----------|-------------| | <uri> | Path or URL to the API document (JSON or YAML) — a local file path, a file:// URL, or an http(s):// URL |

Options:

| Option | Description | |--------|-------------| | -f, --format <format> | Output format for diagnostics: stylish (default) or json | | --json | Shorthand for --format json (wins if both are given) | | -o, --output <file> | Write diagnostics to file instead of stdout | | --json-schema-validation | Enable JSON Schema (AJV) validation (with friendlier error messages) | | --max-problems <n> | Maximum number of problems to report | | --fail-severity <severity> | Minimum diagnostic severity that fails the run: error (default), warning, info, or hint |

Diagnostics are written to stdout, or to a file with -o, --output (created or overwritten; the exit code is unchanged). The output path must differ from the input file — the command refuses to overwrite the document being validated. The default stylish formatter prints a color-coded, human-readable report — a file header, one aligned location severity code message row per problem, and a severity-count summary (colors are disabled automatically when the output is not a TTY, when writing to a file with -o, --output, or when NO_COLOR is set). --format json writes the raw diagnostics array for machine consumption. stderr is reserved for hard errors (e.g. a missing input file or an unwritable output path).

Exit codes (suitable for CI gating):

| Code | Meaning | |------|---------| | 0 | No diagnostic at or above --fail-severity. | | 1 | A diagnostic at or above --fail-severity was found (spec is invalid), or a hard error occurred (missing input, unresolvable $ref, unwritable or input-colliding -o path, internal failure). |

Hard errors report on stderr with an Error: prefix and write no diagnostics to stdout. So a non-zero exit with empty stdout means the run failed; a non-zero exit with diagnostics means the document is invalid.

Note: The code value of reference-validation diagnostics is not stable across runs, so consumers that snapshot or diff the --format json output should not rely on it for reference errors.

Examples

Validate an OpenAPI document:

speclynx validate openapi.json

Validate a document hosted at a URL:

speclynx validate https://example.com/openapi.yaml

Emit machine-readable diagnostics for further processing:

speclynx validate openapi.yaml --format json

Write a machine-readable report to a file:

speclynx validate openapi.yaml --format json -o report.json

Enable JSON Schema (AJV) validation on top of the default checks:

speclynx validate openapi.json --json-schema-validation

Treat lint warnings as failures in CI:

speclynx validate openapi.json --fail-severity warning

License

SpecLynx CLI is licensed under Apache 2.0 license. SpecLynx CLI comes with an explicit NOTICE file containing additional legal notices and information.