CLI reference

Status: The pixmoat CLI install path is not published yet. This reference is generated from the CLI source and describes the commands it will ship with.

This document contains the help content for the pixmoat command-line program.

Command Overview:

• pixmoat↴
• pixmoat mcp↴
• pixmoat capabilities↴
• pixmoat check↴
• pixmoat approve↴
• pixmoat reject↴
• pixmoat finish↴
• pixmoat history↴
• pixmoat feedback↴
• pixmoat builds↴
• pixmoat baselines↴
• pixmoat baselines sync↴
• pixmoat baselines status↴
• pixmoat baselines prune↴
• pixmoat baselines clear↴
• pixmoat config↴
• pixmoat config validate↴
• pixmoat config diff↴
• pixmoat config apply↴
• pixmoat affected↴
• pixmoat watch↴
• pixmoat view↴

pixmoat

pixmoat — visual regression CLI for CI pipelines and AI coding agents.

Authenticates with a project access token or a personal access token. Set the PIXMOAT_URL, PIXMOAT_TOKEN and PIXMOAT_PROJECT environment variables. Prefer them over —url, —token and —project: a token passed on the command line ends up in shell history and process listings. —project is not needed for mcp, capabilities or finish.

The typical agent loop: edit UI code, run Playwright capture, then pixmoat check --build <id> --wait --json to verify. --wait waits for processing, not for human review. Exit 0 = PASS, 1 = REVIEW (diffs pending review), 2 = REVIEW_NEW (new snapshots), 3 = FAIL or processing timeout.

Documentation: https://pixmoat.com/docs/

Usage: pixmoat [OPTIONS] <COMMAND>

Subcommands:

• mcp — Start an MCP (Model Context Protocol) server on stdio
• capabilities — Print locally installed CLI and MCP capabilities as JSON
• check — Check build status and list pending visual changes
• approve — Approve one or more runs in a build
• reject — Reject a run in a build (comment is required)
• finish — Explicitly finish a staged agent review after deciding every actionable run
• history — Show recent change history for a snapshot key
• feedback — Show recent rejection comments for a snapshot key
• builds — List recent builds for the project
• baselines — Manage the local baseline cache at .pixmoat/
• config — Manage .pixmoat.yaml project-local configuration files
• affected — List snapshots affected by recent source code changes
• watch — Watch for file changes in the local capture directory and re-diff
• view — Print the view URL for a run (cropped triptych image)

Options:

• --url <URL> — pixmoat server URL (env: PIXMOAT_URL)
• --token <TOKEN> — Project access token or personal access token (env: PIXMOAT_TOKEN). Prefer the env var: a token on the command line ends up in shell history
• --project <PROJECT> — Project slug (env: PIXMOAT_PROJECT). Not needed for mcp, capabilities or finish
• --json — Output raw JSON instead of human-readable text

pixmoat mcp

Start an MCP (Model Context Protocol) server on stdio.

Exposes pixmoat tools to AI agent harnesses (Claude Code, Cursor, Codex) via the standard MCP protocol over stdin/stdout.

Each tool has its own config format. Copy the Claude Code, Cursor or Codex config from the Agent tab of your project settings in pixmoat. The server reads PIXMOAT_URL, PIXMOAT_TOKEN and PIXMOAT_PROJECT; keep the token in the environment, not in the config file.

Tools: https://pixmoat.com/docs/reference/mcp-tools/

Usage: pixmoat mcp

pixmoat capabilities

Print locally installed CLI and MCP capabilities as JSON.

This reports local support only. It does not verify a remote server endpoint.

Usage: pixmoat capabilities

pixmoat check

Check build status and list pending visual changes.

Exit codes: 0 = PASS (all runs unchanged or approved), 1 = REVIEW (diffs pending review), 2 = REVIEW_NEW (only new snapshots pending review, no diffs), 3 = FAIL (build failed or processing timed out). A request or configuration error, such as a rejected token or an unreachable server, also exits 1 and prints the error to stderr.

Without --wait, a build that is still processing returns WAIT with exit 0; that is not a completed pass.

--wait waits for the server to finish processing the build (default 120 s, max 300 s). It does not wait for human review: a build with diffs still awaiting review returns REVIEW (exit 1) as soon as processing is done.

When to use: after running Playwright capture, call pixmoat check --build <id> --wait to block until diffs are computed, then inspect the result. Exit 0 means continue. Exit 1 means inspect diff images, fix code or approve. Exit 2 means approve to establish baselines.

Usage: pixmoat check [OPTIONS]

Options:

• --build <BUILD> — Build ID to check (required for remote mode, ignored with —local)

• --wait — Wait for the build to finish processing before returning (not for human review)

• --timeout <TIMEOUT> — Timeout in seconds when waiting (default: 120, max: 300)

  Default value: 120

