v0.1 — open source

Beautiful architecture diagrams from YAML

A CLI that renders flow diagrams, Gantt charts, timelines, and quadrant charts from simple YAML. Converts BPMN to YAML. 20+ curated themes. 600+ icons. Built for AI agents and humans alike.

Get Started View on GitHub

$npm install -g @agent-clis/diagrams

Cloud architecture diagram rendered with the cyberpunk theme

Same diagram. Different tool.

Mermaid

diagrams

Mermaid 34 lines

graph LR
    subgraph Edge
        Client["fa:fa-globe Client App"]
        CDN["fa:fa-bolt CloudFront"]
    end
    subgraph API Tier
        APIGW["fa:fa-door-open API Gateway"]
        Cognito["fa:fa-lock Cognito"]
        LambdaAPI["fa:fa-code Lambda API"]
    end
    subgraph Async Processing
        SQS["fa:fa-envelope SQS"]
        LambdaWorker["fa:fa-cogs Lambda Workers"]
        SNS["fa:fa-bell SNS"]
    end
    subgraph Storage
        DynamoDB["fa:fa-database DynamoDB"]
        S3["fa:fa-archive S3"]
    end
    subgraph Operations
        CloudWatch["fa:fa-chart-line CloudWatch"]
    end
    Client --> CDN
    CDN --> APIGW
    APIGW -.->|authz| Cognito
    APIGW --> LambdaAPI
    LambdaAPI --> DynamoDB
    LambdaAPI --> S3
    LambdaAPI -->|enqueue| SQS
    SQS --> LambdaWorker
    LambdaWorker -->|notify| SNS
    LambdaAPI -.-> CloudWatch
    LambdaWorker -.-> CloudWatch

D2 50 lines

direction: right
Edge: {
  Client: "Client App"
  CDN: "CloudFront"
}
API Tier: {
  APIGW: "API Gateway"
  Cognito: "Cognito"
  Lambda API: "Lambda API"
}
Async Processing: {
  SQS: "SQS"
  Lambda Worker: "Lambda Workers"
  SNS: "SNS"
}
Storage: {
  DynamoDB: "DynamoDB" {
    shape: cylinder
  }
  S3: "S3" {
    shape: stored_data
  }
}
Operations: {
  CloudWatch: "CloudWatch"
}
Edge.Client -> Edge.CDN
Edge.CDN -> API Tier.APIGW
API Tier.APIGW -> API Tier.Cognito: authz {
  style.stroke-dash: 3
}
API Tier.APIGW -> API Tier.Lambda API
API Tier.Lambda API -> Storage.DynamoDB
API Tier.Lambda API -> Storage.S3
API Tier.Lambda API -> Async Processing.SQS: enqueue
Async Processing.SQS -> Async Processing.Lambda Worker
Async Processing.Lambda Worker -> Async Processing.SNS: notify
API Tier.Lambda API -> Operations.CloudWatch {
  style.stroke-dash: 3
}
Async Processing.Lambda Worker -> Operations.CloudWatch {
  style.stroke-dash: 3
}

diagrams 108 lines

title: "Cloud Architecture"
direction: LR
nodes:
  - id: client
    label: "Client App"
    icon: "🌐"
  - id: cdn
    label: "CloudFront"
    icon: "aws:cloudfront"
    variant: icon
  - id: apigw
    label: "API Gateway"
    icon: "aws:api-gateway"
    variant: icon
  - id: cognito
    label: "Cognito"
    description: "Auth"
    icon: "aws:cognito"
    variant: icon
  - id: lambda_api
    label: "Lambda"
    description: "API Handlers"
    icon: "aws:lambda"
    variant: icon
  - id: lambda_worker
    label: "Lambda"
    description: "Workers"
    icon: "aws:lambda"
    variant: icon
  - id: dynamo
    label: "DynamoDB"
    icon: "aws:dynamodb"
    variant: icon
  - id: s3
    label: "S3"
    description: "Assets"
    icon: "aws:s3"
    variant: icon
  - id: sqs
    label: "SQS"
    icon: "aws:sqs"
    variant: icon
  - id: sns
    label: "SNS"
    description: "Alerts"
    icon: "aws:sns"
    variant: icon
  - id: cloudwatch
    label: "CloudWatch"
    icon: "aws:cloudwatch"
    variant: icon
groups:
  - id: edge
    label: "Edge"
    members: [client, cdn]
    direction: LR
  - id: api
    label: "API Tier"
    members: [apigw, cognito, lambda_api]
    direction: TB
  - id: async
    label: "Async Processing"
    members: [sqs, lambda_worker, sns]
    direction: TB
  - id: storage
    label: "Storage"
    members: [dynamo, s3]
    direction: TB
  - id: ops
    label: "Operations"
    members: [cloudwatch]
