paperclipai/paperclip · error · Error

--version is only supported for npm package installs, not…

Error message

--version is only supported for npm package installs, not local plugin paths.

What it means

buildPluginInstallRequest got a --version option while the package argument resolves to a local plugin path, and version pinning only applies to npm package installs.

Solutions

1. Drop --version for local plugin paths; --version only applies to npm package installs.

When it happens

Trigger: Thrown at cli/src/commands/client/plugin.ts:167 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/ac3a9d52d14302c8. Report an issue: GitHub.

Appendix: source

Thrown at cli/src/commands/client/plugin.ts:167

  if (path.isAbsolute(packageArg)) return packageArg;
  if (packageArg.startsWith("~")) return expandHomePath(packageArg);
  return path.resolve(cwd, packageArg);
}

export function buildPluginInstallRequest(
  packageArg: string,
  opts: Pick<PluginInstallOptions, "local" | "version"> = {},
  deps: { cwd?: string; existsSync?: (targetPath: string) => boolean } = {},
): PluginInstallRequest {
  const cwd = deps.cwd ?? process.cwd();
  const pathExists = deps.existsSync ?? existsSync;
  const isLocal =
    opts.local ||
    hasLocalPathSyntax(packageArg) ||
    (opts.version ? false : isExistingRelativePath(packageArg, cwd, pathExists));

  if (isLocal && opts.version) {
    throw new Error("--version is only supported for npm package installs, not local plugin paths.");
  }

  return {
    packageName: resolvePackageArg(packageArg, Boolean(isLocal), cwd),
    version: opts.version,
    isLocalPath: Boolean(isLocal),
  };
}

export function renderLocalPluginInstallHint(packagePath: string): string {
  return [
    pc.dim("Local plugin installs run trusted local code from your machine."),
    pc.dim(`Keep ${pc.cyan("pnpm dev")} running in ${packagePath}; Paperclip watches rebuilt dist output and reloads the plugin worker.`),
  ].join("\n");
}

/**
 * Probe `GET /api/health` on the instance the CLI is configured to talk to so a

View on GitHub (pinned to 120ae5428f)