diagram-cli

Generate architecture diagrams, validation reports, and PR impact artifacts from source code.

Table of Contents

• Overview
• Quick Start
• Opinionated Starter Path
• Human Workflows
• AI Agent Workflows
• Machine Output Contracts
• Documentation Index
• Development

Overview

diagram-cli scans your repository and produces:

• Mermaid diagrams (generate, generate-all)
• Architecture policy validation (validate)
• PR architecture impact reports (workflow pr)
• AI-context artifacts (context)

Default resolution precedence for scan parameters is explicit:

1. CLI flags
2. .diagramrc
3. command built-ins

This applies to patterns, exclude, maxFiles, and theme where relevant.

Quick Start

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

Without npm link, run commands with node src/diagram.js ....

Opinionated Starter Path

Use this path for new repositories:

diagram init .
diagram doctor .
diagram validate .
diagram generate-all . --output-dir .diagram --artifact-profile agent
diagram context .

What this gives you:

• .architecture.yml starter rules
• .diagramrc defaults
• CI step sample at .diagram/ci/github-actions-step.yml
• toolchain diagnostics before CI rollout
• compact AI-friendly architecture artifacts

Human Workflows

# Analyze repository structure
diagram analyze .

# Generate one diagram and open preview
diagram generate . --type architecture --open

# Analyze only changed files in your branch
diagram changed . --base origin/main --head HEAD

# Explain a local dependency neighborhood
diagram explain auth-service .

# PR risk/blast-radius report
diagram workflow pr . --base origin/main --head HEAD --risk-threshold medium --fail-on-risk

AI Agent Workflows

# Stable machine outputs
diagram generate . --type architecture --format json --deterministic
diagram workflow pr . --base origin/main --head HEAD --format json --deterministic

# Compact context pack for agent token budgets
diagram generate-all . --output-dir .diagram --artifact-profile agent
diagram context .

Machine Output Contracts

• Use --format json for machine output.
• --json is a compatibility alias and is normalized to --format json.
• Command outputs include explicit schemaVersion values.
• Use --deterministic for stable ordering/timestamps in machine payloads.
• PR impact JSON includes agentSummary with:
  • changedComponents
  • riskReasons
  • suggestedReviewerChecks

Documentation Index

• CLI reference
• Getting started
• Architecture testing
• Migration from dependency-cruiser
• Maintainer docs index

Development

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

License

Apache 2.0 - see LICENSE.