paperclipai/paperclip · error · Error

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

Error message

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

What it means

resolveInstallRequest throws when --version is combined with a local plugin path. Version pinning only applies to npm package installs because local paths are resolved by filesystem location, not a registry.

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 67001ec6eb)

Solutions

1. Drop --version when installing from a local path.
2. To install a specific registry version, pass the npm package name without --local and a path.

Example fix

// before
paperclipai plugin install ./my-plugin --version 1.2.3
// after
paperclipai plugin install ./my-plugin

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

When it happens

Trigger: Running `paperclipai plugin install ./my-plugin --version 1.2.3` or `paperclipai plugin install ./my-plugin --local --version 1.2.3`.

Common situations: Copying a version flag from an npm-style install; assuming --version is universal.

Related errors

• Invalid integer value: ${value}
• Profile name is required
• Invalid --persona value. Use board or agent.
• Unsupported export format: ${value}
• Invalid integer value: ${value}

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