What causes "Interactive --json mutations require --yes." in affaan-m/ECC?

Add --yes to authorize mutations: `ecc setup --json ... --yes`.

Interactive --json mutations require --yes.

Error message

Interactive --json mutations require --yes.

What it means

validateInteractiveJsonOptions throws this when an interactive --json run would perform mutations but neither --yes nor --dry-run was given. The confirmation prompt is interactive and would corrupt JSON output, so non-prompted consent (--yes) or a read-only run (--dry-run) is mandatory.

Solutions

Add --yes to authorize mutations: `ecc setup --json ... --yes`.
Add --dry-run instead if you only want the JSON report without changes.
For CI, pass --yes via your automation config once the flags are verified.

Example fix

// before
npm run setup -- --json --mode claude-plugin --scope project --hooks minimal

// after
npm run setup -- --json --mode claude-plugin --scope project --hooks minimal --yes

Defensive patterns

Strategy: validation

Validate before calling

if (useJson && !opts.yes && !opts.dryRun) {
  throw new Error('Interactive --json mutations require --yes.');
}

Try / catch

try {
  await runSetup(rawArgs);
} catch (err) {
  if (err.message.includes('Interactive --json mutations require --yes')) {
    console.error(err.message);
    process.exitCode = 2;
  } else throw err;
}

Prevention

Always include --yes or --dry-run whenever --json is used.
Store the consent flag in your CI config next to the --json flag.
Keep --dry-run in scheduled jobs that only need reports.

When it happens

Trigger: Running `ecc setup --json --mode claude-plugin --scope project --hooks minimal` in a TTY without --yes and without --dry-run.

Common situations: Scripting JSON output while forgetting consent automation; CI wrappers that forward --json but not --yes; testing a dry inspection but omitting --dry-run.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at scripts/setup.js:358

}

function needsInteractiveChoices(options) {
  return (
    options.mode === undefined
    || options.scope === undefined
    || options.hooks === undefined
  );
}

function validateInteractiveJsonOptions(options, interactive) {
  if (!interactive || !options.json) return;
  if (needsInteractiveChoices(options)) {
    throw new Error(
      'Interactive --json requires explicit --mode, --scope, and --hooks values.'
    );
  }
  if (!options.yes && !options.dryRun) {
    throw new Error('Interactive --json mutations require --yes.');
  }
}

function reconcileClaudePlugin(options) {
  const setupOptions = {
    dryRun: options.dryRun,
    hooks: options.hooks,
    scope: options.scope,
  };
  if (options.moveScope) {
    return migrateClaudePluginScope(setupOptions);
  }

  try {
    return setupClaudePlugin(setupOptions);
  } catch (error) {
    const canAutoMigrate = (
      error instanceof ClaudeSetupError

View on GitHub (pinned to 8321021c54)