affaan-m/ECC · error

--write requires --json, --markdown, or --format…

Error message

--write requires --json, --markdown, or --format json|markdown

What it means

This error is thrown by parseArgs in scripts/platform-audit.js when the user passes --write (a file output path) together with the default text output format. The script can only persist results in machine-readable formats, so combining --write with text output is rejected as a contradictory CLI configuration. It prevents writing a text report where a structured output was expected.

Solutions

1. Add --json or --markdown to the invocation when using --write
2. Pass --format json or --format markdown explicitly alongside --write
3. Drop --write and print the text report to stdout instead

Example fix

// before
node scripts/platform-audit.js --write report.out
// after
node scripts/platform-audit.js --json --write report.json

const formats = ['json', 'markdown'];
if (args.includes('--write') && !args.some(a => ['--json','--markdown','--format=json','--format=markdown'].includes(a))) {
  throw new Error('--write also needs --json, --markdown, or --format json|markdown');
}

function isWritableFormat(format) {
  return format === 'json' || format === 'markdown';
}

try {
  await main(argv);
} catch (e) {
  if (e.message.includes('--write requires')) {
    console.error('Usage: add --json or --markdown when using --write');
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Running `node scripts/platform-audit.js --write report.txt` (or any --write value) without also passing --json, --markdown, or --format json|markdown, leaving parsed.format at its 'text' default.

Common situations: Developers scripting the audit to save output to disk but forgetting that text format is not writable; copy-pasting an invocation that previously used --json; automation wrappers adding --write unconditionally.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• --all-harnesses and --harness are mutually exclusive.
• Choose exactly one memory body source: --stdin or…
• Conflict messages require at least one --file
• connector name required unless --all is set
• graph sync does not accept a session ID when --all is set

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/555c52213e4739da. Report an issue: GitHub.

Appendix: source

Thrown at scripts/platform-audit.js:210

    if (arg === '--use-env-github-token') {
      parsed.useEnvGithubToken = true;
      continue;
    }

    if (arg === '--exit-code') {
      parsed.exitCode = true;
      continue;
    }

    throw new Error(`Unknown argument: ${arg}`);
  }

  if (!['text', 'json', 'markdown'].includes(parsed.format)) {
    throw new Error(`Invalid format: ${parsed.format}. Use text, json, or markdown.`);
  }

  if (parsed.writePath && parsed.format === 'text') {
    throw new Error('--write requires --json, --markdown, or --format json|markdown');
  }

  parsed.allowUntracked = parsed.allowUntracked.map(normalizeRelativePrefix);

  return parsed;
}

function normalizeRelativePrefix(value) {
  return String(value || '')
    .replace(/\\/g, '/')
    .replace(/^\.\/+/, '')
    .replace(/\/+$/, '') + (String(value || '').endsWith('/') ? '/' : '');
}

function runCommand(command, args, options = {}) {
  const result = spawnSync(command, args, {
    cwd: options.cwd,
    env: options.env || process.env,

View on GitHub (pinned to 8321021c54)