jackwener/OpenCLI · error · ArgumentError

${commandName} requires --execute to perform a remote write

Error message

${commandName} requires --execute to perform a remote write

What it means

requireExecute is a safety gate for CLI commands that would perform a remote (write) operation against an Atlassian API. It throws ArgumentError when the --execute flag was not passed, ensuring destructive or state-changing commands never run implicitly. This prevents accidental remote writes from a dry-run/default invocation.

Source

Thrown at clis/_atlassian/shared.js:288

    if (!rows.length) throw new EmptyResultError(label, hint);
    return rows;
}

export function parseLimit(value, defaultValue = 20, maxValue = 100, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireExecute(args, commandName) {
    if (args.execute !== true) {
        throw new ArgumentError(`${commandName} requires --execute to perform a remote write`);
    }
}

export async function readUtf8File(filePath) {
    const path = requireString(filePath, '--file');
    let fileStat;
    try {
        fileStat = await stat(path);
    } catch {
        throw new ArgumentError(`File not found: ${path}`);
    }
    if (!fileStat.isFile()) {
        throw new ArgumentError(`File must be a readable text file: ${path}`);
    }
    let raw;
    try {
        raw = await readFile(path);
    } catch {

View on GitHub (pinned to 49907e53dc)

Solutions

Re-run the command with the --execute flag to explicitly authorize the remote write.
Verify your argument parser converts --execute to a boolean true (not a string), since the check is strict equality with true.
Wrap in try-catch for ArgumentError to print a hint about --execute in scripts.

Example fix

// before
cli confluence update-page --id 12345 --file page.md
// after
cli confluence update-page --id 12345 --file page.md --execute

Defensive patterns

Strategy: validation

Validate before calling

if (args.execute !== true) {
  console.error(`Refusing remote write: re-run with --execute`);
  process.exit(1);
}

Type guard

const isExecuteAuthorized = (args) => args.execute === true;

Try / catch

try {
  await runWriteCommand(args);
} catch (err) {
  if (err.name === 'ArgumentError' && err.message.includes('--execute')) {
    console.error('Dry run blocked: add --execute to apply changes remotely.');
    process.exit(2);
  }
  throw err;
}

Prevention

Always append --execute to write commands in scripts/CI.
Keep dry-run as the default and only add --execute after reviewing the plan output.
Ensure your argv parser stores flags as boolean true, not strings.

When it happens

Trigger: Calling any command wired to requireExecute without passing --execute (i.e. args.execute is not exactly true), e.g. `cli update-issue ...` instead of `cli update-issue ... --execute`.

Common situations: Running a write command from a script or CI job where the flag was omitted; assuming the command would prompt for confirmation instead; flags parsed as strings ('--execute' present but value is a string, not boolean true).

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/5bcc0c1cd22ec263. Report an issue: GitHub.