{"record":{"id":"ac3a9d52d14302c8","repo":"paperclipai/paperclip","slug":"version-is-only-supported-for-npm-package-instal","errorCode":null,"errorMessage":"--version is only supported for npm package installs, not local plugin paths.","messagePattern":"--version is only supported for npm package installs, not local plugin paths\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/plugin.ts","lineNumber":167,"sourceCode":"  if (path.isAbsolute(packageArg)) return packageArg;\n  if (packageArg.startsWith(\"~\")) return expandHomePath(packageArg);\n  return path.resolve(cwd, packageArg);\n}\n\nexport function buildPluginInstallRequest(\n  packageArg: string,\n  opts: Pick<PluginInstallOptions, \"local\" | \"version\"> = {},\n  deps: { cwd?: string; existsSync?: (targetPath: string) => boolean } = {},\n): PluginInstallRequest {\n  const cwd = deps.cwd ?? process.cwd();\n  const pathExists = deps.existsSync ?? existsSync;\n  const isLocal =\n    opts.local ||\n    hasLocalPathSyntax(packageArg) ||\n    (opts.version ? false : isExistingRelativePath(packageArg, cwd, pathExists));\n\n  if (isLocal && opts.version) {\n    throw new Error(\"--version is only supported for npm package installs, not local plugin paths.\");\n  }\n\n  return {\n    packageName: resolvePackageArg(packageArg, Boolean(isLocal), cwd),\n    version: opts.version,\n    isLocalPath: Boolean(isLocal),\n  };\n}\n\nexport function renderLocalPluginInstallHint(packagePath: string): string {\n  return [\n    pc.dim(\"Local plugin installs run trusted local code from your machine.\"),\n    pc.dim(`Keep ${pc.cyan(\"pnpm dev\")} running in ${packagePath}; Paperclip watches rebuilt dist output and reloads the plugin worker.`),\n  ].join(\"\\n\");\n}\n\n/**\n * Probe `GET /api/health` on the instance the CLI is configured to talk to so a","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/plugin.ts#L149-L185","documentation":"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.","triggerScenarios":"Running `paperclipai plugin install ./my-plugin --version 1.2.3` or `paperclipai plugin install ./my-plugin --local --version 1.2.3`.","commonSituations":"Copying a version flag from an npm-style install; assuming --version is universal.","solutions":["Drop --version when installing from a local path.","To install a specific registry version, pass the npm package name without --local and a path."],"exampleFix":"// before\npaperclipai plugin install ./my-plugin --version 1.2.3\n// after\npaperclipai plugin install ./my-plugin","handlingStrategy":"validation","validationCode":"if (isLocal && opts.version) {\n  throw new Error('--version is only supported for npm package installs, not local plugin paths.');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never combine --local (or a path) with --version.","Mutually exclude these flags in the CLI parser."],"tags":["cli","plugin","install","input-validation"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}