Skip to content
Kekonic DiagramsKekonic Diagrams

Quickstart

In a few minutes you will have a .kdiagram file and an SVG. Studio needs no account. Node.js is only required when you want the CLI in a project or CI.

1. Start in Studio

Section titled “1. Start in Studio”

Open Studio and edit the starter diagram. Change a label, add a connection, or change -> to =>. Every meaningful choice stays in the DSL, including layout, theme, and presentation, so the file remains portable.

If you cannot open Studio right now, the editor below uses the same parser, layout engine, and SVG renderer:

Edit source — diagram updates live
Source

Or start with your coding agent

Section titled “Or start with your coding agent”

If the system already lives in a repository, install the official skill and let Cursor, Claude Code, Codex, or another Skills CLI host draft grounded .kdiagram source:

Terminal window
npx skills add kekonic/diagrams

Ask for one reader question, name the files the agent may inspect, and review assumptions as carefully as the diagram. See Design with agents for the workflow and a prompt to start from.

2. Save the source

Section titled “2. Save the source”

Use Studio’s Save or Save as action to keep the source as checkout.kdiagram, or create the same file in your editor:

checkout.kdiagram
diagram "Checkout" {
  direction LR


  browser: client "Web app"
  api: gateway "API"
  checkout: service "Checkout"
  orders: database "Orders"


  browser -> api "POST /orders"
  api -> checkout
  checkout -> orders "insert"
}

The file is ordinary UTF-8 text. Commit it, diff it, and review it like source code. Reopen it in hosted Studio, launch local Studio from the CLI, or edit it with the Kekonic Diagrams extension.

To work against repository files through local Studio:

Terminal window
pnpm dlx @kekonic/diagrams-cli studio checkout.kdiagram --allow-write

3. Choose the first output

Section titled “3. Choose the first output”

For a document, README, wiki, or slide, export SVG directly from Studio. Theme values are included; readers do not need Kekonic Diagrams JavaScript where the image is displayed.

For a repeatable local or CI render, use the CLI without installing it globally:

Terminal window
pnpm dlx @kekonic/diagrams-cli render checkout.kdiagram \
  --output checkout.svg \
  --theme light

Open checkout.svg in a browser. The CLI snapshots theme tokens by default, so the SVG keeps its appearance in a README, wiki, slide, or artifact viewer without Kekonic Diagrams CSS.

If you use npm or Yarn, replace pnpm dlx with npx or yarn dlx.

4. Put the command in your project

Section titled “4. Put the command in your project”

For repeatable builds, install the CLI locally:

Terminal window
pnpm add --save-dev @kekonic/diagrams-cli
package.json
{
  "scripts": {
    "diagrams:check": "kdiagrams check docs/checkout.kdiagram",
    "diagrams:build": "kdiagrams render docs/checkout.kdiagram --output docs/checkout.svg --theme light"
  }
}

check returns a non-zero exit code for invalid source, which makes it suitable for CI.

Prefer JavaScript?

Section titled “Prefer JavaScript?”

Install the SDK when your application owns the source or needs the SVG in memory:

Terminal window
pnpm add @kekonic/diagrams
example.ts
import { writeFile } from "node:fs/promises";
import { KDiagram } from "@kekonic/diagrams";


const result = await KDiagram.renderToSvg(source, {
  theme: "light",
  snapshotTheme: true,
});


if (!result.ok || !result.svg) {
  for (const diagnostic of result.diagnostics) {
    console.error(`${diagnostic.code}: ${diagnostic.message}`);
  }
  throw new Error("Diagram could not be rendered");
}


await writeFile("checkout.svg", result.svg, "utf8");

Expected source mistakes are returned as diagnostics; they are not thrown. See the JavaScript API for browser mounting and staged pipeline access.

Where to go next

Section titled “Where to go next”