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 parseArgs in scripts/operator-readiness-dashboard.js when --write is supplied but the output format remains 'text' (the default). Writing to a file only makes sense for a machine-readable format, so the combination is rejected. Set --json or --markdown (or --format json|markdown) alongside --write.

Source

Thrown at scripts/operator-readiness-dashboard.js:222

    if (arg.startsWith('--generated-at=')) {
      parsed.generatedAt = arg.slice('--generated-at='.length);
      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).filter(Boolean);

  return parsed;
}

function readText(rootDir, relativePath) {
  try {
    return fs.readFileSync(path.join(rootDir, relativePath), 'utf8');
  } catch (_error) {
    return '';
  }
}

function fileExists(rootDir, relativePath) {
  return fs.existsSync(path.join(rootDir, relativePath));
}

View on GitHub (pinned to 01e15490f0)

Solutions

1. Add --json or --markdown when using --write: `--write report.json --json`.
2. Or use `--format json` / `--format markdown` alongside --write.
3. If you only want terminal text output, drop --write entirely.

Example fix

// before
node scripts/operator-readiness-dashboard.js --write report.txt
// after
node scripts/operator-readiness-dashboard.js --write report.json --json

function reconcileWriteWithFormat(args) {
  const wantsWrite = args.includes('--write') || args.some(a => a.startsWith('--write='));
  const isMachine = args.includes('--json') || args.includes('--markdown') || args.some(a => /^--format=(json|markdown)$/.test(a));
  if (wantsWrite && !isMachine) {
    throw new Error('--write requires --json, --markdown, or --format=json|markdown');
  }
}

When it happens

Trigger: Running `--write report.txt` with no format flag; passing `--write` with `--format text` explicitly. The check fires only when format === 'text', so any of --json/--markdown/--format=json/--format=markdown satisfies it.

Common situations: Adding --write to an existing text-mode invocation without changing the format; assuming text output can be dumped to a file (the script deliberately disallows it).

Related errors

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

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