or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tools.mdconfiguration-management.mdcore-analysis.mdindex.mdoutput-formatting.mdreporter-plugins.mdrule-system.mdtranspiler-support.md
tile.json

cli-tools.mddocs/

CLI Tools

Command-line tools for dependency analysis, reporting, and baseline management. Dependency Cruiser provides several binary commands for different use cases.

Capabilities

Main Analysis Tool

The primary command-line interface for dependency analysis and validation.

# Main command (all aliases point to same tool)
dependency-cruiser [options] <files-or-directories>
dependency-cruise [options] <files-or-directories>
depcruise [options] <files-or-directories>

# Initialize configuration (recommended first step)
depcruise --init [oneshot]

Core Options:

# Configuration and validation
-c, --config [file]              # Use configuration file (e.g. .dependency-cruiser.js)
--no-config                      # Don't use configuration file
-m, --metrics                    # Calculate stability metrics
--no-metrics                     # Disable metrics calculation

# Output control
-T, --output-type <type>         # Output format (err, dot, html, json, etc.)
-f, --output-to <file>           # Write output to file (- for stdout)

# Filtering and focusing
-I, --include-only <regex>       # Only include modules matching regex
-F, --focus <regex>              # Focus on modules + direct neighbors
--focus-depth <number>           # Depth for focus (1=direct, 2=neighbors of neighbors)
-R, --reaches <regex>            # Include modules + what can reach them
-A, --affected [revision]        # Include changed modules since revision + dependents
-H, --highlight <regex>          # Highlight modules matching regex
-x, --exclude <regex>            # Exclude modules matching regex
-X, --do-not-follow <regex>      # Include but don't follow dependencies

# Advanced options
-S, --collapse <regex|number>    # Collapse to folder depth or pattern
-P, --prefix <prefix>            # Add prefix to links (e.g. for IDE integration)
-C, --cache [directory]          # Enable caching in directory
--cache-strategy <strategy>      # Cache strategy: metadata or content
-d, --max-depth <n>              # Maximum cruise depth
-M, --module-systems <items>     # Specify module systems (cjs,amd,es6,tsd)
--ignore-known [file]            # Ignore known violations from file
--no-ignore-known                # Don't ignore known violations

# Configuration overrides
--ts-config [file]               # Use TypeScript config
--webpack-config [file]          # Use webpack config  
--ts-pre-compilation-deps        # Detect pre-compilation dependencies
--preserve-symlinks              # Don't resolve symbolic links

# Progress and information
-p, --progress [type]            # Progress type: cli-feedback, performance-log, ndjson, none
-i, --info                       # Show supported languages and extensions

Usage Examples:

# Initialize project configuration
npx depcruise --init

# Basic analysis with default rules
npx depcruise src

# Analyze with specific configuration
npx depcruise src --config .dependency-cruiser.js

# Generate visual dependency graph
npx depcruise src --output-type dot --include-only "^src" | dot -T svg > deps.svg

# HTML report with metrics
npx depcruise src --output-type html --metrics --output-to deps-report.html

# Focus on specific module and its dependencies
npx depcruise src --focus "src/main/app.js" --focus-depth 2 --output-type html

# Check what reaches a specific module
npx depcruise src --reaches "src/utils" --output-type text

# Analyze only changed files since main branch
npx depcruise src --affected main --output-type err-long

# Generate report with highlighted security issues
npx depcruise src --highlight "security|auth" --output-type err-html

# Use caching for faster repeated analysis
npx depcruise src --cache .depcruise-cache --progress cli-feedback

# Collapse dependencies to folder level
npx depcruise src --collapse 2 --output-type dot

# Show supported file extensions and transpilers
npx depcruise --info

Format Tool

Format existing dependency analysis results with different output types.

depcruise-fmt [options] <cruise-result-file>

# Format options
-T, --output-type <type>         # Output format
-f, --output-to <file>          # Output destination
-I, --include-only <regex>       # Filter included modules  
-F, --focus <regex>              # Focus on specific modules
--focus-depth <number>           # Focus depth
-R, --reaches <regex>            # Show what reaches modules
-H, --highlight <regex>          # Highlight modules
-x, --exclude <regex>            # Exclude modules
-S, --collapse <regex|number>    # Collapse modules
-P, --prefix <prefix>            # Add prefix to links

Usage Examples:

# Convert JSON result to HTML report
depcruise-fmt -T html deps-result.json -f deps-report.html

# Generate DOT graph from existing analysis
depcruise-fmt -T dot deps-result.json | dot -T svg > deps.svg

# Create focused view from full analysis
depcruise-fmt -T html --focus "src/core" --focus-depth 1 full-analysis.json

# Generate Mermaid diagram
depcruise-fmt -T mermaid deps-result.json -f deps.mmd

