Initializes a new Bausteinsicht project in the current directory by creating a sample model, a default template, an initial draw.io diagram, and the sync state file.

Flags:

Created files:

Behavior:

Exit codes:

Example:

Validates the architecture model file for consistency. Reports both errors and warnings.

Flags: No command-specific flags. Uses global flags only.

Behavior:

JSON output structure:

Exit codes:

Example:

Runs one bidirectional synchronization cycle between the architecture model and the draw.io diagram.

Flags:

Behavior:

Derived file paths: The draw.io file and sync state file paths are derived from the model file location:

JSON output structure:

Exit codes:

Example:

Watches the model and draw.io files for changes and automatically runs a sync cycle on each detected change.

Flags:

Behavior:

Exit codes:

Example:

Adds a new element to the architecture model. Designed for LLM-driven workflows.

Flags:

Behavior:

Exit codes:

Example:

Adds a new relationship between two existing elements. Designed for LLM-driven workflows.

Flags:

Behavior:

Exit codes:

Example:

Creates a new view or modifies an existing view’s include list. Designed for LLM-driven workflows to dynamically filter architecture diagrams.

Flags:

Behavior:

Exit codes:

Example:

Adds new element or relationship types to the model’s specification. Enables definition of custom architecture notations.

Exports draw.io diagram views to image files (PNG or SVG) using the draw.io CLI.

Flags:

Behavior:

JSON output structure (the errors array is present only on partial failure):

Exit codes:

Example:

Exports element attributes as an AsciiDoc or Markdown table per view or as a combined table across all views.

Flags:

Behavior:

JSON output structure — --format json emits an array of element rows (not a file list):

Exit codes:

Example:

Exports views as text diagrams in one of several formats (C4-PlantUML, Mermaid, Graphviz DOT, D2, standalone HTML, or Structurizr DSL).

Flags:

Behavior:

JSON output structure — --format json emits an array of one object per exported view (not a file list):

Exit codes:

Example:

Exports dynamic views from the model as PlantUML or Mermaid sequence diagram source files. Dynamic views describe the runtime behaviour of the system as ordered message sequences between elements.

Flags:

Behavior:

Arrow type mapping:

JSON output structure:

Exit codes:

Example:

Evaluates the architectural constraints defined in the model and reports violations.

Flags: none beyond the global flags.

Behavior: loads the model and evaluates each constraint. Prints All constraints passed. when constraints exist with no violations, No constraints defined. when the model declares none, or the list of violations otherwise. Use in CI as an architecture gate.

Computes an architecture health score (0–100, with a letter grade) across weighted categories such as completeness, conformance, and complexity.

Flags:

Behavior: requires an explicit --model. Emits a human-readable report (or JSON with --format json) of the overall score, per-category scores, and model statistics.

Analyzes the relationship graph: cycle detection, dependency depth, and centrality metrics.

Flags:

Behavior: requires an explicit --model. Reports element/relationship counts, max dependency depth, graph type (DAG / has cycles), and strongly connected components.

Flags elements that look forgotten. An element is reported only when all three hold: its last modification is older than the threshold, it has no lifecycle status, and it links no ADR (decisions is empty). Archived elements are skipped.

Flags:

Behavior: the last-modified date comes from per-element git history, or from the element’s explicit lastModified field if set. Outside a git repository, elements without an explicit lastModified have no known date and are therefore not flagged by age. Output is deterministically ordered (by risk, then ID).

Lists elements by lifecycle status (proposed, design, implementation, deployed, deprecated, archived).

Flags:

Behavior: requires an explicit --model. Groups elements under their status.

Full-text search over the model.

Arguments: <query> (required) — the search string.

Flags:

Behavior: returns ranked matches grouped by object type, with the matched fields. --format json emits a structured result.

Displays all fields, relationships, and views for a single element.

Arguments: <element-id> (required) — the dot-path ID.

Behavior: prints the element’s kind, title, description, technology, relationships, and the views it appears in. --format json emits the element as structured data.

Manages versioned model snapshots stored in .bausteinsicht-snapshots/.

Subcommands:

Behavior: diff reports a structured architecture delta (added/removed elements and relationships), not a text diff.

Reports the gap between the model’s asIs and toBe sections.

Flags:

Behavior: exits with an error if the model has no asIs/toBe sections.

Generates a human-readable changelog between two versions of the model.

Flags:

Behavior: loads the model at each git ref (via git rev-parse / git show) and reports the architecture changes between them. Only git refs are supported — snapshot IDs are not (yet) resolved, and an empty --since fails to resolve. (Note: changelog uses --changelog-format, not the global --format.)

Imports an architecture model from an external DSL and writes a Bausteinsicht .jsonc file.

Arguments: <input-file> (required) — the source DSL file.

Flags:

Behavior: parses the source DSL, maps people/systems/containers and relationships, and generates a matching specification. Exit 2 if the output file already exists and neither --force nor --dry-run is set — --dry-run prints to stdout and skips the existence check, so it never fails on an existing output. Exit 1 on any other import failure (unknown --from, unreadable input, parse/encoding error).

Generates a draw.io template with a styled shape for each element kind in the specification.

Flags:

Behavior: the generated file carries the bausteinsicht_template attributes the sync engine needs, so it works directly as a --template.

Computes a hierarchical layout for the diagram and writes the element positions back to the draw.io file.

Flags:

Loads external metrics (error rate, coverage, …) from a JSON file and overlays them as a heatmap on draw.io elements; original styles are preserved.

Subcommands:

apply and remove load the model directly and do not auto-detect — pass --model (there is no default). When --output is omitted it resolves relative to the model file’s directory, not the current directory. Any overlay failure (missing model/metrics file, unreadable diagram, unknown metric) exits with code 2.

Starts an interactive shell for editing the model.

Flags: none beyond the global flags.

Behavior: keeps the model in memory; supports add/remove/list/show/validate/undo/save (plus help and exit). Validates before every save; pure additions are patched comment-preserving, modifications/deletions fall back to a full rewrite (with a warning). exit with unsaved changes prompts for confirmation before quitting; Ctrl-D (EOF) warns about unsaved changes and exits cleanly.

Lists and shows Architecture Decision Records linked to model elements (the decisions field).

Subcommands:

Flags: --model, -m (default architecture.jsonc). adr list supports --format text|json and --element <id> to filter; adr show prints text only.

Works with multi-model workspaces that combine several architecture models.

Subcommands:

Manages the JSON Schema for Bausteinsicht models.

Subcommands:

Behavior: the schema is generated from internal/model types, so it stays in sync with the model definitions.