diagram-cli

Generate codebase architecture diagrams from source files. No AI required.

Table of Contents

• Upgrade notice
• Plain-language summary
• Install
• Quick start
• First-run checklist
• Commands
• Diagram types
• AI-focused diagram outputs
• Output formats
• Video and animation prerequisites
• Architecture Testing
• Documentation
• Development
• License

Upgrade notice

⚠️ @brainwav/[email protected] had a packaging regression and failed at runtime with Cannot find module './utils/commands'. Please use @brainwav/[email protected] or later.

Plain-language summary

This tool reads code and draws a map. You point it at a repo. It scans files. It finds links. It prints a clear graph. You can save that graph. You can save PNG or SVG files. You can make short video clips. You can test code layer rules. You can run it on your laptop. You can run it in CI. The goal is simple: keep the code map clear and keep rule drift low.

Install

# Clone and link locally
git clone https://github.com/jscraik/diagram-cli.git
cd diagram-cli
npm install
npm link

Quick start

# Analyze repository structure
diagram analyze .

# Generate architecture diagram (default type)
diagram generate .

# Generate all diagram types into ./diagrams
diagram all .

First-run checklist

Use a small test repo first. Run from the repo root. Start with diagram analyze .. Read the file and link count. Next, run diagram generate .. Save one file with --output. Pick .mmd for text output. Pick .svg for image output. Use diagram all . for all views. Use --max-files if runs are slow. Keep path globs short and clear. Skip build and vendored dirs. Try diagram test --init for rules. Then run diagram test to check rules. Use --dry-run when match sets look odd. Use --verbose if you need more detail. Run npm test to check local health. Run npm run test:deep for deep checks.

Commands

diagram analyze [path]

Analyze file structure and dependencies without rendering a diagram.

diagram analyze ./my-project
diagram analyze . --json
diagram analyze . --patterns "**/*.py,**/*.go"
diagram analyze . --max-files 200

Options:

• -p, --patterns <list> file patterns (default: **/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.py,**/*.go,**/*.rs)
• -e, --exclude <list> exclude patterns
• -m, --max-files <n> max files to analyze (default: 100)
• -j, --json JSON output

diagram generate [path]

Generate one Mermaid diagram and print a preview URL.

diagram generate .
diagram generate . --type sequence
diagram generate . --focus src/api
diagram generate . --theme dark
diagram generate . --output diagram.mmd
diagram generate . --output diagram.svg
diagram generate . --open

Options:

• -t, --type <type> architecture|sequence|dependency|class|flow|database|user|events|auth|security (default: architecture)
• -f, --focus <module> focus on one module or directory
• -o, --output <file> write .mmd, .svg, or .png
• -m, --max-files <n> max files to analyze
• --theme <theme> default|dark|forest|neutral
• --open open generated preview URL

diagram all [path]

Generate all diagram types in one run.

diagram all .
diagram all . --output-dir ./docs/diagrams

Options:

• -o, --output-dir <dir> output directory (default: ./diagrams)

diagram manifest [path]

Summarize the generated .diagram/manifest.json artifact.

diagram manifest .
diagram manifest . --manifest-dir .diagram --output .diagram/manifest-summary.json
diagram manifest . --manifest-dir .diagram --require-types architecture,security --fail-on-placeholder

Options:

• -d, --manifest-dir <dir> directory containing manifest.json (default: .diagram)
• -o, --output <file> write summary JSON to file
• --require-types <list> require specific diagram types, comma-separated
• --fail-on-placeholder fail if any diagram entry is a placeholder

diagram video [path]

Generate an animated video (.mp4, .webm, .mov) from a Mermaid diagram.

diagram video .
diagram video . --type dependency --output architecture.mp4
diagram video . --duration 8 --fps 60 --width 1920 --height 1080

Options:

• -t, --type <type> architecture|sequence|dependency|class|flow|database|user|events|auth|security (default: architecture)
• -o, --output <file> output file (default: diagram.mp4)
• -d, --duration <sec> video duration in seconds (default: 5)
• -f, --fps <n> frames per second (default: 30)
• --width <n> output width in pixels (default: 1280)
• --height <n> output height in pixels (default: 720)
• --theme <theme> default|dark|forest|neutral (default: dark)
• -m, --max-files <n> max files to analyze (default: 100)

diagram animate [path]

Generate an animated SVG with CSS animations.

diagram animate .
diagram animate . --type sequence --output sequence-animated.svg
diagram animate . --theme forest

Options:

• -t, --type <type> architecture|sequence|dependency|class|flow|database|user|events|auth|security (default: architecture)
• -o, --output <file> output file (default: diagram-animated.svg)
• --theme <theme> default|dark|forest|neutral (default: dark)
• -m, --max-files <n> max files to analyze (default: 100)

Diagram types

