SpecLynx CLI

Command line

Validate, overlay, and reshape your API specs with one consistent toolchain, from the command line.

SpecLynx CLI is a command-line tool for working with API specifications. Validate OpenAPI, AsyncAPI, Arazzo, and Overlay documents, and apply or diff Overlay documents, all from your terminal or CI/CD pipeline.

Install globally via npm:

npm install -g @speclynx/cli

Or run directly with npx:

npx @speclynx/cli validate openapi.json
View on npm View on GitHub

Early release: SpecLynx CLI currently ships the overlay apply, overlay diff, and validate commands. More commands (dereference, bundle, and convert) are coming soon.

Installation

Global Install

Install globally to use the speclynx command anywhere:

npm install -g @speclynx/cli

Run Without Installing

Use npx to run without a global install:

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

Verify Installation

speclynx --help

Every command and subcommand has its own help:

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. Supports any JSON or YAML document as a target. 

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

Supported Overlay versions:

Overlay 1.2.0 Reusable Action References ($ref: '#/components/actions/<name>') are resolved before the actions are applied. Only references within the same overlay document are supported.

Arguments

Argument Description
<overlay> Path to overlay document (JSON or YAML)
[target] Path to target document. Optional if the overlay contains an extends field

Options

Option Description
--overlay <path> Apply additional overlays sequentially (repeatable)
-o, --output <file> Write output to a file instead of stdout
-f, --format <format> Output format: json or yaml (auto-detected from the target's file extension)
--strict Fail if action targets match zero nodes
--verbose Print a trace of each applied action to stderr

Usage Examples

Apply an overlay to an OpenAPI document:

speclynx overlay apply overlay.json openapi.json

Use the overlay's extends field to resolve the target:

speclynx overlay apply overlay.yaml

Write result to a file:

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

Force YAML output:

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

Chain multiple overlays:

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

Strict mode, to fail if any action targets match nothing:

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

Show a trace of each action and how many nodes it matched (written to stderr, so stdout stays a clean document):

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 by comparing two API specifications. The produced overlay, when applied to the before document, transforms it into the after document. That makes it perfect for tracking API evolution as discrete, reusable overlay files. The generated document declares Overlay 1.2.0 by default; use --overlay-version to target an older version. 

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

Arguments

Argument Description
<before> Path to the initial API document (JSON or YAML)
<after> Path to the modified API document (JSON or YAML)

Options

Option Description
-o, --output <file> Write the generated overlay to a file instead of stdout
-f, --format <format> Output format: json or yaml (auto-detected from the <before> file extension)
--overlay-version <version> Overlay version of the generated document: 1.1.0 or 1.2.0 (default: 1.2.0). Overlay 1.0.0 is not supported, because the generated actions rely on 1.1.0 semantics (updating primitive values, concatenating arrays)
--fail-on-empty Exit with code 1 when both documents are identical (useful for CI)

Usage Examples

Diff two OpenAPI documents:

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

Save the generated overlay to a file:

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

Force a specific output format:

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

Generate an Overlay 1.1.0 document for tools that don't support 1.2.0 yet:

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

Fail the build when two specs are identical:

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

validate

Validate an API document, from a local file or a remote URL, against its specification. SpecLynx CLI auto-detects the document type and reports problems as color-coded, human-readable diagnostics, or as a machine-readable JSON array for CI/CD. 

speclynx validate [options] <uri>

Problems are reported as a color-coded location  severity  code  message table, ending with a severity-count summary:

Supported specifications:

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

What Gets Checked

Three categories of checks run against every document:

  • 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, such as 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.0, 3.0, and 3.1, AsyncAPI 2.x, Arazzo, and Overlay.

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

Output

  • Diagnostics go to stdout, or to a file with -o, --output. The file is created or overwritten, and the exit code is the same either way.
  • The output path must differ from the input file: the command refuses to overwrite the document being validated.
  • The default stylish report is color-coded. Colors are turned off automatically when stdout is not a terminal or when writing to a file with -o, and when NO_COLOR or NODE_DISABLE_COLORS is set. As in Node.js, FORCE_COLOR overrides both: FORCE_COLOR=1 forces colors, FORCE_COLOR=0 turns them off.
  • --format json writes the raw diagnostics array for machine consumption.
  • stderr is reserved for hard errors, such as a missing input file or an unwritable output path.

Note: the code value of reference-validation diagnostics is not stable across runs. If you snapshot or diff the --format json output, don't rely on it for reference errors.

Usage Examples

Validate a local OpenAPI document:

speclynx validate openapi.json

Validate a document straight from a URL:

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

Emit machine-readable JSON diagnostics:

speclynx validate openapi.yaml --format json

Write JSON diagnostics to a file for CI to archive:

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

Also validate against the official JSON Schema:

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

Fail the build on warnings as well as errors:

speclynx validate openapi.json --fail-severity warning

Exit Codes

The validate command uses exit codes suited to CI gating:

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

Hard errors are reported on stderr with an Error: prefix and write no diagnostics to stdout. So, without -o, a non-zero exit with empty stdout means the run failed, while a non-zero exit with diagnostics means the document is invalid.

Features

Multi-Spec Validation

Validate OpenAPI, AsyncAPI, Arazzo, and Overlay documents with layered semantic, $ref, and best-practice checks.

Overlay Tooling

Apply Overlay 1.0.0 / 1.1.0 / 1.2.0 documents, chain multiple overlays in a single command, and generate Overlay 1.1.0 / 1.2.0 documents from a diff.

Local or Remote, JSON or YAML

Auto-detects format and reads from a local file or a URL. Write results to a file or pipe stdout into your toolchain.

Built for CI/CD

Strict modes, severity gates, and machine-readable JSON output let you fail a build on exactly the problems that matter.

Roadmap

☑ Overlay apply  ·  ☑ Overlay diff  ·  ☑ Validate  ·  ☐ Dereference  ·  ☐ Bundle  ·  ☐ Convert

Built With

ApiDOM

The foundation that the CLI is built upon. Provides parsing, data model, and traversal capabilities.

Explore ApiDOM

Language Service

LSP-compatible library providing the validation and intelligence layer used by the CLI.

Explore Language Service

Frequently Asked Questions

Is SpecLynx CLI free?

Yes. SpecLynx CLI is free, open-source, and licensed under Apache 2.0. Install it from npm at no cost.

What can SpecLynx CLI do?

SpecLynx CLI ships three commands today: validate checks OpenAPI, AsyncAPI, Arazzo, and Overlay documents against their specification; overlay apply applies Overlay 1.x documents to any JSON or YAML API definition; and overlay diff generates an overlay by comparing two specs. Dereference, bundle, and convert are on the roadmap.

Which specifications can it validate?

The validate command supports OpenAPI 2.0 (Swagger), 3.0.x, and 3.1.x; AsyncAPI 2.x; Arazzo 1.x; and Overlay 1.x. It accepts a local file or a remote URL, runs semantic validation, $ref resolution checks, and best-practice linting, and can optionally validate documents against their official JSON Schema.

What is an Overlay document?

An Overlay is a specification defined by the OpenAPI Initiative that describes modifications to an existing API definition. It lets you apply targeted changes, like adding descriptions, updating metadata, or injecting security schemes, without editing the original file.

How does SpecLynx CLI relate to the other SpecLynx tools?

SpecLynx CLI is built on the same foundation as the rest of the ecosystem: ApiDOM and the Language Service. The Editor and OpenAPI Toolkit are visual tools; the CLI brings the same capabilities to your terminal and CI/CD pipelines.