FAQ
Quick answers to the things developers ask first.
No. xops 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. xops gives that whole flow a standard command surface — with dependency ordering, safety checks, and structured exit codes built in from the start.
xops 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/ops engines). Run xops doctor to verify your environment before running workflows.
xgit ships in the same @x12i/ops package as xops. Use xgit when git is primary (xgit status, xgit push — no git prefix). Use xops when npm/monorepo lifecycle is primary. Both share release, validate, ask, scripts, sibling checks, and push rebase recovery. See Install → xgit.
xops 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. xops's tarball gate scans dependencies before install — see Security.
Before any publish, xops 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.
xops 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.
xops 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, xops 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 xops waits and checks again; if the version appears, the release continues and push still runs. If npm reports the version was already published, xops verifies it and continues rather than hard-failing.
When --push or xops release fails with a non-fast-forward error, xops/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: xops 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. xops uses an isolated cache at ~/.cache/xops/npm with automatic fallback to ~/.cache/xops/npm-clean. Fix ownership or permissions; do not use sudo for normal xops runs. See Install → exit codes.
No. Since 2.30.0, xops ask treats non-TTY, CI=true, XOPS_AGENT=1, and --agent as non-interactive contexts. If a matched command requires approval, xops 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. xops 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 xops undo --last. Publish and push are external effects xops 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. xops sets and manages its own npm cache automatically. Generated xops scripts init shell scripts run from the git repo root with repo .npmrc — no wrapper exports required.
No. xops 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. Try it in your browser to see it resolve in real time.
@x12i/ask-cli is the standalone library behind xops ask. Any CLI can use it to add deterministic natural-language command resolution without adding an LLM dependency.
xops 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. xops logs them with full details in the transaction record so you know exactly what happened, but cannot reverse them.
xops detects the hash mismatch and refuses to overwrite the file. You can preview the undo with xops undo --dry-run, or override the protection explicitly with xops undo --force.
Only for catalog-marked seamless tools that install in user space without passwords, secrets, account setup, or privileged writes. For example, xops can bootstrap the native branch-workflow engine when a user asks for branch workflow status. Config-writing, account-backed, secret-sensitive, or privileged setup still uses an explicit setup/apply plan. Set XOPS_AUTO_INSTALL_TOOLS=0 to disable seamless auto-install.
No. xops uses npm, pnpm, or yarn where appropriate. It does not replace package resolution, registries, lockfiles, or native package-manager behavior.
No. xops supports different tool shapes: npm packages, global CLIs, config files, CI workflows, SaaS services, API tokens, local folders, and file standards such as Postman collections and OpenAPI specs. See Tools.
Only when the missing capability is relevant to the repo and xops can actually use it. For example, xops should not recommend MaGit just because MongoDB exists. It should recommend MaGit only when Mongo appears to back metadata, catalog, policy, rule, config, or deployable state. See Recommendations.
xops reports it and operates it where supported. It does not recommend installing or initializing the same capability again.
If it is optional, xops skips it. If it is required by policy, xops reports a clear failure. If xops has evidence that the missing capability would help, it appears under recommendations, not normal status.
Only if explicitly allowed. In agent mode, xops returns setup plans and exits with approval-required for mutating work unless --yes is present.
No. xops can detect local evidence for supported SaaS-backed tools, validate token presence, and generate local config or CI steps when approved. It does not create external accounts, invent tokens, or claim remote setup is complete without evidence.
xops gives code agents a deterministic operating surface for the repo. Agents can ask for status, recommendations, affected packages, plans, risks, and exact commands without rediscovering the repo from scratch or guessing shell commands. See Agents → beyond shell access.
Yes, by reducing discovery and retry loops. Instead of reading many files to understand the repo, an agent can call xops ops status, xops affected, xops recommendations, or xops ask --plan --json.
It can. xops compresses repository state into structured JSON, emits normalized findings instead of noisy logs, scopes work to affected packages, and gives exact next commands. That means less file reading, less log parsing, fewer retries, and less repeated context. See Agents → agent economics.
No. xops is not an agent and does not replace code agents. It is the operating layer that makes code-agent work safer, faster, and more deterministic.
Upstream is bundled in @x12i/ops. Run npm install -g @x12i/ops — no separate plugin install. Authenticate with xops upstream auth login (uses gh auth login or a PAT).
Yes. xops is MIT licensed — 100% free for personal and commercial use. No account required, no trial period, no paid tiers, no feature gates, no expiry.