rows:
  - [edge, api, async, storage]
  - [ops]
edges:
  - from: client
    to: cdn
  - from: cdn
    to: apigw
  - from: apigw
    to: cognito
    style: dashed
    label: "authz"
  - from: apigw
    to: lambda_api
  - from: lambda_api
    to: dynamo
  - from: lambda_api
    to: s3
  - from: lambda_api
    to: sqs
    label: "enqueue"
  - from: sqs
    to: lambda_worker
  - from: lambda_worker
    to: sns
    label: "notify"
  - from: lambda_api
    to: cloudwatch
    style: dashed
  - from: lambda_worker
    to: cloudwatch
    style: dashed

The diagram format AI can actually write

Mermaid uses a custom DSL. D2 invented its own syntax. Both require LLMs to learn non-standard grammars — and they frequently get it wrong.

diagrams uses plain YAML. Every AI model already knows how to write valid YAML. That means your coding assistant, your CI pipeline, and your automation scripts can generate correct diagrams on the first attempt.

Built under the agent-clis umbrella — tools designed from the ground up for human-AI collaboration.

terminal

> "Generate an architecture diagram for a microservices deployment with API gateway, three services, a message queue, and a database"

AI assistant generates:

type: flow

title: Microservices Deployment

theme: nord

nodes:

- id: gateway

label: API Gateway

icon: aws-api-gateway

- id: auth

label: Auth Service

- id: users

label: User Service

- id: orders

label: Order Service

- id: queue

label: Message Queue

icon: rabbitmq

- id: db

label: PostgreSQL

icon: postgresql

edges:

- from: gateway → to: auth

- from: gateway → to: users

- from: gateway → to: orders

- from: orders → to: queue

- from: orders → to: db

$ diagrams render spec.yaml -o arch.svg --theme nord

✓ Rendered flow diagram → arch.svg (6 nodes, 5 edges)

Four diagram types, one simple format

Flow Diagrams

Flow

Nodes, edges, shapes, and colors with automatic layout

Gantt Charts

Gantt

Project timelines with tasks, milestones, and dependencies

Timeline Views

Timeline

Chronological events for roadmaps and changelogs

Quadrant Charts

Quadrant

2D grids for prioritization and competitive analysis

From YAML to the boardroom

YAML spec

diagrams render

SVG / PNG / PDF / PPTX

Every diagrams-as-code tool can output SVG. Only diagrams outputs directly to PowerPoint. Stop screenshotting your terminal and pasting into slides. One command, presentation-ready.

$ diagrams render architecture.yaml -o slides.pptx --theme nord

Import BPMN, render beautifully

Already have business process models? The convert command transforms BPMN XML files into diagrams-compliant YAML with smart icon defaults. Tasks, events, gateways, lanes, and flows are all mapped automatically.

BPMN XML

diagrams convert

YAML spec

diagrams render

SVG / PNG / PPTX

# Convert BPMN to YAML

$ diagrams convert process.bpmn -o process.yaml

# Or convert and render in one step

$ diagrams convert process.bpmn -r -f png -o process.png

# Straight to PowerPoint with a theme

$ diagrams convert process.bpmn -r -f pptx -t nord -o slides.pptx

20+ built-in themes

Switch the look of any diagram with a single flag. No CSS. No config files.

600+ icons across 6 libraries

Mix brand logos, cloud service icons, Geist design system icons, favicons, and emoji in the same diagram.

Geist Icons541

Clean, minimal icons from Vercel

icon: geist:database

Simple Icons100+

Brand and technology logos

icon: docker

AWS Iconsvaries

Amazon Web Services

icon: aws:lambda

GCP Iconsvaries

Google Cloud Platform

icon: gcp:cloud-run

Faviconsany

Auto-fetched from any domain

icon: favicon:github.com

Emojiany

Any emoji character

icon: 🚀

Browse all icon types

How `diagrams` compares

Feature	Mermaid	D2	diagrams
Input format	Custom DSL	Custom DSL	Standard YAML
Themes	Limited	Basic	20+ curated
Brand icons			600+
PPTX output
BPMN import
AI-friendly input	Fragile	Moderate	Native YAML
Visual quality	Basic	Good	Designed

Start rendering in 30 seconds

Install globally, write a YAML spec (or have your AI assistant write one), and render.

# 1. Install

npm install -g @agent-clis/diagrams

# 2. Write a spec (or have your AI assistant write one)

cat > pipeline.yaml << 'EOF'

type: flow

title: Deployment Pipeline

nodes:

- id: build

label: Build

- id: test

label: Test

- id: deploy

label: Deploy

edges:

- from: build

to: test

- from: test

to: deploy

EOF

# 3. Render

diagrams render pipeline.yaml -o pipeline.svg

Read the docs