pbakaus/impeccable · error

usage: comp-spec.mjs --comp <png> (--grid | --regions <json>

Error message

usage: comp-spec.mjs --comp <png> (--grid | --regions <json> | --auto) [--spec out.json]
       comp-spec.mjs --print | --crop <id> [--out file] [--scale n] | --plate-prompt <id>

What it means

If none of the early modes (--help/--print/--plate-prompt/--crop) matched, comp-spec requires the --comp <png> flag to enter its measure modes (--grid/--regions/--auto). This usage message is printed and the command exits 1 when --comp is absent.

Source

Thrown at crates/comp-verbs/src/comp_spec.rs:872

            let _ = std::fs::create_dir_all(parent);
        }
        let text = vec![("impeccable:crop-of".to_string(), format!("{comp_file}#{id}"))];
        match png_io::encode_png(&c, &text) {
            Ok(bytes) => {
                let _ = std::fs::write(&out_path, bytes);
            }
            Err(e) => {
                io.err(&format!("comp-spec: {e}\n"));
                return 1;
            }
        }
        io.out(&format!("CROP {out} ({}x{}) region {id} of {comp_file}. Reference only: regenerate the plate from it, never ship it.\n", c.width, c.height));
        return 0;
    }

    let comp_path = arg(argv, "comp");
    let Some(comp_path) = comp_path else {
        io.err("usage: comp-spec.mjs --comp <png> (--grid | --regions <json> | --auto) [--spec out.json]\n       comp-spec.mjs --print | --crop <id> [--out file] [--scale n] | --plate-prompt <id>\n");
        return 1;
    };
    let comp = match png_io::load_raster(&resolve(io, comp_path)) {
        Ok((d, _)) => d.image,
        Err(e) => {
            io.err(&format!("comp-spec: cannot read {comp_path}: {e}\n"));
            return 1;
        }
    };

    if flag(argv, "grid") {
        let grid_out = resolve(io, GRID_PATH);
        if let Some(parent) = grid_out.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        match png_io::encode_png(&render_grid(&comp), &[]) {
            Ok(bytes) => {
                let _ = std::fs::write(&grid_out, bytes);

View on GitHub (pinned to 2bc2879276)

Solutions

1. Add --comp <path-to-png> to the command line.
2. If you meant to inspect an existing spec, use --print or --crop instead, which do not require --comp.
3. Run `comp-spec --help` to see the full usage.

Example fix

// before
comp-spec --grid
// after
comp-spec --comp comp.png --grid

const args = ['comp-spec', ...modeArgs];
if (!args.includes('--comp')) {
  throw new Error('comp-spec measure modes require --comp <png>');
}

When it happens

Trigger: Calling `comp-spec` with only --grid, --regions, or --auto (or with no arguments beyond --spec) so arg(argv, "comp") returns None.

Common situations: Forgetting --comp when re-running --grid; scripting the command and only passing --regions; confusion between the --crop/--print modes (which don't need --comp) and the measure modes (which do).

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• usage: comp-diff.mjs --comp <png> --build <png> [--spec spec
• usage: write <slug-or-target> <body-file>
• embed-prompt: --scan needs at least one directory
• generate-image: --prompt (or --prompt-file) and --out are re
• surface brief path requires a concrete target

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