What causes "build-phase: record hero --build " in pbakaus/impeccable?

Use exactly `impeccable build-phase record hero --build `

build-phase: record hero --build <png>

Error message

build-phase: record hero --build <png>

What it means

The `build-phase record` subcommand only supports recording the hero artifact: its first argument must be the literal 'hero'. Any other token (or none) prints 'build-phase: record hero --build <png>' as a usage hint and exits 1.

Source

Thrown at crates/comp-verbs/src/build_phase.rs:1904

            io.out(&format!("  {}   one custom property set per region (--r-<id>-x/y/w/h in % of the comp; --r-<id>-cap, --r-<id>-font, --r-<id>-weight where measured); bind these to your own markup\n", out.css));
            io.out(&format!("  {}  a reference page: every region positioned at its box inside a {bp} frame, plates placed with object-fit: contain, text slots at the measured cap height in the ranked face\n", out.html));
            io.out("  The reference is a check, not the page: keep your own semantic structure and bind the numbers to it (an element per region, its box from the properties). Overlapping boxes are overlapping boxes. What the gate reads is pixels; a page that lands each region at its box passes whatever markup it uses.\n");
            0
        }
        "note" => {
            let text = argv[1..].iter().filter(|a| !a.starts_with("--")).cloned().collect::<Vec<_>>().join(" ");
            let phase = state.get("phase").and_then(Value::as_str).unwrap_or("").to_string();
            if let Some(notes) = state.pointer_mut(&format!("/phases/{phase}/notes")).and_then(|v| v.as_array_mut()) {
                notes.push(json!({ "at": now(), "text": text }));
            }
            save_state(io, &state);
            io.out(&format!("noted on {phase}\n"));
            0
        }
        "record" => {
            let which = argv.get(1).map(String::as_str);
            if which != Some("hero") {
                io.err("build-phase: record hero --build <png>\n");
                return 1;
            }
            let build_path = arg(argv, "build").unwrap_or(HERO_REPRO).to_string();
            let min = arg(argv, "min").map(|m| util::parse_f64(m, HERO_MIN)).unwrap_or(HERO_MIN);
            let gate = gate_hero(io, &mut state, &build_path, min, ".impeccable/review/diff/hero", None, organic_scan);
            let records = state.pointer("/phases/hero/records").and_then(Value::as_i64).unwrap_or(0) + 1;
            if let Some(h) = state.pointer_mut("/phases/hero").and_then(|v| v.as_object_mut()) {
                h.insert("records".into(), json!(records));
                h.insert("gate".into(), gate.record_json(&now()));
            }
            save_state(io, &state);
            let spec = load_spec(&abs(io, SPEC_PATH));
            let plate_rows: Vec<String> = gate
                .region_verdicts
                .iter()
                .filter(|(id, _)| {
                    spec.as_ref()
                        .and_then(|s| spec_regions(s).into_iter().find(|r| r.get("id").and_then(Value::as_str) == Some(id.as_str())))

View on GitHub (pinned to 2bc2879276)

Solutions

Use exactly `impeccable build-phase record hero --build <png>`
Note --build defaults to HERO_REPRO if omitted, but the artifact word 'hero' is required
Check the spelling of 'hero'

Example fix

// before
$ impeccable build-phase record --build shots/hero.png
// after
$ impeccable build-phase record hero --build shots/hero.png

Defensive patterns

Strategy: validation

Validate before calling

[ "$2" = "hero" ] || { echo 'usage: build-phase record hero --build <png>'; exit 1; }

Try / catch

impeccable build-phase record hero --build "$PNG" || impeccable build-phase --help

Prevention

Only `hero` is currently a recordable artifact; check release notes for new artifacts
Keep the artifact word before flags in argv order
Copy the exact usage line when scripting

When it happens

Trigger: `impeccable build-phase record` with no artifact argument, or with something other than 'hero' (e.g. `record cta --build x.png`, `record --build x.png`).

Common situations: Assuming record accepts other section names; omitting the artifact word and jumping straight to flags; typo like `record hreo`.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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