CLI Reference

peek provides six commands: snap, check, dev, scene, pool, and clean.

`peek snap`

Take a screenshot of a URL or native app window.

peek snap &lt;url&gt;
peek snap --app &lt;name&gt;
peek snap --pid &lt;number&gt;

Arguments

Argument	Description
`[target]`	URL to screenshot (required for web capture)

Flags

Flag	Default	Description
`-o, --output <path>`	Auto-generated in `/tmp/peek/`	Output file path
`-v, --viewport <size>`	`1280x720`	Viewport size (WIDTHxHEIGHT)
`--full-page`	`false`	Capture full scrollable page
`--wait <ms>`	`0`	Wait time after page load
`--wait-until <event>`	`networkidle2`	Puppeteer waitUntil event (`load`, `domcontentloaded`, `networkidle0`, `networkidle2`)
`-f, --format <format>`	`path`	Output format: `path` or `json`
`--checks`	`false`	Run layout checks alongside screenshot
`--checks-only <names>`	All	Only run specific checks (comma-separated)
`--checks-ignore <selectors>`	None	Ignore elements matching selectors (comma-separated)
`--no-pool`	Pool enabled	Disable browser pooling (launch fresh browser)
`--setup <script>`	None	Setup script to run before capture (e.g., login)
`--app <name>`	None	Capture native app window by name (macOS)
`--pid <number>`	None	Capture native app window by PID (macOS)

Examples

# Basic screenshot
peek snap http://localhost:3000

# Save to specific path with custom viewport
peek snap http://localhost:3000 -o ./screenshot.png -v 1920x1080

# Full-page screenshot
peek snap http://localhost:3000 --full-page

# Screenshot + layout checks in one pass
peek snap http://localhost:3000 --checks --format json

# With login setup script
peek snap http://localhost:3000/dashboard --setup ./login.ts

# Native macOS app
peek snap --app "Finder" -o /tmp/finder.png

# Fresh browser (no pooling)
peek snap http://localhost:3000 --no-pool

Output

By default, prints the absolute file path to stdout:

/tmp/peek/snap_2025-01-15_a3f2c1.png

With --format json or --checks:

&#123;
  "path": "/tmp/peek/snap_2025-01-15_a3f2c1.png",
  "target": "http://localhost:3000",
  "viewport": &#123; "width": 1280, "height": 720 &#125;,
  "timestamp": "2025-01-15T10:30:00.000Z",
  "durationMs": 1200
&#125;

`peek check`

Run layout checks on one or more URLs.

peek check &lt;urls...&gt;

Arguments

Argument	Description
`<urls...>`	One or more URLs to check

Flags

Flag	Default	Description
`-c, --config <path>`	None	Path to config file (`peek.config.js`)
`-f, --format <format>`	`text`	Output format: `text`, `json`, `junit`
`-o, --only <checks>`	All	Only run specific checks (comma-separated)
`-i, --ignore <selectors>`	None	Ignore elements matching selectors (comma-separated)
`-v, --viewport <size>`	`1280x720`	Viewport size (supports multiple: `1920x1080,375x667`)
`--fail-on <severity>`	`error`	Exit with error if issues of this severity found: `error`, `warning`
`--headed`	`false`	Run browser in headed mode (visible)
`--mobile`	`false`	Test mobile viewports (375x667 portrait + 667x375 landscape)
`--wait-for-hydration`	`false`	Wait for SPA hydration before checking
`--framework <name>`	Auto-detect	Specify framework for hydration detection
`--setup <script>`	None	Setup script to run before checks (e.g., login)

Examples

# Basic check
peek check http://localhost:3000

# Multiple URLs with JSON output
peek check http://localhost:3000 http://localhost:3000/about --format json

# Only run specific checks
peek check http://localhost:3000 --only overflow,clickability

# Multiple viewports
peek check http://localhost:3000 -v 1920x1080,375x667

# Mobile testing
peek check http://localhost:3000 --mobile

# With config file
peek check http://localhost:3000 -c peek.config.js

# JUnit output for CI
peek check http://localhost:3000 --format junit &gt; results.xml

# Fail on warnings too
peek check http://localhost:3000 --fail-on warning

# With authentication
peek check http://localhost:3000/dashboard --setup ./login.ts

`peek dev`

Auto-detect framework, start dev server, and check routes for layout issues.

peek dev

Flags

Flag	Default	Description
`-r, --routes <routes>`	`/`	Comma-separated routes to check
`-p, --port <port>`	Auto (framework default)	Dev server port
`-f, --format <format>`	`text`	Output format: `text`, `json`, `junit`
`-o, --only <checks>`	All	Only run specific checks (comma-separated)
`-i, --ignore <selectors>`	None	Ignore elements matching selectors (comma-separated)
`-v, --viewport <size>`	`1280x720`	Viewport size
`--framework <name>`	Auto-detect	Manual framework override (`nextjs`, `sveltekit`, `vite`, `create-react-app`, `remix`, `astro`, `nuxt`)
`--wait-for-hydration`	Auto (based on framework)	Force wait for hydration
`--no-wait-for-hydration`	-	Skip hydration wait
`--no-start-server`	-	Use existing dev server instead of starting one
`--fail-on <severity>`	`error`	Exit with error if issues found: `error`, `warning`
`--headed`	`false`	Show browser
`--mobile`	`false`	Test mobile viewports

Examples

# Auto-detect everything, check root route
peek dev

# Check multiple routes
peek dev --routes /,/about,/settings,/dashboard

# Use existing dev server
peek dev --no-start-server --port 3000

# Force framework
peek dev --framework sveltekit --routes /,/about

Supported Frameworks

Next.js, SvelteKit, Vite, Create React App, Remix, Astro, Nuxt.

`peek scene`

Run spatial checks on a scene manifest JSON for engine-based apps (Bevy, Unity).

peek scene &lt;manifest&gt;

Arguments

Argument	Description
`<manifest>`	Path to scene manifest JSON file

Flags

Flag	Default	Description
`-f, --format <format>`	`text`	Output format: `text`, `json`, `junit`
`-o, --only <checks>`	All	Only run specific checks (comma-separated: `entity-overlap`, `entity-bounds`, `entity-size`, `entity-visibility`)
`--fail-on <severity>`	`error`	Exit with error if issues of this severity found

Examples

# Run all scene checks
peek scene manifest.json

# JSON output for programmatic consumption
peek scene manifest.json --format json

# Only check overlaps
peek scene manifest.json --only entity-overlap

`peek pool`

Manage the persistent browser pool.

`peek pool status`

Show the current pool status including PID, start time, idle time, and WebSocket endpoint.

peek pool status

`peek pool kill`

Kill the pooled browser and clean up the pool file.

peek pool kill

`peek clean`

Remove temporary screenshot files from /tmp/peek/.

peek clean

Exit Codes

Code	Meaning
0	Success (no errors, or issues below `--fail-on` threshold)
1	Failure (check errors, runtime errors)
2	Invalid arguments