Skip to main content
Glama
README.md
# packagetrackdev

[![CI](https://github.com/packagetrack-dev/packagetrackdev/actions/workflows/ci.yml/badge.svg)](https://github.com/packagetrack-dev/packagetrackdev/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Command-line client for [PackageTrack](https://packagetrack.dev). Reads the
lock file in a project and reports which dependencies are behind, which
installed versions have been withdrawn, and what the release notes in
between say.

Supported lock files:

| Ecosystem | Files |
|---|---|
| npm | `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock` (classic and Berry), `bun.lock` |
| PyPI | `uv.lock`, `poetry.lock`, `Pipfile.lock` |
| crates.io | `Cargo.lock` |
| Packagist | `composer.lock` |
| pub.dev | `pubspec.lock` |
| NuGet | `packages.lock.json` |
| Maven | `gradle.lockfile` |
| Go | `go.mod` |

Falls back to `package.json`, `requirements.txt` or `pom.xml` when there is
no lock file; these give direct dependencies only, with versions only where
the file states them. The binary `bun.lockb` is not read: run
`bun install --save-text-lockfile` to write `bun.lock`.

## Install

macOS and Linux:

```sh
curl -fsSL https://packagetrack.dev/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://packagetrack.dev/install.ps1 | iex
```

Installs `uv` if needed, then this package and
[packagetrackdev-mcp](https://github.com/packagetrack-dev/packagetrackdev-mcp)
as `uv` tools, each checked against its published SHA256 first. No root or
administrator rights required. To reinstall or update, run the same command
again. The checked wheels stay in `~/.packagetrack/wheels`: `uv` records the
file it installed from, and `uv tool upgrade --all` reads it again.

Limits: the checksum covers this package's own wheel. Its dependencies are
downloaded by `uv` from PyPI and rest on PyPI's own checks, not on ours.

Where scripts are blocked, or to install only the CLI, follow
[the steps by hand](https://packagetrack.dev/install/manual): download the
file, check its SHA256 yourself, install it with `uv`.

Requires Python 3.11+.

## Updates

```sh
packagetrackdev update
```

Downloads the newest release from `https://packagetrack.dev`, checks its
SHA256, starts it once in a separate process, and unpacks it under
`~/.packagetrack/cli/<version>/`. The next command runs it, and
`packagetrackdev --version` shows both, for example `0.4.0 (active: 0.4.1)`.
Nothing `uv` installed is changed. Once a day after a command, one line on
stderr says when a newer release exists; `PACKAGETRACK_NO_AUTO_UPDATE=1`
turns that line off.

Coming from 0.2.x up to 0.3.1: those releases have no `update`. Run the
install command above once; after that, `packagetrackdev update` is enough.

The newest release on this computer always runs, and there is no way back
to an older one. If a release here is newer than the one the site serves
(for example after the site went back to an earlier release), `update`
changes nothing and says so. `packagetrackdev update --follow-server` then
installs the release the site serves, with the same checks, and only after
that removes the newer folders.

A release that needs a newer Python or newer packages than this installation
has is not taken: `update` asks you to run the install command again (exit
code 3).

Limits:

- The checksum covers this package's own wheel. Its dependencies come from
  PyPI through `uv`.
- Releases are not signed. The checksum comes from the same site as the
  wheel, so it catches a broken download, not a compromised site.
- Releases on this computer are trusted as far as your user account is. On
  macOS and Linux, a release folder that another user owns or can write to
  is skipped; on Windows the profile's permissions are relied on.

## Uninstall

```sh
uv tool uninstall packagetrackdev packagetrackdev-mcp
```

Then delete `~/.packagetrack/wheels` (`%USERPROFILE%\.packagetrack\wheels`
on Windows), the checked wheels `uv` installed from. Uninstall first: while a
tool is installed, `uv tool upgrade --all` reads its wheel there. The rest of
`~/.packagetrack` holds your settings and API key (`config.toml`), the
releases `update` unpacked (`cli`) and the server's own updates (`mcp`).
Deleting `cli` removes every release `update` installed, and the copy `uv`
installed runs again. Delete the whole folder to remove everything.
For a coding agent, also remove the entry: `claude mcp remove packagetrackdev`.

## Usage

```sh
packagetrackdev check                  # report on the current directory, no account needed
packagetrackdev push --name my-app     # upload the dependency set to your dashboard
packagetrackdev login --api-key pkgt_...
```

Common options:

| Option | Description |
|---|---|
| `--project DIR` | Directory to read. Default: current directory. |
| `--ecosystem NAME` | Read only one ecosystem: `npm`, `pypi`, `cargo`, `composer`, `pub`, `nuget`, `maven` or `go`. |
| `--server URL` | PackageTrack server. Default: `https://packagetrack.dev`. |
| `--dry-run` | Print the request payload and send nothing. |
| `--all` | `check` only: also list packages the archive does not hold. |

`push` needs an API key, from `packagetrackdev login`, the
`PACKAGETRACK_API_KEY` environment variable, or `--api-key`.

## What is sent

Package names and versions, and for `push`, which package required which.
No source code, file paths or repository name. `--dry-run` prints the exact
payload.

## Coding agents

The archive is also available to Claude Code, Cursor and other MCP clients
through [packagetrackdev-mcp](https://github.com/packagetrack-dev/packagetrackdev-mcp):

```sh
claude mcp add -s user packagetrackdev -- packagetrackdev-mcp
```

## Development

```sh
uv sync
uv run pytest
```

## License

MIT