@pkgseer/cli 0.2.2 → 0.2.4

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-jyykfhaq.js";
+} from "./shared/chunk-48mwa8wt.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -23,6 +23,7 @@ var CliPackageInfoDocument = gql`
       license
       homepage
       repositoryUrl
+      downloadsLastMonth
     }
     security {
       vulnerabilityCount
@@ -1782,6 +1783,27 @@ function registerConfigShowCommand(program) {
 }
 
 // src/commands/shared.ts
+function parsePackageSpec(spec) {
+  let registry = "npm";
+  let rest = spec;
+  if (spec.includes(":")) {
+    const colonIndex = spec.indexOf(":");
+    const potentialRegistry = spec.slice(0, colonIndex).toLowerCase();
+    if (["npm", "pypi", "hex"].includes(potentialRegistry)) {
+      registry = potentialRegistry;
+      rest = spec.slice(colonIndex + 1);
+    }
+  }
+  const atIndex = rest.lastIndexOf("@");
+  if (atIndex > 0) {
+    return {
+      registry,
+      name: rest.slice(0, atIndex),
+      version: rest.slice(atIndex + 1)
+    };
+  }
+  return { registry, name: rest };
+}
 function toGraphQLRegistry(registry) {
   const map = {
     npm: "NPM",
@@ -2242,7 +2264,7 @@ Examples:
   # Multiple pages
   pkgseer docs get 24293-shared-plugins-during-build-2 npm/express/4.18.2/readme`;
 function registerDocsGetCommand(program) {
-  program.command("get <refs...>").summary("Fetch documentation page(s)").description(GET_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").option("--verbose", "Include metadata (ID, format, source, links, etc.)").option("--preview-lines <n>", "Lines of content to show (0 for full content; default 20)").action(async (refs, options) => {
+  program.command("get <refs...>").summary("Fetch documentation page(s)").description(GET_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-V, --pkg-version <version>", "Package version").option("--json", "Output as JSON").option("--verbose", "Include metadata (ID, format, source, links, etc.)").option("--preview-lines <n>", "Lines of content to show (0 for full content; default 20)").action(async (refs, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await docsGetAction(refs, options, deps);
@@ -2272,13 +2294,15 @@ function formatDocsList(docs) {
   return lines.join(`
 `);
 }
-async function docsListAction(packageName, options, deps) {
+async function docsListAction(packageArg, options, deps) {
   const { pkgseerService } = deps;
-  const registry = toGraphQLRegistry(options.registry);
-  const result = await pkgseerService.cliDocsList(registry, packageName, options.pkgVersion);
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry !== "npm" ? parsed.registry : options.registry);
+  const version2 = parsed.version ?? options.pkgVersion;
+  const result = await pkgseerService.cliDocsList(registry, parsed.name, version2);
   handleErrors(result.errors, options.json ?? false);
   if (!result.data.listPackageDocs) {
-    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   if (options.json) {
@@ -2302,19 +2326,21 @@ Shows all documentation pages with titles, globally unique page IDs,
 word counts, and descriptions. Use the page ID with 'docs get'
 to fetch the full content of a specific page.
 
+Package format: [registry:]name[@version]
+
 Examples:
   pkgseer docs list lodash
-  pkgseer docs list requests --registry pypi
-  pkgseer docs list phoenix --registry hex --version 1.7.0 --json`;
+  pkgseer docs list pypi:requests
+  pkgseer docs list hex:phoenix@1.7.0 --json`;
 function registerDocsListCommand(program) {
-  program.command("list <package>").summary("List documentation pages").description(LIST_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
+  program.command("list <package>").summary("List documentation pages").description(LIST_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-V, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await docsListAction(packageName, options, deps);
     });
   });
 }
-// src/commands/docs/search.ts
+// src/commands/search.ts
 var colors = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -2344,37 +2370,11 @@ function toSearchMode(mode) {
 }
 function parsePackageList(input2) {
   return input2.split(",").map((spec) => {
-    const trimmed = spec.trim();
-    const atIndex = trimmed.lastIndexOf("@");
-    let regPkg;
-    let version2;
-    if (atIndex > 0) {
-      regPkg = trimmed.slice(0, atIndex);
-      version2 = trimmed.slice(atIndex + 1);
-    } else {
-      regPkg = trimmed;
-    }
-    const slashIndex = regPkg.indexOf("/");
-    if (slashIndex === -1) {
-      return {
-        registry: "NPM",
-        name: regPkg,
-        version: version2
-      };
-    }
-    const beforeSlash = regPkg.slice(0, slashIndex);
-    const afterSlash = regPkg.slice(slashIndex + 1);
-    if (beforeSlash.startsWith("@")) {
-      return {
-        registry: "NPM",
-        name: regPkg,
-        version: version2
-      };
-    }
+    const parsed = parsePackageSpec(spec.trim());
     return {
-      registry: toGraphQLRegistry(beforeSlash),
-      name: afterSlash,
-      version: version2
+      registry: toGraphQLRegistry(parsed.registry),
+      name: parsed.name,
+      version: parsed.version
     };
   });
 }
@@ -2394,7 +2394,7 @@ function formatEntry(entry, useColors) {
   if (entry.type === "CODE") {
     const title = entry.title ?? "Unknown";
     const location = entry.filePath ? `${entry.filePath}:${entry.startLine ?? "?"}-${entry.endLine ?? "?"}` : "";
-    const lang = entry.language ? ` • ${entry.language}` : "";
+    const lang = entry.language ? ` * ${entry.language}` : "";
     if (useColors) {
       lines.push(`${badge} ${colors.bold}${title}${colors.reset}`);
       if (location) {
@@ -2446,7 +2446,7 @@ function formatPackageHeader(entry, prevEntry, useColors) {
     return "";
   }
   const header = `${pkg} (${registry})`;
-  const separator = "═".repeat(Math.min(50, header.length + 10));
+  const separator = "=".repeat(Math.min(50, header.length + 10));
   if (useColors) {
     return `
 ${colors.yellow}${header}${colors.reset}
@@ -2478,10 +2478,10 @@ function formatSearchResults(results, useColors) {
   const codeCount = entries.filter((e) => e?.type === "CODE").length;
   const docCount = entries.filter((e) => e?.type === "DOC" || e?.type === "REPO_DOC").length;
   if (useColors) {
-    lines.push(`${colors.dim}───────────────────────────────────────────────────${colors.reset}`);
+    lines.push(`${colors.dim}---------------------------------------------------${colors.reset}`);
     lines.push(`${colors.dim}Results: ${entries.length} total (${codeCount} code, ${docCount} docs)${colors.reset}`);
   } else {
-    lines.push("───────────────────────────────────────────────────");
+    lines.push("---------------------------------------------------");
     lines.push(`Results: ${entries.length} total (${codeCount} code, ${docCount} docs)`);
   }
   const indexingWarnings = formatIndexingWarnings(results.indexingStatus);
@@ -2661,7 +2661,7 @@ function summarizeSearchResults(results) {
   return lines.join(`
 `);
 }
-async function docsSearchAction(queryArg, options, deps) {
+async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
   const { pkgseerService } = deps;
   const query = Array.isArray(queryArg) ? queryArg.join(" ") : queryArg ?? "";
   if (!query.trim()) {
@@ -2678,7 +2678,7 @@ async function docsSearchAction(queryArg, options, deps) {
   }
   const packages = parsePackageList(options.packages);
   const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
-  const mode = toSearchMode(options.mode);
+  const mode = options.mode ? toSearchMode(options.mode) : defaultMode;
   const useColors = shouldUseColors(options.noColor);
   const result = await pkgseerService.combinedSearch(packages, query, {
     mode,
@@ -2713,36 +2713,79 @@ Searches both code (functions, classes) and documentation pages
 using the combined search endpoint. Returns results with snippets
 showing matches.
 
+Package format: [registry:]name[@version]
+
 Examples:
   # Search a single package (code + docs)
-  pkgseer docs search "error handling" -P express
+  pkgseer search "error handling" -P express
 
   # Search code only
-  pkgseer docs search "Router.use" -P express --mode code
+  pkgseer search "Router.use" -P express --mode code
 
   # Search docs only
-  pkgseer docs search "middleware" -P express --mode docs
+  pkgseer search "middleware" -P express --mode docs
 
   # Search multiple packages
-  pkgseer docs search "auth" -P express,passport
+  pkgseer search "auth" -P express,passport
 
   # With registry prefix (for non-npm packages)
-  pkgseer docs search "orm" -P pypi/django,pypi/sqlalchemy
+  pkgseer search "orm" -P pypi:django,pypi:sqlalchemy
 
   # With specific version
-  pkgseer docs search "routing" -P express@4.18.2
+  pkgseer search "routing" -P express@4.18.2
 
   # Output for piping
-  pkgseer docs search "routing" -P express --refs-only
+  pkgseer search "routing" -P express --refs-only
 
   # JSON output
-  pkgseer docs search "error" -P express --json`;
+  pkgseer search "error" -P express --json`;
 function addSearchOptions(cmd) {
   return cmd.option("-P, --packages <packages>", "Packages to search (comma-separated). Format: name or registry/name[@version]. Examples: express | express,lodash | pypi/django@4.2").option("-m, --mode <mode>", "Search mode: all (default), code, docs").option("-l, --limit <n>", "Max results (default: 25)").option("-v, --verbose", "Expanded output with more details").option("--refs-only", "Output only references (for piping)").option("--count", "Output result counts by package").option("--format <format>", "Output format: human|summary|json", "human").option("--no-color", "Disable colored output").option("--json", "Output as JSON");
 }
-function registerDocsSearchCommand(program) {
-  const cmd = program.command("search [query...]").summary("Search code and documentation").description(SEARCH_DESCRIPTION);
+function registerSearchCommand(program) {
+  const cmd = program.command("search [query...]").summary("Search code and documentation across packages").description(SEARCH_DESCRIPTION);
   addSearchOptions(cmd).action(async (query, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await searchAction(query, options, deps);
+    });
+  });
+}
+
+// src/commands/docs/search.ts
+async function docsSearchAction(queryArg, options, deps) {
+  await searchAction(queryArg, options, deps, "DOCS");
+}
+var DOCS_SEARCH_DESCRIPTION = `Search documentation across packages.
+
+Searches documentation pages in package docs. For searching both
+code and docs, use the top-level 'pkgseer search' command instead.
+
+Package format: [registry:]name[@version]
+
+Examples:
+  # Search documentation
+  pkgseer docs search "middleware" -P express
+
+  # Search multiple packages
+  pkgseer docs search "auth" -P express,passport
+
+  # With registry prefix (for non-npm packages)
+  pkgseer docs search "orm" -P pypi:django,pypi:sqlalchemy
+
+  # With specific version
+  pkgseer docs search "routing" -P express@4.18.2
+
+  # JSON output
+  pkgseer docs search "error" -P express --json
+
+Note: For code search, use 'pkgseer search --mode code' instead.`;
+function addDocsSearchOptions(cmd) {
+  return cmd.option("-P, --packages <packages>", "Packages to search (comma-separated). Format: [registry:]name[@version]. Examples: express | express,lodash | pypi:django@4.2").option("-l, --limit <n>", "Max results (default: 25)").option("-v, --verbose", "Expanded output with more details").option("--refs-only", "Output only references (for piping)").option("--count", "Output result counts by package").option("--format <format>", "Output format: human|summary|json", "human").option("--no-color", "Disable colored output").option("--json", "Output as JSON");
+}
+function registerDocsSearchCommand(program) {
+  const cmd = program.command("search [query...]").summary("Search documentation").description(DOCS_SEARCH_DESCRIPTION);
+  addDocsSearchOptions(cmd).action(async (query, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await docsSearchAction(query, options, deps);
@@ -3858,13 +3901,7 @@ function generateSkillContent(invocation = "pkgseer") {
   return `---
 name: pkgseer
 version: ${version}
-description: >-
-  Search code and documentation across npm, PyPI, and Hex packages.
-  Find functions, classes, APIs, and usage examples. Also provides
-  quality scores, security vulnerabilities, dependencies, and comparisons.
-  Triggers on: "how does X work", "find examples of", "search for",
-  "is X secure", "compare X vs Y", package evaluation, dependency decisions,
-  "what package should I use for", API lookup, security audits.
+description: Search code/docs across npm, PyPI, Hex packages. Provides quality scores, security vulnerabilities, dependencies, comparisons. Use when user asks about package security, CVEs, vulnerabilities, code examples, API usage, package comparison, dependency analysis, or which package to use.
 ---
 
 # PkgSeer - Package Intelligence
@@ -3875,50 +3912,55 @@ Search and analyze packages across npm, PyPI, and Hex. All commands support \`--
 
 \`\`\`bash
 # Search code and docs across packages
-${invocation} search "<query>" -P lodash,express    # npm packages
-${invocation} search "<query>" -P requests -r pypi  # PyPI packages
-${invocation} search "authentication" -P phoenix,plug -r hex
+${invocation} search "<query>" -P lodash,express         # npm packages
+${invocation} search "<query>" -P pypi:requests          # PyPI packages
+${invocation} search "authentication" -P hex:phoenix,hex:plug
 
 # Search modes
-${invocation} search "<query>" -P <packages> --code  # Code only
-${invocation} search "<query>" -P <packages> --docs  # Docs only
+${invocation} search "<query>" -P <packages> --mode code  # Code only
+${invocation} search "<query>" -P <packages> --mode docs  # Docs only
 
-# Search project dependencies (requires pkgseer.yml)
-${invocation} docs search "<query>"
+# Docs-only search (shorthand)
+${invocation} docs search "<query>" -P <packages>
 \`\`\`
 
 ## Package Analysis
 
+Package format: \`[registry:]name[@version]\`
+
 \`\`\`bash
 # Overview: metadata, versions, quickstart
-${invocation} pkg info <package> [-r npm|pypi|hex]
+${invocation} pkg info lodash
+${invocation} pkg info pypi:requests
 
 # Quality score (0-100) with category breakdown
-${invocation} pkg quality <package> [-r registry] [-v version]
+${invocation} pkg quality express@4.18.0
+${invocation} pkg quality pypi:django@4.2
 
 # Security: CVEs, severity, upgrade paths
-${invocation} pkg vulns <package> [-r registry] [-v version]
+${invocation} pkg vulns lodash@4.17.21
 
 # Dependencies: direct, transitive, tree view
-${invocation} pkg deps <package> [-r registry] [-t] [-d depth]
+${invocation} pkg deps express --transitive
 
 # Compare up to 10 packages
 ${invocation} pkg compare lodash underscore ramda
-${invocation} pkg compare npm:axios pypi:httpx  # cross-registry
+${invocation} pkg compare axios pypi:httpx  # cross-registry
 \`\`\`
 
 ## Documentation
 
 \`\`\`bash
-${invocation} docs list <package> [-r registry]  # List pages
-${invocation} docs get <package>/<page-id>       # Fetch content
+${invocation} docs list pypi:requests             # List pages
+${invocation} docs get <package>/<page-id>        # Fetch content
+${invocation} docs search "<query>" -P <packages> # Search docs only
 \`\`\`
 
 ## Tips
 
-- Default registry: npm. Use \`-r pypi\` or \`-r hex\` for others
+- Package format: \`[registry:]name[@version]\` (e.g., \`pypi:django@4.2\`)
+- Default registry: npm
 - Use \`--json\` for structured output when parsing
-- Version defaults to latest; use \`-v\` for specific
 `;
 }
 function extractSkillVersion(content) {
@@ -5161,27 +5203,6 @@ in MCP configuration files. Use 'pkgseer mcp' for interactive setup.`).action(as
 }
 
 // src/commands/pkg/compare.ts
-function parsePackageSpec(spec) {
-  let registry = "npm";
-  let rest = spec;
-  if (spec.includes(":")) {
-    const colonIndex = spec.indexOf(":");
-    const potentialRegistry = spec.slice(0, colonIndex).toLowerCase();
-    if (["npm", "pypi", "hex"].includes(potentialRegistry)) {
-      registry = potentialRegistry;
-      rest = spec.slice(colonIndex + 1);
-    }
-  }
-  const atIndex = rest.lastIndexOf("@");
-  if (atIndex > 0) {
-    return {
-      registry,
-      name: rest.slice(0, atIndex),
-      version: rest.slice(atIndex + 1)
-    };
-  }
-  return { registry, name: rest };
-}
 function formatPackageComparison(comparison) {
   const lines = [];
   lines.push("\uD83D\uDCCA Package Comparison");
@@ -5302,14 +5323,16 @@ function formatPackageDependencies(data, transitiveRequested) {
   return lines.join(`
 `);
 }
-async function pkgDepsAction(packageName, options, deps) {
+async function pkgDepsAction(packageArg, options, deps) {
   const { pkgseerService } = deps;
-  const registry = toGraphQLRegistry(options.registry);
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry !== "npm" ? parsed.registry : options.registry);
+  const version2 = parsed.version ?? options.pkgVersion;
   const transitiveRequested = options.transitive ?? false;
-  const result = await pkgseerService.cliPackageDeps(registry, packageName, options.pkgVersion, options.transitive, options.maxDepth ? Number.parseInt(options.maxDepth, 10) : undefined);
+  const result = await pkgseerService.cliPackageDeps(registry, parsed.name, version2, options.transitive, options.maxDepth ? Number.parseInt(options.maxDepth, 10) : undefined);
   handleErrors(result.errors, options.json ?? false);
   if (!result.data.packageDependencies) {
-    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   const format = options.json ? "json" : options.format ?? "human";
@@ -5348,12 +5371,14 @@ var DEPS_DESCRIPTION = `Get package dependencies.
 Lists direct dependencies and shows version constraints and
 dependency types (runtime, dev, optional).
 
+Package format: [registry:]name[@version]
+
 Examples:
   pkgseer pkg deps express
-  pkgseer pkg deps lodash --transitive
-  pkgseer pkg deps requests --registry pypi --json`;
+  pkgseer pkg deps lodash@4.17.21 --transitive
+  pkgseer pkg deps pypi:requests@2.28.0 --json`;
 function registerPkgDepsCommand(program) {
-  program.command("deps <package>").summary("Get package dependencies").description(DEPS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("-t, --transitive", "Include transitive dependencies").option("--max-depth <n>", "Maximum transitive depth (1-10, defaults to server)").option("--format <format>", "Output format: human|summary|json", "human").option("--json", "Output as JSON").action(async (packageName, options) => {
+  program.command("deps <package>").summary("Get package dependencies").description(DEPS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-V, --pkg-version <version>", "Package version").option("-t, --transitive", "Include transitive dependencies").option("--max-depth <n>", "Maximum transitive depth (1-10, defaults to server)").option("--format <format>", "Output format: human|summary|json", "human").option("--json", "Output as JSON").action(async (packageName, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await pkgDepsAction(packageName, options, deps);
@@ -5361,6 +5386,15 @@ function registerPkgDepsCommand(program) {
   });
 }
 // src/commands/pkg/info.ts
+function formatDownloads(count) {
+  if (count >= 1e6) {
+    return `${(count / 1e6).toFixed(1)}M`;
+  }
+  if (count >= 1000) {
+    return `${(count / 1000).toFixed(1)}K`;
+  }
+  return count.toLocaleString();
+}
 function formatPackageSummary(data) {
   const lines = [];
   const pkg = data.package;
@@ -5380,6 +5414,11 @@ function formatPackageSummary(data) {
     ["License", pkg.license]
   ]));
   lines.push("");
+  if (pkg.downloadsLastMonth != null && pkg.downloadsLastMonth > 0) {
+    lines.push("Downloads:");
+    lines.push(keyValueTable([["Last Month", formatDownloads(pkg.downloadsLastMonth)]]));
+    lines.push("");
+  }
   if (pkg.homepage || pkg.repositoryUrl) {
     lines.push("Links:");
     const links = [];
@@ -5402,13 +5441,14 @@ function formatPackageSummary(data) {
   return lines.join(`
 `);
 }
-async function pkgInfoAction(packageName, options, deps) {
+async function pkgInfoAction(packageArg, options, deps) {
   const { pkgseerService } = deps;
-  const registry = toGraphQLRegistry(options.registry);
-  const result = await pkgseerService.cliPackageInfo(registry, packageName);
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry !== "npm" ? parsed.registry : options.registry);
+  const result = await pkgseerService.cliPackageInfo(registry, parsed.name);
   handleErrors(result.errors, options.json ?? false);
   if (!result.data.packageSummary) {
-    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   if (options.json) {
@@ -5429,16 +5469,18 @@ async function pkgInfoAction(packageName, options, deps) {
 }
 var INFO_DESCRIPTION = `Get package summary and metadata.
 
-Displays comprehensive information about a package including:
+Displays information about a package's latest version including:
 - Basic metadata (version, license, description)
 - Download statistics
-- Security advisories
 - Quick start instructions
 
+Note: This command shows the latest version only.
+For version-specific info, use 'pkg vulns', 'pkg quality', or 'pkg deps'.
+
 Examples:
   pkgseer pkg info lodash
-  pkgseer pkg info requests --registry pypi
-  pkgseer pkg info phoenix --registry hex --json`;
+  pkgseer pkg info pypi:requests
+  pkgseer pkg info hex:phoenix --json`;
 function registerPkgInfoCommand(program) {
   program.command("info <package>").summary("Get package summary and metadata").description(INFO_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("--json", "Output as JSON").action(async (packageName, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
@@ -5466,13 +5508,15 @@ function formatPackageQuality(data) {
   return lines.join(`
 `);
 }
-async function pkgQualityAction(packageName, options, deps) {
+async function pkgQualityAction(packageArg, options, deps) {
   const { pkgseerService } = deps;
-  const registry = toGraphQLRegistry(options.registry);
-  const result = await pkgseerService.cliPackageQuality(registry, packageName, options.pkgVersion);
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry !== "npm" ? parsed.registry : options.registry);
+  const version2 = parsed.version ?? options.pkgVersion;
+  const result = await pkgseerService.cliPackageQuality(registry, parsed.name, version2);
   handleErrors(result.errors, options.json ?? false);
   if (!result.data.packageQuality) {
-    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   const format = options.json ? "json" : options.format ?? "human";
@@ -5500,12 +5544,14 @@ Analyzes package quality across multiple dimensions:
 - Security practices
 - Community engagement
 
+Package format: [registry:]name[@version]
+
 Examples:
   pkgseer pkg quality lodash
-  pkgseer pkg quality express -v 4.18.0
-  pkgseer pkg quality requests --registry pypi --json`;
+  pkgseer pkg quality express@4.18.0
+  pkgseer pkg quality pypi:requests@2.28.0 --json`;
 function registerPkgQualityCommand(program) {
-  program.command("quality <package>").summary("Get package quality score").description(QUALITY_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--format <format>", "Output format: human|summary|json", "human").option("--json", "Output as JSON").action(async (packageName, options) => {
+  program.command("quality <package>").summary("Get package quality score").description(QUALITY_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-V, --pkg-version <version>", "Package version").option("--format <format>", "Output format: human|summary|json", "human").option("--json", "Output as JSON").action(async (packageName, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await pkgQualityAction(packageName, options, deps);
@@ -5565,13 +5611,15 @@ function formatPackageVulnerabilities(data) {
   return lines.join(`
 `);
 }
-async function pkgVulnsAction(packageName, options, deps) {
+async function pkgVulnsAction(packageArg, options, deps) {
   const { pkgseerService } = deps;
-  const registry = toGraphQLRegistry(options.registry);
-  const result = await pkgseerService.cliPackageVulns(registry, packageName, options.pkgVersion);
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry !== "npm" ? parsed.registry : options.registry);
+  const version2 = parsed.version ?? options.pkgVersion;
+  const result = await pkgseerService.cliPackageVulns(registry, parsed.name, version2);
   handleErrors(result.errors, options.json ?? false);
   if (!result.data.packageVulnerabilities) {
-    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   if (options.json) {
@@ -5600,12 +5648,14 @@ Scans for known security vulnerabilities and provides:
 - Affected version ranges
 - Upgrade recommendations
 
+Package format: [registry:]name[@version]
+
 Examples:
   pkgseer pkg vulns lodash
-  pkgseer pkg vulns express -v 4.17.0
-  pkgseer pkg vulns requests --registry pypi --json`;
+  pkgseer pkg vulns express@4.17.0
+  pkgseer pkg vulns pypi:requests@2.28.0 --json`;
 function registerPkgVulnsCommand(program) {
-  program.command("vulns <package>").summary("Check for security vulnerabilities").description(VULNS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
+  program.command("vulns <package>").summary("Check for security vulnerabilities").description(VULNS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-V, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await pkgVulnsAction(packageName, options, deps);
@@ -6044,6 +6094,9 @@ Getting started:
   pkgseer login        Authenticate with your account
   pkgseer skill init   Install AI agent skill
 
+Search:
+  pkgseer search <query> -P <packages>   Search code and docs
+
 Package commands:
   pkgseer pkg info <package>      Get package summary
   pkgseer pkg vulns <package>     Check vulnerabilities
@@ -6054,7 +6107,7 @@ Package commands:
 Documentation commands:
   pkgseer docs list <package>     List doc pages
   pkgseer docs get <pkg> <page>   Fetch a doc page
-  pkgseer docs search <query>     Search documentation
+  pkgseer docs search <query>     Search docs only
 
 Learn more at https://pkgseer.dev`);
 registerInitCommand(program);
@@ -6062,6 +6115,7 @@ registerMcpCommand(program);
 registerSkillCommand(program);
 registerLoginCommand(program);
 registerLogoutCommand(program);
+registerSearchCommand(program);
 var auth = program.command("auth").description("View and manage authentication");
 registerAuthStatusCommand(auth);
 var config = program.command("config").description("View and manage configuration");

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-jyykfhaq.js";
+} from "./shared/chunk-48mwa8wt.js";
 export {
   version
 };

package/dist/shared/{chunk-jyykfhaq.js → chunk-48mwa8wt.js}

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.2.2";
+var version = "0.2.4";
 
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pkgseer/cli",
   "description": "CLI companion for PkgSeer - package intelligence for developers and AI assistants",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "files": [
     "dist",