Patch/v0.2.5

CHANGELOG.md

@@ -15,10 +15,30 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-06-01
+
+Installer migration improvements.
+
+### Added
+
+- Add `install.sh --replace-npm` to migrate from a global npm-managed `agoraio-cli` install to the standalone installer by running `npm uninstall -g agoraio-cli` before installing the binary.
+
+### 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.
+
+## [0.2.4] - 2026-06-01
+
+npm release workflow trigger tag for the v0.2.3 Cosign bundle signing fix.
+
 ### Changed
 
 - Split npm release authentication: `agoraio-cli` continues to use npm trusted publishing with provenance, while the six native platform packages publish with `NPM_TOKEN`.
 
+## [0.2.3] - 2026-06-01
+
+Release signing fix.
+
 ### Fixed
 
 - Update GoReleaser Cosign signing to emit `checksums.txt.sigstore.json` with `--bundle`, matching Cosign's current bundle-based signing flow.
@@ -276,7 +296,10 @@ Set `AGORA_ALLOW_UPGRADE_IN_CI=1` only when a CI job intentionally needs to muta
 - Support machine-readable JSON output for automation and agent workflows.
 - Ship automated release packaging through GoReleaser, including cross-platform archives, Linux packages, Homebrew, Scoop, npm wrapper packages, Docker images, and install scripts.
 
