Skip to main content

Login and first run

Package Ninja CLI connection uses browser-based device authorization instead of terminal password entry. A normal first run is: install the CLI, run package-ninja connect, approve the device in the browser, and then keep working. connect signs in when needed, enrolls the current project, fetches policy, and shows the active workspace, team, project, ecosystems, and policy version.

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 connect a project?​

package-ninja connect

The CLI will:

  1. detect the nearest supported project root
  2. start browser device authorization if this machine is not signed in
  3. wait for site approval from a workspace-enabled account
  4. fetch the current workspace/team policy
  5. write .package-ninja/project.json with project, workspace, team, ecosystem, and policy metadata

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 after connect?​

package-ninja restore

You can preview the routing first without executing a package manager:

package-ninja plan --json --workflow restore --cwd .

Execution sequence:

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

Direct governed commands such as restore, add, test, supported publish flows, and run -- <command> protect that command invocation. connect also enrolls the current project so installed shims can govern normal package-manager commands from that project. Use enable only when you intentionally want to enroll a project without walking through the full connection check.

How do you turn on transparent package-manager protection?​

Use direct Package Ninja commands when you want the clearest governed flow:

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

Use shims when you want normal package-manager commands such as npm install, go test, or cargo add to be intercepted automatically from enrolled projects:

package-ninja setup-shims
package-ninja doctor

For agents, CI images, or managed workspaces, use the JSON contract:

package-ninja setup-shims --json
package-ninja doctor --json
package-ninja enable --cwd . --json
package-ninja status --cwd . --json

If your environment uses a custom shim location, verify that exact path:

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

How do you inspect or reset the local session?​

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

Use status for one combined view of auth, workspace, project, detected ecosystems, policy, and runtime state. Use logout for normal sign-out and token invalidation.
Use factory-reset for full local recovery.