DiagramPin CLI

Agent-friendly CLI for diagram layout automation. All output is structured JSON — designed for LLM agents, CI pipelines, and scripting.

Install

npm install -g diagrampin

Or use without installing:

npx diagrampin analyze schema.dbml

Output Format

Every command returns JSON with a consistent envelope:

Success (exit 0):

{
  "ok": true,
  "schemaVersion": 1,
  "command": "analyze",
  "data": { ... },
  "warnings": []
}

Error (exit 1):

{
  "ok": false,
  "schemaVersion": 1,
  "command": "analyze",
  "error": {
    "code": "MISSING_PATH",
    "message": "Schema path is required."
  }
}

Parse with: JSON.parse(stdout) — check ok field first.

Agent Workflow (Recommended)

Follow this sequence for a complete layout automation round-trip:

1. analyze          → Understand the schema (read-only)
2. group plan       → Suggest table groupings (dry-run)
3. layout plan      → Preview layout positions (dry-run)
4. layout apply     → Write positions to sidecar file
5. layout validate  → Verify layout quality
6. layout export-inline → Write back to DBML @layout comments

Minimal example:

# Step 1: Analyze the schema
diagrampin analyze schema.dbml

# Step 2: Auto-layout and save to sidecar file
diagrampin layout apply schema.dbml --strategy group-aware

# Step 3: Export positions back into DBML inline comments
diagrampin layout export-inline schema.dbml

Commands

analyze <schema.dbml>

Parse a DBML file and return structured metadata. Read-only — no files are modified.

diagrampin analyze schema.dbml

Output includes: table count, relationships, groups, orphan tables, inline layout count.

group plan <schema.dbml> [--mode hybrid|name|relationship]

Suggest table groupings based on naming patterns and/or relationships. Dry-run — no files are modified.

diagrampin group plan schema.dbml --mode hybrid

| Option | Default | Values | |--------|---------|--------| | --mode | hybrid | name, relationship, hybrid |

group promote <schema.dbml> [--clusters c1,c2]

Promote sidecar visual clusters into DBML TableGroup blocks. Modifies the DBML file.

diagrampin group promote schema.dbml --clusters sales-domain,user-domain

layout plan <schema.dbml> [--strategy group-aware]

Calculate layout positions. Dry-run — returns the plan without writing.

diagrampin layout plan schema.dbml --strategy group-aware

| Option | Default | Values | |--------|---------|--------| | --strategy | group-aware | grid, relationship, group-aware, hybrid |

layout apply <schema.dbml> [--strategy group-aware]

Calculate and write positions to a sidecar state file (*.diagrampin.json). Creates a checkpoint for undo.

diagrampin layout apply schema.dbml

layout validate <schema.dbml>

Validate the merged layout state (sidecar + inline). Returns quality metrics. Read-only.

diagrampin layout validate schema.dbml

layout import-inline <schema.dbml>

Import @layout comments from DBML into the sidecar state file. Creates a checkpoint.

diagrampin layout import-inline schema.dbml

layout export-inline <schema.dbml>

Write sidecar positions back into DBML as @layout comments. Modifies the DBML file.

diagrampin layout export-inline schema.dbml

layout checkpoints <schema.dbml>

List available recovery checkpoints.

diagrampin layout checkpoints schema.dbml

layout undo <schema.dbml> [--checkpoint <id>]

Restore layout state from a previous checkpoint.

diagrampin layout undo schema.dbml

Sidecar State File

layout apply creates a *.diagrampin.json file next to your DBML:

project/
├── schema.dbml
└── schema.diagrampin.json   ← sidecar state file

This file stores:

• Table positions (x, y, fixed flag)
• Visual clusters (grouped tables with confidence scores)
• Constraints (e.g., mustBeNear)
• View metadata (source, last planner strategy)

Commit this file to Git — it makes layout reproducible across machines and reviewable in PRs.

Example:

{
  "version": 1,
  "schemaFile": "schema.dbml",
  "tables": {
    "users": { "x": 180, "y": 60, "fixed": true },
    "orders": { "x": 500, "y": 60, "fixed": true }
  },
  "visualClusters": {
    "sales-domain": {
      "tables": ["orders", "order_items"],
      "source": "hybrid",
      "confidence": 0.94
    }
  },
  "view": {
    "source": "sidecar",
    "lastPlanner": "group-aware"
  }
}

Layout Source Priority

When both inline @layout and sidecar exist, the merge order is:

sidecar  >  inline @layout  >  auto-layout

Use layout import-inline to migrate inline positions into sidecar, and layout export-inline to write sidecar positions back.

Common Options

| Option | Available in | Description | |--------|-------------|-------------| | --strategy <s> | layout plan, layout apply | Layout algorithm (grid, relationship, group-aware, hybrid) | | --mode <m> | group plan | Grouping strategy (name, relationship, hybrid) | | --state-file <path> | All layout/group commands | Override sidecar file location | | --clusters <c1,c2> | group promote | Comma-separated cluster names to promote | | --checkpoint <id> | layout undo | Specific checkpoint to restore |

stdin Support

Pipe DBML content via stdin using - as the file path:

cat schema.dbml | diagrampin analyze -
echo "Table users { id int [pk] }" | diagrampin analyze -

Requirements

• Node.js >= 18