CLI Reference

Complete reference for all Unreach CLI commands and options.

Command: scan

Scan a codebase for unused code.

Usage

unreach scan [directory] [options]

Arguments

• [directory] - Directory to scan (default: current directory)

Options

Option	Short	Description
--entry <entry>	-e	Custom entry point(s). Multiple entry points can be specified comma-separated (e.g., src/index.ts,src/cli.ts).
--export [format]		Export report in specified format(s). If no format is specified, defaults to JSON. Multiple formats can be comma-separated (e.g., json,html,md). Supported formats: json, csv, tsv, md, html. Reports are saved to reports/ directory by default.
--export-path <dir>		Specify output directory for exported reports. Defaults to {scanned-directory}/reports/ if not specified. Files will be named unreach-report.{ext}. Directories will be created automatically if they don't exist.
--history		Keep previous reports by appending timestamps (e.g., unreach-report-2024-01-15T14-30-45.json). By default, reports are replaced.
--quiet		Suppress all output except errors.
--no-progress		Disable progress indicator (enabled by default).
--no-incremental		Disable incremental analysis (re-analyze all files, ignoring cache).
--visualize		Generate an interactive dependency graph visualization (dependency-graph.html).
--benchmark		Track and display performance metrics (parse time, analysis time, memory usage).
--verbose		Show detailed output including file-by-file processing information.
--debug		Enable debug mode with stack traces and detailed error information.
--group-by <type>		Group output by type or file (default: type).
--interactive		Show interactive menu to configure scan options.
--watch		Watch for file changes and automatically re-scan (continuous monitoring).
--no-config		Ignore configuration file and use default settings.
--stats		Show summary statistics (files analyzed, packages analyzed, entry points, unused items breakdown).
--fix		Automatically remove unused code (coming soon).

Examples

# Scan current directory
unreach scan

# Scan specific directory
unreach scan /path/to/project

# Scan with custom entry point
unreach scan --entry src/index.ts

# Scan with multiple entry points
unreach scan --entry src/index.ts,src/cli.ts

# Export as JSON (explicit format)
unreach scan --export json

# Export as JSON (default when no format specified)
unreach scan --export

# Export in multiple formats
unreach scan --export json,html,md

# Export to custom directory
unreach scan --export json --export-path ./custom-reports

# Keep history with timestamps
unreach scan --export json --history

# Quiet mode
unreach scan --quiet

# Disable progress bar
unreach scan --no-progress

# Watch mode (continuous monitoring)
unreach scan --watch

# Interactive mode (menu-driven configuration)
unreach scan --interactive

# Verbose mode (detailed output)
unreach scan --verbose

# Debug mode (stack traces and detailed errors)
unreach scan --debug

# Benchmark mode (performance metrics)
unreach scan --benchmark

# Generate dependency graph visualization
unreach scan --visualize

# Group output by file instead of type
unreach scan --group-by file

# Disable incremental analysis (full re-scan)
unreach scan --no-incremental

# Ignore configuration file
unreach scan --no-config

# Show summary statistics
unreach scan --stats

Command: check-update

Check for available updates from the npm registry.

Usage

unreach check-update

Automatically detects your package manager (npm, yarn, pnpm, bun) and shows the correct install command. Detection is based on lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock), environment variables, or defaults to npm if none detected.

Examples

# Check for updates
unreach check-update

Global Options

Option	Short	Description
--version	-v	Show version number
--help	-h	Show help message

Examples

# Show version
unreach --version
unreach -v

# Show help
unreach --help
unreach scan --help

Output Formats

Text Output (Default)

When no export format is specified, Unreach outputs results to the console in a human-readable format:

🔍 Scanning codebase...

📌 Found 1 entry point(s):
   • src/index.ts

📊 Building dependency graph...
████████████████████████████████████████ 100.0% | 42/42 files | 1.2s elapsed | ETA: 0.0s

🔬 Analyzing reachability...
   Analysis complete

Unused exports: 6
  - checkMaxDepth [src/core/scanner/index.ts]:2
  - createFileDetail [src/core/scanner/index.ts]:3
  ...

