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. This guide documents the canonical package-ninja command and the canonical @packageninja/cli package.

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

The canonical npm package is @packageninja/cli.

If your machine is still on a legacy compatibility channel, upgrade to @packageninja/cli before following the examples below.

Which commands are the main Package Ninja workflow?​

package-ninja connect
package-ninja enable
package-ninja disable
package-ninja login
package-ninja setup-shims
package-ninja doctor
package-ninja restore
package-ninja add left-pad
package-ninja remove left-pad
package-ninja test
package-ninja publish
package-ninja plan --json --workflow restore --cwd .
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|bun> force JavaScript workspace 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)

What command surface is first-class today?​

Today, the first-class command surface is split deliberately:

  • package-ninja restore and package-ninja test are universal governed shortcuts for the current production adapter set.
  • package-ninja connect is the recommended first-run path. It signs in when needed, enrolls the current project, fetches policy, and reports the active workspace/project state.
  • package-ninja add <package> is the explicit governed dependency-add path where the ecosystem has a safe default add flow.
  • package-ninja remove <package> is the explicit governed dependency-removal path where the ecosystem has a safe default remove flow.
  • package-ninja plan previews the same root, ecosystems, native commands, risk class, policy freshness, artifact inspection, and audit behavior that governed execution will use.
  • package-ninja run -- <native command> is the universal governed execution path for supported package-manager commands.
  • package-ninja setup-shims installs wrappers for the supported native package-manager commands so enrolled projects can use normal package-manager commands under governance.
  • package-ninja doctor verifies that the shim directory is first on PATH, each managed command resolves through Package Ninja, and the real underlying package-manager binaries are still reachable.
  • package-ninja dev auto-routes only when a safe default local start workflow is known.
  • package-ninja publish stays limited to ecosystems with verified local publish guardrails.
  • package-ninja fix can now auto-apply direct safe-version remediation for npm-family, PyPI uv/Poetry/Pipenv projects, Cargo, Go modules, NuGet, Composer, and narrow Maven/Gradle manifest patterns when the incident contains a verified upgrade target.
  • package-ninja install remains a compatibility alias: no package arguments means restore, package arguments mean add.

That means a Go project can use package-ninja restore for go mod download, package-ninja add github.com/stretchr/testify@v1.9.0 for governed dependency changes, package-ninja test for go test ./..., and package-ninja dev for go run . when the project root exposes package main. A Rust project can use package-ninja restore for cargo fetch, package-ninja add serde for governed dependency changes, package-ninja test for cargo test, and package-ninja dev for cargo run when the workspace has a runnable binary target. A single runnable .NET project can use package-ninja dev for dotnet run --project <project>.

When you need an exact native workflow, use the same governed runner instead of a one-off Package Ninja command:

package-ninja run -- cargo test
package-ninja run -- go test ./...
package-ninja run -- dotnet restore
package-ninja run -- mvn dependency:resolve

Preview before executing, especially from CI or an AI agent:

package-ninja plan --json --workflow restore --cwd .
package-ninja plan add left-pad --json --cwd .
package-ninja plan run --json -- firebase deploy --only hosting

plan does not fetch policy or execute native package-manager commands. It is a deterministic local preview of command routing and risk metadata. Actual governed execution still performs policy preflight before side effects.

For the exact support breakdown, use:

How does project scoping work?​

Package Ninja now treats project governance as simple, inspectable local project state.

  • package-ninja connect enrolls the current project after auth and policy validation
  • package-ninja enable enrolls the current project directly when you intentionally want to skip the full connection check
  • package-ninja disable removes that project enrollment and stops local runtime state
  • installed shims auto-enroll supported projects when no explicit disabled binding exists
  • direct governed commands such as package-ninja restore, package-ninja add, or package-ninja run -- npm pack apply policy and keep the project binding current

If you are inside a nested folder, the CLI resolves upward to the nearest supported project root such as package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, .csproj, .sln, pom.xml, build.gradle, or composer.json. When a single root contains multiple ecosystems, Package Ninja will only auto-route the safe shared restore/test flows from that mixed root. Exact package-manager selection, custom args, and JavaScript --pm overrides should be run from the precise project root.

Inside an enrolled project, every subfolder uses the same Package Ninja project binding. Moving to a different unrelated project uses its own .package-ninja/project.json; the same signed-in device/workspace session can govern multiple projects.

What are the typical usage patterns?​

Install and run tests under governance:

package-ninja connect
package-ninja restore
package-ninja add left-pad
package-ninja test

Run a direct command with the same policy guardrails:

package-ninja run -- npm pack
package-ninja run -- cargo test
package-ninja run -- go test ./...

Machine-readable execution:

  • package-ninja plan --json ... emits one JSON object on stdout.
  • governed workflow commands such as restore --json, add --json, and run --json emit Package Ninja JSON Lines on stderr so wrapped command stdout remains usable.
  • setup and local-state commands such as setup-shims --json, enable --json, disable --json, doctor --json, audit status --json, audit flush --json, and audit preflight --json emit one JSON object on stdout.
  • JSON events include stable fields such as schema_version, event, ok, exit_code, exit_code_name, error_code, and next_step where applicable.

Install or inspect shims from automation:

package-ninja setup-shims --json
package-ninja doctor --json
package-ninja doctor --shim-dir /opt/package-ninja/shims --json

doctor --shim-dir <path> is intended for managed images, CI runners, and agent workspaces that put shims outside the default ~/.package-ninja/bin directory.

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 connect