Getting started

Install

puml ships as a single static Rust binary. The fastest path today is cargo install from source:

cargo install --git https://github.com/alliecatowo/puml --bin puml

That gives you the puml CLI on your $PATH. There is also a separate language-server binary, puml-lsp, used by the VS Code extension.

No JVM, no Graphviz, no runtime services. The browser editor on this site doesn’t need any of them either — everything runs locally.

Your first diagram

Create a file hello.puml:

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi there
@enduml

Render it:

puml hello.puml
# wrote hello.svg

Open hello.svg in any browser or image viewer. You can also pipe through stdin and stream the result:

cat hello.puml | puml - > hello.svg

Or render PNG (rasterized from the canonical SVG):

puml --format png --dpi 192 hello.puml -o hello@2x.png

Validate without rendering

The --check mode parses and normalizes without emitting SVG. Use it as a CI lint:

puml --check hello.puml
echo $?         # 0 if valid, 1 if validation failed

Add --diagnostics json for machine-readable output, perfect for editor integrations and bots.

Try it in the browser

You can skip the install entirely and use the studio editor on this site. It loads CodeMirror with .puml syntax highlighting and renders diagrams live in your browser via the puml WASM bundle — see In-browser renderer for how that bridge works.

Wire it into your editor

VS Code

A first-party extension lives in extensions/vscode/ in the repo. It speaks to the puml-lsp binary for diagnostics, hover, and semantic tokens. See the VS Code extension spec for the contract.

Anything with LSP support

Run puml-lsp over stdio and point your editor at it. The LSP spec documents capabilities, message shapes, and semantic-token taxonomy.

Markdown documents

If your docs are full of fenced code blocks, you can render them directly:

puml --from-markdown --check docs/sequence-notes.md

See Markdown fences for the full set of supported fence languages.

Next