Unused variables: 1
  - unusedVariable [src/utils/version.ts]:9

Safe to remove: yes (7 items)

When using --stats, additional summary statistics are displayed:

📊 Summary Statistics
──────────────────────────────────────────────────
   Files analyzed: 42
   Packages analyzed: 15
   Entry points: 1

Unused Items Breakdown:
   • Packages        2
   • Imports         3
   • Exports         6
   • Functions       1
   • Variables       1

   Total unused items: 13

JSON Output

Machine-readable format for automation:

{
  "unusedPackages": [
    {
      "name": "lodash",
      "version": "4.17.21"
    }
  ],
  "unusedImports": [
    {
      "file": "src/components/Button.tsx",
      "importPath": "./utils.ts",
      "line": 5,
      "column": 10
    }
  ],
  "unusedExports": [
    {
      "file": "src/utils/helpers.ts",
      "exportName": "helperFunction",
      "line": 15,
      "column": 5
    }
  ],
  "unusedFunctions": [],
  "unusedVariables": [],
  "unusedTypes": [],
  "unusedFiles": [],
  "unusedConfigs": [],
  "unusedScripts": [],
  "unusedCSSClasses": [],
  "unusedAssets": []
}

Other Formats

• CSV - Spreadsheet-compatible format
• TSV - Tab-separated values
• Markdown (md) - Human-readable markdown format
• HTML - Beautiful HTML report with styling

Exit Codes

• 0 - Success (scan completed successfully)
• 1 - Error occurred (validation error, analysis error, or other failure)

Common Error Types

• Directory not found - The specified directory doesn't exist
• Configuration error - Invalid configuration file format or values
• Entry point not found - Custom entry point specified but file doesn't exist
• Analysis error - Error during code analysis (parse errors, etc.)

Use --debug flag to get detailed error information including stack traces.

Entry Point Auto-Detection

When no entry points are specified (via --entry or config), Unreach automatically detects entry points in the following order:

1. package.json fields - Checks bin, main, module, browser, exports, types, typings
2. tsconfig.json - Checks files array and include patterns
3. Common entry point patterns - Looks for files like index.ts, main.ts, app.ts, etc. in common source directories (src, lib, app, etc.)
4. Framework-specific patterns - Detects entry points for:
   • Next.js: pages/**/*.{ts,tsx,js,jsx}, app/**/*.{ts,tsx,js,jsx}
   • Nuxt: pages/**/*.vue, app.vue
   • Svelte: src/routes/**/*.svelte
   • Astro: src/pages/**/*.astro
   • Gatsby: src/pages/**/*.{ts,tsx,js,jsx}
   • Remix: app/routes/**/*.{ts,tsx,js,jsx}, app/root.tsx
   • Vite: src/main.{ts,tsx,js,jsx}
   • Angular: src/main.ts, src/app/**/*.ts
5. Test files - Includes test files (**/*.test.{ts,tsx,js,jsx}, **/*.spec.{ts,tsx,js,jsx}, **/__tests__/**) if test file detection is enabled

Cache and Incremental Analysis

Unreach uses caching to speed up subsequent scans:

• Cache location: .unreach-cache/ directory in the scanned project
• What's cached: Parsed ASTs and file hashes
• When cache is used: Only for files that haven't changed (based on file hash)
• When to disable: Use --no-incremental to force a full re-analysis

The cache is automatically invalidated when files change, ensuring accurate results.

Watch Mode Details

Watch mode continuously monitors your codebase and automatically re-scans on file changes:

• Rate limiting: Configurable via watchRateLimit in config (default: 1 scan per second)
• Signal handling: Gracefully handles SIGINT (Ctrl+C) and SIGTERM to stop watching
• File change detection: Debounced to prevent excessive scans
• All scan options supported: Works with all scan options (export, visualize, benchmark, etc.)

Automatic Version Checking

Unreach automatically checks for updates in the background (unless --quiet or --debug is used):

• Checks npm registry for newer versions
• Shows update notification if a newer version is available
• Includes package manager-specific install commands
• Non-blocking (doesn't affect scan performance)

To manually check for updates, use the check-update command.