What causes "usage: impeccable surface-brief write " in pbakaus/impeccable?

Supply both arguments: `impeccable surface-brief write `.

usage: impeccable surface-brief write <primary-target> <body

Error message

usage: impeccable surface-brief write <primary-target> <body-file>

What it means

`surface-brief write` was called without both required arguments (primary target and body file); the command prints this usage line and exits 1. It is a pure argument-shape check via the `(Some(t), Some(bf))` pattern before any I/O.

Source

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

            let rows: Vec<Value> = list_surface_briefs(&project_root).iter().map(|b| summary(b, &project_root)).collect();
            io.out(&format!("{}\n", json_pretty(&Value::Array(rows))));
            0
        }
        Some("read") => {
            let result = resolve_surface_brief(&project_root, target);
            if let Some(b) = result.brief {
                io.out(&b.text);
                return 0;
            }
            if !result.candidates.is_empty() {
                let rows: Vec<Value> = result.candidates.iter().map(|b| summary(b, &project_root)).collect();
                io.err(&format!("{}\n", json_pretty(&Value::Array(rows))));
            }
            2
        }
        Some("write") => {
            let (Some(t), Some(bf)) = (target, body_file) else {
                io.err("usage: impeccable surface-brief write <primary-target> <body-file>\n");
                return 1;
            };
            let body = match std::fs::read(bf) {
                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
                }

View on GitHub (pinned to 2bc2879276)

Solutions

Supply both arguments: `impeccable surface-brief write <primary-target> <body-file>`.
Write the brief body to a temp file first, then pass its path.
Check scripted calls pass arguments after flags correctly.
See the usage line printed by the command for the exact form.

Example fix

// before
impeccable surface-brief write src/App.tsx
// after
impeccable surface-brief write src/App.tsx /tmp/brief-body.md

Defensive patterns

Strategy: validation

Validate before calling

const args = ['write', target, bodyFile];
if (args.slice(1).some(a => !a)) throw new Error('usage: impeccable surface-brief write <primary-target> <body-file>');

Try / catch

const r = run(`impeccable surface-brief write ${target} ${bodyFile}`);
if (r.code === 1 && r.stderr.startsWith('usage: impeccable surface-brief write')) {
  console.error('missing target or body-file argument');
}

Prevention

Always pass both <primary-target> and <body-file> positionally.
Write the body to a file first; the command does not read stdin.
In scripts, assert argument count before spawning the CLI.
Remember flags come before positionals for other verbs; keep order fixed here.

When it happens

Trigger: `impeccable surface-brief write` with zero or one of the two required positional arguments (<primary-target>, <body-file>).

Common situations: Omitting the body file because the brief body was meant to come from stdin (not supported), forgetting arguments in scripted invocations, or argument-order mistakes.

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/1e8648c257e87ce3. Report an issue: GitHub.