@speclynx/cli

Messy API specs? Bring order from the command line — overlay, dereference, bundle, convert, and validate.

Note: Currently only the overlay command is implemented. More commands are coming soon.

Documentation | npm | Issues

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

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

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

License

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