◆ arch_guard

CLI

arch_guard [project_path] [options]          # check the project
arch_guard init [project_path] [options]     # write arch_guard.yaml
arch_guard affected --since <ref> [options]  # list tests a branch can affect
arch_guard why <from> <to> [project_path]    # show the import chain from A to B

project_path defaults to the current directory. How you call it depends on how you installed it:

Installed with Run as
dart pub add --dev arch_guard dart run arch_guard
dart pub global activate arch_guard arch_guard
Standalone binary ./arch_guard

Commands

Command What it does Exits 1 when
arch_guard Scans the project and checks every rule. There are problems (only new ones, with a baseline).
init Detects your layout and writes arch_guard.yaml. –
affected Prints the test files changed code can reach. –
why Prints the shortest import chain between two files, folders or packages. There is no such chain.
mcp Runs an MCP server on stdin/stdout for AI coding agents. –

Options

Flags for the main check. Repeatable flags can be given more than once (--scan-dir lib --scan-dir bin).

What to scan

Flag Default Description
--scan-dir lib Folder to scan, relative to the project root. Repeatable.
--exclude generated files Glob of files to leave out, on top of *.g.dart, *.freezed.dart and other generated files. Repeatable.
--[no-]workspace on Find the members of a Dart workspace or Melos-style monorepo and scan them all.

What fails the run

Flag Default Description
--[no-]fail-on-cycle on Exit 1 when there are cycles. Other rules still fail the run when it is off.
--baseline <file> arch_guard_baseline.json Problems in this file are known and don’t fail the run.
--update-baseline   Write today’s problems to the baseline and exit 0.
--since <ref>   Report only problems in files changed since the merge base with <ref>. See below.

Output

Flag Default Description
-f, --format text text, html, mermaid, dot, json, sarif, markdown or all. Repeatable. See Output formats.
-o, --output arch_guard_output Folder for report files.
--no-graph-diff   With --since, skip the What this change adds comparison (and its checkout of the merge base). --watch re-runs always skip it.
--json off Print the JSON report (the same as -f json) to stdout and nothing else, for scripts and AI agents. The usual report and warnings go to stderr. The exit code is unchanged.
--scope cycles What graphs show: cycles (each cycle plus the files one import away) or all (the full graph).
--group-by – layer, module, package or folder: graphs show one node per group, with import counts on edges and rule violations in red. Implies --scope all unless --scope is given. See Output formats.
--offline off Inline the scripts in the HTML report, for machines without internet.
--[no-]color on ANSI colours in the terminal.

Other

Flag Description
--explain <file> Show one file’s imports, importers and cycle membership. See below.
--watch Re-run on every change. See Watch mode.
--version Print the version.
-h, --help Print usage.

These combinations are rejected with exit 64: --since or --watch with --update-baseline or --explain, --watch with init, affected or why, and --json with --watch or --explain.

Fix a cycle

Every cycle comes with the one import to remove to break it. When no single import does, it names the one that shrinks the cycle most.

  Strongly Connected Component #1 (2 files)
    [Metrics: 2 internal edges | Avg Fan-In: 1.5 | Avg Fan-Out: 1.0 | Hub: lib/screens/home.dart]
    Representative Cycle Path:
    lib/widgets/nav.dart
    -> lib/screens/home.dart
    -> lib/widgets/nav.dart
    Suggested fix: remove lib/screens/home.dart:1 -> lib/widgets/nav.dart (breaks the cycle)

Only files changed on this branch

Analyse the whole project, but report and fail on only the problems that touch files changed since the merge base with origin/main, plus uncommitted and untracked files:

arch_guard --since origin/main

The report ends with Only problems touching 7 file(s) changed since origin/main.

What this change adds

With -f markdown, -f json, -f all or --json, --since also compares the dependency graph with the merge base. Nothing here fails the run. The Markdown report gets a What this change adds section, and the JSON report a diff key, listing:

The merge base is checked out in a temporary git worktree and scanned with your current arch_guard.yaml, so a layer means the same files on both sides. Files git ignores, such as generated *.config.dart files, are left out of the comparison. A PR that adds nothing gets no section. In JSON, diff is absent without --since and null when the base could not be scanned (a warning says why).

Watch mode

Keep a terminal open while you refactor; the check re-runs on every save:

arch_guard --watch
arch_guard --watch --since origin/main     # only problems in changed files

Explain one file

Why is this file in a cycle? What does it import, and what imports it?

arch_guard --explain lib/services/auth_service.dart

Output formats

Format File Use it for
text terminal Day-to-day checks: cycles with metrics, violations with the broken rule.
html dependency_graph.html Exploring the graph: search, click a cycle to focus it, see each file’s imports.
mermaid .mmd Diagrams in GitHub or GitLab Markdown.
dot .dot Graphviz (dot -Tsvg), clustered by package.
json .json Dashboards and scripts: nodes, edges, cycles, violations, hotspots (with commits and churnSince when metrics: churn_since is set).
sarif .sarif GitHub Code Scanning and SARIF viewers. Results point at the import line.
markdown arch_guard_report.md PR comments and CI job summaries.
arch_guard -f html -o build/reports              # interactive graph
arch_guard -f html --offline -o build/reports    # same, works without internet
arch_guard -f sarif -f markdown -o build/reports # for CI
arch_guard -f all -o build/reports               # everything

