pbakaus/impeccable · error · Error

usage: surface-brief.mjs <path|list|read|write> [target] [bo

Error message

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

What it means

Thrown by surface-brief.mjs main when the command is missing entirely or is not one of path/list/read/write. It is the catch-all usage error emitted after all known command branches have been checked.

Source

Thrown at plugin/skills/impeccable/scripts/surface-brief.mjs:55

    if (result.brief) {
      process.stdout.write(result.brief.text);
      return;
    }
    if (result.candidates.length) process.stderr.write(`${JSON.stringify(result.candidates.map((brief) => summary(brief, projectRoot)), null, 2)}\n`);
    process.exit(2);
  }
  if (command === 'write') {
    if (!target || !bodyFile) throw new Error('usage: surface-brief.mjs write <primary-target> <body-file>');
    const filePath = writeSurfaceBrief({
      projectRoot,
      primaryTarget: target,
      relatedTargets,
      body: fs.readFileSync(bodyFile, 'utf-8'),
    });
    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\n`);
    return;
  }
  throw new Error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]');
}

function isMainModule() {
  if (!process.argv[1]) return false;
  try {
    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1]);
  } catch {
    return import.meta.url === pathToFileURL(process.argv[1]).href;
  }
}

if (isMainModule()) {
  try {
    main(process.argv.slice(2));
  } catch (error) {
    process.stderr.write(`${error?.message || error}\n`);
    process.exit(1);
  }

View on GitHub (pinned to d14711ae3d)

Solutions

1. Use one of the supported commands: `path`, `list`, `read`, or `write`.
2. Check the script's help/README for the exact command vocabulary.
3. If automating, assert the command string against the known set before calling.

Example fix

# before
node surface-brief.mjs

# after
node surface-brief.mjs list

const KNOWN_COMMANDS = new Set(['path', 'list', 'read', 'write']);
function isKnownCommand(cmd) {
  return typeof cmd === 'string' && KNOWN_COMMANDS.has(cmd);
}

function isSurfaceBriefCommand(value) {
  return value === 'path' || value === 'list' || value === 'read' || value === 'write';
}

if (!isSurfaceBriefCommand(command)) {
  console.error('usage: surface-brief.mjs <path|list|read|write> ...');
  process.exit(2);
}

When it happens

Trigger: Running `surface-brief.mjs` with no command, or with an unrecognized command like `surface-brief.mjs foo`.

Common situations: Typo in the command name, or invoking the script bare expecting default behavior.

Related errors

• usage: surface-brief.mjs <path|list|read|write> [target] [bo
• surface brief path requires a concrete target
• usage: surface-brief.mjs write <primary-target> <body-file>
• Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule
• Pass a glob, e.g. ${IMPECCABLE_COMMAND} hooks ignore-file "s

AI-assisted analysis of pbakaus/impeccable@d14711ae3d (2026-08-13). Data as JSON: /api/errors/08d022c4df4a30b1. Report an issue: GitHub.