[Windows] One-click updater .bat for Codex CLI (npm) — safe kill, skip-if-latest, alt prefix, progress UI

[brainit-consulting]

I made a Windows one-click updater for Codex CLI that:

• safely kills codex.exe (optionally node.exe with --killnode)
• cleans stale .codex-* staging dirs that can cause EBUSY/EPERM
• skips install when already on the latest (unless --forceinstall)
• supports an alternate npm prefix (--alt) when global dir is locked
• narrates steps and shows a simple progress bar

Tested with codex-cli 0.34.0 (latest as of Sep 10, 2025).
Usage (at script start is printed too):
update-codex-cli.bat [--forceinstall] [--killnode] [--alt]

Flags:
--forceinstall Force reinstall even if already on latest
--killnode Also stop node.exe (may stop n8n/dev servers)
--alt Install to %LocalAppData%\codex-global\bin

I will put the example.bat file under
scripts/windows/update-codex-cli.bat

[brainit-consulting]

But for now just save it as a .bat file in your codex cli folder
@echo off
setlocal EnableExtensions EnableDelayedExpansion
title Update Codex CLI via npm (@openai/codex@latest)

:: ------------------------------------------------------------
:: Codex CLI updater (Windows) - npm only
:: • Kills Codex (and optionally node.exe via --killnode)
:: • Cleans stale ".codex-*" staging directories
:: • Skips install if already latest (unless --forceinstall)
:: • Fallback to alternate prefix install (--alt)
:: • Narrated steps with progress bar
:: ------------------------------------------------------------

set "STEP=0"
set "TOTAL=8"
set "OLDVER="
set "NEWVER="
set "LATEST="
set "OLDVER_NUM="
set "NPM_ROOT="
set "PKG_DIR="
set "PKG_PARENT="
set "NPGBIN="
set "FORCEKILLNODE=0"
set "USE_ALTPREFIX=0"
set "FORCEINSTALL=0"
set "ALTPREFIX=%LocalAppData%\codex-global"

:: ---- parse args ------------------------------------------------
for %%A in (%*) do (
if /I "%%~A"=="--killnode" set "FORCEKILLNODE=1"
if /I "%%~A"=="--force" set "FORCEKILLNODE=1"
if /I "%%~A"=="--alt" set "USE_ALTPREFIX=1"
if /I "%%~A"=="--forceinstall" set "FORCEINSTALL=1"
)

call :header
call :usage

:: [1] Kill Codex (and optionally node.exe)
call :step "Checking for running Codex processes..."
for %%P in (codex.exe codex-x86_64-pc-windows-msvc.exe) do (
tasklist /FI "IMAGENAME eq %%P" /NH | findstr /I "%%P" >nul 2>&1 && (
echo - Found running %%P; terminating...
taskkill /IM %%P /F >nul 2>nul
)
)
if "%FORCEKILLNODE%"=="1" (
echo - --killnode enabled ^(may stop n8n or other Node apps^)
tasklist /FI "IMAGENAME eq node.exe" /NH | findstr /I "node.exe" >nul 2>&1 && (
echo Killing node.exe...
taskkill /IM node.exe /F >nul 2>nul
)
)
timeout /t 1 >nul

:: [2] Ensure npm
call :step "Checking Node/npm on PATH..."
where npm >nul 2>nul || (
echo [ERROR] npm not found on PATH. Install Node.js from https://nodejs.org and re-run.
goto :end
)

:: [3] Discover npm global root dynamically
call :step "Locating npm global root..."
for /f "delims=" %%p in ('npm root -g 2^>nul') do set "NPM_ROOT=%%p"
if not defined NPM_ROOT (
echo [ERROR] Could not determine npm global root.
goto :end
)
set "PKG_DIR=%NPM_ROOT%@openai\codex"
set "PKG_PARENT=%NPM_ROOT%@openai"
echo - npm root: %NPM_ROOT%

:: [4] Detect current Codex version
call :step "Detecting current Codex version ^(if installed^)..."
for /f "delims=" %%v in ('codex --version 2^>nul') do set "OLDVER=%%v"
if defined OLDVER (
echo - Current: !OLDVER!
:: Extract numeric part if output looks like "codex-cli 0.34.0"
set "OLDVER_NUM=!OLDVER:codex-cli =!"
) else (
echo - Not currently installed ^(or not on PATH^).
)

:: [5] Clean stale staging dirs (.codex-)
call :step "Cleaning stale staging folders in @openai..."
if exist "%PKG_PARENT%" (
for /d %%D in ("%PKG_PARENT%.codex-") do (
echo - Removing "%%~nxD"
rd /s /q "%%~fD" 2>nul
)
) else (
echo - Package namespace not present yet.
)

