What causes "Use either the positional source argument or --from, not both." in paperclipai/paperclip?

Remove the positional argument and use only --from.

paperclipai/paperclip · error · Error

Use either the positional source argument or --from, not bot

Error message

Use either the positional source argument or --from, not both.

What it means

Thrown at the top of worktreeMergeHistoryCommand when both a positional [source] argument and the --from option are supplied. The positional exists as a back-compat alias for --from; providing both is ambiguous so the CLI rejects it. The guard fires before any selector resolution.

Source

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

      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.");
  }

  const scopes = parseWorktreeMergeScopes(opts.scope);
  const sourceHandle = await openConfiguredDb(sourceEndpoint.configPath);
  const targetHandle = await openConfiguredDb(targetEndpoint.configPath);

View on GitHub (pinned to 67001ec6eb)

Solutions

Remove the positional argument and use only --from.
Or remove --from and rely on the positional source argument.

Example fix

// before
paperclipai worktree:merge-history feature-x --from feature-y
// after
paperclipai worktree:merge-history --from feature-y

Defensive patterns

Strategy: validation

Validate before calling

function resolveSourceInput(positional: string | undefined, fromFlag: string | undefined): string | undefined {
  if (positional && fromFlag) {
    throw new Error("Use either the positional source argument or --from, not both.");
  }
  return positional ?? fromFlag;
}

const source = resolveSourceInput(argv[2], opts.from);

Prevention

Standardize on --from in scripts and aliases; stop using the positional form to avoid confusion.
When shelling out, build argv from a single source variable so both forms cannot be populated simultaneously.

When it happens

Trigger: Calling `paperclipai worktree:merge-history <path> --from <other>` with both the positional source and --from set.

Common situations: A developer migrates from the old positional-only syntax to --from but leaves the positional in place. Or a shell alias/script concatenates args and ends up populating both.

Related errors

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