pbakaus/impeccable · error

usage: impeccable surface-brief <path|list|read|write> [targ

Error message

usage: impeccable surface-brief <path|list|read|write> [target] [body-file] [related-target ...]

What it means

The `impeccable surface-brief` subcommand prints this usage line to stderr and exits with code 1 when it is invoked without a recognized sub-action as the first argument. The sub-command supports only `path`, `list`, `read`, and `write` actions, so any other (or missing) first argument falls into the catch-all `_` arm of the argument match. It tells the developer the correct command shape so they can retry.

Source

Thrown at crates/context/src/surface_brief_cli.rs:87

                Ok(b) => String::from_utf8_lossy(&b).into_owned(),
                Err(e) => {
                    io.err(&format!("{}\n", node_read_error(bf, &e)));
                    return 1;
                }
            };
            match write_surface_brief(&project_root, t, &related, &body) {
                Ok(fp) => {
                    io.out(&format!("{}\n", rel_out(&fp)));
                    0
                }
                Err(msg) => {
                    io.err(&format!("{}\n", msg));
                    1
                }
            }
        }
        _ => {
            io.err("usage: impeccable surface-brief <path|list|read|write> [target] [body-file] [related-target ...]\n");
            1
        }
    }
}

View on GitHub (pinned to 2bc2879276)

Solutions

1. Run `impeccable surface-brief <path|list|read|write> [target] [body-file] [related-target ...]` with a valid action: e.g. `impeccable surface-brief list`, `impeccable surface-brief read src/index.html`, or `impeccable surface-brief write src/index.html brief.md related.html`.
2. If you only meant to scan a file, use `impeccable detect <path>` instead — surface-brief manages stored briefs, not scanning.
3. Check shell scripts for an empty/unset variable holding the action word.

Example fix

// before
impeccable surface-brief src/index.html   # missing action
// after
impeccable surface-brief read src/index.html

const VALID = new Set(["path", "list", "read", "write"]);
const [action] = process.argv.slice(2);
if (!VALID.has(action)) {
  console.error(`surface-brief: action must be one of ${[...VALID].join("|")}`);
  process.exit(1);
}

const isSurfaceBriefAction = (a) => ["path","list","read","write"].includes(a);

const r = spawnSync("impeccable", ["surface-brief", action, target]);
if (r.status !== 0 && /usage: impeccable surface-brief/.test(r.stderr.toString())) {
  console.error("Invalid surface-brief action:", action);
}

When it happens

Trigger: Running `impeccable surface-brief` with no arguments at all, or with a first argument that is not one of path|list|read|write (e.g. `impeccable surface-brief show mypage.html` or a typo like `impeccable surface-brief pat file.html`).

Common situations: Typos in the sub-action name; forgetting the action verb entirely and passing only a target path; copying syntax from other sub-commands (e.g. `detect`) that take a path directly; scripting errors where a variable holding the action is empty.

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

• usage: latest <slug-or-target> [--json]
• usage: close <resolved-target> <snapshot-file>
• usage: impeccable critique-storage <slug|write|latest|trend|
• {}
• "init" is not a CLI command. Type /impeccable init in your A

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