Install — Get xops

Flags reference

Flags compose.
Pick exactly what you need.

xops, xops i, and xops 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
xops 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`
Package export contracts
xops exports check	Inspect package ESM/CJS artifacts and report missing or stale `package.json` export conditions
xops exports fix	When dual artifacts already exist, update `type`, `main`, `module`, `types`, and `exports` with undo journaling
xops exports fix --dry-run	Preview the exact export-map fix without writing `package.json`
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

Package exports

ESM/CJS contracts
without hand-editing export maps.

When a package already builds both ESM and CJS artifacts, xops exports checks whether package.json exposes them correctly to ESM hosts, CommonJS consumers, bundlers, and TypeScript.

✓
Detects dual artifact pairsRecognizes pairs such as dist/index.js + dist/index.cjs and subpaths such as dist/package-levels.js + dist/package-levels.cjs.
✓
Writes the package contractUpdates type, main, module, types, and exports conditions for import and require.
✓
Stops when the build is not realIf the package is still CJS-only, xops reports that an ESM artifact is required instead of pretending an export map can create named ESM exports.

exports workflow

$ xops exports check ! 2 export subpaths need conditions $ xops exports fix --dry-run .: import ./dist/index.js require ./dist/index.cjs ./package-levels: import ./dist/package-levels.js require ./dist/package-levels.cjs $ xops exports fix ✓ package.json updated Undo with: xops undo --last

Common commands

Copy-paste examples
for every situation.

Release playbook (named command)

xops release --report

Publish in dependency order (natural language)

xops ask "publish everything in the right order"

Scaffold tiered publish scripts

xops scripts init

Generate agent publish runbook + shell

xops scripts init runbook

Agent monorepo deploy guide

xops agent-deploy-guide

Git-first CLI — same package

xgit status xgit release --report

Install only

xops install

Install and build

xops install --build

Install, build, test

xops --build --test

Full flow — fix, install, build, test, publish, push

xops --full-flow

Publish flow — fix, install, publish, push (skip build/test)

xops --publish-flow

Pre-flight tarball inspection (no install)

xops install --inspect-only

Check and fix ESM/CJS package exports

xops exports check xops exports fix --dry-run xops exports fix

Dry run — see the plan without touching anything

xops --full-flow --dry-run

Publish without bumping the version

xops --publish --no-version-bump

Target a scope only

xops --filter "@x12i/*" --build --publish

Target two scopes

xops --filter "@x12i/*" --filter "@exellix/*" --build --test

First publish as a private scoped package

xops --build --test --new-private --push --report

Connect to remote (monorepo)

xops --connect git@github.com:x12i/pkg.git --repo-mode monorepo --push

One-off via npx — no install needed

npx @x12i/ops@latest --build --test

Natural language — resolve intent to flags

xops ask "publish all @x12i packages and push"

Check recent runs and undo status

xops history

Preview what undo would restore

xops undo --dry-run

Undo the last run (local changes only)

xops undo --last

File upstream CR/FR (auth + file submit)

xops upstream auth login xops upstream submit --file fr.md --package @x12i/ops --repo x12i/npm

Scoped fix — in-house only by default

xops install --fix xops install --fix-public --dry-run xops why-upgrade vite

Dependency usage reports

xops deps unused --include-dev xops deps usage react

Validate workspace + build smoke

xops validate --build

Check environment and fix PATH issues

xops doctor

Monorepo publish scripts

Tiered scripts and runbooks.
Generate once, run by name.

xops 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.

xops uses an isolated npm cache at ~/.cache/xops/npm with automatic fallback to ~/.cache/xops/npm-clean when the primary cache is not writable (exit 3 if no cache works).

Preflight validate

xops scripts run preflight

Build, test, publish

xops scripts run core

Full release

xops scripts run all

Agent/human runbook + ordered shell

xops scripts init runbook

Runbook for a scope only

xops scripts init runbook --filter "@scope/*"

Tiered scripts + runbook

xops scripts init all

Typical monorepo flow

$ xops map $ xops scripts init $ xops --all install $ xops scripts run preflight $ xops scripts run all

Stack releases — 2.30.0

Release order from the
stack file, not guesswork.

Stack releases honor explicit dependsOn edges in .xops/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.

$ xops list $ xops ask "release the jobs reliability stack" --plan --json $ xops release --stack jobs-reliability --dry-run --report --yes $ xops release --stack jobs-reliability --yes --report

Stacks can also opt into release-time internal dependency sync: local file: links stay for development, and xops rewrites them to registry ranges for the publish step only. See Safety.

.xops/stacks/jobs-reliability.json

{ "stack": "jobs-reliability", "syncInternalDepsOnPublish": true, "restoreFileDepsAfterRelease": true, "packages": [ { "path": "jobs-db", "name": "@exellix/jobs-db", "versionPolicy": "patch" }, { "path": "jobs", "name": "@exellix/jobs", "dependsOn": ["@exellix/jobs-db"], "versionPolicy": "patch" } ] }

Exit codes

Structured exits for CI
and agents.

Since 2.29.1, publish verification is retry-aware: after npm publish succeeds, xops 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, xops 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

xops forwards npm and git
when automation isn't needed.

You don't need to switch binaries for everyday commands. xops detects native npm and git subcommands and forwards them directly.

implicit forwarding

$ xops run build → npm run build $ xops install lodash → npm install lodash $ xops status → git status $ xops push → git push $ xops pull → git pull

explicit passthrough

$ xops npm outdated $ xops npm list --depth 0 $ xops git log --oneline -5 $ xops git diff --stat # ask resolves to passthrough too $ xops ask "show git status" → git status

Disambiguation — same word, different destination

You type	Routes to	Why
install
xops install	xops automation	bare install stays on xops
xops install --build	xops automation	xops-only flag detected
xops install lodash	npm install lodash	package name arg → native npm
xops install -D lodash	npm install -D lodash	npm flag (-D, --save-dev, …) → native npm
overloaded verbs
xops --push	xops lifecycle git push	xops flag — part of the automation run
xops push	git push	bare subcommand → passthrough
xops --test	xops lifecycle test	xops flag — runs in correct order after build
xops test	npm test	bare subcommand → passthrough
always xops — never passthrough
xops ask	xops ask	reserved
xops list / ls	xops package discovery	reserved
xops history	xops transaction history	reserved
xops undo	xops undo	reserved
xops doctor	xops doctor	reserved
xops scripts	xops 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	xops release playbook	monorepo cross-solve
xgit npm run build	npm run build	explicit npm prefix

One install.
Everything included.

Global install

CI / no install

Check setup

Flags compose.
Pick exactly what you need.

ESM/CJS contracts
without hand-editing export maps.

Copy-paste examples
for every situation.

Tiered scripts and runbooks.
Generate once, run by name.

Release order from the
stack file, not guesswork.

Same engine.
Natural git commands.

Structured exits for CI
and agents.

xops forwards npm and git
when automation isn't needed.

Open source.
MIT licensed.

One install.Everything included.

Global install

CI / no install

Check setup

Flags compose.Pick exactly what you need.

ESM/CJS contractswithout hand-editing export maps.

Copy-paste examplesfor every situation.

Tiered scripts and runbooks.Generate once, run by name.

Release order from thestack file, not guesswork.

Same engine.Natural git commands.

Structured exits for CIand agents.

xops forwards npm and gitwhen automation isn't needed.

Open source.MIT licensed.

One install.
Everything included.

Flags compose.
Pick exactly what you need.

ESM/CJS contracts
without hand-editing export maps.

Copy-paste examples
for every situation.

Tiered scripts and runbooks.
Generate once, run by name.

Release order from the
stack file, not guesswork.

Same engine.
Natural git commands.

Structured exits for CI
and agents.

xops forwards npm and git
when automation isn't needed.

Open source.
MIT licensed.