:: [6] Query latest on npm (optional)
call :step "Checking latest published version on npm..."
for /f "delims=" %%v in ('npm -g view @openai/codex version 2^>nul') do set "LATEST=%%v"
if defined LATEST ( echo - Latest on npm: !LATEST! ) else ( echo - Unable to query npm registry; continuing anyway. )

:: [6.5] Skip install if already latest (unless --forceinstall)
if "%FORCEINSTALL%"=="0" if defined LATEST if defined OLDVER_NUM (
if /I "!OLDVER_NUM!"=="!LATEST!" (
call :step "Already at latest (^!LATEST^). Skipping npm install."
goto verify
)
)

:: [7] Install/update @openai/codex@latest (primary attempt)
call :step "Installing @openai/codex@latest globally via npm..."
echo.
echo ------------------------------------------------------------
echo Running: npm -g install @openai/codex@latest
echo ^(npm will print its own progress; this may take a minute.^)
echo ------------------------------------------------------------
echo.
npm -g install @openai/codex@latest
if errorlevel 1 (
echo.
echo [WARN] Primary install failed ^(likely file lock^).
if "%USE_ALTPREFIX%"=="0" (
echo - Hint: re-run with --alt to install to an alternate prefix.
goto verify
) else (
echo - Trying fallback: alternate prefix
if not exist "%ALTPREFIX%\bin" mkdir "%ALTPREFIX%\bin" >nul 2>nul
echo Running: npm -g install @openai/codex@latest --prefix "%ALTPREFIX%"
npm -g install @openai/codex@latest --prefix "%ALTPREFIX%"
if errorlevel 1 (
echo [ERROR] Fallback install to "%ALTPREFIX%" failed.
goto verify
) else (
echo - Fallback succeeded.
set "NPGBIN=%ALTPREFIX%\bin"
)
)
)

:verify
:: [8] Verify & PATH guidance
call :step "Verifying installation and PATH..."
for /f "delims=" %%v in ('codex --version 2^>nul') do set "NEWVER=%%v"

if defined NEWVER (
echo - Codex now: !NEWVER!
) else (
for /f "delims=" %%p in ('npm bin -g 2^>nul') do set "NPGBIN=%%p"
if not defined NPGBIN if exist "%ALTPREFIX%\bin\codex.cmd" set "NPGBIN=%ALTPREFIX%\bin"
if exist "%NPGBIN%\codex.cmd" (
echo - Codex installed at: "%NPGBIN%\codex.cmd"
echo PATH likely missing: %NPGBIN%
echo Add it to PATH or open a new terminal.
) else (
echo - Could not find codex on PATH. Check npm output above.
)
)

echo.
echo ------------------------------------------------------------
echo Finished: %DATE% %TIME%
if defined OLDVER if defined NEWVER (
if /I "!OLDVER!"=="!NEWVER!" (
echo [INFO] Already at the latest version.
) else (
echo [OK] Updated from "!OLDVER!" to "!NEWVER!".
)
)
echo.
echo Quick commands:
echo codex --version
echo codex --continue ^(resume last session^)
echo codex --resume ^(pick a session^)
echo ------------------------------------------------------------
echo.
pause
goto :end

:: ---------- helpers ----------
:header
echo.
echo ================================================
echo Codex CLI Updater (npm) - @openai/codex@latest
echo ================================================
echo Started: %DATE% %TIME%
echo.
exit /b

:usage
echo Usage:
echo update-codex-cli.bat [--forceinstall] [--killnode] [--alt]
echo.
echo Flags:
echo --forceinstall Force reinstall even if already on latest
echo --killnode Also stop node.exe ^(may stop n8n or dev servers^)
echo --alt Install to alternate prefix: %LocalAppData%\codex-global
echo.
echo Examples:
echo update-codex-cli.bat
echo update-codex-cli.bat --killnode
echo update-codex-cli.bat --killnode --alt
echo.
exit /b

:step
set /a STEP+=1
call :bar
echo [%STEP%/%TOTAL%] %~1
exit /b

:bar
set /a PCT=(STEP100)/TOTAL
set /a FILLED=(PCT28)/100
set /a EMPTY=28-FILLED
set "BAR="
for /l %%i in (1,1,!FILLED!) do set "BAR=!BAR!#"
for /l %%i in (1,1,!EMPTY!) do set "BAR=!BAR!."
echo [!BAR!] !PCT!%%
exit /b

:end
endlocal

[brainit-consulting]

update-codex-cli.txt
Just, rename to .bat