SpecLynx CLI

CLI Tool

Messy API specs? Bring order from the command line.

SpecLynx CLI is a command-line tool for working with API specifications. Apply Overlay documents to any JSON or YAML API definition from the terminal or CI/CD pipeline.

Install globally via npm:

npm install -g @speclynx/cli

Or run directly with npx:

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

Early release: SpecLynx CLI currently ships the overlay apply command. More commands — validate, 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

Features

Overlay Application

Apply Overlay 1.0.0 and 1.1.0 documents to any JSON or YAML API definition.

Multiple Overlay Chaining

Apply multiple overlays in sequence with a single command using the repeatable --overlay option.

Format Auto-Detection

Automatically detects JSON or YAML format from input files. Override with -f when needed.

Strict Validation Mode

Catch overlay misconfigurations early — strict mode fails if any action target matches zero nodes.

File Output

Write results directly to a file or pipe stdout into your existing toolchain.

Verbose Tracing

Detailed trace output for debugging overlay application and understanding what changed.

Roadmap

☑ Overlay apply  ·  ☐ 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?

Currently, SpecLynx CLI can apply Overlay 1.x documents to any JSON or YAML API definition. Validate, dereference, bundle, and convert commands are on the roadmap.

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.