usage: comp-diff.mjs --comp <png> --build <png> [--spec spec

Error message

usage: comp-diff.mjs --comp <png> --build <png> [--spec spec.json] [--out-dir dir] [--align top|stretch] [--label name] [--threshold 0.75] [--json]

What it means

`comp-diff run` requires both `--comp <png>` and `--build <png>` arguments naming the reference and built screenshots to compare. If either is missing, it prints the full usage line to stderr and exits 1. This is argument validation before any file I/O happens.

Source

Thrown at crates/comp-verbs/src/comp_diff.rs:692

}

fn resolve(io: &Io, p: &str) -> PathBuf {
    let path = Path::new(p);
    if path.is_absolute() {
        path.to_path_buf()
    } else {
        io.cwd.join(path)
    }
}

// ---- CLI -------------------------------------------------------------------

/// `impeccable comp-diff --comp <png> --build <png> ...`
pub fn run(argv: &[String], io: &mut Io) -> i32 {
    let comp_path = arg(argv, "comp");
    let build_path = arg(argv, "build");
    let (Some(comp_path), Some(build_path)) = (comp_path, build_path) else {
        io.err("usage: comp-diff.mjs --comp <png> --build <png> [--spec spec.json] [--out-dir dir] [--align top|stretch] [--label name] [--threshold 0.75] [--json]\n");
        return 1;
    };
    let comp = match read_png(io, comp_path) {
        Ok(v) => v,
        Err(e) => {
            io.err(&format!("comp-diff: cannot read comp {comp_path}: {e}\n"));
            return 1;
        }
    };
    let build = match read_png(io, build_path) {
        Ok(v) => v,
        Err(e) => {
            io.err(&format!("comp-diff: cannot read build {build_path}: {e}\n"));
            return 1;
        }
    };
    let mut spec: Option<Value> = None;
    let spec_path = arg(argv, "spec");

View on GitHub (pinned to 2bc2879276)

Solutions

Pass both `--comp <png>` and `--build <png>` with paths to existing PNG files.
Check the invoking script for unset/empty variables feeding the flags.
Add optional flags (--spec, --out-dir, --align, --label, --threshold, --json) only after the two required ones.

Example fix

// before
$ impeccable comp-diff --build ./build.png
usage: comp-diff.mjs --comp <png> --build <png> ...
// after
$ impeccable comp-diff --comp ./comp.png --build ./build.png

Defensive patterns

Strategy: validation

Validate before calling

const args = parseArgs(argv);
if (!args.comp || !args.build) {
  console.error('comp-diff requires both --comp <png> and --build <png>');
  process.exit(1);
}

Type guard

function hasRequiredCompDiffArgs(a) {
  return typeof a?.comp === 'string' && a.comp.length > 0 &&
         typeof a?.build === 'string' && a.build.length > 0;
}

Try / catch

const r = spawnSync('impeccable', ['comp-diff', '--comp', comp, '--build', build]);
if (r.status === 1 && /usage: comp-diff/.test(r.stderr.toString())) {
  console.error('Missing --comp or --build; see usage above.');
}

Prevention

Assert both flags exist in any wrapper script before invoking comp-diff.
Fail fast in CI when a screenshot variable is empty.
Keep required flags first; optional flags are additive.

When it happens

Trigger: Calling `comp-diff` (binary or the run() entrypoint) with an empty argv, or omitting `--comp` and/or `--build`, or misspelling the flags so `arg()` returns None.

Common situations: Scripting the comparison step and forgetting one of the two images; a wrapper script builds the argv dynamically and drops an empty/failed variable; calling the legacy `.mjs` flags incorrectly after the move to the Rust binary.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/727ff9e44f6fa9b8. Report an issue: GitHub.