CLI Reference

The CLI is the most direct way to use kUML — render, generate, validate, simulate, export, parse. Every subcommand prints its own help with --help.

Synopsis

kuml <subcommand> [options] <script>...

Common options on every subcommand:

  • --config <path> — load a kuml.config.kts file

  • --verbose / -v — enable debug output

  • --version — print version and exit

  • --help / -h — print subcommand help

kuml render

Render a script to SVG or PNG.

kuml render [options] <script>...

Options:

  • --output <path> — output file (or directory if multiple scripts)

  • --format svg|png — default svg

  • --theme <name> — theme name (e.g. plain, kuml, elegant, playful)

  • --engine <id> — layout engine ID (e.g. elk.layered, kuml.grid)

  • --layout grid|elk|auto — shorthand layout selector added in V2.0.26; auto lets kUML choose based on diagram type. Equivalent to --engine kuml.grid, --engine elk.layered, or engine auto-detection respectively.

  • --width <pixels> — PNG width (height is derived from aspect ratio)

  • --latex-standalone — wrap the SVG output in a \begin{figure}…​\end{figure} block suitable for direct inclusion in LaTeX documents (added in V2.0.31).

If the script contains a umlModel { …​ } with multiple diagrams, each diagram renders to its own file using the diagram name as the file stem.

kuml generate

Generate code from a script using a registered code generator.

kuml generate [options] <script>

Options:

  • --output <dir> — output directory (created if missing)

  • --plugin <name> — generator name (kotlin, java, sql, or custom)

  • --package <fqn> — target package (Java/Kotlin)

  • --options key=value,key=value — generator-specific options

Examples:

kuml generate model.kuml.kts --plugin java --package com.example --options java-style=records
kuml generate model.kuml.kts --plugin sql --options dialect=mysql,sql-drop=true

kuml validate

Validate expressions and structure. Exits non-zero on any violation.

kuml validate [options] <script>...

Options:

  • --strict — also evaluate profile-level stereotype constraints (default: only element-level constraints)

  • --no-check-structure — skip structural checks (duplicate IDs, circular inheritance); OCL only

  • --json — emit violations as a JSON array to stdout instead of human-readable text

Output is structured: every violation prints constraint name, host classifier, OCL body, and a short failure message. Exit code 3 on violations, 0 on clean. Suitable as a CI step.

See Validation Reference for full flag details, exit codes, and a GitHub Actions integration example.

kuml simulate

Run a state-machine simulation. See the simulate reference for the full event/trace format.

kuml simulate [options] <script>

Options:

  • --events <path> — JSON file with event array

  • --interactive — REPL mode (no --events)

  • --output <path> — write the trace to a file (otherwise stdout)

  • --expected <path> — diff trace against an expected file; exit code 6 on mismatch

  • --epoch-clock — replace wall-clock timestamps with monotonic epoch ms from 0

  • --machine <name> — pick a machine by name when the script contains multiple

kuml transform

Model-to-model (M2M) code generation. Applies a named transformer to a kUML source script and writes the result to a file.

kuml transform [options] <script>

Options:

  • --transformer <name> — transformer ID (e.g. uml-to-sysml2-requirements, uml-to-openapi)

  • --list-transformers — list all registered transformers and exit (no script required)

  • --output <path> — output file path; if omitted, writes to stdout

Examples:

kuml transform --list-transformers
kuml transform domain.kuml.kts --transformer uml-to-sysml2-requirements \
    --output sysml2-req.kuml.kts

SysML 2 transformer targets are supported as of V2.x. See SysML 2 DSL Reference.

kuml version

Print kUML version information.

kuml version [--json]

Options:

  • --json — emit version info as a JSON object ({ "version": "…​", "buildDate": "…​", "commit": "…​" })

Without flags, prints the same human-readable version string as kuml --version. Useful in CI to record the exact kUML version used for a build artefact.

kuml export

Export a kUML model to an external format.

kuml export [options] <script>

Options:

  • --format <name> — currently structurizr (more formats in V2)

  • --output <path> — output file

kuml parse

Read an external format back into a kUML script.

kuml parse [options] <input>

Options:

  • --format <name> — structurizr

  • --output <path> — output *.kuml.kts file

kuml profile

Inspect registered profiles. Useful for debugging stereotype-driven codegen.

kuml profile list
kuml profile show JavaEE
kuml profile validate JavaEE       # self-check: every stereotype constraint is parseable

kuml reverse

Reverse-engineer Java or Kotlin source code into a *.kuml.kts script. Discovers reverse engines via ServiceLoader from kuml-codegen-reverse-java (V3.0.7) and kuml-codegen-reverse-kotlin (V3.0.8).

kuml reverse --list-engines                                # list registered engines
kuml reverse src/main/java   --lang java   --output domain.kuml.kts
kuml reverse src/main/kotlin --lang kotlin --output domain.kuml.kts
kuml reverse src/main/java   --lang auto                   # majority-vote on file extensions
kuml reverse src/main/kotlin --verbose-diagnostics         # print every INFO/WARN on stderr

Options:

  • --lang java|kotlin|auto — source language. Default: auto (file-extension majority, ≥ 60 % share required).

  • --output <file> — write the generated *.kuml.kts here; defaults to stdout.

  • --include "<glob>" (repeatable) — file include patterns. Defaults: **/*.java / **/*.kt per --lang.

  • --exclude "<glob>" (repeatable) — file exclude patterns.

  • --model-name <name> — name of the generated model (default ReverseEngineered).

  • --list-engines — print available reverse engines (id + description) and exit.

  • --verbose-diagnostics — print every WARN/INFO diagnostic on stderr (default: one-line summary).

The Kotlin engine is JVM-only (it bundles kotlin-compiler-embeddable), so the reverse subcommand is available in the Fat-JAR / installDist / distTar / runtimeZip distributions but excluded from the GraalVM Native Image build.

Diagnostic codes are grouped per engine:

  • REV-CORE-NNN — engine-agnostic

  • REV-J-NNN — Java engine

  • REV-K-NNN — Kotlin engine

See the kuml-codegen-reverse-api README for the full table.

kuml ai

Hook for LLM-assisted workflows. Currently exposes the MCP server stdio frontend:

kuml ai mcp-stdio                   # speak MCP over stdio

The MCP server exposes tools for diagram introspection, validation, and code generation — agents can query a kUML model the same way they query a database. See the source for the full tool list.

Exit codes

Code Meaning

0

Success.

1

Script error (compilation, missing imports).

2

User error (bad argument, file not found).

3

Validation error (OCL constraint violated).

4

Generation error (code generator threw).

5

Layout error (engine failed to produce a result).

6

Trace diff (simulate --expected mismatch).

14

kuml reverse --lang <id> referenced an unknown engine.

15

kuml reverse engine returned ERROR-level diagnostics.

16

kuml reverse found no source files in the given directory.

These codes are stable — CI scripts can branch on them.

Performance notes

The CLI compiles each script once and caches the result in the Kotlin scripting host. The first invocation is slow (cold JVM, JIT warmup, ELK initialisation) — typically 2-4 seconds. Subsequent invocations within the same JVM (use kuml shell if needed) are sub-second.

For build pipelines that render dozens of diagrams, the Gradle plugin’s kumlRender task is much faster: it reuses the Gradle daemon’s warm JVM and Gradle’s incremental input checks skip unchanged files entirely.