Learn how to use the next-introspect command-line interface to analyze your Next.js projects

Command Line Interface

The next-introspect CLI provides a powerful interface for analyzing Next.js projects from the command line.

Basic Usage

# Analyze current directory
next-introspect introspect .

# Analyze specific project
next-introspect introspect /path/to/nextjs/project

Output Formats

JSON Output

next-introspect introspect . --format json --output routes.json

Markdown Documentation

next-introspect introspect . --format markdown --output ROUTES.md

TypeScript Types

next-introspect introspect . --format typescript --output routes.ts

Pretty-printed JSON

next-introspect introspect . --format json --indent 4

Analysis Modes

Basic Analysis (Fastest)

next-introspect introspect . --mode basic

Includes: route paths, patterns, and basic metadata.

Detailed Analysis

next-introspect introspect . --mode detailed

Includes: component types, special files, and extended metadata.

Comprehensive Analysis (Slowest)

next-introspect introspect . --mode comprehensive

Includes: all exports, data fetching methods, and complete metadata.

Path Display Options

Relative to Project Root

next-introspect introspect . --path-style relative-to-project --show-file-paths

Relative to App Directory

next-introspect introspect . --path-style relative-to-app --show-file-paths

Strip Custom Prefix

next-introspect introspect . --path-style strip-prefix --strip-prefix "src/app" --show-file-paths

Advanced Options

Quiet Mode

next-introspect introspect . --quiet --output result.json

Exclude Fields

next-introspect introspect . --exclude-fields "filePath,pattern,router" --format json

Nested Structure

next-introspect introspect . --nested --format json

Include Empty Segments

next-introspect introspect . --nested --include-empty-segments --format json

Package Summary

next-introspect introspect . --package-summary
next-introspect introspect . --package-summary --include-scripts --include-deps

Metadata Integration

next-introspect introspect . --metadata metadata.json --format markdown

Watch Mode

Watch mode continuously monitors your Next.js project for file changes and automatically re-runs the analysis.

Basic Watch Mode

next-introspect introspect . --watch

Watch with Custom Output

next-introspect introspect . --watch --format typescript --output routes.ts

Quiet Watch Mode

next-introspect introspect . --watch --quiet --output routes.json

Full Watch Command

next-introspect introspect . --watch --mode comprehensive --format markdown --output ROUTES.md

Merge Command

Merge existing introspection results with additional metadata.

Basic Merge

next-introspect merge routes.json metadata.json --output merged.json

Merge with Field Filtering

next-introspect merge routes.json metadata.json --exclude-fields "filePath" --output clean.json

Merge to Markdown

next-introspect merge routes.json metadata.json --format markdown --output merged.md

Command Reference

introspect

next-introspect introspect <projectPath> [options]

Options:

-f, --format <format>: Output format (object, json, markdown, typescript)
-m, --mode <mode>: Analysis mode (basic, detailed, comprehensive)
-o, --output <file>: Write output to file instead of console
--indent <number>: JSON indentation (default: 2)
--quiet: Suppress progress messages
--path-style <style>: Path display style (absolute, relative-to-project, relative-to-app, relative-to-pages, strip-prefix)
--strip-prefix <prefix>: Prefix to strip from paths when using strip-prefix style
--strip-prefixes <prefix>: Prefix to strip from route paths (can be used multiple times)
--show-file-paths: Format file paths according to the path style
--package-summary: Show only package.json summary
--include-scripts: Include scripts section in summary
--include-deps: Include dependencies/devDependencies in summary
--nested: Output routes in nested hierarchical structure
--include-empty-segments: Include empty path segments in nested structure
--exclude-fields <fields>: Comma-separated list of fields to exclude
--metadata <file>: Path to metadata file (JSON or TOML) with titles and descriptions
-w, --watch: Watch mode: continuously monitor for file changes

merge

next-introspect merge <jsonFile> <metadataFile> [options]

Options:

-o, --output <file>: Write merged output to file instead of console
-f, --format <format>: Output format for merged result
--indent <number>: JSON indentation (default: 2)
--exclude-fields <fields>: Comma-separated list of fields to exclude

Examples

Development Workflow

# Watch for changes during development
next-introspect introspect . --watch --format typescript --output src/routes.ts

Documentation Generation

# Auto-update route documentation
next-introspect introspect . --watch --format markdown --output docs/ROUTES.md

CI/CD Integration

# Monitor route changes in deployment pipeline
next-introspect introspect . --watch --quiet --output routes.json

Advanced Analysis

# Full analysis with all options
next-introspect introspect /path/to/project \
  --format markdown \
  --mode comprehensive \
  --path-style relative-to-project \
  --show-file-paths \
  --package-summary \
  --include-scripts \
  --include-deps \
  --nested \
  --metadata metadata.json \
  --output project-routes.md

CLI Usage

On this page