Skip to main content

CLI reference

Use the Package Ninja CLI when you want package-manager commands to run with pre-execution policy enforcement and audit visibility. The canonical command is package-ninja, the canonical npm package is @packageninja/cli, and compatibility aliases still exist for older installs.

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

The canonical npm package is @packageninja/cli.

If your machine still exposes the compatibility executable name package-ninja-ee, substitute that name for package-ninja in the examples below.

Which commands are the main Package Ninja workflow?​

package-ninja enable
package-ninja disable
package-ninja login
package-ninja install
package-ninja test
package-ninja publish
package-ninja bypass -- npm install left-pad
package-ninja run -- <command>
package-ninja status
package-ninja stop

Which commands handle login, logout, and local recovery?​

package-ninja auth status
package-ninja logout
package-ninja factory-reset --yes

Which flags matter most in normal CLI usage?​

  • --cwd <path> run command for a target workspace
  • --pm <npm|pnpm|yarn> force package manager selection
  • --persistent keep reusable local session active
  • --offline disable upstream resolution path
  • --admin-skip break-glass override (requires authorized role + enabled emergency mode)

How does project scoping work?​

Package Ninja now treats project governance as an explicit opt-in.

  • package-ninja enable enrolls the current project so globally installed shims govern it
  • package-ninja disable removes that project enrollment and stops local runtime state
  • plain npm, pnpm, yarn, and bun commands outside an enrolled project run directly without Package Ninja interference
  • direct governed commands such as package-ninja install or package-ninja run -- npm pack apply policy to that command without persistently enrolling unrelated repositories

If you are inside a nested folder, the CLI resolves upward to the nearest project root with a package.json.

Inside an enrolled project, every subfolder uses the same Package Ninja project binding. Moving to a different unrelated project does not automatically carry governance over; that repo must be enrolled separately.

What are the typical usage patterns?​

Install and run tests under governance:

package-ninja install
package-ninja test

Run a direct command with the same policy guardrails:

package-ninja run -- npm pack

Run a one-off intentional bypass while still leaving an auditable trail:

package-ninja bypass -- npm install some-risky-package

What does bypass do?​

  • it still evaluates the requested packages
  • it shows the same green/review/blocked preview in the terminal
  • it records the run as a bypass in audit history, including blocked packages, vulnerability signals, and remediation hints
  • it does not require a free-form reason

Recover from local auth/runtime corruption:

package-ninja factory-reset --yes
package-ninja login