usage: build-phase.mjs start --comp <png> [--breakpoint WxH]

Error message

usage: build-phase.mjs start --comp <png> [--breakpoint WxH] | status [--json] | advance [--force --reason "..."] | record hero --build <png> | scaffold | note "<text>" | finish --disposition <word>

What it means

build-phase's run() prints its full usage line to stderr and returns exit code 1 when invoked with no subcommand or with a --help flag. It is the command's built-in help/validation gate, not an unexpected failure.

Source

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

        }
        lines.push(line);
    }
    if let Some(finish) = state.get("finish").filter(|v| !v.is_null()) {
        let disp = finish.get("disposition").and_then(Value::as_str).unwrap_or("");
        let at = finish.get("at").and_then(Value::as_str).unwrap_or("");
        lines.push(format!("  finish      {disp} at {at}"));
    }
    lines.push(format!("NEXT {}", next_instruction(io, state)));
    lines.join("\n")
}

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

/// `impeccable build-phase <cmd> ...`
pub fn run(argv: &[String], io: &mut Io, organic_scan: OrganicScan) -> i32 {
    let cmd = argv.first().map(String::as_str);
    if cmd.is_none() || flag(argv, "help") {
        io.err("usage: build-phase.mjs start --comp <png> [--breakpoint WxH] | status [--json] | advance [--force --reason \"...\"] | record hero --build <png> | scaffold | note \"<text>\" | finish --disposition <word>\n");
        return 1;
    }
    let cmd = cmd.unwrap();
    if cmd == "start" {
        let comp = arg(argv, "comp");
        let direction = arg(argv, "direction");
        if comp.is_none() && direction.is_none() {
            io.err("build-phase: start needs --comp <approved comp png> (comp already approved) or --direction <seed key> (comp round still to run)\n");
            return 1;
        }
        if let Some(c) = comp {
            if !abs(io, c).exists() {
                io.err(&format!("build-phase: comp {c} does not exist\n"));
                return 1;
            }
        }
        if direction.is_some() && arg(argv, "kind").is_some() {
            io.out("choice ping skipped\n");

View on GitHub (pinned to 2bc2879276)

Solutions

Include a subcommand: start, status, advance, record, scaffold, note, or finish
Pass --help deliberately if you want to see the usage text
Example: `impeccable build-phase start --comp design.png`

Example fix

// before
$ impeccable build-phase --comp hero.png
// after
$ impeccable build-phase start --comp hero.png

Defensive patterns

Strategy: validation

Validate before calling

[ -n "$SUBCMD" ] || { impeccable build-phase --help; exit 1; }

Try / catch

impeccable build-phase "$sub" ... || impeccable build-phase --help

Prevention

Always include a subcommand; --comp/--direction belong to `start` only
Treat the usage line as documentation — it lists all valid subcommands
Alias `impeccable build-phase --help` for quick reference

When it happens

Trigger: Running `impeccable build-phase` with no cmd (argv.first() is None), or with --help; any first token outside the known set (start/status/advance/record/scaffold/note/finish) would otherwise fall through differently, so bare/help invocations always land here.

Common situations: Exploring the command to see options; forgetting the subcommand entirely (e.g. `impeccable build-phase --comp hero.png`); intentionally requesting help.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

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