npm package: @pkgseer/cli
Description: CLI companion for PkgSeer - package intelligence for developers and AI assistants
Author: Juha Litola
Latest version: 0.6.6

# @pkgseer/cli

CLI and MCP server for [PkgSeer](https://pkgseer.dev) — package intelligence for developers and AI assistants.

Get insights about packages across npm, PyPI, Hex, and crates.io registries: search code and documentation, 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:

```bash
npx @pkgseer/cli --help
```

Or install globally:

```bash
npm install -g @pkgseer/cli
```

## Quick Start

```bash
# 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:

```bash
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:

```bash
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`:

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

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

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

## CLI Commands

### Search

Search code and documentation across packages:

```bash
# 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 --resume <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 resume with `--resume <ref>`.

### Package Commands

```bash
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
```

Package format: `[registry:]name[@version]`
- `lodash` — npm (default registry)
- `pypi:requests` — PyPI
- `hex:phoenix` — Hex
- `crates:serde` — crates.io
- `lodash@4.17.21` — specific version

### Documentation Commands

```bash
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
```

### Project Commands

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

### Authentication

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

### Configuration

```bash
pkgseer config show      # Display current configuration
```

## MCP Tools

When running as an MCP server, these tools are available:

| Tool | Description |
|------|-------------|
| `package_summary` | Package metadata, versions, quickstart examples |
| `package_vulnerabilities` | Security advisories and CVEs |
| `package_dependencies` | Dependency tree (direct and transitive) |
| `package_quality` | Quality score with category breakdown |
| `compare_packages` | Side-by-side comparison of packages |
| `list_package_docs` | Available documentation pages |
| `fetch_package_doc` | Full content of a documentation page |
| `search` | Search code and docs across packages |
| `read_file` | Read source code by file path and line range |
| `search_project_docs` | Search docs for packages in current project |

## Configuration

### Project Configuration

Create `pkgseer.yml` in your project root:

```yaml
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](docs/implementation/architecture.md)
- [MCP Installation Guide](docs/implementation/mcp-installation.md)
- [Creating MCP Tools](docs/implementation/tools.md)
- [Authentication Flow](docs/implementation/auth.md)
- [Skills System](docs/implementation/skills.md)
- [Configuration Reference](docs/implementation/configuration.md)

## Development

See [CLAUDE.md](CLAUDE.md) for development guidelines.

```bash
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](https://pkgseer.dev) for documentation
- Report issues on [GitHub](https://github.com/pkgseer/pkgseer-cli/issues)

## License

(c) 2025-2026 Juha Litola