affaan-m/ECC · error · Error

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

Error message

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

What it means

Thrown by platform-audit when --write (a file path to persist the report) is set but the output format is still `text`. Writing a human-readable text report to a file is intentionally disallowed; --write requires a machine format (json or markdown) so downstream consumers get structured content. The guard fires after format validation, so format must already be valid.

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 01e15490f0)

Solutions

1. Add the matching format flag: `--write report.json --json` or `--write report.md --markdown`.
2. Or set format explicitly: `--write report.json --format json`.
3. If you only want terminal text output, drop --write entirely.

Example fix

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

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

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

try {
  parseArgs(process.argv);
} catch (err) {
  if (err.message.startsWith('--write requires')) {
    console.error('Add --json or --markdown when using --write.');
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: `--write report.json` with no `--json`/`--markdown` (defaults to text); combining `--write out.md` with `--format text`; an automation script that always passes --write but conditionally sets the format.

Common situations: User adds --write to a CI invocation that previously only printed text; mismatch between the --write filename extension and the actual format flag.

Related errors

• Invalid format: ${parsed.format}. Use text, json, or markdow
• Invalid format: ${parsed.format}. Use text or json.
• ${flagName} requires a value
• Invalid ${flagName}: ${value}
• Unknown argument: ${arg}

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/555c52213e4739da. Report an issue: GitHub.