@diagrams-js/cli

CLI for diagrams-js - render, import, export, diff, and manage architecture diagrams from the terminal.

Installation

Install globally with npm:

npm install -g @diagrams-js/cli

# then run `diagrams`
diagrams render diagram.ts

Alternatively, install locally in your project:

npm install @diagrams-js/cli

# then run `npx diagrams`
npx diagrams render diagram.ts

Or use directly with npx:

npx @diagrams-js/cli render diagram.ts

Usage

Render a diagram

# Render to SVG (default)
diagrams render diagram.ts

# Render to PNG
diagrams render diagram.ts -o diagram.png

# Render with theme and direction
diagrams render diagram.ts -f svg -t dark -d LR -o out.svg

# Render to JSON
diagrams render diagram.json -f json

Render from external formats (plugin import)

The render command automatically imports from .yaml/.yml files via plugins:

# Import Docker Compose and render to SVG
diagrams render docker-compose.yml -o architecture.svg

# Import Kubernetes manifest
diagrams render k8s-deployment.yaml -p kubernetes -o architecture.svg

# Import with custom options
diagrams render compose.yml -f png -t dark --width 1200 -o out.png

Export to external formats

# Export diagram to Docker Compose
diagrams export diagram.json -f docker-compose -o docker-compose.yml

# Export to Kubernetes
diagrams export diagram.ts -f kubernetes -o manifest.yaml

Diff diagrams in git

# Diff a single file against HEAD
diagrams diff show HEAD diagram.ts -o diff.html

# Diff between branches
diagrams diff show main...feature diagram.json -f html -o diff.html

# List changed diagram files
diagrams diff list HEAD

# Batch diff all changed files
diagrams diff batch main...feature -o ./diffs

Scaffold a new diagram

# Create a basic diagram
diagrams init "My Architecture"

# Create with AWS template
diagrams init "AWS Stack" -t aws -o aws.ts

# Create with Kubernetes template
diagrams init "K8s Cluster" -t k8s -o k8s.ts

Watch and auto-render

# Watch a diagram file and re-render on changes
diagrams watch diagram.ts -o out.svg

# Watch with custom options
diagrams watch diagram.ts -f png -t dark --scale 2 -o out.png

Manage plugins

# List installed plugins
diagrams plugins list

# Show plugin info
diagrams plugins info docker-compose

Configuration

Create a .diagramsrc.json file in your project root:

{
  "format": "svg",
  "theme": "light",
  "direction": "TB",
  "curveStyle": "ortho",
  "scale": 2,
  "diff": {
    "layout": "side-by-side",
    "showUnchanged": "show",
    "ignorePosition": true
  }
}

Supported File Formats

Input

| Extension | Description | | ---------------- | --------------------------------------------- | | .ts | TypeScript diagram file | | .js / .mjs | JavaScript diagram file | | .json | Diagram JSON export | | .svg | Diagram SVG with embedded metadata | | .yaml / .yml | Importable config (docker-compose, k8s, etc.) |

Output

| Format | Description | | ------ | -------------------------------------- | | svg | Scalable Vector Graphics (default) | | png | PNG image (requires sharp in Node.js) | | jpg | JPEG image (requires sharp in Node.js) | | dot | Graphviz DOT source | | json | Diagram JSON serialization | | html | Self-contained HTML diff |

License

MIT