Messy API specs? Bring order from the command line — overlay, dereference, bundle, convert, and validate.
Note: Currently the
overlayandvalidatecommands are implemented. More commands are coming soon.
@speclynx/cli is part of the SpecLynx ecosystem, built on top of ApiDOM and ApiDOM Language Service.
npm install -g @speclynx/cliOr use directly with npx:
npx @speclynx/cli overlay apply overlay.json openapi.jsonspeclynx --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 optionsApply Overlay 1.x documents to API definitions.
Supported Overlay versions:
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 |
Apply an overlay to an OpenAPI document:
speclynx overlay apply overlay.json openapi.jsonApply an overlay that uses the extends field to reference the target:
speclynx overlay apply overlay.yamlWrite the result to a file:
speclynx overlay apply overlay.json openapi.json -o result.jsonForce YAML output regardless of target extension:
speclynx overlay apply overlay.json openapi.json -f yamlApply multiple overlays sequentially:
speclynx overlay apply first.json openapi.json --overlay second.json --overlay third.jsonUse strict mode to catch unmatched targets:
speclynx overlay apply overlay.json openapi.json --strictShow detailed trace of each action:
speclynx overlay apply overlay.json openapi.json --verboseOverlay: overlay.json -> openapi.json
[ok] update $.info (1 matches)
Overlay was successfully applied
{ ... }
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 |
Generate an overlay from two OpenAPI documents:
speclynx overlay diff openapi-v1.json openapi-v2.jsonWrite the generated overlay to a file:
speclynx overlay diff openapi-v1.yaml openapi-v2.yaml -o migration.yamlForce JSON output regardless of input format:
speclynx overlay diff openapi-v1.yaml openapi-v2.yaml -f jsonFail when the two documents are identical (useful in CI):
speclynx overlay diff openapi-v1.json openapi-v2.json --fail-on-emptyValidate 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
$refresolves 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] <file>
Arguments:
| Argument | Description |
|---|---|
<file> |
Path to the API document (JSON or YAML) |
Options:
| Option | Description |
|---|---|
-f, --format <format> |
Output format for diagnostics: stylish (default) or json |
--json |
Shorthand for --format json (wins if both are given) |
--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. 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, 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 file). The command exits with code 1 when a diagnostic at or above --fail-severity is found, and 0 otherwise — suitable for CI gating.
Note: The
codevalue of reference-validation diagnostics is not stable across runs, so consumers that snapshot or diff the--format jsonoutput should not rely on it for reference errors.
Validate an OpenAPI document:
speclynx validate openapi.jsonEmit machine-readable diagnostics for further processing:
speclynx validate openapi.yaml --format jsonEnable JSON Schema (AJV) validation on top of the default checks:
speclynx validate openapi.json --json-schema-validationTreat lint warnings as failures in CI:
speclynx validate openapi.json --fail-severity warningSpecLynx CLI is licensed under Apache 2.0 license. SpecLynx CLI comes with an explicit NOTICE file containing additional legal notices and information.