> ## 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 Intelligence: metadata, vulnerabilities, dependencies, and upgrades

> Check package metadata, vulnerabilities, dependencies, changelogs, and upgrades.

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

<Note>
  The Package Intelligence tools support **12 registries**: npm, PyPI, Hex, Crates, vcpkg, Zig, NuGet, Maven, Packagist, RubyGems, Go, and Swift. Dependency data supports all 12 registries. Vulnerability data is unavailable for vcpkg and Zig.
</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. The vulnerability summary keeps two counts separate: advisories that affect the latest version, and package-wide advisory history across all versions. Pass `verbose: true` to add GitHub language breakdown, topics, last-pushed date, published-version count, download refresh date, package-wide advisory history, 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="target" type="string" required>
      Latest-only package target in `registry:name` form, for example `npm:express` or `npm:@types/node`. Scoped names are supported. Registries: `npm`, `pypi`, `hex`, `crates`, `vcpkg`, `zig`, `nuget`, `maven`, `packagist`, `rubygems`, `go`, or `swift`. `pkg_info` always returns the latest version, so omit any `@version` pin; supplying one is rejected.
    </ParamField>

    <ParamField query="verbose" type="boolean">
      When `true`, adds GitHub language/topics/last-pushed, published-version count, download refresh date, package-wide advisory history (all versions), 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 with separate latest-version and package-wide advisory counts.

    JSON output includes `versionCount` (published versions), `downloads.refreshedAt` (download data freshness), and `advisoryHistory.total` (package-wide advisory count). To list the historical advisories themselves, use `pkg_vulns` with `advisory_scope: "all"`.
  </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.

    Since CLI and MCP 0.23.0, text output labels each advisory as affecting the inspected version or historical when the service supplies that status. This is especially useful with `scope: "all"` (CLI `--scope all`): a historical critical advisory does not mean the inspected version is currently affected. JSON retains the existing applicability fields.

    By default the tool checks only the inspected package. Pass `include_transitive: true` (CLI `--transitive`) for an npm-audit-style audit that also reports vulnerabilities in the versions resolved by the dependency graph. Transitive audits are opt-in because they add graph-analysis cost.

    **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 npm:express --transitive
    npx githits@latest pkg vulns pypi:pillow --verbose
    ```

    **Parameters**

    <ParamField query="target" type="string" required>
      Package target in `registry:name[@version]` form, for example `npm:lodash@4.17.20`. Omit the version to check the latest release. Scoped names are supported. Go module versions are accepted with or without the leading `v` (`1.24.0` or `v1.24.0`); other registries reject tag-style `v`-prefixed inputs except Swift. Vulnerability data is unavailable for vcpkg and Zig.
    </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. Applies to both direct and transitive rows.
    </ParamField>

    <ParamField query="include_withdrawn" type="boolean">
      When `true`, includes retracted advisories. Defaults to `false`. Affects direct package rows only; transitive withdrawn advisories remain excluded.
    </ParamField>

    <ParamField query="include_transitive" type="boolean">
      When `true`, audits vulnerabilities in the versions resolved by the dependency graph in addition to the inspected package. Defaults to `false` because the audit adds graph-analysis cost. In the CLI, use `--transitive`.
    </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. Applies to both direct and transitive rows.
    </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.

    Pass `include_issues: true` (CLI `--issues`) to compute deprecated, outdated, duplicate, and conflict analysis across the resolved dependency graph, including actionable conflict constraints and importer provenance.

    **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
    npx githits@latest pkg deps npm:express --issues
    ```

    **Parameters**

    <ParamField query="target" type="string" required>
      Package target in `registry:name[@version]` form, for example `npm:express@5.2.1`. Omit the version to inspect the latest release. Scoped names are supported. Go module versions are accepted with or without the leading `v` (`1.24.0` or `v1.24.0`); other registries reject tag-style `v`-prefixed inputs (e.g., `v4.18.0`) except Swift — pass the canonical version number (`4.18.0`). Dependency data is available on all 12 registries: npm, PyPI, Hex, Crates, NuGet, Maven, Zig, vcpkg, Packagist, RubyGems, Go, and Swift.
    </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_issues" type="boolean">
      When `true`, computes deprecated, outdated, duplicate, and conflict analysis across the resolved dependency graph. Without `max_depth`, the analysis traverses the full graph; set `max_depth` to bound analysis cost and scope. Defaults to `false`. Use `format: "json"` (CLI `--json`) for complete issue rows, or `--verbose` in the CLI for complete issue details in text. In the CLI, use `--issues`.
    </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. Latest mode returns up to ten entries by default. Results preserve source order, which may interleave maintained release lines, so do not assume newest-first ordering. A `@from..to` range returns entries after `from` through `to`, with the starting version excluded and the ending version included. Use `@from` separately for the starting release's own notes.

    Since `githits` and `@githits/mcp` 0.21.0, `pkg_changelog` is package-only: the retired `registry`, `package_name`, `repo_url`, `git_ref`, `from_version`, and `to_version` inputs are replaced by a single required `target`, and the CLI drops `--repo-url` and `--git-ref`. Standalone repository targets are rejected. Look them up by their published package instead.

    **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@5.2.1
    npx githits@latest pkg changelog npm:express --from 4.18.0 --to 4.19.0
    npx githits@latest pkg changelog npm:express@4.21.2..5.2.1
    ```

    **Parameters**

    <ParamField query="target" type="string" required>
      Package target in one of three shapes: `registry:name` for latest mode, `registry:name@version` for one selected release, or `registry:name@from..to` for releases after `from` through `to`. Open bounds `@from..` and `@..to` are also accepted. Scoped names are supported. Go module versions are accepted with or without the leading `v`; other registries reject tag-style `v`-prefixed inputs except Swift. Package targets only — repository and `site:` targets are rejected.
    </ParamField>

    <ParamField query="limit" type="number">
      Maximum number of entries to return (1–50, default 10). Applies only to latest mode and upper-cap `@..to` targets. Rejected with an exact `@version`, a `@from..to` range, or a lower-open `@from..` target. Ranges with a starting version have no count cap.
    </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`. MCP text output with `verbose: true` includes full bodies even when this is set. In the CLI, use `--no-body`.
    </ParamField>

    <ParamField query="verbose" type="boolean">
      Text output only. Shows full body content for every entry. From MCP 0.27.0, overrides `body_lines` and `omit_bodies: true`. The CLI still rejects `--verbose` with `--no-body`.
    </ParamField>

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

    **Example**

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

    Returns: up to three entries in source order, with version, date, source URL, and a 10-line body preview. An exact version selects one release or returns `VERSION_NOT_FOUND`; a release without notes succeeds with `hasChangelog: false`. Empty latest or range selections also succeed.
  </Accordion>

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

    Use it when your agent needs upgrade facts instead of guessing from semver. The tool reports changes; 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..4.4.3
    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
    ```

    Use `..` as the range delimiter for the positional `<registry>:<name>@<current>..<target>` form and for repeatable `--package` entries. The legacy `->` delimiter is rejected with guidance to switch to `..`. A positional range already contains its target, so combining it with `--to` or `--package` is rejected.

    **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. Go module versions are accepted with or without the leading `v`. Tag-style inputs with a leading `v` are rejected for other registries except Swift.
    </ParamField>

    <ParamField query="target_version" type="string">
      The version you want to review. Go module versions are accepted with or without the leading `v`. Tag-style inputs with a leading `v` are rejected for other registries except Swift.
    </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. A batch accepts at most 30 packages after blank entries are removed; larger batches are rejected before any backend call.
    </ParamField>

    <ParamField query="skip_transitive_security" type="boolean">
      When `true`, skips current-vs-target transitive vulnerability summary diffs. Defaults to `false`, so transitive security checks 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 comparison with direct vulnerability changes, changelog entries, target deprecation status, peer dependency changes, and transitive security summaries.

    <Warning>
      A version number alone, including a patch update, does not establish compatibility. 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, upgrade paths, and opt-in transitive audits |
| `pkg_deps` | `npx githits@latest pkg deps <registry>:<package>` | Direct and transitive dependency graph with opt-in issue analysis |
| `pkg_changelog` | `npx githits@latest pkg changelog <registry>:<package>` | Release notes in source order, with range queries for upgrade review |
| `pkg_upgrade_review` | `npx githits@latest pkg upgrade-review <registry>:<package>@<current>..<target>` | Compare current and target versions without assigning risk |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.