npm + git orchestration
xnpm discovers your packages, maps who depends on what, and runs install → build → test → publish → push in the right order — across one package or fifty.
One global install. Run from any folder. Works with single packages, monorepos, and independent repos side by side.
not installed yet? ↓ install xnpm
When packages depend on each other, the order matters, the steps multiply, and one mistake means a broken release. xnpm makes it automatic and safe.
When @scope/api depends on @scope/core, you have to publish core first, update api to consume the new version, then publish api. Across 5 packages, this is a 20-step process you run from memory.
It reads every package.json, maps who depends on what, and runs the full lifecycle in dependency-first order — automatically updating each package to consume freshly published siblings before they're published themselves.
A misplaced .npmrc or .env file in your published package silently leaks credentials. By the time anyone notices, it's already on npm. xnpm blocks this before every publish.
xnpm calls the native npm and git commands on your machine. No new package manager, no custom dependency resolution, no reinvented wheel. Your existing .npmrc, auth, and git config all apply.
Run xnpm from any folder. It finds your packages, sorts them, then runs exactly the steps you asked for — nothing more.
Steps 1–3 always run. Steps 4–7 only run when the corresponding flag is passed.
Every decision was made to avoid the class of mistakes that happen when you manage multi-package releases manually.
Reads every package's dependencies, finds local relationships, and runs packages in dependency-first order. Cycles are detected and reported before any commands run.
Detects whether packages share a git root. In a monorepo, git push runs once at the end. In a multi-repo layout, each repo pushes after its own lifecycle completes.
Validates .gitignore and .npmignore, creates one if missing. Runs npm pack --dry-run twice — before and after the version bump. If any .env or .npmrc would be included, publishing is blocked.
Target specific packages with --package by exact name, or --filter with glob patterns like @x12i/* or @x12i/ai-*. Multiple filters are OR-based.
--new-public and --new-private handle first-time npm publication without a version bump. --create-git initializes local repos and optionally creates remotes on GitHub, GitLab, or Bitbucket.
Uses each package's own .npmrc if present, falls back to the invocation root via NPM_CONFIG_USERCONFIG. Never copies or prints your auth token. Tokens are redacted from all output.
--clean-local removes only file: overrides for packages in the current run. --clean-all removes the entire overrides object. A second npm install runs automatically so the lockfile stays in sync.
Without --report, native output streams directly. With it, a concise summary shows package counts, version changes, git results, security checks, and failure details. Works with --dry-run too.
Run any native npm or git command through xnpm directly — xnpm run build, xnpm status, xnpm git log. One daily command instead of three. Same isolated cache as automation.
Describe workflows in plain English. xnpm ask resolves them deterministically — a shipped phrase catalog, not an LLM. Unknown requests fail with examples, not guesses. Dangerous ops require your confirmation.
xnpm forwards native npm and git commands so you don't need to switch binaries. Automation when you need it, native tools when you don't — same process, same isolated cache.
Smart disambiguation — overloaded words routed correctly
| You type | Routes to | Why |
|---|---|---|
| install | ||
| xnpm install | xnpm scoped install | bare install stays on xnpm automation |
| 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 install flag (-D, --save-dev, etc.) → native npm |
| push / test / publish | ||
| xnpm --push | xnpm lifecycle git push | xnpm flag prefix — part of the automation run |
| xnpm push | git push | bare subcommand — passthrough to git |
| xnpm --test | xnpm lifecycle test | xnpm flag prefix — runs after build in order |
| xnpm test | npm test | bare subcommand — passthrough to npm |
| reserved — always xnpm, never passthrough | ||
| xnpm ask | xnpm ask | reserved command |
| xnpm list / ls | xnpm package discovery | reserved command |
| xnpm help | xnpm help | reserved command |
xnpm ask turns plain English into the same validated xnpm command you would type by hand — deterministic catalog matching, not AI. Safe ops run immediately; publish, push, and git operations wait for your confirmation.
You know what you want — "install and test everything under @x12i." Translating that into --filter "@x12i/*" --build --test every time is overhead. It's worse when you hand off release steps to someone else.
xnpm ask is not a separate tool. It resolves to normal xnpm flags, uses the same validator and execution plan, and never runs commands it didn't explicitly map from the catalog. Unknown input fails with examples — not guesses.
Publish, push, connect, and git creation ops are irreversible in practice. xnpm ask shows exactly what it will run and asks for y/N before any dangerous step — especially when the input came from natural language.
| You might say | Resolves to |
|---|---|
| Install & lifecycle | |
| install all packages | xnpm |
| build and test everything | xnpm --build --test |
| install, build and test all @x12i packages | xnpm --filter "@x12i/*" --build --test |
| publish all @x12i packages and push | xnpm --filter "@x12i/*" --build --test --publish --push --report |
| create new private npm packages for @x12i | xnpm --filter "@x12i/*" --build --test --new-private --report |
| Git connect & setup | |
| connect git repo to git@github.com:x12i/packages.git | xnpm --connect "git@github.com:x12i/packages.git" |
| connect monorepo to git@github.com:x12i/packages.git | xnpm --connect "..." --repo-mode monorepo |
| link remote git@github.com:x12i/core.git and push | xnpm --connect "..." --push --report |
| create git and connect to git@github.com:x12i/demo.git | xnpm --create-git --connect "..." |
| create private github repo for x12i and push | xnpm --create-git --git-create-remote --git-provider github ... |
Connect and git-create-remote operations require y/yes confirmation before running.
Flags are additive. xnpm, xnpm i, and xnpm install are equivalent. The alias x12i-npm also works.
| Flag | What it does |
|---|---|
| Lifecycle | |
| --build | Run npm run build after install |
| --test | Run npm test after build |
| --publish | Bump minor version and publish to npm |
| --push | Commit and push via git after lifecycle completes |
| --report | Suppress noisy output, show high-level summary only |
| --dry-run | Show planned execution order and steps without modifying any files |
| --no-version-bump | Publish the current version as-is, skip the minor bump |
| --clean-local | Remove local file: overrides from package.json |
| --clean-all | Remove the entire overrides object from package.json |
| Selection | |
| --package <name> | Select a specific package by exact name (repeatable) |
| --filter <glob> | Select packages matching a glob, e.g. @x12i/* or @x12i/ai-* |
| Creation (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 — clearer name for --git-link, same behavior |
xnpmxnpm --buildxnpm --build --testxnpm --build --test --publish --pushxnpm --build --test --publish --push --reportxnpm --build --test --publish --push --dry-runxnpm --publish --no-version-bumpxnpm --filter "@x12i/*" --build --publishxnpm --build --test --new-private --push --reportxnpm --connect git@github.com:x12i/pkg.git --repo-mode monorepo --pushxnpm run buildxnpm git log --oneline -5xnpm ask "build and test all @x12i packages"npx @x12i/npm --build --test
Global install makes xnpm available from any folder on your machine. The same command with @latest keeps it up to date.
To update: run the same command — @latest always installs the newest version
Requires Node.js ≥ 20 · npmjs.com/package/@x12i/npm ↗