nomnoml

Convert plain-text descriptions into nomnoml markup and (optionally) render it via CLI.

Primary reference: https://nomnoml.com

Quick start

Minimal diagram

[User]->[AuthService]
[AuthService]->[DB]

Typical class box

[Order|
  +id: UUID;
  +total: Money;
  |
  +addItem(item);
  +checkout();
]

Syntax essentials

Nodes (boxes)

• Basic: [A]
• With compartments (title | attributes | methods): [A|x; y|do();]
• Escape newlines with actual newlines (preferred) or \n when needed.

Relationships (common)

[A]->[B]        # association / dependency
[A]-->[B]       # dotted
[A]-:>[B]       # composition-like (varies by style)
[A]<-[B]        # reverse arrow
[A]-[B]         # line without arrow

If arrow semantics are ambiguous, prefer clear labels:

[API]->[DB]
[API] "reads/writes" -> [DB]

Cardinalities / labels

[Customer] 1->* [Order]
[Order] 1->* [OrderLine]

Grouping

[<frame> Payments|
  [API]
  [Worker]
]

[API]->[Worker]

Common containers:

• <frame>: big box grouping
• <package>: package-like grouping
• <actor>: actor stick figure

Styling / directives

Add directives at the top using #:

#direction: right
#spacing: 40
#ranker: tight-tree

[Client]->[API]

Common directives:

• #direction: right|down
• #spacing: <number>
• #padding: <number>
• #ranker: network-simplex|tight-tree|longest-path

Workflow: generate a diagram from a description

1. Identify the diagram type:

   • Class/data model → boxes with compartments + inheritance/associations
   • Architecture/services → frames/packages + arrows + labeled edges
   • Flow/steps → simple boxes + arrows; keep it readable

2. Choose names:

   • Use stable nouns for nodes (AuthService, TokenStore, Frontend).
   • Keep node names short; put details in compartments or labels.

3. Produce nomnoml code:

   • Start with #direction: right for architecture diagrams.
   • Use frames/packages to group by bounded context.
   • Add labels for anything non-obvious.

4. Iterate:

   • If diagram is too dense, split into multiple diagrams (by subsystem).

Rendering (tool)

If a rendered asset is needed, use the nomnoml tools instead of CLI.

Option A: quick preview

Use the tool to render directly in chat:

• nomnoml-display with inline source for a quick preview.

Option B: render to SVG

Use the tool to render and optionally write a file:

• nomnoml-render with inline source and optional outputFile.
• nomnoml-render-file with inputFile and optional outputFile.

If rendering isn’t required, still produce the .nomnoml source file so it can be rendered later.

Patterns

Architecture sketch (recommended default)

#direction: right

[<actor> User]->[WebApp]

[<frame> Backend|
  [API]
  [Worker]
]

[WebApp]->[API]
[Worker]->[DB]
[API]->[DB]

[DB]

Class diagram with inheritance

[<abstract> Animal|+name: string|+speak()]
[Dog|+breed: string|+speak()]
[Cat|+color: string|+speak()]

[Animal]<:-[Dog]
[Animal]<:-[Cat]

Entity relationship (simple)

#direction: down

[User|id; email]
[Session|id; userId; expiresAt]

[User] 1->* [Session]

When asked to “update an existing diagram”

• Preserve existing node names unless there’s a clear rename.
• Apply the smallest diff:
  • add one box/edge at a time
  • keep direction/ranker consistent
• If you change meaning, update edge labels to stay explicit.