Generate Mermaid from Plain English with AI (CLI Walkthrough)

TL;DR You already know flowchart TD cold. You don't know sequenceDiagram participant aliases, erDiagram cardinality glyphs, or which state diagram dialect Mermaid is on this year. This post is a walkthrough of five prompts → five diagrams using bd ai generate, plus when the AI-first path is wrong.

Disclosure: I work on a small web editor and CLI that's mentioned in the second half. The first half — the prompting workflow and the five diagram types — works with any AI that produces Mermaid; the tool just packages the pipeline.

The friction isn't drawing — it's remembering

I've shipped probably 200 flowcharts. I can sketch a flowchart TD with arrows and labels without thinking. The syntax has lived in my hands long enough that it's muscle memory.

Then someone asks for a sequence diagram of the OAuth flow, and I open the Mermaid docs. Again. For the seventh time this year.

That's the actual friction with diagrams-as-code: most teams write one diagram type 90% of the time and four other types maybe twice a year each. The rare types never make it into your fingers — you re-read the docs every time, hit a syntax snag, and lose ten minutes. Multiply by every infrequent diagram across a docs repo and that's a real tax.

AI removes the activation energy. You describe the diagram in plain English, get back syntactically valid Mermaid, and skip straight to "does this say what I want." That's a different kind of editing — refining a draft instead of looking up glyphs.

The path this post walks: prompt → AI → Mermaid → rendered diagram.

The shape of the workflow

Two paths, same engine underneath:

1. In an editor — paste your prompt into an AI panel that writes Mermaid for you, tweak the source, pick a theme, export.

2. In the terminal — bd ai generate "<prompt>" prints the Mermaid to stdout. Pipe it into a renderer, redirect to a file, or paste into your README.

The editor path is the right entry point if you're iterating — you can see the rendered diagram live as you refine the source. The CLI is the right surface once you know what you want and you're scripting it into a docs build, a package.json task, or a CI job.

The five examples below all use the CLI form so the prompts and outputs are easy to copy.

Prompt 1 — OAuth login (sequence diagram)

Sequence diagrams are the textbook case for "I know what I want, I don't remember the syntax." Participants, arrows, dotted return lines, loop blocks — there's just enough surface to forget between uses.

bd ai generate "user signs in with Google OAuth: web app redirects \
to Google's authorize endpoint, user approves, Google returns an \
authorization code, web app exchanges the code at our API for a \
session token"

The AI returns something like:

sequenceDiagram
  participant U as User
  participant W as Web App
  participant G as Google OAuth
  participant A as App API
  U->>W: Click "Sign in with Google"
  W->>G: Redirect to /authorize
  G->>U: Consent prompt
  U->>G: Approve scopes
  G->>W: Authorization code
  W->>A: Exchange code
  A->>W: Session token
  W->>U: Logged in

Render it:

OAuth authorization-code flow, generated from the prompt above and rendered with the atlas theme.

The participants are aliased (U as User, W as Web App) without me having to remember the syntax. The arrows pick ->> for solid calls. Two minutes from prompt to rendered diagram, of which ten seconds was renaming "App API" to "Backend" to match the codebase.

Prompt 2 — Multi-tenant SaaS schema (ER diagram)

ER diagrams are the worst offender for syntax recall. Cardinality glyphs — ||--o{, }o--||, |o--o| — never live in anyone's head.

bd ai generate "multi-tenant SaaS database: users belong to many \
workspaces through memberships; workspaces own projects; projects \
contain tasks; users are also assigned to tasks"

Output:

