What is the safest way to recover when an Ionic CLI upgrade fails midway and leaves mixed versions?

1. Immediate Recovery Steps

When an npm install -g @ionic/cli aborts, the global node_modules may contain a half‑written @ionic directory. The safest fix is to uninstall first and then reinstall the exact version you know works.

npm uninstall -g @ionic/cli
# Verify the directory is gone
npm root -g | xargs -I{} sh -c 'test -d {}/@ionic/cli && echo "leftover" || echo "clean"
'
# Re‑install the pinned version
npm install -g @ionic/cli@

Running npm uninstall removes any corrupted files. If the uninstall command fails due to permissions, avoid sudo—instead adjust the npm prefix to a user‑writable location (e.g., nvm or brew node). After reinstall, which ionic should point to the new binary.

2. Verification Checklist

• npm list -g @ionic/cli – should report a single version line and no errors.
• ionic --version – confirms the binary resolves.
• ionic info – shows CLI, Node, npm, and the Cordova/Capacitor tooling versions. Verify that these match the expectations for your project.
• Run a real build: ionic build (or ionic capacitor build ios if applicable). If the build succeeds and the output matches the previous stable run, the CLI is functional.

These steps guarantee that only one CLI instance is present and that it is compatible with the project’s framework and plugins.

3. Why NPM Global Installs Aren’t Transactional

NPM performs a non‑atomic copy of the package tarball into node_modules. If the process is interrupted, the directory can be left in a partially written state. NPM offers no built‑in rollback. The only supported mitigation is to pin the CLI version (e.g., via a package.json devDependency or a tool like Volta/asdf) and reinstall that version when needed.

4. Optional Cache Cleanup

Corrupted tarballs are extremely rare because NPM’s content‑addressable cache verifies integrity. Use npm cache verify only if reinstall attempts keep failing. Avoid npm cache clean --force as a first step.

5. Additional Considerations

• Make sure you’re using a single Node installation. Multiple prefixes (e.g., Homebrew node vs nvm) can leave stray global packages. Check which node and npm prefix -g to confirm.
• If you previously used sudo npm install -g, clean the global node_modules of root‑owned files before reinstalling.

6. Quick Diagnostic Question

To tailor the guidance further, could you confirm the global npm prefix you’re using?