@vscode/component-explorer-cli

Command-line tool for capturing, comparing, and managing component fixture screenshots.

Installation

npm install @vscode/component-explorer-cli

The binary is available as component-explorer.

Commands

screenshot

Capture screenshots of all fixtures using a headless browser.

component-explorer screenshot [options]

| Option | Description | |---|---| | -p, --project <path> | Project: a directory, vite config file, or component-explorer.json (default: cwd) | | --filter <pattern> | Filter fixtures by glob pattern | | --accept | Write to baseline instead of current (mutually exclusive with --target) | | --target <dir> | Screenshot output directory (default: .screenshots/current, or .screenshots/baseline with --accept) | | --compare | Compare screenshots after capturing | | --compare-target <dir> | Directory to compare against (default: .screenshots/baseline, or .screenshots/current with --accept) | | --report <dir> | Output report folder with report.json, report.md, and changed screenshots (requires --compare) | | -v, --verbose | Increase log verbosity (-v debug, -vv trace) |

# Capture all fixtures
component-explorer screenshot

# Capture and accept as baseline
component-explorer screenshot --accept

# Capture, then compare against baseline
component-explorer screenshot --compare

# Filter by glob
component-explorer screenshot --filter "Button/*"

screenshot:compare

Compare two screenshot directories (file-level hash comparison).

component-explorer screenshot:compare [options]

| Option | Description | |---|---| | -p, --project <path> | Project directory (default: cwd) | | --baseline <dir> | Baseline screenshots directory (default: .screenshots/baseline) | | --current <dir> | Current screenshots directory (default: .screenshots/current) | | --filter <pattern> | Filter fixtures by glob pattern | | --report <dir> | Output report folder (contains report.json, report.md, and changed screenshots) | | -v, --verbose | Increase log verbosity |

Exits with code 1 if differences are found, 0 otherwise.

# Compare default directories
component-explorer screenshot:compare

# Compare with custom paths
component-explorer screenshot:compare --baseline ./golden --current ./actual

# Generate report folder
component-explorer screenshot:compare --report ./report

screenshot:accept

Promote current screenshots to baseline by copying them from .screenshots/current to .screenshots/baseline.

component-explorer screenshot:accept [options]

| Option | Description | |---|---| | -p, --project <path> | Project directory (default: cwd) | | --filter <pattern> | Filter fixtures by glob pattern | | --screenshot-dir <dir> | Screenshots directory (default: .screenshots) | | -v, --verbose | Increase log verbosity |

# Accept all current screenshots as baseline
component-explorer screenshot:accept

# Accept specific fixtures
component-explorer screenshot:accept --filter "Button/*"

watch

Watch for source changes and automatically re-capture/compare screenshots. Supports both simple mode (single project) and config mode (multiple sessions with git worktrees).

component-explorer watch [options]

| Option | Description | |---|---| | -p, --project <path> | Project: a directory, vite config file, or component-explorer.json (default: cwd) | | -v, --verbose | Increase log verbosity |

In simple mode, starts a Vite dev server and re-captures screenshots on every HMR update. In config mode (when given a component-explorer.json), manages multiple sessions including git worktree-based baselines.

# Watch all fixtures
component-explorer watch

# Watch with config
component-explorer watch -p component-explorer.json

serve

Start or attach to a Component Explorer daemon process. The daemon manages Vite servers and browser sessions in the background.

component-explorer serve -p <config> [options]

| Option | Description | |---|---| | -p, --project, -c <path> | (required) Path to a component-explorer.json config file | | --background | Spawn as a detached background process | | --attach | Attach to a running daemon and stream events | | --kill | Shut down a running daemon | | -v, --verbose | Increase log verbosity |

Without flags, starts a foreground daemon. Combine --background and --attach to ensure a daemon is running and then stream its events.

# Start in foreground
component-explorer serve -p config.json

# Start in background
component-explorer serve -p config.json --background

# Attach to running daemon
component-explorer serve -p config.json --attach

# Ensure daemon + attach
component-explorer serve -p config.json --background --attach

# Kill running daemon
component-explorer serve -p config.json --kill

mcp

Start a Model Context Protocol server over stdio. Auto-starts a daemon if one is not already running.

component-explorer mcp -p <config>

| Option | Description | |---|---| | -p, --project, -c <path> | (required) Path to a component-explorer.json config file |

component-explorer mcp --project config.json

Global Options

All commands support -v / --verbose for increased log output. Use -vv for trace-level logging.