Skip to main content

Install the CLI

Install @packageninja/cli when you want the current Package Ninja command set and package naming. A healthy install gives you the package-ninja command, a working --help output, and local runtime status without requiring a workspace login yet.

Package Ninja uses package-ninja as the canonical command name.

The canonical npm package is @packageninja/cli.

This guide documents only the canonical package and command names. If your machine is still on a legacy compatibility channel, upgrade to @packageninja/cli before following the examples below.

How do you install Package Ninja globally?​

npm i -g @packageninja/cli
package-ninja --help

How do you run Package Ninja without a global install?​

npx -y @packageninja/cli --help

What runtime prerequisites does Package Ninja need?​

  • Node.js 20 or newer for the published CLI launcher
  • Windows, macOS, or Linux
  • the native package manager for the target workspace, such as npm, pnpm, yarn, bun, pip, uv, poetry, pipenv, Go, Cargo, dotnet, NuGet, Maven, Gradle, or Composer

Does Package Ninja work beyond JavaScript?​

Yes for the current production adapter set.

  • package-ninja restore auto-detects supported workspaces and runs the native restore command under policy.
  • package-ninja add <package> uses the ecosystem's native add/install command where that is safe and deterministic.
  • Persistent shim setup covers the native package-manager commands for npm-family, PyPI-family, Go modules, Cargo, NuGet/dotnet, Maven/Gradle, and Composer projects.
  • package-ninja test now auto-detects the same production adapter set and runs the native test workflow where a safe default exists.
  • package-ninja plan --json previews detected ecosystems, native commands, risk class, policy freshness, artifact inspection, and audit behavior before side effects.
  • package-ninja run -- <native command> remains the universal governed path when you want to run a specific package-manager command directly.
  • package-ninja install remains available as a compatibility alias while teams move to the explicit restore and add split.
  • package-ninja dev only auto-routes when a safe default local start workflow is known, publish stays limited to ecosystems with verified local publish guardrails, and fix only auto-applies when the ecosystem supports governed direct-version remediation. For Python, that currently means uv, Poetry, and Pipenv projects rather than requirements-only or editable-manifest roots. For JVM projects, it currently means pom.xml dependencies and literal Gradle dependency declarations rather than inherited or property-backed version indirection.

The public coverage breakdown lives here:

Ecosystem coverage and rollout

How do you verify that the install worked?​

  • version returns package + runtime versions.
  • status returns auth, workspace, project, policy, and local runtime health.
  • connect completes browser authorization and project enrollment when setup is not complete yet.
  • setup-shims --json installs package-manager wrappers and reports the shim files it created.
  • doctor --json reports whether the wrappers are active on PATH.
package-ninja version
package-ninja status
package-ninja connect
package-ninja setup-shims --json
package-ninja doctor --json
package-ninja plan --json --workflow restore --cwd .

How do you upgrade the CLI?​

npm i -g @packageninja/cli@latest

How do you recover from a stale or broken local install?​

package-ninja factory-reset --yes
package-ninja connect