SpecLynx CLI

Command line

Validate, overlay, and reshape your API specs — 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

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.0.0
  • ✓ Overlay 1.1.0

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 by default)
--strict Fail if action targets match zero nodes
--verbose Display detailed trace information

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 — fail if any action targets match nothing:

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

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 — perfect for tracking API evolution as discrete, reusable overlay files. 

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 (inferred from input by default)
--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

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 — 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 $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.

Arguments

Argument Description
<uri> Local path or URL 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)
-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

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 and diff Overlay 1.0.0 / 1.1.0 documents, and chain multiple overlays in a single command.

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.