• --min-mismatch <MIN_MISMATCH> — Only show runs with mismatch ratio >= this value

• --quiet — Print nothing on PASS (exit 0); print full digest on any other verdict

• --local — Run offline diffing against local cache instead of the server

• --dir <DIR> — Directory containing captured PNGs and index.json (default: .pixmoat/current)

• --against <AGAINST> — What to diff against: “baseline” (default) or “previous”

  Default value: baseline

• --offline — Suppress the server baseline-version staleness check

• --since <SINCE> — Correlate visual changes with changed source files since a git ref (e.g. HEAD~1)

pixmoat approve

Approve one or more runs in a build.

Sends decisions with source=“agent” for audit trail. Respects the project’s agent_auto_approve setting (all / intent_only / none).

When to use: after pixmoat check reports diffs (exit 1) or new snapshots (exit 2) that you intended. Use —run for a single run, —name for a glob pattern, —expected for intent-based approval, or —scope for bulk approval.

Usage: pixmoat approve [OPTIONS] --build <BUILD>

Options:

• --build <BUILD> — Build ID
• --run <RUN> — Approve a single run by handle or UUID
• --name <NAME> — Approve runs matching a name glob pattern (e.g. “checkout/*”)
• --expected <EXPECTED> — Comma-separated list of expected change names for intent declaration
• --scope <SCOPE> — Bulk-approve all runs of a given scope: “diff” or “new”
• --group <GROUP> — Approve all runs in a change group (e.g. “g1”)
• --comment <COMMENT> — Comment explaining the approval

pixmoat reject

Reject a run in a build (comment is required).

When to use: when a diff represents a regression that the agent cannot fix, reject it with a descriptive comment so the next reviewer (human or agent) understands what’s wrong.

Usage: pixmoat reject --build <BUILD> --run <RUN> --comment <COMMENT>

Options:

• --build <BUILD> — Build ID
• --run <RUN> — Run handle or UUID to reject
• --comment <COMMENT> — Comment explaining the rejection (required)

pixmoat finish

Explicitly finish a staged agent review after deciding every actionable run.

Exit codes: 0 approved, 3 rejected, 2 waiting, 1 blocked, 4 errors.

Usage: pixmoat finish --build <BUILD>

Options:

• --build <BUILD> — Build ID

pixmoat history

Show recent change history for a snapshot key.

When to use: before deciding on a diff, check if this screenshot has been changing frequently or was recently rejected.

Usage: pixmoat history [OPTIONS] --name <NAME> --branch <BRANCH>

Options:

• --name <NAME> — Snapshot name (e.g. “checkout/cart-desktop”)

• --branch <BRANCH> — Branch to filter by

• --limit <LIMIT> — Number of history entries (default: 10, max: 50)

  Default value: 10

pixmoat feedback

Show recent rejection comments for a snapshot key.

When to use: if a snapshot was previously rejected by a human, read the feedback to understand what needs fixing before re-submitting.

Usage: pixmoat feedback [OPTIONS] --name <NAME> --branch <BRANCH>

Options:

• --name <NAME> — Snapshot name (e.g. “header/nav-mobile”)

• --branch <BRANCH> — Branch to filter by

• --limit <LIMIT> — Number of feedback entries (default: 5, max: 20)

  Default value: 5

pixmoat builds

List recent builds for the project.

When to use: to find the build ID for a recent capture, or to check the status of previous builds on a branch.

Usage: pixmoat builds [OPTIONS]

Options:

• --branch <BRANCH> — Branch to filter by

• --limit <LIMIT> — Number of builds to return (default: 10)

  Default value: 10

pixmoat baselines

Manage the local baseline cache at .pixmoat/.

Subcommands: sync, status, prune, clear.

The cache stores content-addressed baseline images for offline diffing with pixmoat check --local. Use sync to download baselines for a branch, status to inspect the cache, prune to remove unreferenced blobs, and clear to delete the entire cache.

Usage: pixmoat baselines <COMMAND>

Subcommands:

• sync — Sync baselines from the server to the local .pixmoat/ cache
• status — Show cache status: size, blob count, synced_at, branch
• prune — Remove blobs not referenced by the current manifest
• clear — Remove the entire .pixmoat/ cache directory

pixmoat baselines sync

Sync baselines from the server to the local .pixmoat/ cache.

Downloads the baseline manifest for the given branch and fetches any missing blobs. Existing blobs (by SHA-256) are not re-downloaded.

Usage: pixmoat baselines sync [OPTIONS]

Options:

• --branch <BRANCH> — Branch to sync baselines for. If omitted, inferred from git rev-parse --abbrev-ref HEAD
• --max-size <MAX_SIZE> — Maximum cache size in bytes (default: 2 GB)
• --force — Force sync even if branch differs from cached config

pixmoat baselines status

Show cache status: size, blob count, synced_at, branch

Usage: pixmoat baselines status

pixmoat baselines prune

Remove blobs not referenced by the current manifest

Usage: pixmoat baselines prune

pixmoat baselines clear

Remove the entire .pixmoat/ cache directory

Usage: pixmoat baselines clear

pixmoat config

Manage .pixmoat.yaml project-local configuration files.

Subcommands: validate, diff, apply.

The config file lets you check project settings into version control. Use validate to check syntax and rules, diff to compare against the server, and apply to push project-global settings.

Usage: pixmoat config <COMMAND>

Subcommands:

• validate — Validate a .pixmoat.yaml file against all schema and semantic rules
• diff — Compare the local .pixmoat.yaml against the project’s current server settings
• apply — Validate, diff, and apply project-global settings from .pixmoat.yaml to the server

pixmoat config validate

Validate a .pixmoat.yaml file against all schema and semantic rules.

Parses the YAML file, checks for secret fields, and validates all constraints (tolerance ranges, DPR values, viewport format, etc.). This is purely local — no network calls are made.

Exit codes: 0 = the file is valid; 1 = validation error, parse error, or file not found.

Usage: pixmoat config validate [OPTIONS]

Options:

• --file <FILE> — Path to the config file (default: .pixmoat.yaml in CWD)

pixmoat config diff

Compare the local .pixmoat.yaml against the project’s current server settings.

Prints a human-readable diff showing changed, added, and removed fields. In verbose mode, unchanged fields are also shown.

Exit codes: 0 = the file matches the server settings; 1 = differences found, file not found, or error.

Usage: pixmoat config diff [OPTIONS]

Options:

• --file <FILE> — Path to the config file (default: .pixmoat.yaml in CWD)
• --verbose — Show unchanged fields as well

pixmoat config apply

Validate, diff, and apply project-global settings from .pixmoat.yaml to the server.

Reads the config file, validates it, computes a diff against the server’s current settings, and writes the project-global settings (retention, agent_auto_approve, webhook) via PUT /api/projects/:slug.

By default, the command is gated to the project’s default branch — it refuses to apply if the current git branch does not match. Use --force to bypass this check for local development.

Exit codes: 0 = settings applied (or already up to date); 1 = validation error, auth error, branch gate rejection, or file not found.

Usage: pixmoat config apply [OPTIONS]

Options:

• --file <FILE> — Path to the config file (default: .pixmoat.yaml in CWD)
• --force — Bypass the default-branch gate (for local development)

pixmoat affected

List snapshots affected by recent source code changes.

Uses git diff and the element index from the server to determine which snapshots could be affected by changes since a git ref. Falls back to emitting all snapshots when the element index is unavailable or when global files (CSS, Tailwind config, layout files) have changed.

This is a workstation heuristic — not supported or recommended in CI. In CI, always capture and diff all snapshots.

Usage: pixmoat affected [OPTIONS] --since <SINCE>

Options:

• --since <SINCE> — Git ref to compare against (e.g. HEAD~1, main, abc123)
• --as-grep — Emit a grep pattern on stdout suitable for npx playwright test --grep "…"
• --global-patterns <GLOBAL_PATTERNS> — Comma-separated list of glob patterns for global files (overrides defaults)
• --branch <BRANCH> — Branch to fetch element index for (default: from cache config or git)

pixmoat watch

Watch for file changes in the local capture directory and re-diff.

Watches .pixmoat/current/ (or --dir override) for PNG file changes, debounces rapid writes (200ms), and re-diffs each changed snapshot against its cached baseline. Prints one summary line per change.

Press Ctrl-C to stop.

Usage: pixmoat watch [OPTIONS]

Options:

• --dir <DIR> — Directory to watch (default: .pixmoat/current)

pixmoat view

Print the view URL for a run (cropped triptych image).

The view endpoint returns a composed image (baseline | current | diff) cropped to the largest changed region. Use handles or UUIDs for run_ref.

Example: pixmoat view --build <id> h7k2

Usage: pixmoat view [OPTIONS] --build <BUILD> <RUN_REF>

Arguments:

• <RUN_REF> — Run reference — a 4-char handle or full UUID

Options:

• --build <BUILD> — Build ID

• --kind <KIND> — Image kind: triptych, baseline, current, or diff (default: triptych)

  Default value: triptych

• --region <REGION> — Region to crop: largest, all, full, or a region index (default: largest)

  Default value: largest

Exit codes

pixmoat check exits with one of these codes. pixmoat finish has its own codes, listed in its help above. Argument errors exit with 2 before any request is sent. A request or configuration error, such as a rejected token, an unreachable server or a missing PIXMOAT_PROJECT, exits with 1 and prints the error to stderr, so a gate that treats 1 as “review needed” should also check stderr.