FAQ
Quick answers to the things developers ask first.
No. xnpm calls your installed npm binary. It does not reimplement npm, does not change how packages resolve, and does not touch the registry directly. It is a workflow layer that sits in front of npm and git.
npm scripts are useful, but every repo reinvents the release flow. xnpm gives that whole flow a standard command surface — with dependency ordering, safety checks, and structured exit codes built in from the start.
xnpm discovers packages by walking the directory tree and reading package.json files. It works alongside npm workspaces without requiring a specific monorepo structure.
Node.js 20 and above (matches @x12i/npm engines). Run xnpm doctor to verify your environment before running workflows.
xgit ships in the same @x12i/npm package as xnpm. Use xgit when git is primary (xgit status, xgit push — no git prefix). Use xnpm when npm/monorepo lifecycle is primary. Both share release, validate, ask, scripts, sibling checks, and push rebase recovery. See Install → xgit.
xnpm is a Node.js CLI and calls npm and git through their standard interfaces. macOS and Linux are fully supported. Windows support is in progress — current status is tracked in the issue tracker.
A CVE describes a bug in software. Phantom Gyp abuses gyp's <!(...) command substitution — a legitimate feature, not a flaw in npm or node-gyp. See Security for the full threat context.
npm audit only reports packages with published advisories — it cannot catch a technique proactively. --ignore-scripts blocks lifecycle hooks but not node-gyp rebuild from a malicious binding.gyp. xnpm's tarball gate scans dependencies before install — see Security.
Before any publish, xnpm validates .npmignore, runs npm pack --dry-run --json, and checks the full file list for sensitive file patterns (.env, keys, secrets). Publish is blocked until the issue is resolved. The check also runs again after the version bump.
xnpm uses your existing .npmrc, lockfiles, npm auth tokens, and git config. It does not store credentials, does not proxy the registry, and does not transmit auth information anywhere outside of npm and git themselves.
xnpm exits with code 2 (partial success) so CI pipelines can catch and handle the state correctly. The package is already on npm. The push failure is surfaced clearly — not silenced.
Since 2.29.1, xnpm retries npm registry verification after publish (5 attempts, 3s delay by default). npm can accept a package before npm view sees it everywhere — that replication lag used to be treated as a failed publish and blocked the git push. Now xnpm waits and checks again; if the version appears, the release continues and push still runs. If npm reports the version was already published, xnpm verifies it and continues rather than hard-failing.
When --push or xnpm release fails with a non-fast-forward error, xnpm/xgit fetches, shows remote and local commits, and asks: Rebase onto origin/<branch> and push now? [Y/n]. Approve to run git pull --rebase origin <branch> then push. Non-interactive: xnpm release --push --yes. Manual fallback: git pull --rebase origin main && git push origin main.
Exit 3 means an environment or permissions problem blocked the run — for example npm cache not writable, global install directory permissions, or node_modules not writable. xnpm uses an isolated cache at ~/.cache/xnpm/npm with automatic fallback to ~/.cache/xnpm/npm-clean. Fix ownership or permissions; do not use sudo for normal xnpm runs. See Install → exit codes.
No. Since 2.30.0, xnpm ask treats non-TTY, CI=true, XNPM_AGENT=1, and --agent as non-interactive contexts. If a matched command requires approval, xnpm prints the plan and exits with code 4 instead of waiting on stdin. Use --plan --json to resolve only, or --yes to execute intentionally. See Ask → code-agent-safe.
For stack releases that opt into syncInternalDepsOnPublish, yes. xnpm uses versions published earlier in the same stack release to replace local in-stack dependency specs before downstream publish, then restores the original local specs when done. See Safety → agent safety.
Local file changes are journaled and reversible with xnpm undo --last. Publish and push are external effects xnpm cannot undo, which is why they require --yes — an agent cannot trigger them by accident in a non-interactive run without that flag being set explicitly by whoever configured it. If a run fails partway, the exit code and report say exactly what happened and what didn't. See Agents → for the developer overseeing the agent.
No. xnpm sets and manages its own npm cache automatically. Generated xnpm scripts init shell scripts run from the git repo root with repo .npmrc — no wrapper exports required.
No. xnpm ask uses deterministic phrase catalogs. Unknown input fails safely with suggestions — it does not guess. Same input always produces the same command, which makes it safe to use in scripts and agent workflows.
@x12i/ask-cli is the standalone library behind xnpm ask. Any CLI can use it to add deterministic natural-language command resolution without adding an LLM dependency.
xnpm can undo local file changes: package.json edits, .gitignore and .npmignore updates, override cleanup, and lockfile changes from installs. It records every file it touches before making changes, and restores the exact prior state.
No. npm publish, git push, and remote repo creation are irreversible external effects. xnpm logs them with full details in the transaction record so you know exactly what happened, but cannot reverse them.
xnpm detects the hash mismatch and refuses to overwrite the file. You can preview the undo with xnpm undo --dry-run, or override the protection explicitly with xnpm undo --force.
Upstream is bundled in @x12i/npm. Run npm install -g @x12i/npm — no separate plugin install. Authenticate with xnpm upstream auth login (uses gh auth login or a PAT).
Yes. xnpm is MIT licensed — 100% free for personal and commercial use. No account required, no trial period, no paid tiers, no feature gates, no expiry.