How to upgrade Codex CLI with Homebrew

A newer Codex release can be available while Homebrew still has older package metadata. Refreshing that metadata lets Homebrew upgrade its Codex CLI cask and replace the executable linked into the package-manager prefix.

The codex cask supports macOS and Linux, and the installed copy must already be managed by Homebrew. An npm or standalone installation earlier on PATH can continue to answer codex after the cask changes.

Package replacement leaves Codex's separately stored login and configuration state in place. Homebrew can remove the previous cask version during upgrade, so returning to that release requires a separate recovery plan rather than an automatic downgrade.

1. Identify the installed Codex cask release.

   $ brew list --cask --versions codex
   codex 0.164.0

   A missing cask means this Homebrew installation does not manage Codex yet.
   Related: How to install Codex CLI with Homebrew

2. Update local Homebrew metadata.

   $ brew update

3. Upgrade the Codex cask as your normal Homebrew user.

   The upgrade replaces the installed package and can remove the old release. If returning to the previous release is essential, a backup of your Codex home and access to that release are prerequisites; reinstalling the current cask does not restore an older version.

   $ brew upgrade --cask codex
   ##### snipped #####
   ==> Upgrading codex
     0.164.0 -> 0.165.0
   ==> Unlinking Binary '/home/linuxbrew/.linuxbrew/bin/codex'
   ==> Linking Binary 'codex' to '/home/linuxbrew/.linuxbrew/bin/codex'
   ==> Purging files for version 0.164.0 of Cask codex
   🍺  codex was successfully upgraded!
   ##### snipped #####

   The --cask flag selects the Codex CLI cask. An already-current installation produces a warning instead of downloading a replacement.

4. Confirm that the active shell resolves the Homebrew binary.

   $ command -v codex
   /home/linuxbrew/.linuxbrew/bin/codex

   The path depends on the Homebrew prefix. Common macOS paths are shown below. A path outside that prefix indicates that another installation, alias, or function may take precedence.

   /opt/homebrew/bin/codex
   /usr/local/bin/codex

5. Check the cask release recorded by Homebrew after the upgrade.

   $ brew list --cask --versions codex
   codex 0.165.0

6. Verify that the active Codex CLI executable reports the upgraded release.

   $ codex --version
   codex-cli 0.165.0

   The CLI release should match the installed cask version. The release number varies with the available update.
   Related: How to check Codex CLI version