--move-scope requires an explicit --scope destination.

Error message

--move-scope requires an explicit --scope destination.

What it means

parseArgs throws this when --move-scope is passed without also passing an explicit --scope. Scope migration needs a concrete destination scope to move the installation to; requesting the move without naming the destination is ambiguous and rejected.

Solutions

Add the destination: `ecc setup --move-scope --scope user` (or project/local).
Drop --move-scope if migration is already auto-detected by choosing a different scope.
Run `ecc setup --help` to see the documented pairing `--scope project --move-scope`.

Example fix

// before
npm run setup -- --move-scope

// after
npm run setup -- --move-scope --scope user

Defensive patterns

Strategy: validation

Validate before calling

const has = (f) => argv.includes(f);
if (has('--move-scope') && !has('--scope')) {
  throw new Error('--move-scope requires an explicit --scope destination.');
}

Try / catch

try {
  await runSetup(rawArgs);
} catch (err) {
  if (err.message.includes('--move-scope requires')) {
    console.error(err.message);
    process.exitCode = 2;
  } else throw err;
}

Prevention

Always pair --move-scope with --scope in the same command line.
Define migration invocations as full literal commands in scripts.
Note that plain scope changes migrate automatically; --move-scope is only for explicit requests.

When it happens

Trigger: Running `ecc setup --move-scope` or `ecc setup --mode claude-plugin --move-scope --hooks minimal` — --move-scope present but --scope undefined.

Common situations: Assuming --move-scope alone migrates to a default destination; copying the flag from migration docs but dropping the paired --scope; refactoring scripts where the --scope argument was removed.

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/4f5239e4aff5843c. Report an issue: GitHub.

Appendix: source

Thrown at scripts/setup.js:113

      options.json = true;
    } else if (argument === '--help' || argument === '-h') {
      options.help = true;
    } else {
      throw new Error(`Unknown argument: ${argument}`);
    }
  }

  if (options.mode !== undefined && options.mode !== MODE) {
    throw new Error(`Invalid setup mode: ${options.mode}. This command currently supports ${MODE}.`);
  }
  if (options.scope !== undefined && !VALID_SCOPES.has(options.scope)) {
    throw new Error(`Invalid --scope value: ${options.scope}`);
  }
  if (options.hooks !== undefined && !VALID_HOOK_MODES.has(options.hooks)) {
    throw new Error(`Invalid --hooks value: ${options.hooks}`);
  }
  if (options.moveScope && options.scope === undefined) {
    throw new Error('--move-scope requires an explicit --scope destination.');
  }
  return options;
}

function questionWithCancellation(terminal, prompt) {
  return new Promise((resolve, reject) => {
    let settled = false;
    const finish = callback => value => {
      if (settled) return;
      settled = true;
      terminal.removeListener('close', onClose);
      callback(value);
    };
    const onClose = finish(() => {
      const error = new Error('Readline was closed before an answer was received.');
      error.code = 'ABORT_ERR';
      reject(error);
    });

View on GitHub (pinned to 8321021c54)