| Type | Description | Best for | | --- | --- | --- | | architecture | Component hierarchy by directory | Overall structure | | sequence | Service or module interactions | API and flow analysis | | dependency | Internal and external imports | Dependency review | | class | Class-oriented relationships | OOP-heavy codebases | | flow | Process/data flow | Control-flow mapping | | database | Database operations and condition paths | Conditional persistence flows | | user | User-facing entrypoints and handlers | Interaction flow mapping | | events | Event streams and async channels | Event-driven architecture | | auth | Authentication and authorization checks | Credential/identity flow | | security | Security boundaries and trust paths | Threat/risk analysis |

AI-focused diagram outputs

For agent workflows, the Mermaid output is especially useful because it is compact, textual, and structured. Feeding .mmd into an AI at startup lets it understand architecture faster than reading all source files.

The generated types cover these high-value areas for automated reasoning:

• Database Operations — conditional record paths (for example "record exists?" / "not found" branches), storage and mutation decisions.
• User Actions and Interactions — user entrypoints and downstream handler chains.
• Events and Channels — internal publishers, workers, listeners, and trigger paths.
• Authentication Flows — step-by-step identity and credential checks.
• Security and Data Flows — trust boundaries, sensitive components, and integrations to support security review and compliance context.

When reviewing PRs, run:

diagram all . --output-dir .diagram

so .diagram/ includes the new AI-oriented variants beside the classic ones.

The command also writes .diagram/manifest.json summarizing what diagrams were produced and whether any outputs are placeholder/no-data (helpful for CI and agent bootstrap checks).

Output formats

• Terminal Mermaid output
• .mmd Mermaid source files
• .svg/.png rendered images (requires Mermaid CLI)
• .mp4/.webm/.mov video export (requires Playwright + ffmpeg)
• Animated .svg export (requires Playwright)
• .diagram/manifest.json machine-readable artifact index

Install Mermaid CLI for image export:

npm install -g @mermaid-js/mermaid-cli

Video and animation prerequisites

Install Playwright browser dependencies:

npm install
npx playwright install chromium

Install ffmpeg for diagram video:

brew install ffmpeg

Quick verification:

diagram video . --duration 2 --output smoke-test.mp4
diagram animate . --output smoke-test-animated.svg

Architecture Testing

Validate codebase architecture against declarative YAML rules to prevent architectural drift.

Architecture test quick start

# Generate starter configuration
diagram test --init

# Run validation
diagram test

# Preview file matching without validating
diagram test --dry-run

# CI-friendly output
diagram test --format junit --output test-results.xml

Configuration (.architecture.yml)

version: "1.0"

rules:
  - name: "Domain isolation"
    description: "Domain logic should not depend on UI"
    layer: "src/domain"
    must_not_import_from: ["src/ui", "src/components"]

  - name: "API contract"
    description: "API routes only use domain and shared"
    layer: "src/api"
    may_import_from: ["src/domain", "src/shared", "src/types"]
    must_not_import_from: ["src/ui"]

  - name: "Test independence"
    description: "Tests should not import other tests"
    layer: "**/*.test.ts"
    must_not_import_from: ["**/*.test.ts", "**/*.spec.ts"]

Rule types

| Constraint | Description | | --- | --- | | must_not_import_from | Forbidden import patterns | | may_import_from | Whitelist of allowed imports | | must_import_from | Required import patterns |

Command options

diagram test [path] [options]

Options:
  -c, --config <file>    Config file (default: ".architecture.yml")
  -f, --format <format>  Output: console, json, junit
  -o, --output <file>    Write output to file
  --dry-run              Preview file matching
  --verbose              Show detailed output
  --init                 Generate starter config
  --force                Overwrite existing config when used with --init

Exit codes

| Code | Meaning | | --- | --- | | 0 | All rules passed | | 1 | One or more rules failed | | 2 | Configuration error |

CI Integration

# .github/workflows/architecture.yml
name: Architecture
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm test
      - run: npm run test:deep
      - run: npm run ci:artifacts
      - uses: actions/upload-artifact@v4
        with:
          name: diagram-ci-artifacts
          path: .diagram
      - uses: dorny/test-reporter@v1
        if: success() || failure()
        with:
          name: Architecture Tests
          path: .diagram/architecture-results.xml
          reporter: java-junit

Documentation

• Getting started: docs/getting-started.md
• Architecture testing guide: docs/architecture-testing.md
• Migration guide: docs/migration-from-dependency-cruiser.md
• Contributor guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support policy: SUPPORT.md
• Code of conduct: CODE_OF_CONDUCT.md
• Maintainer docs index: docs/README.md
• Release history: CHANGELOG.md

Documentation signature

brAInwav - from demo to duty

Development

npm install
npm test
npm run test:deep
node src/diagram.js --help

License

MIT - see LICENSE.