v0.2.2-beta

Reference

CLI commands.

ngcompass exposes a set of subcommands. Run any of them with --help to see the latest flag list for your installed version.

ngcompass analyze

Runs static analysis on your Angular project and reports violations grouped by file. The exit code is non-zero when violations at or above failOnSeverity are found.

bash
01npx ngcompass analyze

Common examples:

bash
01# Default console output
02npx ngcompass analyze
03

04# JSON output to a file
05npx ngcompass analyze --format json --output results.json
06

07# Stricter CI run
08npx ngcompass analyze --profile ci
  • --format <fmt>

    Output format: console (default) | json | sarif | html. Overrides outputFormat from config.

  • --output <path>

    File path for HTML or JSON output. Overrides outputPath from config.

  • --profile <name>

    Activate a named profile defined in ngcompass.config.ts. Useful for stricter CI rules.

  • --rule <id>

    Run only a single rule by ID. Useful for debugging one specific pattern.

  • --compact

    ESLint-style single-line output (console format only).

  • -q, --quiet

    Show summary counts only — suppress individual violation details.

  • --no-recommendation

    Suppress inline fix hints from output.

  • --force

    Ignore cached results and re-run all checks from scratch.

  • --skip-type-check

    Skip type-aware rules. Fastest mode with lowest memory — syntax-only rules still run.

  • --mode <mode>

    Performance preset: balanced (default) | turbo. turbo maximises throughput on capable machines.

  • --max-workers <n>number

    Cap the number of worker threads. Lower values use less memory. Overrides maxWorkers from config.

ngcompass graph

Generates a full import dependency graph of your Angular project and writes it as a JSON file. Load the output into the interactive Dependency graph viewer to explore every import relationship, see what each file depends on and what depends on it, and identify the heaviest modules.

bash
01npx ngcompass graph --output graph.json

More examples:

bash
01# Write to the default location (ngcompass-graph.json)
02npx ngcompass graph
03

04# Write to a custom path
05npx ngcompass graph --output reports/graph.json
06

07# Scope to one file and its 2-hop neighborhood
08npx ngcompass graph --focus src/app/app.component.ts
09

10# Print JSON to stdout
11npx ngcompass graph --stdout
  • --output <path>default ngcompass-graph.json

    File path for the generated JSON. Pass this file to the /graph viewer on ngcompass.dev.

  • --stdout

    Write JSON to stdout instead of a file.

  • --focus <file>

    Scope the graph to a single file and its import neighborhood. Accepts a relative path or a partial filename.

  • --depth <n>numberdefault 2

    Neighborhood radius in import hops when using --focus. 1 = direct imports only, 2 = imports of imports, etc.

  • --force

    Ignore cached results and re-run from scratch.

ngcompass circular

Scans your project for circular import chains and reports every cycle — the exact files and the import order that closes the loop. Use --format json to produce a file you can load in the interactive Circular dependencies viewer.

bash
01npx ngcompass circular --format json --output cycles.json

More examples:

bash
01# Print cycles to the terminal
02npx ngcompass circular
03

04# Generate a JSON file for the /cycles viewer
05npx ngcompass circular --format json --output cycles.json
06

07# Open an interactive HTML report
08npx ngcompass circular --format ui
09

10# Scope to one file and its direct imports
11npx ngcompass circular --focus src/app/app.module.ts
  • --format <fmt>default console

    Output format: console | json. Use json to produce a file for the /cycles viewer; ui opens a self-contained HTML report.

  • --output <path>

    Write the report or JSON export to a file instead of stdout.

  • --focus <file>

    Scope cycle detection to a single file and its import neighborhood. Accepts a relative path or a partial filename.

  • --depth <n>numberdefault 1

    Neighborhood radius in import hops when using --focus.

  • --force

    Ignore cached results and re-run from scratch.

ngcompass init

Creates an ngcompass.config.ts file in the project root with the ngcompass:recommended preset. Prefer ng add ngcompass for Angular CLI projects — it runs init automatically as part of the schematic.

bash
01npx ngcompass init
  • --force

    Overwrite an existing ngcompass.config.ts. Without this flag, init aborts if the file already exists.

ngcompass config health

Validates the active config file. Reports unknown rule IDs, invalid severity values, unrecognised keys, and schema errors. Useful to run after editing ngcompass.config.ts manually.

bash
01npx ngcompass config health

Related

Configuration →

All config file options and CLI flag overrides.

Dependency graph viewer →

Load a graph.json and explore your imports visually.

Cycles viewer →

Load a cycles.json and inspect every circular import.