erDiagram
  USERS ||--o{ MEMBERSHIPS : has
  WORKSPACES ||--o{ MEMBERSHIPS : has
  WORKSPACES ||--o{ PROJECTS : owns
  PROJECTS ||--o{ TASKS : contains
  USERS ||--o{ TASKS : assigned

A multi-tenant SaaS schema, generated from a one-sentence prompt and rendered with the blueprint theme.

The model picked the right cardinality glyphs without you typing them. It also picked an entity-naming convention (uppercase, plural) and stuck with it across all five entities. That's the kind of consistency tax you'd otherwise pay manually.

When this matters: the diagram is wrong if MEMBERSHIPS should have been an attribute on USERS instead of a join entity. The AI guessed "many-to-many through membership", which is the right call for most multi-tenant SaaS — but if you're modeling something else, you'll edit. That's the workflow: get a draft fast, refine the parts that don't match your domain.

Prompt 3 — CI/CD pipeline (flowchart)

Yes, even the flowchart you can write blindfolded benefits from a prompt when the diagram has six branches and a manual gate.

bd ai generate "GitHub Actions pipeline: PR merged to main triggers \
tests; if tests pass build a container image, deploy to staging, \
require manual approval, then deploy to production. If tests fail, \
notify the PR author."

Output:

flowchart TD
  PR[PR merged to main] --> Test[Run tests]
  Test -->|pass| Build[Build image]
  Test -->|fail| Notify[Notify author]
  Build --> Stage[Deploy to staging]
  Stage --> Gate{Manual approval}
  Gate -->|approve| Prod[Deploy to prod]
  Gate -->|reject| Hold[Hold release]

The CI/CD pipeline, with the failure branches the prompt asked for. Rendered with the modern theme.

Two details worth noting. First, the AI chose {Manual approval} (decision diamond) instead of [Manual approval] (rectangle) for the gate — the right shape for a yes/no branch. Second, it used -->|pass| for labelled edges instead of breaking the label onto a separate line, which is the cleaner Mermaid idiom.

You could have written this. The question is whether you want to spend three minutes typing it or thirty seconds prompting it. For a diagram that's going in your team's onboarding doc and won't change for six months, the prompt path is the better trade.

Prompt 4 — Order lifecycle (state diagram)

State machines are another "syntax-rare" category. [*] --> X, transitions with labels, the difference between stateDiagram and stateDiagram-v2 (the v2 syntax is what Mermaid currently maintains).

bd ai generate "order lifecycle state machine: starts in cart, \
becomes placed on checkout, paid when payment succeeds, shipped \
when fulfilled, delivered when the carrier confirms. From paid, \
the customer can cancel to refunded."

Output:

stateDiagram-v2
  [*] --> Cart
  Cart --> Placed: Checkout
  Placed --> Paid: Payment OK
  Paid --> Shipped: Fulfilled
  Shipped --> Delivered: Carrier confirms
  Delivered --> [*]
  Paid --> Refunded: Customer cancels
  Refunded --> [*]

Order lifecycle states, with the refund branch the prompt described. Rendered with the slate theme.

The AI picked stateDiagram-v2 (the current syntax), used [*] for entry and exit, and put transition labels after the colon. All things I'd otherwise look up.

There's a subtler thing happening: the prompt described "from paid, the customer can cancel to refunded" — a side branch from the main happy path. The AI laid it out as a separate transition rather than nesting it inside a state Paid { ... } block. That's a layout decision the model made for you. If you wanted the refund flow nested, you'd add "group Paid → Refunded into a Paid composite state" to the prompt.

Prompt 5 — Notification class hierarchy (class diagram)

Class diagrams are the format devs hate most. The syntax is verbose, the inheritance arrows are easy to mix up, and you write maybe two per year.

bd ai generate "class hierarchy for a polymorphic notification \
system: base Notification with channel and deliver(), then \
EmailNotification with htmlBody and fromAddress, SmsNotification \
with shortMessage and senderId, PushNotification with deeplink \
and iconUrl"

Output:

classDiagram
  class Notification {
    +String channel
    +deliver()
  }
  class EmailNotification {
    +String htmlBody
    +String fromAddress
  }
  class SmsNotification {
    +String shortMessage
    +String senderId
  }
  class PushNotification {
    +String deeplink
    +String iconUrl
  }
  Notification <|-- EmailNotification
  Notification <|-- SmsNotification
  Notification <|-- PushNotification

Three-channel notification class hierarchy. Rendered with the atelier theme.

<|-- (empty triangle, hollow head, line) is the inheritance arrow. Reversed direction (--|>) means the same relationship from the other end. Knowing that one glyph fluently is the difference between a 30-second class diagram and a 5-minute one. The AI knows it; you don't have to.

When NOT to use AI

The prompt-to-diagram path is great for drafts. It's a worse fit for these cases:

1. The diagram already exists, you're refining it. Editing five nodes by hand is faster than prompting "the same diagram but with X changed." Refinement is what a source pane is for.

2. You need precise layout. AI controls the content (nodes, edges, labels). It doesn't control left-vs-right ordering, column widths, where the diamond lands. If a stakeholder needs the "approve" branch on the right specifically, you'll be editing the source anyway.

3. The diagram encodes ground truth. Database schemas pulled from \dt, API call sequences pulled from logs, dependency graphs from your build system — pull these from the source of truth, don't have an AI guess. The AI is useful when you're the source of truth and the friction is just getting it into Mermaid syntax.

4. You're learning Mermaid. If your goal is to internalise the syntax for a diagram type you'll need monthly, hand-write the first five. After that, automation is fine. Skipping the learning round costs you forever.

The rule of thumb: use AI for "I know what I want and I don't want to look up the syntax." Don't use it for "I don't know what the diagram should show yet" or "this diagram needs to be load-bearing for an audit."

---

A small recommendation (disclosed at the top)

The tool I work on, Beauty Diagram, bundles prompt-to-Mermaid generation, a fixed set of production themes (classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier), and SVG/PNG export into one editor — useful if you want the prompt → rendered diagram loop without juggling separate tools.

The same pipeline runs from a CLI:

# Prompt → rendered SVG, one pipe
npx @beauty-diagram/cli ai generate "user signup with email verification" \
  | npx @beauty-diagram/cli beautify - --theme modern --out signup.svg

bd ai generate is paid-plan only (each call costs us a model invocation); bd auth login saves a key locally. The renderer half (bd beautify, bd export) works anonymously if you only need rendering. → Try the editor if you want to see the prompt loop without installing anything.

---

Wrap-up

The three takeaways:

• Use AI for the diagram types you don't write often. Sequence, ER, class, state — anything where you'd otherwise re-read the docs. Flowcharts you already write fluently; skip the AI if you don't need the speed.

• Treat the output as a draft. Rename, reorder, retheme. The prompt got you past the syntax wall; you still own the diagram.

• Two surfaces, one engine. Editor for iteration, CLI for scripts. The CLI's bd ai generate | bd beautify - pipe is the fastest "prompt to SVG on disk" path.

Most teams I've watched adopt this end up using AI for the 20% of diagrams that aren't flowcharts, and keep hand-writing flowcharts because the muscle memory is faster than a prompt. That split happens organically — you don't have to enforce it.