Skip to main content

Login and first run

Package Ninja CLI login uses browser-based device authorization instead of terminal password entry. A normal first run is: install the CLI, run package-ninja login, approve the device in the browser, and then run a governed command such as package-ninja install to fetch policy and enforce it before package-manager side effects start.

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.

How do you start device authorization?​

package-ninja login

The CLI will:

  1. generate and print a device authorization code
  2. open the site authorization page in your browser
  3. poll for approval from the control plane
  4. persist local session credentials after approval

What account states can appear during first login?​

The browser flow supports these onboarding outcomes:

  • Workspace-enabled account: authorize the device immediately
  • No workspace yet: choose one setup path
    • create workspace
    • join by invite code
    • request workspace access
  • No plan/seat availability: onboarding explains blocked state and the next required admin action

What happens on the first governed command?​

package-ninja install

Preflight sequence:

  1. resolve active workspace, user, and team context
  2. fetch the current policy snapshot from the control plane
  3. evaluate the command and package request against policy
  4. emit an audit event
  5. execute the command only if the verdict permits

Direct governed commands such as install, test, publish, and run -- <command> protect that command invocation without permanently enrolling unrelated repositories. Use enable only when you want persistent shim-based governance for that project.

How do you inspect or reset the local session?​

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

Use logout for normal sign-out and token invalidation.
Use factory-reset for full local recovery.