What causes "Use either --apply or --dry, not both." in paperclipai/paperclip?

Drop --dry if you want to import: `paperclipai worktree:merge-history --apply`.

paperclipai/paperclip · error · Error

Use either --apply or --dry, not both.

Error message

Use either --apply or --dry, not both.

What it means

Thrown at the top of worktreeMergeHistoryCommand when both --apply and --dry are set. These flags are mutually exclusive because --apply performs the import and --dry explicitly means preview-only; the default (neither flag) is already preview-only, so specifying both is contradictory intent. The guard fails fast before any worktree resolution.

Source

Thrown at cli/src/commands/worktree.ts:3292

    return {
      insertedProjects,
      insertedProjectWorkspaces,
      insertedIssues,
      insertedComments,
      insertedDocuments,
      mergedDocuments,
      insertedDocumentRevisions,
      insertedAttachments,
      skippedMissingAttachmentObjects,
      insertedIssueIdentifiers,
    };
  });
}

export async function worktreeMergeHistoryCommand(sourceArg: string | undefined, opts: WorktreeMergeHistoryOptions): Promise<void> {
  if (opts.apply && opts.dry) {
    throw new Error("Use either --apply or --dry, not both.");
  }

  if (sourceArg && opts.from) {
    throw new Error("Use either the positional source argument or --from, not both.");
  }

  const targetEndpoint = opts.to
    ? resolveWorktreeEndpointFromSelector(opts.to, { allowCurrent: true })
    : resolveCurrentWorktreeEndpoint();
  const sourceEndpoint = opts.from
    ? resolveWorktreeEndpointFromSelector(opts.from, { allowCurrent: true })
    : sourceArg
      ? resolveWorktreeEndpointFromSelector(sourceArg, { allowCurrent: true })
      : await promptForSourceEndpoint(targetEndpoint.rootPath);

  if (path.resolve(sourceEndpoint.configPath) === path.resolve(targetEndpoint.configPath)) {
    throw new Error("Source and target Paperclip configs are the same. Choose different --from/--to worktrees.");
  }

View on GitHub (pinned to 67001ec6eb)

Solutions

Drop --dry if you want to import: `paperclipai worktree:merge-history --apply`.
Drop --apply if you only want a preview: `paperclipai worktree:merge-history --dry` (or neither, since preview is the default).

Example fix

// before
paperclipai worktree:merge-history --from feature-x --apply --dry
// after
paperclipai worktree:merge-history --from feature-x --apply --yes

Defensive patterns

Strategy: validation

Validate before calling

function validateMergeFlags(opts: { apply?: boolean; dry?: boolean }): void {
  if (opts.apply && opts.dry) {
    throw new Error("Use either --apply or --dry, not both.");
  }
}

// validate before constructing the full argv / calling the command:
validateMergeFlags({ apply: process.env.APPLY === "1", dry: process.env.DRY === "1" });

Prevention

When deriving flags from env vars, use an explicit precedence (e.g. dry wins only if apply is unset) rather than independent toggles.
In wrapper scripts, assert mutual exclusivity before forwarding argv to the CLI.
Remember that neither flag (preview-only) is the default, so you rarely need --dry at all.

When it happens

Trigger: Calling `paperclipai worktree:merge-history --apply --dry ...`.

Common situations: A developer copies a previous command, adds --apply, and forgets to remove --dry. Or a wrapper script toggles both flags from environment variables without an exclusive-or check.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/9b505fb755b71589. Report an issue: GitHub.