omg-md-cli

Command-line interface for OMG (OpenAPI Markdown Grammar).

Installation

``bash
npm install -g omg-md-cli
`

Or use via npx:

`bash
npx omg-md-cli build api.omg.md -o openapi.yaml
`

Commands

$3

Initialize a new OMG project with example files.

`bash
omg init my-api/
`

Creates:
- api.omg.md - API root definition
- endpoints/health.omg.md - Example endpoint
- partials/responses/errors.omg.md - Standard errors

$3

Compile OMG to OpenAPI.

`bash


Output to file

omg build api.omg.md -o openapi.yaml

Output to stdout

omg build api.omg.md

Watch mode

omg build api.omg.md -o openapi.yaml --watch

JSON output

omg build api.omg.md -o openapi.json
`

Options:
- -o, --output - Output file
- -f, --format - Output format: yaml or json
- -w, --watch - Watch for changes

$3

Parse an OMG file and show the AST (for debugging).

`bash
omg parse endpoints/get-user.omg.md
omg parse endpoints/get-user.omg.md --json
`

$3

Validate OMG files using Spectral-style rules.

`bash


Lint a directory

omg lint my-api/

Lint a single file

omg lint endpoints/get-user.omg.md

Custom config

omg lint my-api/ -c .spectral-omg.yaml

JSON output

omg lint my-api/ --json

Only errors

omg lint my-api/ -s error
`

Options:
- -c, --config - Config file path
- -s, --severity - Minimum severity: error, warn, hint
- -r, --rules - Comma-separated rules to run
- --json - Output as JSON
- -q, --quiet - Only output on error

$3

Format OMG files.

`bash


Preview changes

omg fmt my-api/

Write changes

omg fmt my-api/ --write

Check formatting (for CI)

omg fmt my-api/ --check
`

Options:
- -w, --write - Write formatted output
- --check - Exit 1 if files need formatting
- --indent - Indentation size (default: 2)

$3

Import an OpenAPI specification to OMG format.

`bash
omg import openapi.yaml -o my-api/
omg import openapi.json -o my-api/ --dry-run
`

Options:
- -o, --output - Output directory
- --inline - Inline schemas instead of references
- --dry-run - Show what would be generated
- --no-partials - Disable partial extraction
- --partial-threshold - Min occurrences for partial (default: 3)

$3

Compare two OMG API specifications.

`bash
omg diff v1/api.omg.md v2/api.omg.md
omg diff v1/api.omg.md v2/api.omg.md --format json
`

Requires: oasdiff

$3

Detect breaking changes between API versions.

`bash
omg breaking v1/api.omg.md v2/api.omg.md
omg breaking v1/api.omg.md v2/api.omg.md --fail-on-diff
`

Options:
- --fail-on-diff - Exit 1 if breaking changes found (for CI)

Requires: oasdiff

$3

Generate a changelog between API versions.

`bash
omg changelog v1/api.omg.md v2/api.omg.md
omg changelog v1/api.omg.md v2/api.omg.md -o CHANGELOG.html --format html
`

Requires: oasdiff

Exit Codes

- 0 - Success
- 1` - Error (parse failure, lint errors, breaking changes)

License

MIT