@pkgseer/cli

@pkgseer/cli

CLI and MCP server for PkgSeer — package intelligence for developers and AI assistants.

Get insights about packages across npm, PyPI, Hex, Crates, NuGet, Maven, and more: search code and documentation, navigate source code, trace call graphs, check security vulnerabilities, analyze dependencies, and compare packages. Works standalone or as an MCP server for AI assistants like Claude and Cursor.

Installation

Use npx without installation:

npx @pkgseer/cli --help

Or install globally:

npm install -g @pkgseer/cli

Quick Start

# Interactive setup (recommended for first-time users)
pkgseer init

# Or set up manually:
pkgseer login              # Authenticate with your PkgSeer account
pkgseer skill init         # Install as AI assistant skill

AI Assistant Integration

PkgSeer works with AI assistants in two ways:

Skills

Skills teach your AI assistant to use PkgSeer CLI commands through natural language:

pkgseer skill init

This installs a skill definition for Claude Code or Codex CLI. The AI runs CLI commands and reads the output.

MCP Server

MCP provides structured tools that AI assistants can call programmatically:

pkgseer mcp init

This provides structured tools that AI assistants can call programmatically. Configuration varies by assistant:

Claude Code / Codex CLI: The mcp init command configures these automatically.

Cursor IDE: Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pkgseer": {
      "command": "npx",
      "args": ["-y", "@pkgseer/cli", "mcp", "start"]
    }
  }
}

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "pkgseer": {
      "command": "npx",
      "args": ["-y", "@pkgseer/cli", "mcp", "start"]
    }
  }
}

CLI Commands

Search

Search code and documentation across packages:

# Search in specific packages
pkgseer search "authentication" -P express,passport
pkgseer search "http client" -P pypi:requests,pypi:httpx
pkgseer search "json parsing" -P hex:jason,hex:poison

# Search modes
pkgseer search "auth" -P lodash --type code   # Code only
pkgseer search "auth" -P lodash --type docs   # Docs only

# Wait options (for packages that need indexing)
pkgseer search "api" -P new-package --wait 60000  # Wait up to 60s
pkgseer search "api" -P new-package --no-wait     # Return immediately

# Resume long-running searches
pkgseer search "api" -P large-package --no-poll   # Disable polling, get searchRef
pkgseer search status <searchRef>                 # Check status / get results

If packages haven't been indexed yet, the search will wait up to 30 seconds by default. Use --wait <ms> to customize or --no-wait to return immediately with progress info.

For long-running searches, use --no-poll to get a searchRef and later poll with pkgseer search status <ref> (or the equivalent legacy form --resume <ref>).

Package Commands

pkgseer pkg info lodash              # Package summary and metadata
pkgseer pkg vulns lodash@4.17.21     # Security vulnerabilities
pkgseer pkg quality express          # Quality score (0-100)
pkgseer pkg deps express             # Direct dependencies
pkgseer pkg deps express --transitive  # Include transitive deps
pkgseer pkg compare axios got fetch-h2  # Compare packages
pkgseer pkg changelog express          # Changelog entries between versions

Package format: [registry:]name[@version]

• lodash — npm (default registry)
• pypi:requests — PyPI
• hex:phoenix — Hex
• crates:serde — Crates
• nuget:Newtonsoft.Json — NuGet
• maven:com.google.guava:guava — Maven
• lodash@4.17.21 — specific version

Documentation Commands

pkgseer docs list pypi:requests        # List available doc pages
pkgseer docs get lodash/chunk          # Fetch specific doc page
pkgseer docs search "routing" -P express  # Search docs only

Code Navigation Commands

pkgseer code overview express               # Codebase overview (languages, complexity, test coverage)
pkgseer code find express Router --include-code  # Find a symbol and read its source
pkgseer code context express src/router/index.js  # All code intelligence for a file
pkgseer code callers npm:express#Router      # What calls this symbol
pkgseer code callees npm:express#Router      # What this symbol calls
pkgseer code path npm:express#listen npm:express#createServer  # Call path between symbols
pkgseer code search express "ERR_HTTP_HEADERS_SENT"  # Search within package code
pkgseer code grep express src/router/index.js "handle"  # Pattern match in a file
pkgseer code read express src/router/index.js  # Read source file by path
pkgseer code files express --path-prefix src/  # List files in repository
pkgseer code list express --scope exports    # Browse symbols
pkgseer code imports express --resolved-only  # List import statements
pkgseer code diff express v4.18.2 v5.0.0    # Compare symbols between versions

Indexing Commands

pkgseer index trigger express lodash   # Pre-warm indexes for packages
pkgseer index status <ref>             # Check indexing progress

Project Commands

pkgseer project init     # Create pkgseer.yml config
pkgseer project detect   # Detect package manifests
pkgseer project upload   # Upload project to PkgSeer

Authentication

pkgseer login            # Authenticate via browser
pkgseer logout           # Sign out
pkgseer auth status      # Check authentication state

Configuration

pkgseer config show      # Display current configuration

MCP Tools

When running as an MCP server, 26 tools are available across four categories:

Registry metadata (instant, no indexing):

Tool	Description
package_summary	Package metadata, versions, quickstart examples
package_vulnerabilities	Security advisories and CVEs
package_dependencies	Dependency tree (direct and transitive) with lifecycle filter
package_quality	Quality score with category breakdown
compare_packages	Side-by-side comparison of packages
package_changelog	Changelog entries (GitHub Releases, CHANGELOG.md, HexDocs)

Documentation (requires doc site crawling):

Tool	Description
list_package_docs	Available documentation pages
fetch_package_doc	Full content of a documentation page
search_project_docs	Search docs for packages in current project

Code navigation (requires indexing, dual addressing — package or repo scope):

Tool	Description
code_overview	Statistical overview of a codebase (languages, complexity, test coverage)
file_context	All code intelligence for a single file (symbols, imports, callers, callees)
find_symbol	Find functions, classes, or modules by name
list_symbols	Browse symbols by scope (exports or file contents)
search_symbols	Search code navigation index (symbol-level results)
symbol_callers	Find what calls a symbol (cross-package capable)
symbol_callees	Find what a symbol calls (cross-package capable)
call_path	Find call path between two symbols
list_imports	Get import statements
version_diff	Compare symbols between two versions or git refs
list_files	List files in an indexed repository
grep_file	Search for pattern within a file
read_file	Read source code by file path and line range

Search and utility:

Tool	Description
search	Lexical keyword search across code and docs in multiple targets
search_status	Check async search progress and retrieve results
trigger_indexing	Pre-warm indexes for packages/repositories
indexing_status	Poll navigation indexing progress

Configuration

Project Configuration

Create pkgseer.yml in your project root:

project: my-project-name

# Optional: limit which tools are available
enabled_tools:
  - package_summary
  - package_vulnerabilities
  - search_project_docs

Environment Variables

Variable	Description
PKGSEER_API_TOKEN	API token (alternative to pkgseer login)
PKGSEER_URL	Base URL for PkgSeer (for development/testing)

Documentation

• Architecture Overview
• MCP Installation Guide
• Creating MCP Tools
• Authentication Flow
• Skills System
• Configuration Reference

Development

See CLAUDE.md for development guidelines.

bun install              # Install dependencies
bun run dev              # Development mode
bun test                 # Run tests
bun run build            # Build for production
bun run codegen          # Regenerate GraphQL types

Need Help?

• Visit pkgseer.dev for documentation
• Report issues on GitHub

License

(c) 2025-2026 Juha Litola