Quick start: CLI
1. Install
You don't need to install anything up front — npx fetches it on demand. If you'd rather install it:
npm install --save-dev openapi-merge-cli
# or: bun add -d openapi-merge-cli2. Generate a starting configuration
Run init in a directory containing your OpenAPI files:
npx openapi-merge-cli initinit scans the current directory (not recursively) for .json/.yaml/.yml files that declare a top-level openapi: 3.x, and writes openapi-merge.yaml pre-filled with what it found — plus every other optional setting this tool supports, included and commented out, each with a one-line explanation. See CLI reference → Getting started for the full behaviour.
3. Edit the configuration
Open openapi-merge.yaml. At minimum you need inputs (one entry per file to merge) and output. A typical gateway-style configuration looks like:
inputs:
- inputFile: ./gateway.swagger.json
- inputFile: ./jira.swagger.json
pathModification:
stripStart: /rest
prepend: /jira
operationSelection:
includeTags: [included]
- inputFile: ./confluence.swagger.yaml
dispute:
prefix: Confluence
pathModification:
prepend: /confluence
output: ./output.swagger.jsonThe full field-by-field reference is in CLI reference → Configuration.
4. Run the merge
npx openapi-merge-cliThis reads openapi-merge.yaml (or openapi-merge.json, for older configurations) from the current directory and writes the merged document to the configured output path. Point at a specific file instead with:
npx openapi-merge-cli --config path/to/openapi-merge.yaml5. Check the exit code in CI
The CLI's exit codes are part of its contract — see CLI reference → Exit codes for the full table and which failures are worth retrying.
openapi-merge-cli
case $? in
0) echo "merged" ;;
7) echo "upstream is down, retrying later"; exit 75 ;;
*) echo "merge failed permanently"; exit 1 ;;
esac