# @vscode/component-explorer-cli

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

## Installation

```bash
npm install @vscode/component-explorer-cli
```

The binary is available as `component-explorer`.

## Commands

### `screenshot`

Capture screenshots of all fixtures using a headless browser.

```bash
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) |

```bash
# 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).

```bash
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.

```bash
# 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`.

```bash
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 |

```bash
# 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).

```bash
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.

```bash
# 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.

```bash
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.

```bash
# 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](https://modelcontextprotocol.io/) server over stdio. Auto-starts a daemon if one is not already running.

```bash
component-explorer mcp -p <config>
```

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

```bash
component-explorer mcp --project config.json
```

## Global Options

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

All commands also support `--log-file <path>` to append log messages to a file. This works in combination with `-v`/`-vv` to control what gets written. Multiple processes can safely append to the same file. Log entries include timestamp, log level, process type, and PID:

```
2024-01-15T10:30:45.123Z [DEBUG] [serve] [pid:12345] Server started on port 5173
```

When the MCP server spawns a daemon, it inherits the verbosity level and log file path.