Getting Started

Installation

Install diagrams globally via npm:

npm install -g @agent-clis/diagrams

Or use npx to run without installing:

npx @agent-clis/diagrams render spec.yaml

Your First Diagram

Create a file called spec.yaml:

type: flow
title: My First Diagram
nodes:
  - id: start
    label: Start
  - id: process
    label: Process
  - id: end
    label: End
edges:
  - from: start
    to: process
  - from: process
    to: end

Render it:

diagrams render spec.yaml -o my-diagram.svg

CLI Options

Flag	Description	Default
-o, --output	Output file path	diagram.svg
-t, --theme	Theme name	default
-f, --format	Output format (svg, png, pdf, pptx)	svg
--width	Image width in pixels	800
--height	Image height in pixels	600
--list-themes	List all available themes	—
--list-icons	List all available icons	—

Output Formats

diagrams supports four output formats:

• SVG — Scalable vector graphics, ideal for web and docs
• PNG — Raster image, good for presentations and chat
• PDF — Print-ready vector output
• PPTX — PowerPoint slides with editable shapes

Diagram Types

Type	Description
flow	Directed graph with nodes and edges
gantt	Project timeline with tasks and milestones
timeline	Chronological event display
quadrant	2D grid with labeled axes

Commands

diagrams has two main commands:

render — Render a YAML spec

diagrams render spec.yaml -o output.svg --theme nord

convert — Convert BPMN to YAML

Convert existing BPMN 2.0 XML files into diagrams-compliant YAML, optionally rendering in one step:

# Convert to YAML
diagrams convert process.bpmn -o process.yaml

# Convert and render directly
diagrams convert process.bpmn -r -f png -o process.png

See the BPMN Conversion page for full details.