> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Package inspection: versions, docs, vulns, deps, changelogs, upgrades

> Inspect dependencies with package metadata, documentation context, vulnerabilities, dependency graphs, changelogs, and upgrade context across 12 registries.

The package inspection tools give your agent immediate access to structured metadata about any dependency without leaving the coding session. Instead of switching to a browser or running registry lookups manually, your agent can call these tools directly to triage a package, check documentation context, review vulnerabilities, understand dependencies, and inspect upgrade changes.

All five tools are available as MCP tools and as subcommands under `npx githits@latest pkg`.

<Note>
  Package inspection supports **12 registries**: npm, PyPI, Hex, Crates, vcpkg, Zig, NuGet, Maven, Packagist, RubyGems, Go, and Swift. Vulnerability data is unavailable for vcpkg and Zig. Dependency data supports npm, PyPI, Hex, Crates, Zig, vcpkg, RubyGems, Go, and Swift.
</Note>

<AccordionGroup>
  <Accordion title="pkg_info — package overview">
    `pkg_info` returns a quick triage summary for any package: the latest version, license, repository popularity, download volume, publish age, and vulnerability status. Pass `verbose: true` to add GitHub language breakdown, topics, last-pushed date, recent advisories, and recent changes.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest pkg info npm:express
    npx githits@latest pkg info pypi:requests --verbose
    npx githits@latest pkg info crates:serde
    ```

    **Parameters**

    <ParamField query="registry" type="string" required>
      The package registry. One of: `npm`, `pypi`, `hex`, `crates`, `vcpkg`, `zig`, `nuget`, `maven`, `packagist`, `rubygems`, `go`, or `swift`.
    </ParamField>

    <ParamField query="package_name" type="string" required>
      The package name. Scoped names are supported (e.g., `@types/node`).
    </ParamField>

    <ParamField query="verbose" type="boolean">
      When `true`, adds GitHub language/topics/last-pushed, recent advisories, and recent changes to the text output. Has no effect when `format: "json"` is set.
    </ParamField>

    **Example**

    ```bash theme={null}
    npx githits@latest pkg info npm:express
    ```

    Returns: version, license (MIT), description, GitHub stars/forks/open issues, weekly downloads, publish age, and a compact vulnerability status line.
  </Accordion>

  <Accordion title="pkg_vulns — vulnerability advisories">
    `pkg_vulns` fetches CVE and OSV security advisories for a package or a specific pinned version. It returns a count summary, each advisory with its OSV ID, severity, affected version ranges, and fix versions. Malicious-package advisories appear in a separate bucket.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest pkg vulns npm:lodash
    npx githits@latest pkg vulns npm:lodash@4.17.20 --severity high
    npx githits@latest pkg vulns pypi:pillow --verbose
    ```

    **Parameters**

    <ParamField query="registry" type="string" required>
      Package registry. Vulnerability data is unavailable for vcpkg and Zig.
    </ParamField>

    <ParamField query="package_name" type="string" required>
      Package name (scoped names supported).
    </ParamField>

    <ParamField query="version" type="string">
      Specific version to check. Defaults to latest when omitted.
    </ParamField>

    <ParamField query="min_severity" type="string">
      Filter to advisories at or above this level: `low`, `medium`, `high`, or `critical`. Omit to include all advisories, including those with no assigned severity.
    </ParamField>

    <ParamField query="include_withdrawn" type="boolean">
      When `true`, includes retracted advisories. Defaults to `false`.
    </ParamField>

    <ParamField query="advisory_scope" type="string">
      Which advisories to return: `affected` (default, only advisories that affect the inspected version), `non_affecting` (historical advisories that do not affect this version), or `all` (both affected and historical). Counts always include affected/non-affecting/all totals.
    </ParamField>

    <ParamField query="verbose" type="boolean">
      When `true`, shows every advisory with full detail rows in text output. `format: "json"` always returns the complete structured envelope regardless of this setting.
    </ParamField>

    **Example**

    ```bash theme={null}
    npx githits@latest pkg vulns npm:lodash@4.17.20 --severity high
    ```

    Returns: a severity-filtered advisory list with OSV IDs, affected ranges, and recommended fix versions or upgrade paths when available.

    <Warning>
      Default text output caps advisory rows for readability. Use `--verbose` to see every advisory or `--json` for the complete structured envelope.
    </Warning>
  </Accordion>

  <Accordion title="pkg_deps — dependency graph">
    `pkg_deps` lists a package's direct runtime dependencies with resolved versions. Use the `lifecycle` parameter to include non-runtime groups (development, peer, optional, build), or pass `lifecycle: "all"` to see every available group. Pass `max_depth` to add a bounded transitive dependency footprint with conflict detection and circular-dependency flags.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest pkg deps npm:express
    npx githits@latest pkg deps npm:react --lifecycle all
    npx githits@latest pkg deps npm:webpack --depth 3
    ```

    **Parameters**

    <ParamField query="registry" type="string" required>
      Package registry. Dependency data is available on npm, PyPI, Hex, Crates, Zig, vcpkg, RubyGems, Go, and Swift.
    </ParamField>

    <ParamField query="package_name" type="string" required>
      Package name (scoped names supported).
    </ParamField>

    <ParamField query="version" type="string">
      Specific version to inspect. Defaults to latest. Tag-style inputs with a leading `v` (e.g., `v4.18.0`) are rejected — pass the canonical version number (`4.18.0`).
    </ParamField>

    <ParamField query="lifecycle" type="string">
      Dependency group breadth. Omit for runtime-only. Use `runtime` for explicit runtime-only, a concrete non-runtime lifecycle (`development`, `build`, `peer`, `optional`) to add matching groups, or `all` for every available group. Accepts a single value, a comma-separated string, or an array. `all` cannot be combined with other values.
    </ParamField>

    <ParamField query="include_importers" type="boolean">
      When `true`, each entry in `transitive.packages[]` also carries an `importers` array showing every upstream package that pulls it in. If `max_depth` is omitted, this also requests the full transitive block. Off by default because enabling it roughly quadruples envelope size on heavy graphs.
    </ParamField>

    <ParamField query="max_depth" type="number">
      Add a `transitive` block and cap traversal at this depth (1-10). Omit for direct dependencies only. In the CLI, use `--depth`.
    </ParamField>

    **Example**

    ```bash theme={null}
    npx githits@latest pkg deps npm:express --lifecycle all
    ```

    Returns: runtime, development, and peer dependency groups with resolved versions for each direct dependency.
  </Accordion>

  <Accordion title="pkg_changelog — release notes">
    `pkg_changelog` retrieves release notes for a package or GitHub repository, newest-first. By default it returns the ten most recent entries. Use `from_version` and `to_version` to fetch every entry in a version range without a count cap.

    You can address by registry + package name, or directly by a GitHub repository URL when you have the URL but no registry mapping.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest pkg changelog npm:express
    npx githits@latest pkg changelog npm:express --limit 5
    npx githits@latest pkg changelog npm:express --from 4.18.0 --to 4.19.0
    npx githits@latest pkg changelog --repo-url https://github.com/expressjs/express
    ```

    **Parameters**

    <ParamField query="registry" type="string">
      Package registry (used with `package_name`). Mutually exclusive with `repo_url`.
    </ParamField>

    <ParamField query="package_name" type="string">
      Package name (used with `registry`). Mutually exclusive with `repo_url`.
    </ParamField>

    <ParamField query="repo_url" type="string">
      GitHub repository URL (e.g., `https://github.com/expressjs/express`). Mutually exclusive with `registry` + `package_name`. Use when you have a repo URL without a registry mapping.
    </ParamField>

    <ParamField query="limit" type="number">
      Maximum number of entries to return in latest mode (1–50, default 10). Cannot be combined with `from_version`.
    </ParamField>

    <ParamField query="from_version" type="string">
      Start of a version range. When set, returns every entry between `from_version` and `to_version` (or latest) with no count cap. Tag-style `v`-prefixed inputs are rejected.
    </ParamField>

    <ParamField query="to_version" type="string">
      End of the version range or latest-mode cap. Defaults to latest.
    </ParamField>

    <ParamField query="omit_bodies" type="boolean">
      When `true`, omits body content from each entry — useful when you only need the version / date / URL timeline. Defaults to `false`. In the CLI, use `--no-body`.
    </ParamField>

    <ParamField query="verbose" type="boolean">
      Text output only. Shows full body content for every entry. Mutually exclusive with `body_lines`.
    </ParamField>

    <ParamField query="body_lines" type="number">
      Text output only. Number of body lines to preview per entry (1–50, default 10). Mutually exclusive with `verbose: true`.
    </ParamField>

    **Example**

    ```bash theme={null}
    npx githits@latest pkg changelog npm:express --limit 3
    ```

    Returns: the three most recent release entries with version, date, source URL, and a 10-line body preview.
  </Accordion>

  <Accordion title="pkg_upgrade_review — upgrade evidence">
    `pkg_upgrade_review` compares the version you use today with a target version. It checks direct vulnerability changes, changelog range evidence, target deprecation metadata, peer dependency changes, dependency changes, and optional transitive evidence.

    Use it when your agent needs upgrade facts instead of guessing from semver. The tool reports evidence only; it does not decide whether an upgrade is safe.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest pkg upgrade-review npm:zod@4.3.6 --to 4.4.3
    npx githits@latest pkg upgrade-review --package npm:zod@4.3.6..4.4.3 --package npm:lint-staged@16.2.7..16.4.0
    ```

    **Parameters**

    <ParamField query="registry" type="string">
      Package registry for single-package mode. Supported registries: `npm`, `pypi`, `hex`, `crates`, `nuget`, `maven`, `zig`, `vcpkg`, `packagist`, `rubygems`, `go`, and `swift`.
    </ParamField>

    <ParamField query="package_name" type="string">
      Package name for single-package mode. Scoped names are supported.
    </ParamField>

    <ParamField query="current_version" type="string">
      The version you currently use. Tag-style inputs with a leading `v` are rejected.
    </ParamField>

    <ParamField query="target_version" type="string">
      The version you want to review. Tag-style inputs with a leading `v` are rejected.
    </ParamField>

    <ParamField query="packages" type="array">
      Batch mode. Each entry includes `registry`, `package_name`, `current_version`, and `target_version`. Mutually exclusive with the single-package fields.
    </ParamField>

    <ParamField query="skip_transitive_security" type="boolean">
      When `true`, skips current-vs-target transitive vulnerability summary diffs. Defaults to `false`, so transitive security evidence is included unless explicitly skipped. In the CLI, use `--no-transitive-security`.
    </ParamField>

    <ParamField query="include_dependency_issues" type="boolean">
      When `true`, diffs current vs target transitive deprecated, outdated, duplicate, and conflict summaries. Defaults to `false`.
    </ParamField>

    <ParamField query="min_severity" type="string">
      Minimum direct-advisory severity: `low`, `medium`, `high`, or `critical`.
    </ParamField>

    <ParamField query="verbose" type="boolean">
      Text output only. Includes dependency change examples, including transitive version changes.
    </ParamField>

    **Example**

    ```bash theme={null}
    npx githits@latest pkg upgrade-review npm:zod@4.3.6 --to 4.4.3
    ```

    Returns: a current-vs-target evidence report with direct vulnerability changes, changelog entries, target deprecation status, peer dependency changes, and transitive security summaries.

    <Warning>
      Do not treat semver alone, including patch updates, as enough upgrade evidence. Use `pkg_upgrade_review` to collect facts, then make the final risk call in your review.
    </Warning>
  </Accordion>
</AccordionGroup>

## MCP tool reference

| MCP tool             | CLI command                                                                          | Purpose                                                            |
| -------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `pkg_info`           | `npx githits@latest pkg info <registry>:<package>`                                   | Version, license, popularity, downloads, vulnerability status      |
| `pkg_vulns`          | `npx githits@latest pkg vulns <registry>:<package>`                                  | CVE/OSV advisories with severity filtering and upgrade paths       |
| `pkg_deps`           | `npx githits@latest pkg deps <registry>:<package>`                                   | Direct and transitive dependency graph                             |
| `pkg_changelog`      | `npx githits@latest pkg changelog <registry>:<package>`                              | Release notes, newest-first, with range queries for upgrade review |
| `pkg_upgrade_review` | `npx githits@latest pkg upgrade-review <registry>:<package>@<current> --to <target>` | Current-vs-target upgrade evidence without assigning risk          |