@umlay/cli

Command-line interface for the Umlay DSL. Parses .umlay files, runs the lint catalog, prints diagnostics with ERROR / WARNING / INFO severity, and optionally renders any view to SVG or PNG.

This release tracks Umlay spec 1.9.0, which builds on 1.6.x with:

• spec 1.7 (RFCs 0050–0052): first-class event declarations, @states(initial, final) field markers, @emits(EventName) on functions, plus lint rules L050–L056 enforcing state-machine / sequence / event integrity across views.
• spec 1.8 (RFC 0053): multiple named seq <name> { ... } blocks per @sequence_diagram view; lint L057 ensures uniqueness.
• spec 1.9 (RFC 0054): per-view @@style(key: value, ...) override for color tokens and Gantt layout knobs (row_height, day_width, label_width); lint L058 catches unknown keys / bad values.
• See umlay-oss/packages/spec/src/rfcs/ for the full RFC catalog (RFCs 0001–0054 inclusive).

Install

npm i -g @umlay/cli
# or
pnpm add -g @umlay/cli

PNG rendering is opt-in (keeps the bundle small):

npm i -g @resvg/resvg-js

Usage

umlay <command> <file> [options]
umlay <file>                          # alias for `umlay check <file>`

umlay check <file> — parse + lint

umlay check schema.umlay
umlay check schema.umlay --mode strict --quiet
umlay check schema.umlay --json > diagnostics.json

| Option | Default | Notes | | --- | --- | --- | | --mode <m> | draft | draft / beta / strict — promotes lint severity | | --quiet | off | only print errors | | --json | off | emit diagnostics as a single JSON array | | --stats | off | per-rule fire-count summary (suppresses individual rows) |

--stats for corpus monitoring

Combine --stats --json to feed a directory-wide aggregator and spot rules that never fire (retirement candidates) or fire on every file (default-on candidates):

for f in **/*.umlay; do
  umlay check "$f" --stats --json
done | jq -s '
  map(.byRule[]) |
  group_by(.code) |
  map({ code: .[0].code, total: (map(.count) | add) }) |
  sort_by(-.total)'

Exit code: 0 if no errors, 1 if any error.

Output:

umlay check  schema.umlay
  ERROR  schema.umlay:12:1 [S03] Unknown stereotype '@master'.
  WARN   schema.umlay:8:5 [L001] Attribute 'totaL' lacks explicit visibility
  INFO   schema.umlay:1:1 [W002] @experimental in use

1 error  1 warning  1 info

umlay render <file> — generate diagrams

umlay render schema.umlay                        # → schema.svg (first ER / class view)
umlay render schema.umlay --view shop-overview
umlay render schema.umlay --kind sequence_diagram --out flow.svg
umlay render schema.umlay --format png --out shop.png
umlay render schema.umlay --theme dark

| Option | Default | Notes | | --- | --- | --- | | --view <id> | first ER / class view | render this view-id | | --kind <k> | — | render the first view of this kind | | --out <path> | <input>.<ext> | output file | | --format <f> | svg | svg or png (PNG needs @resvg/resvg-js) | | --theme <t> | default | default / dark / light / high-contrast |

Supported view kinds: er_diagram, class_diagram, sequence_diagram, component_diagram, wbs_diagram, gantt_chart, state_machine, package_diagram, activity_diagram. (Composite views are rendered via their child views.)

umlay parse <file> — emit IR JSON

umlay parse schema.umlay > schema.ir.json

Useful for piping into other tools.

Exit codes

| Code | Meaning | | --- | --- | | 0 | success / no errors | | 1 | parse / lint error | | 2 | invalid arguments |

Color output

The CLI uses ANSI colors when stdout is a TTY. Set NO_COLOR=1 or pipe to disable.

License

Apache-2.0