package-wizard

package-wizard is an npm library and CLI for previewing, reviewing, and applying dependency maintenance. It uses a native package.wizard.* configuration when present, with fallback support for renovate.json, npm-check-updates' .ncurc.json, and Dependabot's .github/dependabot.yml. Every change-capable command previews first; --apply is required to write package.json.

Install

To run without installing it to package.json, just run:

npx package-wizard@latest update

For use within another project's dependencies, see using as a project dependency.

Guided terminal experience

Running package-wizard without arguments opens an interactive Clack flow. It shows the selected target project, then guides users through update scope, audit severity, policy checks, pinning, exclusions, and target selection. Interactive mode requires a TTY; use an explicit command in scripts and CI.

The default task is a preview. After results are shown, interactive mode offers an explicit Apply changes confirmation. Direct commands require --apply to write.

package-wizard update
package-wizard audit
package-wizard peer-check
package-wizard check
package-wizard pin --no-update
package-wizard update --level major --apply
package-wizard update --check-peer-deps

Update runs can optionally reject candidate versions whose peer dependencies or Node.js/npm engines are incompatible with the current environment. In guided mode, this choice appears after the package-skip prompt. The standalone peer-check command performs the same compatibility check for the current dependency set.

Terminal ergonomics

Use --help for concise command-specific help, --verbose for every skipped-package reason, and --color auto|always|never or --no-color for display control. --json writes one machine-readable result to stdout.

Shell completion scripts are available for bash, zsh, and fish:

package-wizard completion zsh
package-wizard completion bash
package-wizard completion fish

Load completion for the current shell session:

source <(package-wizard completion bash)

source <(package-wizard completion zsh)

package-wizard completion fish | source

To load it in future sessions, add the Bash or Zsh command to ~/.bashrc or ~/.zshrc:

eval "$(package-wizard completion bash)"

eval "$(package-wizard completion zsh)"

For Fish, save the generated file in Fish's completion directory:

mkdir -p ~/.config/fish/completions
package-wizard completion fish > ~/.config/fish/completions/package-wizard.fish

For explanations of package behavior, update policies, audit handling, and configuration, see the package overview.

For installation in another project's dependencies, scripts, direct CLI usage, or library usage, see using as a project dependency.

Support

package-wizard is maintained in my spare time. I am a husband, father of three, and a professional nerd working to get more involved in open source.

If this project saves you time, you can support its continued maintenance through GitHub Sponsors. Funding helps with dependency updates, bug fixes, documentation, and new features.

Contributing

Install dependencies, make your changes, and run the full validation suite:

npm install
npm run test
npm run build

Open a merge request with focused changes and tests where appropriate. Use Conventional Commits for commit messages, for example:

feat: add dependency update policy
fix: handle missing package metadata
docs: clarify interactive menu usage

Releases use semantic release. Merging Conventional Commits to the release branch determines the next version, changelog, and Git tag automatically; do not edit the package version manually for normal changes.