From c560e1478e1dd3211a98cfcebdf3d35fdddc72a9 Mon Sep 17 00:00:00 2001 From: digitallysavvy Date: Mon, 1 Jun 2026 17:14:54 -0400 Subject: [PATCH] docs(release): update installer migration docs Add website install and troubleshooting guidance for npm-to-standalone migration, and clarify that --force is only for intentional side-by-side installs. --- CHANGELOG.md | 1 + docs/install.md | 4 ++-- docs/troubleshooting.md | 17 +++++++++++++++++ 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9294e3b..51e344c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,7 @@ Installer migration improvements. ### Changed - Improve managed-install errors with explicit uninstall-and-reinstall guidance so users can switch to the standalone installer without relying on side-by-side PATH shadowing. +- Update website install and troubleshooting docs with npm-to-standalone migration steps and clearer PATH shadowing guidance. ## [0.2.4] - 2026-06-01 diff --git a/docs/install.md b/docs/install.md index c5086b4..6a78f3e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -192,7 +192,7 @@ Both `install.sh` and `install.ps1` use the same stable exit-code contract for s | 4 | unsupported platform / architecture | | 5 | network or download failure | | 6 | checksum verification failed | -| 7 | install or permission failure (non-writable dir, sudo, or refused to overwrite a managed install without `--force` / `-Force`) | +| 7 | install or permission failure (non-writable dir, sudo, or refused to overwrite a managed install) | | 8 | post-install verification failed | ### Idempotent re-runs @@ -201,7 +201,7 @@ Both installers short-circuit with exit `0` when the target install path already ### Managed-install detection -Both installers refuse to overwrite an `agora` binary that came from a package manager and exit `7` with a recommended upgrade command. Override with `--force` / `-Force`. +Both installers refuse to overwrite an `agora` binary that came from a package manager and exit `7` with a recommended upgrade command. Uninstall the package-manager version before switching to the standalone installer. For global npm installs on Unix shells, `--replace-npm` can run `npm uninstall -g agoraio-cli` before installing the standalone binary. Use `--force` / `-Force` only for intentional side-by-side installs. | Manager | Detected by | Recommended upgrade | | ---------------------- | ------------------------------------------------------------ | --------------------------- | diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 4d332f6..849ea1f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -65,6 +65,23 @@ where.exe agora # Windows PowerShell Reorder `PATH` so the installer's directory comes first, or remove the older binary. +If the older binary came from a global npm install and you want to switch +to the standalone installer, either migrate in one installer run: + +```bash +curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --replace-npm +``` + +Or uninstall npm first and then run the standalone installer: + +```bash +npm uninstall -g agoraio-cli +curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh +``` + +Use `--force` only when you intentionally want two installs and understand +that the first `agora` on `PATH` wins. + ## `agora init` or `agora quickstart create` fails on `git clone` The CLI shells out to `git clone` for quickstarts. Most failures map to a stable error code: