Skip to main content

Fmt

Format OMG files for consistent style.

Usage​

omg fmt <path> [options]

Arguments​

ArgumentDescription
pathFile or directory to format

Options​

OptionDescription
-w, --writeWrite formatted output back to file(s)
--checkCheck if files are formatted (exit 1 if not)
--indent <size>Indentation size (default: 2)

Examples​

Preview formatting​

omg fmt my-api/

Outputs the formatted content to stdout without modifying files.

Format files in place​

omg fmt my-api/ --write

Check formatting in CI​

omg fmt my-api/ --check

Returns exit code 1 if any files need formatting.

Format a single file​

omg fmt my-api/endpoints/get-user.omg.md -w

Custom indentation​

omg fmt my-api/ -w --indent 4

What gets formatted​

The formatter normalizes:

  • YAML frontmatter: Consistent key ordering and formatting
  • OMG schema blocks: Consistent indentation and line breaks
  • JSON example blocks: Pretty-printed with consistent indentation
  • Empty response blocks: A // no response body comment is inserted so a bodyless response doesn't read as a mistake (compiled output is unchanged)

Markdown prose and other code blocks are preserved as-is.

Frontmatter key order​

Frontmatter keys are sorted in this order:

  1. method
  2. path
  3. operationId
  4. tags
  5. summary
  6. deprecated
  7. auth
  8. follows
  9. webhooks
  10. Other keys (alphabetically)

Exit codes​

CodeDescription
0All files formatted (or already formatted with --check)
1Files need formatting (with --check) or error occurred

CI integration​

Add to your CI pipeline to enforce consistent formatting:

- name: Check formatting
  run: npx omg-md-cli fmt . --check