@thepixelhouse/cli 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,851 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command as Command7 } from "commander";
+import chalk7 from "chalk";
+
+// src/commands/screenshot.ts
+import { Command } from "commander";
+import * as fs2 from "fs";
+import * as path2 from "path";
+import ora from "ora";
+
+// src/api/client.ts
+var ApiClient = class {
+  baseUrl;
+  apiKey;
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+  }
+  // ─── Screenshots ──────────────────────────────────
+  async captureScreenshot(params) {
+    return this.post("/v1/screenshots?sync=true", params);
+  }
+  async getScreenshot(id) {
+    return this.get(`/v1/screenshots/${id}`);
+  }
+  async downloadScreenshotImage(id) {
+    return this.getBlob(`/v1/screenshots/${id}/image`);
+  }
+  // ─── Comparisons ──────────────────────────────────
+  async compareScreenshots(params) {
+    return this.post("/v1/comparisons", params);
+  }
+  async getComparison(id) {
+    return this.get(`/v1/comparisons/${id}`);
+  }
+  async downloadDiffImage(id) {
+    return this.getBlob(`/v1/comparisons/${id}/diff`);
+  }
+  // ─── Baselines ────────────────────────────────────
+  async createBaseline(params) {
+    return this.post("/v1/baselines", params);
+  }
+  async listBaselines(params) {
+    const query = new URLSearchParams({ projectId: params.projectId });
+    if (params.branch) query.set("branch", params.branch);
+    if (params.cursor) query.set("cursor", params.cursor);
+    if (params.limit !== void 0) query.set("limit", String(params.limit));
+    return this.getPaginated(`/v1/baselines?${query.toString()}`);
+  }
+  async deleteBaseline(id) {
+    return this.delete(`/v1/baselines/${id}`);
+  }
+  // ─── Tests ────────────────────────────────────────
+  async runTest(params) {
+    return this.post("/v1/tests/run", params);
+  }
+  // ─── Monitors ─────────────────────────────────────
+  async listMonitors(params) {
+    const query = new URLSearchParams({ projectId: params.projectId });
+    if (params.cursor) query.set("cursor", params.cursor);
+    if (params.limit !== void 0) query.set("limit", String(params.limit));
+    return this.getPaginated(`/v1/monitors?${query.toString()}`);
+  }
+  async createMonitor(params) {
+    return this.post("/v1/monitors", params);
+  }
+  async updateMonitor(id, params) {
+    return this.patch(`/v1/monitors/${id}`, params);
+  }
+  async deleteMonitor(id) {
+    return this.delete(`/v1/monitors/${id}`);
+  }
+  // ─── Internal helpers ─────────────────────────────
+  async request(path5, init) {
+    const url = `${this.baseUrl}${path5}`;
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    headers.set("Accept", "application/json");
+    headers.set("User-Agent", "@pixelhouse/cli");
+    return fetch(url, { ...init, headers });
+  }
+  async get(path5) {
+    try {
+      const res = await this.request(path5, { method: "GET" });
+      const body = await res.json();
+      if (!res.ok || "error" in body) {
+        const errBody = body;
+        return { success: false, error: errBody.error?.message ?? `API returned ${res.status}` };
+      }
+      return { success: true, data: body.data };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error" };
+    }
+  }
+  async getPaginated(path5) {
+    try {
+      const res = await this.request(path5, { method: "GET" });
+      const body = await res.json();
+      if (!res.ok || "error" in body) {
+        const errBody = body;
+        return { success: false, error: errBody.error?.message ?? `API returned ${res.status}` };
+      }
+      return { success: true, data: body };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error" };
+    }
+  }
+  async post(path5, body) {
+    try {
+      const res = await this.request(path5, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+      const json = await res.json();
+      if (!res.ok || "error" in json) {
+        const errBody = json;
+        return { success: false, error: errBody.error?.message ?? `API returned ${res.status}` };
+      }
+      return { success: true, data: json.data };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error" };
+    }
+  }
+  async patch(path5, body) {
+    try {
+      const res = await this.request(path5, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+      const json = await res.json();
+      if (!res.ok || "error" in json) {
+        const errBody = json;
+        return { success: false, error: errBody.error?.message ?? `API returned ${res.status}` };
+      }
+      return { success: true, data: json.data };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error" };
+    }
+  }
+  async delete(path5) {
+    try {
+      const res = await this.request(path5, { method: "DELETE" });
+      const json = await res.json();
+      if (!res.ok || "error" in json) {
+        const errBody = json;
+        return { success: false, error: errBody.error?.message ?? `API returned ${res.status}` };
+      }
+      return { success: true, data: json.data };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error" };
+    }
+  }
+  async getBlob(path5) {
+    try {
+      const res = await this.request(path5, { method: "GET" });
+      if (!res.ok) {
+        let message = `API returned ${res.status}`;
+        try {
+          const errJson = await res.json();
+          if (errJson.error?.message) message = errJson.error.message;
+        } catch {
+        }
+        return { success: false, error: message };
+      }
+      const buffer = await res.arrayBuffer();
+      return { success: true, data: buffer };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error" };
+    }
+  }
+};
+
+// src/config/loader.ts
+import * as fs from "fs";
+import * as path from "path";
+var CONFIG_FILE_NAME = ".pixelhouserc.json";
+function findConfigFile(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (true) {
+    const candidate = path.join(dir, CONFIG_FILE_NAME);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    if (dir === root) {
+      return null;
+    }
+    dir = path.dirname(dir);
+  }
+}
+function readConfigFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function resolveConfig(flags) {
+  const configPath = findConfigFile(process.cwd());
+  const fileConfig = configPath ? readConfigFile(configPath) ?? {} : {};
+  const envApiKey = process.env["PIXELHOUSE_API_KEY"];
+  const envApiUrl = process.env["PIXELHOUSE_API_URL"];
+  return {
+    ...fileConfig,
+    apiKey: flags.apiKey ?? envApiKey ?? fileConfig.apiKey,
+    apiUrl: flags.apiUrl ?? envApiUrl ?? fileConfig.apiUrl ?? "https://api.thepixelhouse.co.uk"
+  };
+}
+function requireApiKey(config) {
+  if (!config.apiKey) {
+    throw new Error(
+      "No API key found. Provide one via --api-key, PIXELHOUSE_API_KEY env var, or .pixelhouserc.json"
+    );
+  }
+  return config.apiKey;
+}
+
+// src/lib/errors.ts
+var EXIT_CODES = {
+  SUCCESS: 0,
+  REGRESSION: 1,
+  ERROR: 2
+};
+var CliError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = EXIT_CODES.ERROR) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+};
+function toCliError(err) {
+  if (err instanceof CliError) {
+    return err;
+  }
+  if (err instanceof Error) {
+    return new CliError(err.message, EXIT_CODES.ERROR);
+  }
+  return new CliError(String(err), EXIT_CODES.ERROR);
+}
+function handleError(err) {
+  const cliError = toCliError(err);
+  if (cliError.message) {
+    process.stderr.write(`Error: ${cliError.message}
+`);
+  }
+  process.exit(cliError.exitCode);
+}
+
+// src/lib/output.ts
+import chalk from "chalk";
+function formatJson(data) {
+  return JSON.stringify(data, null, 2);
+}
+function formatTable(rows, columns) {
+  if (rows.length === 0) {
+    return "  No results.";
+  }
+  const cols = columns ?? Object.keys(rows[0]);
+  const widths = {};
+  for (const col of cols) {
+    widths[col] = col.length;
+  }
+  for (const row of rows) {
+    for (const col of cols) {
+      const value = String(row[col] ?? "");
+      widths[col] = Math.max(widths[col] ?? 0, value.length);
+    }
+  }
+  const header = cols.map((col) => col.toUpperCase().padEnd(widths[col] ?? 0)).join("  ");
+  const separator = cols.map((col) => "-".repeat(widths[col] ?? 0)).join("  ");
+  const body = rows.map(
+    (row) => cols.map((col) => String(row[col] ?? "").padEnd(widths[col] ?? 0)).join("  ")
+  );
+  return [
+    chalk.bold(header),
+    chalk.dim(separator),
+    ...body
+  ].join("\n");
+}
+function formatSuccess(message) {
+  return chalk.green(`${chalk.bold("OK")} ${message}`);
+}
+function formatError(message) {
+  return chalk.red(`${chalk.bold("Error")} ${message}`);
+}
+function formatInfo(label, value) {
+  return `${chalk.dim(label + ":")} ${value}`;
+}
+function output(text, jsonData, jsonMode) {
+  if (jsonMode) {
+    process.stdout.write(formatJson(jsonData) + "\n");
+  } else {
+    process.stdout.write(text + "\n");
+  }
+}
+
+// src/commands/screenshot.ts
+function createScreenshotCommand() {
+  const cmd = new Command("screenshot").description("Capture a screenshot of a URL").argument("<url>", "URL to capture").option("--viewport <viewport>", "viewport preset or WxH (e.g. desktop, 1440x900)", "desktop").option("--full-page", "capture the full scrollable page", false).option("--project <id>", "project ID to associate the screenshot with").option("--output <path>", "save the screenshot PNG to a local file").option("--wait-for <strategy>", "page load strategy: networkIdle, domContentLoaded, load", "networkIdle").action(async (url, opts) => {
+    const parentOpts = cmd.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora("Capturing screenshot...").start();
+    const result = await client.captureScreenshot({
+      url,
+      viewport: opts.viewport,
+      fullPage: opts.fullPage,
+      projectId: opts.project,
+      waitFor: opts.waitFor
+    });
+    if (!result.success) {
+      spinner?.fail("Screenshot capture failed");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    const screenshot = result.data;
+    if (opts.output) {
+      const downloadResult = await client.downloadScreenshotImage(screenshot.id);
+      if (!downloadResult.success) {
+        spinner?.warn("Screenshot captured but download failed");
+        throw new CliError(`Failed to download image: ${downloadResult.error}`, EXIT_CODES.ERROR);
+      }
+      const outputPath = path2.resolve(opts.output);
+      fs2.writeFileSync(outputPath, Buffer.from(downloadResult.data));
+      spinner?.succeed("Screenshot captured and saved");
+      const text2 = [
+        formatSuccess("Screenshot captured and saved"),
+        formatInfo("ID", screenshot.id),
+        formatInfo("URL", screenshot.url),
+        formatInfo("Viewport", `${screenshot.viewport} (${String(screenshot.viewportWidth)}x${String(screenshot.viewportHeight ?? "auto")})`),
+        formatInfo("Dimensions", `${String(screenshot.width ?? "?")}x${String(screenshot.height ?? "?")}`),
+        formatInfo("Image URL", screenshot.imageUrl),
+        formatInfo("Saved to", outputPath)
+      ].join("\n");
+      output(text2, screenshot, jsonMode);
+      return;
+    }
+    spinner?.succeed("Screenshot captured");
+    const text = [
+      formatSuccess("Screenshot captured"),
+      formatInfo("ID", screenshot.id),
+      formatInfo("URL", screenshot.url),
+      formatInfo("Viewport", `${screenshot.viewport} (${String(screenshot.viewportWidth)}x${String(screenshot.viewportHeight ?? "auto")})`),
+      formatInfo("Dimensions", `${String(screenshot.width ?? "?")}x${String(screenshot.height ?? "?")}`),
+      formatInfo("Image URL", screenshot.imageUrl)
+    ].join("\n");
+    output(text, screenshot, jsonMode);
+  });
+  return cmd;
+}
+
+// src/commands/compare.ts
+import { Command as Command2 } from "commander";
+import * as fs3 from "fs";
+import * as path3 from "path";
+import ora2 from "ora";
+import chalk2 from "chalk";
+function createCompareCommand() {
+  const cmd = new Command2("compare").description("Compare two screenshots for visual differences").argument("<screenshot-a>", "ID of the first screenshot (before)").argument("<screenshot-b>", "ID of the second screenshot (after)").option("--threshold <number>", "diff threshold percentage (0-100)", "1.0").option("--output <path>", "save the diff image to a local file").action(async (screenshotA, screenshotB, opts) => {
+    const parentOpts = cmd.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const threshold = parseFloat(opts.threshold);
+    if (Number.isNaN(threshold) || threshold < 0 || threshold > 100) {
+      throw new CliError("Threshold must be a number between 0 and 100", EXIT_CODES.ERROR);
+    }
+    const spinner = jsonMode ? null : ora2("Comparing screenshots...").start();
+    const result = await client.compareScreenshots({
+      screenshotAId: screenshotA,
+      screenshotBId: screenshotB,
+      threshold
+    });
+    if (!result.success) {
+      spinner?.fail("Comparison failed");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    const comparison = result.data;
+    if (opts.output && comparison.diffImageUrl) {
+      const downloadResult = await client.downloadDiffImage(comparison.id);
+      if (downloadResult.success) {
+        const outputPath = path3.resolve(opts.output);
+        fs3.writeFileSync(outputPath, Buffer.from(downloadResult.data));
+      }
+    }
+    spinner?.succeed("Comparison complete");
+    const statusLabel = comparison.status === "pass" ? chalk2.green("PASS") : comparison.status === "fail" ? chalk2.red("FAIL") : chalk2.yellow(comparison.status.toUpperCase());
+    const lines = [
+      `${chalk2.bold("Result:")} ${statusLabel}`,
+      formatInfo("Comparison ID", comparison.id),
+      formatInfo("Diff percentage", comparison.diffPercentage !== null ? `${String(comparison.diffPercentage)}%` : "N/A"),
+      formatInfo("SSIM score", comparison.ssimScore !== null ? String(comparison.ssimScore) : "N/A"),
+      formatInfo("Threshold", `${String(comparison.threshold)}%`)
+    ];
+    if (comparison.diffImageUrl) {
+      lines.push(formatInfo("Diff image", comparison.diffImageUrl));
+    }
+    if (opts.output && comparison.diffImageUrl) {
+      lines.push(formatInfo("Saved to", path3.resolve(opts.output)));
+    }
+    output(lines.join("\n"), comparison, jsonMode);
+  });
+  return cmd;
+}
+
+// src/commands/regression.ts
+import { Command as Command3 } from "commander";
+import ora3 from "ora";
+import chalk3 from "chalk";
+function toTableRow(url, result) {
+  return {
+    url,
+    status: result.status,
+    diff: result.diffPercentage !== null ? `${String(result.diffPercentage)}%` : "N/A",
+    ssim: result.ssimScore !== null ? String(result.ssimScore) : "N/A",
+    threshold: `${String(result.threshold)}%`
+  };
+}
+function createRegressionCommand() {
+  const regression = new Command3("regression").description("Visual regression testing commands");
+  regression.command("run").description("Run visual regression tests").option("--url <url>", "single URL to test").option("--baseline <id>", "baseline ID to compare against").option("--threshold <number>", "diff threshold percentage", "1.0").option("--viewport <viewport>", "viewport preset or WxH", "desktop").option("--ci", "CI mode: exit with code 0 (pass), 1 (regression), 2 (error)", false).option("--fail-on-diff", "exit with non-zero code if any diff exceeds threshold", false).action(async (opts) => {
+    const parentOpts = regression.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const threshold = parseFloat(opts.threshold);
+    if (Number.isNaN(threshold) || threshold < 0 || threshold > 100) {
+      throw new CliError("Threshold must be a number between 0 and 100", EXIT_CODES.ERROR);
+    }
+    const pages = buildPageList(opts, config);
+    if (pages.length === 0) {
+      throw new CliError(
+        "No pages to test. Provide --url and --baseline, or define pages in .pixelhouserc.json",
+        EXIT_CODES.ERROR
+      );
+    }
+    const spinner = jsonMode ? null : ora3(`Running ${String(pages.length)} regression test(s)...`).start();
+    const rows = [];
+    const results = [];
+    let hasFailure = false;
+    let hasError = false;
+    for (const page of pages) {
+      try {
+        const result = await client.runTest({
+          url: page.url,
+          baselineId: page.baselineId,
+          viewport: page.viewport ?? opts.viewport,
+          threshold: page.threshold ?? threshold
+        });
+        if (!result.success) {
+          hasError = true;
+          rows.push({
+            url: page.url,
+            status: "error",
+            diff: "N/A",
+            ssim: "N/A",
+            threshold: `${String(page.threshold ?? threshold)}%`
+          });
+          continue;
+        }
+        results.push(result.data);
+        rows.push(toTableRow(page.url, result.data));
+        if (result.data.status === "fail") {
+          hasFailure = true;
+        }
+        if (result.data.status === "error") {
+          hasError = true;
+        }
+      } catch {
+        hasError = true;
+        rows.push({
+          url: page.url,
+          status: "error",
+          diff: "N/A",
+          ssim: "N/A",
+          threshold: `${String(page.threshold ?? threshold)}%`
+        });
+      }
+    }
+    const colouredRows = rows.map((row) => ({
+      ...row,
+      status: row.status === "pass" ? chalk3.green("pass") : row.status === "fail" ? chalk3.red("fail") : chalk3.yellow(row.status)
+    }));
+    spinner?.stop();
+    const summary = hasFailure ? formatError(`${String(rows.filter((r) => r.status === "fail" || r.status === chalk3.red("fail")).length)} test(s) failed`) : hasError ? formatError(`${String(rows.filter((r) => r.status === "error" || r.status === chalk3.yellow("error")).length)} test(s) errored`) : formatSuccess(`All ${String(rows.length)} test(s) passed`);
+    const tableOutput = formatTable(colouredRows, ["url", "status", "diff", "ssim", "threshold"]);
+    const text = `${tableOutput}
+
+${summary}`;
+    output(text, { results, summary: { total: rows.length, passed: rows.filter((r) => r.status === "pass").length, failed: rows.filter((r) => r.status === "fail").length, errored: rows.filter((r) => r.status === "error").length } }, jsonMode);
+    if (opts.ci || opts.failOnDiff) {
+      if (hasError) {
+        process.exit(EXIT_CODES.ERROR);
+      }
+      if (hasFailure) {
+        process.exit(EXIT_CODES.REGRESSION);
+      }
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+  });
+  return regression;
+}
+function buildPageList(opts, config) {
+  if (opts.url && opts.baseline) {
+    return [
+      {
+        url: opts.url,
+        baselineId: opts.baseline,
+        viewport: opts.viewport,
+        threshold: parseFloat(opts.threshold)
+      }
+    ];
+  }
+  if (config.pages && config.pages.length > 0) {
+    return config.pages.filter((p) => !!p.baselineId).map((page) => ({
+      url: page.url,
+      baselineId: page.baselineId,
+      viewport: page.viewport ?? config.viewport,
+      threshold: page.threshold ?? config.threshold
+    }));
+  }
+  return [];
+}
+
+// src/commands/baseline.ts
+import { Command as Command4 } from "commander";
+import ora4 from "ora";
+import chalk4 from "chalk";
+function createBaselineCommand() {
+  const baseline = new Command4("baseline").description("Manage screenshot baselines");
+  baseline.command("list").description("List baselines for a project").requiredOption("--project <id>", "project ID").option("--branch <name>", "filter by branch name").option("--limit <number>", "max results to return", "25").action(async (opts) => {
+    const parentOpts = baseline.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora4("Fetching baselines...").start();
+    const result = await client.listBaselines({
+      projectId: opts.project,
+      branch: opts.branch,
+      limit: parseInt(opts.limit, 10)
+    });
+    if (!result.success) {
+      spinner?.fail("Failed to fetch baselines");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed(`Found ${String(result.data.data.length)} baseline(s)`);
+    const rows = result.data.data.map((b) => ({
+      id: b.id,
+      url: b.url,
+      viewport: b.viewport,
+      branch: b.branch,
+      active: b.isActive ? chalk4.green("yes") : chalk4.dim("no"),
+      created: b.createdAt
+    }));
+    const tableText = formatTable(rows, ["id", "url", "viewport", "branch", "active", "created"]);
+    output(tableText, result.data, jsonMode);
+  });
+  baseline.command("create").description("Promote a screenshot to a baseline").argument("<screenshot-id>", "screenshot ID to promote").requiredOption("--project <id>", "project ID").requiredOption("--url <url>", "page URL the baseline represents").option("--viewport <viewport>", "viewport for this baseline", "desktop").option("--branch <name>", "branch name", "main").action(async (screenshotId, opts) => {
+    const parentOpts = baseline.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora4("Creating baseline...").start();
+    const result = await client.createBaseline({
+      screenshotId,
+      projectId: opts.project,
+      url: opts.url,
+      viewport: opts.viewport,
+      branch: opts.branch
+    });
+    if (!result.success) {
+      spinner?.fail("Failed to create baseline");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed("Baseline created");
+    const text = [
+      formatSuccess("Baseline created"),
+      formatInfo("ID", result.data.id),
+      formatInfo("URL", result.data.url),
+      formatInfo("Viewport", result.data.viewport),
+      formatInfo("Branch", result.data.branch)
+    ].join("\n");
+    output(text, result.data, jsonMode);
+  });
+  baseline.command("delete").description("Delete a baseline").argument("<id>", "baseline ID to delete").action(async (id) => {
+    const parentOpts = baseline.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora4("Deleting baseline...").start();
+    const result = await client.deleteBaseline(id);
+    if (!result.success) {
+      spinner?.fail("Failed to delete baseline");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed("Baseline deleted");
+    const text = formatSuccess(`Baseline ${id} deleted`);
+    output(text, { id, deleted: true }, jsonMode);
+  });
+  return baseline;
+}
+
+// src/commands/monitor.ts
+import { Command as Command5 } from "commander";
+import ora5 from "ora";
+import chalk5 from "chalk";
+function intervalToCron(interval) {
+  if (interval.includes(" ")) {
+    return interval;
+  }
+  const match = /^(\d+)(m|h|d)$/i.exec(interval);
+  if (!match) {
+    return interval;
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "m":
+      return `*/${String(value)} * * * *`;
+    case "h":
+      return `0 */${String(value)} * * *`;
+    case "d":
+      return `0 0 */${String(value)} * *`;
+    default:
+      return interval;
+  }
+}
+function createMonitorCommand() {
+  const monitor = new Command5("monitor").description("Manage scheduled visual monitors");
+  monitor.command("list").description("List monitors for a project").requiredOption("--project <id>", "project ID").option("--limit <number>", "max results to return", "25").action(async (opts) => {
+    const parentOpts = monitor.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora5("Fetching monitors...").start();
+    const result = await client.listMonitors({
+      projectId: opts.project,
+      limit: parseInt(opts.limit, 10)
+    });
+    if (!result.success) {
+      spinner?.fail("Failed to fetch monitors");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed(`Found ${String(result.data.data.length)} monitor(s)`);
+    const rows = result.data.data.map((m) => ({
+      id: m.id,
+      url: m.url,
+      viewport: m.viewport,
+      schedule: m.cronExpression,
+      threshold: `${String(m.threshold)}%`,
+      active: m.isActive ? chalk5.green("yes") : chalk5.dim("no"),
+      lastRun: m.lastRunAt ?? "never",
+      lastStatus: m.lastStatus ?? "-"
+    }));
+    const tableText = formatTable(rows, ["id", "url", "viewport", "schedule", "threshold", "active", "lastRun", "lastStatus"]);
+    output(tableText, result.data, jsonMode);
+  });
+  monitor.command("add").description("Add a new visual monitor for a URL").argument("<url>", "URL to monitor").requiredOption("--project <id>", "project ID").option("--every <interval>", "check interval (e.g. 30m, 1h, 6h)", "1h").option("--threshold <number>", "diff threshold percentage", "1.0").option("--viewport <viewport>", "viewport preset or WxH", "desktop").action(async (url, opts) => {
+    const parentOpts = monitor.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const threshold = parseFloat(opts.threshold);
+    if (Number.isNaN(threshold) || threshold < 0 || threshold > 100) {
+      throw new CliError("Threshold must be a number between 0 and 100", EXIT_CODES.ERROR);
+    }
+    const cronExpression = intervalToCron(opts.every);
+    const spinner = jsonMode ? null : ora5("Creating monitor...").start();
+    const result = await client.createMonitor({
+      projectId: opts.project,
+      url,
+      viewport: opts.viewport,
+      cronExpression,
+      threshold
+    });
+    if (!result.success) {
+      spinner?.fail("Failed to create monitor");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed("Monitor created");
+    const text = [
+      formatSuccess("Monitor created"),
+      formatInfo("ID", result.data.id),
+      formatInfo("URL", result.data.url),
+      formatInfo("Schedule", result.data.cronExpression),
+      formatInfo("Threshold", `${String(result.data.threshold)}%`),
+      formatInfo("Viewport", result.data.viewport)
+    ].join("\n");
+    output(text, result.data, jsonMode);
+  });
+  monitor.command("pause").description("Pause a monitor").argument("<id>", "monitor ID to pause").action(async (id) => {
+    const parentOpts = monitor.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora5("Pausing monitor...").start();
+    const result = await client.updateMonitor(id, { isActive: false });
+    if (!result.success) {
+      spinner?.fail("Failed to pause monitor");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed("Monitor paused");
+    const text = formatSuccess(`Monitor ${id} paused`);
+    output(text, result.data, jsonMode);
+  });
+  monitor.command("resume").description("Resume a paused monitor").argument("<id>", "monitor ID to resume").action(async (id) => {
+    const parentOpts = monitor.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora5("Resuming monitor...").start();
+    const result = await client.updateMonitor(id, { isActive: true });
+    if (!result.success) {
+      spinner?.fail("Failed to resume monitor");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed("Monitor resumed");
+    const text = formatSuccess(`Monitor ${id} resumed`);
+    output(text, result.data, jsonMode);
+  });
+  monitor.command("delete").description("Delete a monitor").argument("<id>", "monitor ID to delete").action(async (id) => {
+    const parentOpts = monitor.parent?.opts();
+    const config = resolveConfig({
+      apiKey: parentOpts?.apiKey,
+      apiUrl: parentOpts?.apiUrl
+    });
+    const jsonMode = parentOpts?.json ?? false;
+    const apiKey = requireApiKey(config);
+    const client = new ApiClient(config.apiUrl ?? "https://api.thepixelhouse.co.uk", apiKey);
+    const spinner = jsonMode ? null : ora5("Deleting monitor...").start();
+    const result = await client.deleteMonitor(id);
+    if (!result.success) {
+      spinner?.fail("Failed to delete monitor");
+      throw new CliError(result.error, EXIT_CODES.ERROR);
+    }
+    spinner?.succeed("Monitor deleted");
+    const text = formatSuccess(`Monitor ${id} deleted`);
+    output(text, { id, deleted: true }, jsonMode);
+  });
+  return monitor;
+}
+
+// src/commands/init.ts
+import { Command as Command6 } from "commander";
+import * as fs4 from "fs";
+import * as path4 from "path";
+import chalk6 from "chalk";
+var DEFAULT_CONFIG = {
+  apiUrl: "https://api.thepixelhouse.co.uk",
+  viewport: "desktop",
+  threshold: 1,
+  branch: "main",
+  pages: []
+};
+function createInitCommand() {
+  const cmd = new Command6("init").description("Create a .pixelhouserc.json configuration file").option("--force", "overwrite existing configuration file", false).action(async (opts) => {
+    const parentOpts = cmd.parent?.opts();
+    const jsonMode = parentOpts?.json ?? false;
+    const configPath = path4.join(process.cwd(), CONFIG_FILE_NAME);
+    if (fs4.existsSync(configPath) && !opts.force) {
+      throw new CliError(
+        `${CONFIG_FILE_NAME} already exists. Use --force to overwrite.`,
+        EXIT_CODES.ERROR
+      );
+    }
+    const config = { ...DEFAULT_CONFIG };
+    const apiKey = parentOpts?.apiKey ?? process.env["PIXELHOUSE_API_KEY"];
+    if (apiKey) {
+      config.apiKey = apiKey;
+    }
+    fs4.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    const text = [
+      formatSuccess("Configuration file created"),
+      formatInfo("Path", configPath),
+      "",
+      chalk6.dim("Next steps:"),
+      chalk6.dim(`  1. Add your API key to ${CONFIG_FILE_NAME} or set PIXELHOUSE_API_KEY`),
+      chalk6.dim('  2. Add pages to the "pages" array for regression testing'),
+      chalk6.dim('  3. Run "pixelhouse screenshot <url>" to capture your first screenshot')
+    ].join("\n");
+    output(text, { path: configPath, config }, jsonMode);
+  });
+  return cmd;
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+function createProgram() {
+  const program2 = new Command7();
+  program2.name("pixelhouse").description("Visual regression testing CLI for The Pixel House").version(VERSION, "-v, --version").option("--api-key <key>", "API key (overrides PIXELHOUSE_API_KEY env var)").option("--api-url <url>", "API base URL (default: https://api.thepixelhouse.co.uk)").option("--json", "output results as JSON", false).option("--no-color", "disable coloured output").hook("preAction", (_thisCommand, actionCommand) => {
+    const rootOpts = actionCommand.optsWithGlobals();
+    if (rootOpts.color === false) {
+      chalk7.level = 0;
+    }
+  });
+  program2.addCommand(createScreenshotCommand());
+  program2.addCommand(createCompareCommand());
+  program2.addCommand(createRegressionCommand());
+  program2.addCommand(createBaselineCommand());
+  program2.addCommand(createMonitorCommand());
+  program2.addCommand(createInitCommand());
+  return program2;
+}
+var program = createProgram();
+program.parseAsync(process.argv).catch(handleError);

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@thepixelhouse/cli",
+  "version": "0.1.0",
+  "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>",
+  "homepage": "https://thepixelhouse.co.uk/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/togglekit/the-pixel-house.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/togglekit/the-pixel-house/issues"
+  },
+  "keywords": [
+    "visual-regression",
+    "screenshot",
+    "testing",
+    "diff",
+    "pixel",
+    "monitoring",
+    "cli",
+    "visual-testing",
+    "screenshot-testing"
+  ],
+  "bin": {
+    "pixelhouse": "./dist/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup src/cli.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "ora": "^8.0.0"
+  },
+  "devDependencies": {
+    "@pixelhouse/shared": "workspace:*",
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  }
+}