@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 [email protected]     # 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
• [email protected] — 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