Install
xnpm is MIT licensed — 100% free for personal and commercial use. Install once and you get the full workflow layer — automation, safety checks, undo, ask, upstream.
Requires Node.js ≥ 20 · npm ≥ 8 · git ≥ 2
Installs xnpm, xgit, x12i-npm, and x12i-git — same package, two ergonomics (xgit is git-first).
Three ways to run xnpm
Flags reference
xnpm, xnpm i, and xnpm install are equivalent. Steps 1–3 (discover, graph, install) always run. Steps 4–7 only run when you pass the flag.
Every install runs a tarball inspection gate on new registry dependencies (Security). Publish checks live on Safety.
| Flag | What it does |
|---|---|
| Lifecycle | |
| --build | Run npm run build after install, in dependency order |
| --test | Run npm test after build — blocks publish if tests fail |
| --publish | Pack-check → version bump → publish via real npm binary |
| --publish-flow | Shortcut: fix deps, install, publish, push, report |
| --full-flow | Shortcut: fix deps, install, build, test, publish, push, report |
| xnpm release | Named release playbook — same steps as --full-flow with stack support |
| --push | git add / commit / push after lifecycle — on non-fast-forward, prompts to pull --rebase then push (--yes auto-approves) |
| --yes | Non-interactive: approve dependency fixes and git rebase recovery on push |
| --report | Suppress raw output; show high-level summary with counts and version changes |
| --dry-run | Show planned steps and order without modifying any files |
| --no-version-bump | Publish the current version as-is, skip the minor bump |
| --clean-local | Remove file: overrides for discovered packages from package.json |
| --clean-all | Remove the entire overrides object from package.json |
| --inspect-only | Run pre-install tarball inspection without npm install (CI pre-flight) |
| --skip-inspect | Skip tarball inspection gate (debug only; logs a warning) |
| --force | Re-inspect tarballs; npm cache clean before install; after declined rebase, retry push with --force-with-lease |
| Selection | |
| --package <name> | Select a specific package by exact name (repeatable) |
| --filter <glob> | Select packages by glob pattern, e.g. @x12i/* — multiple filters are OR-based |
| --monorepo | From a package subfolder: discover the full git-root monorepo |
| --here | Force cwd-only discovery (default inside a named package folder) |
| --all | Discover all packages under cwd, including nested git repos (may prompt) |
| Undo & history | |
| --tx | Force transaction journaling on a single command |
| --no-tx | Disable journaling for this run (e.g. in CI where you don't need it) |
| First publish & git setup (opt-in) | |
| --new-public | First-publish as a public npm package — no version bump |
| --new-private | First-publish as a restricted npm package — scoped names only |
| --create-git | Initialize local git repo where missing, run initial commit |
| --repo-mode <mode> | monorepo or multi-repo — required when creating git across multiple packages |
| --git-create-remote | Create a new remote repo via provider API (GitHub, GitLab, Bitbucket) |
| --connect <url>alias: --git-link | Attach local repo to an existing remote |
Common commands
xnpm release --report
xnpm ask "publish everything in the right order"
xnpm scripts init
xnpm scripts init runbook
xnpm agent-deploy-guide
xgit status
xgit release --report
xnpm install
xnpm install --build
xnpm --build --test
xnpm --full-flow
xnpm --publish-flow
xnpm install --inspect-only
xnpm --full-flow --dry-run
xnpm --publish --no-version-bump
xnpm --filter "@x12i/*" --build --publish
xnpm --filter "@x12i/*" --filter "@exellix/*" --build --test
xnpm --build --test --new-private --push --report
xnpm --connect git@github.com:x12i/pkg.git --repo-mode monorepo --push
npx @x12i/npm@latest --build --test
xnpm ask "publish all @x12i packages and push"
xnpm history
xnpm undo --dry-run
xnpm undo --last
xnpm upstream auth login
xnpm upstream submit --file fr.md --package @x12i/npm --repo x12i/npm
xnpm install --fix
xnpm install --fix-public --dry-run
xnpm why-upgrade vite
xnpm deps unused --include-dev
xnpm deps usage react
xnpm validate --build
xnpm doctor
Monorepo publish scripts
xnpm scripts init writes scripts/publish-*.sh and wires root package.json publish:* entries. Scripts run from the git repo root with repo .npmrc — no wrapper exports for cache or npmrc.
xnpm uses an isolated npm cache at ~/.cache/xnpm/npm with automatic fallback to ~/.cache/xnpm/npm-clean when the primary cache is not writable (exit 3 if no cache works).
xnpm scripts run preflightxnpm scripts run corexnpm scripts run allxnpm scripts init runbookxnpm scripts init runbook --filter "@scope/*"xnpm scripts init allTypical monorepo flow
Stack releases — 2.30.0
Stack releases honor explicit dependsOn edges in .xnpm/stacks/<name>.json, even when package.json doesn't contain every operational edge. Publish order is a release contract, not just a runtime import graph.
Stacks can also opt into release-time internal dependency sync: local file: links stay for development, and xnpm rewrites them to registry ranges for the publish step only. See Safety.
xgit — git-first CLI
xgit ships in the same @x12i/npm package. Use xgit when git is primary; use xnpm when npm/monorepo lifecycle is primary. Both cross-solve: release, validate, ask, scripts, sibling checks, push rebase recovery.
Exit codes
Since 2.29.1, publish verification is retry-aware: after npm publish succeeds, xnpm checks the registry for the new version and retries (5 attempts, 3s delay by default) while npm replication catches up — instead of treating a visibility lag as a failed publish and skipping the git push. If npm reports the version was already published, xnpm verifies it and continues. See Safety.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Failed — package, registry, validation, or command error |
| 2 | Partial success — e.g. publish OK but git push failed (or rebase declined) |
| 3 | Environment / permissions — cache, global install dir, or node_modules not writable |
| 4 | Approval required — a matched command needs confirmation but none was given in a non-interactive context (--agent, CI=true, non-TTY); the plan is printed, nothing executes |
Passthrough
You don't need to switch binaries for everyday commands. xnpm detects native npm and git subcommands and forwards them directly.
Disambiguation — same word, different destination
| You type | Routes to | Why |
|---|---|---|
| install | ||
| xnpm install | xnpm automation | bare install stays on xnpm |
| xnpm install --build | xnpm automation | xnpm-only flag detected |
| xnpm install lodash | npm install lodash | package name arg → native npm |
| xnpm install -D lodash | npm install -D lodash | npm flag (-D, --save-dev, …) → native npm |
| overloaded verbs | ||
| xnpm --push | xnpm lifecycle git push | xnpm flag — part of the automation run |
| xnpm push | git push | bare subcommand → passthrough |
| xnpm --test | xnpm lifecycle test | xnpm flag — runs in correct order after build |
| xnpm test | npm test | bare subcommand → passthrough |
| always xnpm — never passthrough | ||
| xnpm ask | xnpm ask | reserved |
| xnpm list / ls | xnpm package discovery | reserved |
| xnpm history | xnpm transaction history | reserved |
| xnpm undo | xnpm undo | reserved |
| xnpm doctor | xnpm doctor | reserved |
| xnpm scripts | xnpm scripts subcommand | init, list, run, runbook |
| xgit (git-first — same package) | ||
| xgit status | git status | natural git passthrough |
| xgit push | git push | plain git; lifecycle push uses --push |
| xgit release | xnpm release playbook | monorepo cross-solve |
| xgit npm run build | npm run build | explicit npm prefix |
xnpm is 100% free — personal and commercial use. No trial, no tiers, no account required.
xnpm calls your installed npm and git binaries. It uses your existing .npmrc, lockfiles, auth tokens, and git config.
It does not replace the registry, does not reimplement dependency resolution, and does not intercept or store your credentials.