One node per layer

--group-by layer (or module, package, folder) turns the mermaid, dot and html graphs into the diagram teams draw by hand: one node per layer with its file count, and one edge per pair of layers with the number of imports. An edge that breaks a layer, module or workspace rule is red and says how many violations it holds. Files in no layer go under (none).

arch_guard -f mermaid --group-by layer -o build/reports
flowchart LR
    g0["data<br/>2 files"]
    g1["domain<br/>2 files"]
    g2["ui<br/>2 files"]
    g0 -->|"2"| g1
    g2 -->|"1, 1 violation"| g0
    g2 -->|"1"| g1
    linkStyle 1 stroke:#ef4444,stroke-width:2px,color:#ef4444;

The HTML report opens on the grouped graph. File view switches to the file graph; clicking a group lists its files and its imports in and out. folder groups by the first folder under lib/ (lib/features). --group-by draws the whole project; add --scope cycles to group only the files in cycles.

Unused files in each format

With unused_files: in the config:

Format What it shows
Terminal Up to 20 files, then … and N more. With a baseline, only new ones.
JSON The full sorted list under unusedFiles. The key is absent when the check is off.
SARIF One result per file under the rule unused-file: error with fail: true, warning otherwise, with baselineState when a baseline is used.
Markdown An Unused files row in the summary table, and a New unused files list.

init

arch_guard init                      # detect the layout and write arch_guard.yaml
arch_guard init --preset bloc        # auto | none | clean_architecture | feature_first | bloc | riverpod
arch_guard init --dry-run            # print the config instead of writing it
arch_guard init --force              # overwrite an existing arch_guard.yaml

After writing the file, init scans the project and prints how many files fall into each layer, how many problems exist, and what to do next. How it picks a preset is on the Presets page.

Tests affected by a branch

List the test files that changes since origin/main (plus uncommitted and untracked files) can affect, and run only those:

# single package (Flutter: flutter test)
t=$(arch_guard affected --since origin/main); [ -n "$t" ] && dart test $t

# melos monorepo: test only affected packages
p=$(arch_guard affected --since origin/main --print packages | paste -sd, -)
[ -n "$p" ] && melos exec --scope="$p" -- dart test

Keep the [ -n ... ] guard. dart test with no paths runs every test.

Option Default Description
--since <ref>   Required. The git ref to compare with.
--print tests tests, files or packages, one per line on stdout.
--json   Print since, changedFiles, files, tests, packages (name, path) and ignoredChanges as JSON.
--exclude, --[no-]workspace   As for the main command.

How it decides what is affected:

Notes go to stderr: changed non-Dart files that affect nothing, and No affected tests. when the list is empty.

Why does A depend on B

Print the shortest import chain from a file or folder to a file, folder or package:

arch_guard why lib/domain flutter
lib/domain/user.dart reaches package:flutter in 3 step(s):
  lib/domain/user.dart:3  import  lib/domain/repo.dart
  lib/domain/repo.dart:5  export  lib/data/api.dart
  lib/data/api.dart:1  import  package:flutter/material.dart
Argument Accepts
<from> A file, a folder, or a file name that matches exactly one file (user.dart).
<to> The same, plus package:x, a bare package name (flutter) or a core library (dart:io).

See the why example.

Exit codes

Code Main check affected why
0 No problems (or none new, with a baseline). Done, also when nothing is affected. Found a chain.
1 Cycles, layer violations or other rule failures. – No chain.
2 Missing directory, unreadable project, invalid baseline, or git failed for --since. Git failed. The project could not be scanned.
64 Bad flags or arguments. Bad flags, or no --since. Bad arguments.

Standalone binaries

No Dart SDK needed. On Linux (x64, arm64), macOS (Apple Silicon) or Windows in Git Bash:

curl -fsSL https://creatorpiyush.github.io/arch_guard/install.sh | sh

The script downloads the binary for your platform from the latest GitHub Release, checks it against the release’s SHA256SUMS.txt and installs it as ~/.local/bin/arch_guard. Run it again to upgrade. Two environment variables change the defaults:

Variable Default Description
ARCH_GUARD_VERSION latest Release to install, e.g. 1.15.0.
ARCH_GUARD_INSTALL_DIR ~/.local/bin Folder to install into.
curl -fsSL https://creatorpiyush.github.io/arch_guard/install.sh | ARCH_GUARD_VERSION=1.15.0 sh

There is no binary for Intel macOS; use dart pub global activate arch_guard there. On Windows outside Git Bash, download arch_guard-windows-x64.exe from the release page by hand and compare it with SHA256SUMS.txt.