# Create error report with filtering
depcruise-fmt -T err-long --include-only "^src" deps-result.json

Baseline Tool

Generate baseline files of known violations for suppressing existing issues.

depcruise-baseline [options] <files-or-directories>

# Options (inherits from main depcruise command)
-c, --config [file]              # Configuration file
-f, --output-to <file>          # Output baseline file

Usage Examples:

# Generate baseline of current violations
depcruise-baseline src --config .dependency-cruiser.js -f .known-violations.json

# Create baseline with specific output file
depcruise-baseline src test --output-to baseline-violations.json

# Use baseline in subsequent analysis (ignores known issues)
depcruise src --ignore-known .known-violations.json

HTML Wrapper Tool

Wrap stream input in HTML for web display.

depcruise-wrap-stream-in-html

# Reads from stdin, outputs HTML to stdout
# Typically used in pipelines with visualization tools

Usage Examples:

# Wrap DOT output in HTML for web viewing
depcruise src --output-type dot | dot -T svg | depcruise-wrap-stream-in-html > deps.html

# Create interactive dependency graph
depcruise src --output-type x-dot-webpage | depcruise-wrap-stream-in-html > interactive.html

Output Types

Complete list of available output formats for -T, --output-type:

# Error reporting
err                    # Default error output
err-long              # Detailed error output with file locations
err-html              # HTML error report

# Data formats  
json                  # JSON dependency data
csv                   # CSV format
text                  # Plain text summary
markdown              # Markdown format

# Visualization formats
html                  # HTML dependency graph
dot                   # GraphViz DOT format
ddot                  # Directory-level DOT
cdot                  # Custom DOT format
archi                 # Architecture diagram DOT
fdot                  # Flat DOT format
x-dot-webpage         # Interactive DOT webpage

# Diagram formats
mermaid               # Mermaid diagram format
d2                    # D2 diagram format

# CI/CD formats
teamcity              # TeamCity test reporting format
azure-devops          # Azure DevOps format
baseline              # Baseline violations format

# Special formats
metrics               # Stability metrics only
anon                  # Anonymized output
null                  # No output (exit code only)

Common Workflows

Initial Setup

# 1. Install dependency-cruiser
npm install --save-dev dependency-cruiser

# 2. Initialize configuration (answers questions about your project)
npx depcruise --init

# 3. Run first analysis
npx depcruise src

# 4. Generate visual graph
npx depcruise src --output-type dot | dot -T svg > dependency-graph.svg

CI/CD Integration

# Basic validation in CI (fails build on violations)
npx depcruise src --config .dependency-cruiser.js

# Generate baseline for legacy projects
npx depcruise-baseline src --output-to .known-violations.json

# CI with baseline (only fail on new violations)
npx depcruise src --ignore-known .known-violations.json

# Generate reports for build artifacts
npx depcruise src --output-type html --output-to reports/dependencies.html
npx depcruise src --output-type json --output-to reports/dependencies.json

Development Workflows

# Quick check during development
npx depcruise src --output-type err-long --include-only "^src"

# Focus on current work (replace with your module)
npx depcruise src --focus "src/features/auth" --output-type html

# Check impact of changes
npx depcruise src --affected HEAD~1 --output-type text

# Generate documentation
npx depcruise src --output-type html --metrics --output-to docs/architecture.html

Performance Optimization

# Use caching for large projects
npx depcruise src --cache .depcruise-cache

# Faster analysis with metadata caching
npx depcruise src --cache .cache --cache-strategy metadata

# Progress feedback for long-running analysis
npx depcruise src --progress cli-feedback

# Limit analysis depth for faster results
npx depcruise src --max-depth 5

Exit Codes

The CLI tools return different exit codes based on results:

  • 0: No violations found or successful operation
  • 1: Violations found (when using error output types)
  • 2: Invalid command line arguments or configuration
  • 3: File system or permission errors
  • 4: Analysis errors (e.g., parsing failures)
# Use exit codes in scripts
if depcruise src --output-type null; then
  echo "No dependency violations found"
else
  echo "Violations detected, exit code: $?"
fi

Configuration Integration

CLI tools automatically discover configuration files:

  1. .dependency-cruiser.js
  2. .dependency-cruiser.json
  3. dependency-cruiser section in package.json
# Explicit configuration
depcruise src --config custom-rules.js

# No configuration (uses defaults)
depcruise src --no-config

# Override specific options
depcruise src --config .dependency-cruiser.js --max-depth 3

Environment Variables

Some behavior can be controlled via environment variables:

# Disable colored output
NO_COLOR=1 depcruise src

# Control Node.js options
NODE_OPTIONS=--max-old-space-size=4096 depcruise large-project/

# Set specific language/locale
LANG=en_US.UTF-8 depcruise src