-[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/AgoraIO/cli/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/AgoraIO/cli/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/AgoraIO/cli/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/AgoraIO/cli/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/AgoraIO/cli/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/AgoraIO/cli/compare/v0.1.9...v0.2.0

README.md

@@ -310,7 +310,7 @@ GitHub Actions are configured for:
 
 Release workflow behavior:
 
-- a pushed tag matching `v*` (for example `v0.2.2`) triggers the release workflow
+- a pushed tag matching `v*` (for example `v0.2.5`) triggers the release workflow
 - the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically
 - release artifacts include checksums
 

RELEASING.md

@@ -5,8 +5,8 @@ Releases are fully automated via GoReleaser. Pushing a `v*` tag is the only manu
 ## Release
 
 ```bash
-git tag v0.2.2
-git push origin v0.2.2
+git tag v0.2.5
+git push origin v0.2.5
 ```
 
 The release workflow (`.github/workflows/release.yml`) then:

docs/install.md

@@ -105,6 +105,8 @@ If your PowerShell execution policy blocks inline scripts, download `install.ps1
 --list-versions         Print recent published versions and exit.
 --force                 Reinstall even if the requested version is present, or
                         proceed past an existing managed install warning.
+--replace-npm           If an existing npm-managed agora is detected, uninstall
+                        agoraio-cli with npm before installing this binary.
 
 # Shell integration (auto-on; pass an opt-out flag to disable)
 --no-path               Don't append the install directory to your shell rc file.
@@ -137,7 +139,7 @@ If your PowerShell execution policy blocks inline scripts, download `install.ps1
 -SkipShell              Umbrella for -NoPath -NoCompletion.
 ```
 
-If another managed `agora` install is detected, the installer refuses by default to avoid creating two installs that shadow each other on PATH. Pass `--force` to install alongside it.
+If another managed `agora` install is detected, the installer refuses by default to avoid creating two installs that shadow each other on PATH. Uninstall the existing package first, then re-run the standalone installer. For global npm installs, `--replace-npm` can perform that migration for you. Pass `--force` only when you intentionally want a side-by-side install.
 
 ## Uninstall
 
@@ -317,7 +319,14 @@ $env:VERSION = "0.2.1"
 The shell installer refuses to install over an existing managed `agora` to avoid creating two installs that shadow each other on PATH. Either:
 
 - Keep using the existing install, or
-- Re-run the installer with `--force` to install alongside it.
+- Uninstall the existing package, then re-run the standalone installer:
+
+  ```bash
+  curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
+  ```
+
+- If it is npm-managed, re-run the installer with `--replace-npm` to run `npm uninstall -g agoraio-cli` before installing the standalone binary.
+- Re-run the installer with `--force` only if you intentionally want a side-by-side install.
 
 ### PATH issues
 

install.sh

@@ -45,6 +45,7 @@ NO_COLOR_ENV="${NO_COLOR:-}"
 # ---- Mode flags ------------------------------------------------------------
 DRY_RUN=0
 FORCE=0
+REPLACE_NPM=0
 LIST_VERSIONS=0
 PRERELEASE=0
 QUIET=0
@@ -192,6 +193,8 @@ ${BOLD}Options:${RESET}
   --list-versions         Print recent published versions and exit.
   --force                 Reinstall even if the requested version is already present,
                           or proceed past a Homebrew/npm-managed install warning.
+  --replace-npm           If an existing npm-managed agora is detected, uninstall
+                          agoraio-cli with npm before installing this binary.
 
 ${BOLD}Shell integration${RESET} ${DIM}(auto-on; pass an opt-out flag to disable)${RESET}
   --no-path               Don't append the install directory to your shell rc file.
@@ -281,6 +284,10 @@ parse_args() {
         FORCE=1
         shift
         ;;
+      --replace-npm)
+        REPLACE_NPM=1
+        shift
+        ;;
       --no-path)
         NO_PATH=1
         shift
@@ -755,13 +762,41 @@ guard_managed_install() {
     return 0
   fi
 
+  if [ "$MANAGED_INSTALL" = "npm" ] && [ "$REPLACE_NPM" = "1" ]; then
+    say_step "Replacing npm-managed Agora CLI at ${MANAGED_PATH}"
+    if [ "$DRY_RUN" = "1" ]; then
+      say "  [dry-run] Would run: npm uninstall -g agoraio-cli"
+      return 0
+    fi
+    if ! npm uninstall -g agoraio-cli; then
+      die "Could not uninstall npm-managed agoraio-cli. Run ${MANAGED_UPGRADE_CMD} or uninstall it manually, then retry." "$EXIT_INSTALL"
+    fi
+    hash -r 2>/dev/null || true
+    if current_path=$(command -v agora 2>/dev/null); then
+      if [ "$current_path" = "$MANAGED_PATH" ]; then
+        die "npm uninstall completed, but agora is still present at ${MANAGED_PATH}. Remove it manually or run with --force to install alongside it." "$EXIT_INSTALL"
+      fi
+    fi
+    say_ok "Removed npm package agoraio-cli."
+    return 0
+  fi
+
   if [ "$FORCE" = "1" ]; then
     warn "Detected ${MANAGED_INSTALL}-managed install at ${MANAGED_PATH}. Continuing because --force is set."
     return 0
   fi
 
   err "Detected ${MANAGED_INSTALL}-managed install at ${MANAGED_PATH}."
   say "  Recommended: ${BOLD}${MANAGED_UPGRADE_CMD}${RESET}"
+  if [ "$MANAGED_INSTALL" = "npm" ]; then
+    say "  To switch to the standalone installer manually:"
+    say "    ${GREEN}npm uninstall -g agoraio-cli${RESET}"
+    say "    ${GREEN}curl -fsSL https://raw.githubusercontent.com/${GITHUB_REPO}/main/install.sh | sh${RESET}"
+    say "  Or re-run with ${BOLD}--replace-npm${RESET} to uninstall the npm package and install this binary."
+  else
+    say "  To switch to the standalone installer, uninstall the ${MANAGED_INSTALL} package first, then re-run:"
+    say "    ${GREEN}curl -fsSL https://raw.githubusercontent.com/${GITHUB_REPO}/main/install.sh | sh${RESET}"
+  fi
   say "  Or re-run with ${BOLD}--force${RESET} to install alongside (may shadow the ${MANAGED_INSTALL} install on PATH)."
   exit "$EXIT_INSTALL"
 }