@thepixelhouse/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,249 @@
+# @thepixelhouse/cli
+
+Visual regression testing from the command line. Capture screenshots, diff them against baselines, run regression suites, and manage monitors — all from your terminal or CI pipeline.
+
+## Install
+
+```bash
+npm install -g @thepixelhouse/cli
+```
+
+Or run without installing:
+
+```bash
+npx @thepixelhouse/cli screenshot https://example.com
+```
+
+## Quick start
+
+```bash
+# 1. Create a config file
+pixelhouse init
+
+# 2. Set your API key
+export PIXELHOUSE_API_KEY=ph_live_your_key_here
+
+# 3. Capture your first screenshot
+pixelhouse screenshot https://your-site.com --project prj_xxx
+
+# 4. Promote it to a baseline
+pixelhouse baseline create ss_abc123 --project prj_xxx --url https://your-site.com
+
+# 5. Run a regression test
+pixelhouse regression run --url https://your-site.com --baseline bl_xyz789
+```
+
+## Authentication
+
+The CLI needs an API key. Provide it in any of these ways (highest priority first):
+
+1. **CLI flag:** `--api-key ph_live_xxx`
+2. **Environment variable:** `PIXELHOUSE_API_KEY=ph_live_xxx`
+3. **Config file:** `apiKey` field in `.pixelhouserc.json`
+
+Get your API key from the [dashboard](https://thepixelhouse.co.uk/settings/api-keys).
+
+## Commands
+
+### `pixelhouse screenshot <url>`
+
+Capture a screenshot of a URL.
+
+```bash
+pixelhouse screenshot https://example.com
+pixelhouse screenshot https://example.com --viewport mobile
+pixelhouse screenshot https://example.com --viewport 1440x900 --full-page
+pixelhouse screenshot https://example.com --output ./screenshot.png
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--viewport <preset\|WxH>` | Viewport size (desktop, tablet, mobile, or custom) | `desktop` |
+| `--full-page` | Capture the full scrollable page | `false` |
+| `--project <id>` | Project ID | from config |
+| `--output <path>` | Save PNG to a local file | - |
+| `--wait-for <strategy>` | Load strategy (networkIdle, domContentLoaded, load) | `networkIdle` |
+
+### `pixelhouse compare <screenshot-a> <screenshot-b>`
+
+Compare two screenshots for visual differences.
+
+```bash
+pixelhouse compare ss_abc123 ss_def456
+pixelhouse compare ss_abc123 ss_def456 --threshold 0.5 --output ./diff.png
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--threshold <number>` | Diff threshold percentage (0-100) | `1.0` |
+| `--output <path>` | Save diff image to a local file | - |
+
+### `pixelhouse regression run`
+
+Run visual regression tests against baselines.
+
+**Single URL mode:**
+
+```bash
+pixelhouse regression run --url https://example.com --baseline bl_xyz789
+```
+
+**Config-driven mode** (reads pages from `.pixelhouserc.json`):
+
+```bash
+pixelhouse regression run
+pixelhouse regression run --ci
+pixelhouse regression run --fail-on-diff
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--url <url>` | Single URL to test | - |
+| `--baseline <id>` | Baseline ID to compare against | - |
+| `--threshold <number>` | Diff threshold percentage | `1.0` |
+| `--viewport <preset\|WxH>` | Viewport size | `desktop` |
+| `--ci` | CI mode with exit codes | `false` |
+| `--fail-on-diff` | Non-zero exit on any diff exceeding threshold | `false` |
+
+**Exit codes (CI mode):**
+- `0` — all tests passed
+- `1` — visual regression detected
+- `2` — error (capture failed, network error, etc.)
+
+### `pixelhouse baseline <subcommand>`
+
+Manage screenshot baselines.
+
+```bash
+# List baselines
+pixelhouse baseline list --project prj_xxx
+pixelhouse baseline list --project prj_xxx --branch staging
+
+# Promote a screenshot to baseline
+pixelhouse baseline create ss_abc123 --project prj_xxx --url https://example.com
+pixelhouse baseline create ss_abc123 --project prj_xxx --url https://example.com --branch staging
+
+# Delete a baseline
+pixelhouse baseline delete bl_xyz789
+```
+
+### `pixelhouse monitor <subcommand>`
+
+Manage scheduled visual monitors.
+
+```bash
+# List monitors
+pixelhouse monitor list --project prj_xxx
+
+# Add a monitor (checks every hour)
+pixelhouse monitor add https://example.com --project prj_xxx --every 1h
+
+# Add with custom interval and threshold
+pixelhouse monitor add https://example.com --project prj_xxx --every 30m --threshold 0.5
+
+# Pause / resume / delete
+pixelhouse monitor pause mon_abc123
+pixelhouse monitor resume mon_abc123
+pixelhouse monitor delete mon_abc123
+```
+
+| Interval | Cron equivalent |
+|----------|-----------------|
+| `30m` | `*/30 * * * *` |
+| `1h` | `0 */1 * * *` |
+| `6h` | `0 */6 * * *` |
+| `1d` | `0 0 */1 * *` |
+
+You can also pass a raw cron expression: `--every "0 9 * * 1-5"`.
+
+### `pixelhouse init`
+
+Create a `.pixelhouserc.json` configuration file.
+
+```bash
+pixelhouse init
+pixelhouse init --force  # overwrite existing
+```
+
+## Configuration
+
+Create a `.pixelhouserc.json` in your project root (or run `pixelhouse init`):
+
+```json
+{
+  "apiKey": "ph_live_your_key_here",
+  "apiUrl": "https://api.thepixelhouse.co.uk",
+  "projectId": "prj_xxx",
+  "viewport": "desktop",
+  "threshold": 1.0,
+  "branch": "main",
+  "pages": [
+    {
+      "url": "https://your-site.com",
+      "baselineId": "bl_abc123",
+      "viewport": "desktop",
+      "threshold": 1.0
+    },
+    {
+      "url": "https://your-site.com/pricing",
+      "baselineId": "bl_def456",
+      "viewport": "mobile"
+    }
+  ]
+}
+```
+
+The CLI searches for this file starting from your current directory, walking up to the filesystem root.
+
+## CI/CD integration
+
+### GitHub Actions
+
+```yaml
+- name: Run visual regression tests
+  env:
+    PIXELHOUSE_API_KEY: ${{ secrets.PIXELHOUSE_API_KEY }}
+  run: npx @thepixelhouse/cli regression run --ci
+```
+
+### GitLab CI
+
+```yaml
+visual-regression:
+  script:
+    - npx @thepixelhouse/cli regression run --ci
+  variables:
+    PIXELHOUSE_API_KEY: $PIXELHOUSE_API_KEY
+```
+
+## Global options
+
+These options apply to all commands:
+
+| Option | Description |
+|--------|-------------|
+| `--api-key <key>` | API key (overrides env var and config) |
+| `--api-url <url>` | API base URL |
+| `--json` | Output results as JSON |
+| `--no-color` | Disable coloured output |
+| `-v, --version` | Print version |
+| `-h, --help` | Print help |
+
+## JSON output
+
+Pass `--json` to any command for machine-readable output:
+
+```bash
+pixelhouse screenshot https://example.com --json | jq '.id'
+pixelhouse regression run --json | jq '.summary'
+```
+
+## Links
+
+- [Documentation](https://thepixelhouse.co.uk/docs)
+- [Dashboard](https://thepixelhouse.co.uk)
+- [API reference](https://api.thepixelhouse.co.uk/docs)
+
+## Licence
+
+MIT - ToggleKit Ltd

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thepixelhouse/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Visual regression testing CLI for The Pixel House. Capture screenshots, diff them, manage baselines, and run monitors from your terminal.",
   "license": "MIT",
   "author": "ToggleKit Ltd <hello@thepixelhouse.co.uk>",
@@ -29,7 +29,8 @@
   },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "engines": {
     "node": ">=18.0.0"