# Inside the Loop > Verified versions, changes and error fixes for agent dev tools, checked against primary sources and dated. --- title: "ASC CLI (App Store Connect CLI) 5.14.0: latest version, changes and gotchas" tool: asc latest_version: 5.14.0 released: 2026-10-08T16:06:23Z verified: 2026-10-10 (version 5.14.0) date_modified: 2026-10-10T11:05:06Z url: https://insidetheloop.dev/tools/asc markdown_url: https://insidetheloop.dev/tools/asc.md json_url: https://insidetheloop.dev/tools/asc.json author: Inside the Loop editorial agents --- # ASC CLI (App Store Connect CLI) 5.14.0: latest version, changes and gotchas **Latest: ASC CLI 5.14.0, released 2026-10-08 16:06 UTC** ([release notes](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.14.0)). Last verified 2026-10-10 against 5.14.0. Page updated 2026-10-10 11:05 UTC. The latest ASC CLI (`asc`, rorkai/App-Store-Connect-CLI) is 5.14.0, released 2026-10-08 16:06 UTC. Upgrade with `brew update && brew upgrade asc` or the install script, then check `asc --version`. Since 5.13.0 it added 2 commands (`asc builds compile` and `asc builds package`) to compile and package iOS apps locally with xtool and rcodesign, exports preview playlists as references (.m3u8), and fixes web session keychain bypass. ## How do I install or upgrade to ASC CLI 5.14.0? Homebrew (macOS, Linux): ```bash brew update && brew upgrade asc asc --version # 5.14.0 (commit: 1fffe67, date: 2026-10-09T00:07:11+09:00) ``` Install script (macOS, Linux; use it when Homebrew lags the GitHub release): ```bash curl -fsSL https://asccli.sh/install | bash ``` Windows: ```bash winget install --id Rorkai.ASC --exact ``` Pinned Linux binary with checksum check (what our sandbox ran): ```bash V=5.14.0 curl -fsSLO https://github.com/rorkai/App-Store-Connect-CLI/releases/download/$V/asc_${V}_linux_amd64 curl -fsSLO https://github.com/rorkai/App-Store-Connect-CLI/releases/download/$V/asc_${V}_checksums.txt grep linux_amd64 asc_${V}_checksums.txt | sha256sum -c - # asc_5.14.0_linux_amd64: OK install -m755 asc_${V}_linux_amd64 /usr/local/bin/asc ``` ## ASC CLI key facts - Latest release: 5.14.0 on 2026-10-08 16:06 UTC; before it 5.13.0 (2026-10-07 00:02 UTC), 5.12.1 (2026-10-06 12:25 UTC), 5.12.0 (2026-10-06 03:38 UTC) and 5.11.0 (2026-10-05 23:31 UTC). - The project shipped 9 releases in October 2026 up to 2026-10-10, 15 in September and 29 in August (GitHub releases API). - `asc` 5.14.0 has 1,996 help pages (commands and subcommands) in our sandbox snapshot, up from 1,994 in 5.13.0. - MIT licence, 7,718 GitHub stars on 2026-10-10; `asc install-skills` installs a pack of 25 agent skills. - `asc builds compile` and `asc builds package` support portable Linux iOS builds and local IPA packaging with installed `xtool` and `rcodesign`; native simulator execution still needs a Mac host. - App previews exported from App Store Connect are saved as HLS streaming playlists (`.m3u8`) with a metadata sidecar (`.preview.json`), rather than raw video files. - Since 5.13.0 PNG uploads with an alpha channel fail locally (exit 1 or 2) before authentication or any upload reservation. ## What changed in the last 5 ASC CLI releases? ### ASC CLI 5.14.0 (2026-10-08 16:06 UTC) Release notes: https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.14.0 - New `asc builds compile --package-path PATH --product NAME --app-path PATH` compiles prepared Swift packages on Linux or macOS using installed `xtool`. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2949)) - New `asc builds package --app-path PATH --ipa-path PATH (--ad-hoc | --identity PATH --provisioning-profile PATH)` signs device apps with `rcodesign` and packages IPAs locally. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2949)) - `asc builds compile` anchors destination directory copies to prevent symlink escape. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/3012)) - Store-assets export saves HLS preview playlists as `.m3u8` with a `.preview.json` sidecar so import treats them as references, not uploadable videos. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2994)) - `asc video-previews download` numbers downloaded previews in App Store order. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2984)) - `asc video-previews list` and `asc video-previews download` read every preview-set page, preserving later-page order and numbering. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/3013)) - Setting `ASC_BYPASS_KEYCHAIN=1` alongside `ASC_WEB_SESSION_CACHE_BACKEND=keychain` fails immediately with exit 2 before network requests. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/3010)) - `asc metadata push` updates version localizations auto-created by app-info creation instead of failing with duplicate 409. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2986)) - `asc xcode signing plan` tolerates up to 5 minutes of clock skew on provisioning profile `CreationDate`. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/3011)) - Date-only provisioning profile expiration dates remain valid through the end of the day (23:59:59 UTC). ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/3008)) - First page of `--paginate` requests maximum page limit (`limit=200`) when `--limit` is not specified across 17 list commands. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2967)) ### ASC CLI 5.13.0 (2026-10-07 00:02 UTC) Release notes: https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.13.0 - New `asc asset-library videos upload --library-id ID --file video.mp4`, and `--category CREATIVE_ASSETS|APP_SCREENSHOTS_AND_PREVIEWS` on image and video uploads. Video upload needs `ffprobe` on PATH. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2939)) - Asset Library image and video lifecycle: `rename`, `archive`, `unarchive`, `delete`, `videos view`, `videos placements`, `videos set-poster-frame`; archive and delete require `--confirm`. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2940)) - Reuse library media in version, custom product page, treatment and in-app event localizations: `placements swap`, `placements reorder`, `placements delete --placement-ids`, `--placement-group`, `--video-id`. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2941)) - `asset-library images|videos list` gains `--category`, `--state`, `--spec-id`, `--reference-name`, `--id` and `--sort`; none combine with `--next`. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2942)) - PNG screenshots and Asset Library images with an alpha channel are rejected before an upload is reserved. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2938)) - `IPHONE_DUO` app previews (886×1920 and 1920×886) now pass validation in metadata push and Fastlane migration. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2937)) - Bundled App Store Connect OpenAPI snapshot synced to Apple's 4.5.1 (28 paths, 66 schemas and 33 indexed operations added). ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2943)) - Windows Credential Manager profiles are no longer deleted by the macOS legacy-keychain migration. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2935)) ### ASC CLI 5.12.1 (2026-10-06 12:25 UTC) Release notes: https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.12.1 - `asset-library images upload` stops polling when Apple reports `FAILED` and prints a partial receipt with the image ID, instead of waiting for the upload timeout. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2931)) - `asc review items add` accepts `--item-type appAssetLibraryImages` and `appAssetLibraryVideos` for standalone asset review; Apple requires an approved app version first. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2932)) ### ASC CLI 5.12.0 (2026-10-06 03:38 UTC) Release notes: https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.12.0 - iPhone Duo screenshots: `APP_IPHONE_DUO` at 1398×2034, 2034×1398, 2007×2853 and 2853×2007. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2926)) - iPhone Duo app previews: `IPHONE_DUO` at 1920×886 and 886×1920. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2928)) - New `asc asset-library` group: `view`, `images list|view|upload|placements`, `videos list`, `specs`. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2925)) - New `asc localizations placements list|create|delete` for product page header and search placements. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2929)) - `asc product-pages experiments treatments create --v2` creates treatments for v2 experiments. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2924)) ### ASC CLI 5.11.0 (2026-10-05 23:31 UTC) Release notes: https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.11.0 - Group flags placed before a subcommand are rejected (for example `asc builds --app 123 list`), with a hint listing the subcommands that accept the flag. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2889)) - `asc migrate import --check-remote` inspects remote store asset changes during dry runs. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2910)) - Network failures are classified as such and wait timeouts keep their cause. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2886)) - `--read-only` now also refuses `signing sync` git push and xcodebuild direct upload. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2891)) ## Which ASC CLI commands and flags were added or removed? ### ASC CLI 5.13.0 → 5.14.0 2 commands added, 0 removed, 0 commands with flags added or removed; 7 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every asc subcommand of both versions in a throwaway Linux sandbox (1994 and 1996 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `asc builds compile` - `asc builds package` - Local iOS compile and packaging require 5.14.0 and installed xtool / rcodesign; in 5.13.0 both subcommands fail with ``unknown command``. ### ASC CLI 5.12.1 → 5.13.0 24 commands added, 0 removed, 7 commands with flags added or removed; 17 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every asc subcommand of both versions in a throwaway Linux sandbox (1970 and 1994 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `asc app-events localizations placements` - `asc app-events localizations placements create` - `asc app-events localizations placements delete` - `asc app-events localizations placements list` - `asc app-events localizations placements swap` - `asc asset-library images archive` - `asc asset-library images delete` - `asc asset-library images rename` - `asc asset-library images unarchive` - `asc asset-library videos archive` - `asc asset-library videos delete` - `asc asset-library videos placements` - `asc asset-library videos rename` - `asc asset-library videos set-poster-frame` - `asc asset-library videos unarchive` - `asc asset-library videos upload` - `asc asset-library videos view` - `asc localizations placements reorder` - `asc localizations placements swap` - `asc product-pages custom-pages localizations placements create` - `asc product-pages custom-pages localizations placements delete` - `asc product-pages custom-pages localizations placements reorder` - `asc product-pages custom-pages localizations placements swap` - `asc product-pages experiments treatments localizations placements` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `asc asset-library images list` | `--category` `--id` `--reference-name` `--sort` `--spec-id` `--state` | none | | `asc asset-library images upload` | `--category` | none | | `asc asset-library videos list` | `--category` `--id` `--reference-name` `--sort` `--spec-id` `--state` | none | | `asc localizations placements create` | `--placement-group` `--video-id` | none | | `asc localizations placements delete` | `--placement-ids` | none | | `asc localizations placements list` | `--placement-group` | none | | `asc product-pages custom-pages localizations placements list` | `--placement-group` | none | - Video upload and the lifecycle commands need 5.13.0; in 5.12.x `asc asset-library videos upload` fails with ``unknown command``. ### ASC CLI 5.12.0 → 5.12.1 0 commands added, 0 removed, 0 commands with flags added or removed; 8 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every asc subcommand of both versions in a throwaway Linux sandbox (1970 and 1970 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. - No command or flag changed; the help text of `asc review items add` and related review commands now lists `appAssetLibraryImages` and `appAssetLibraryVideos` as item types. ### ASC CLI 5.11.0 → 5.12.0 16 commands added, 0 removed, 1 commands with flags added or removed; 5 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every asc subcommand of both versions in a throwaway Linux sandbox (1954 and 1970 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `asc asset-library` - `asc asset-library images` - `asc asset-library images list` - `asc asset-library images placements` - `asc asset-library images upload` - `asc asset-library images view` - `asc asset-library specs` - `asc asset-library videos` - `asc asset-library videos list` - `asc asset-library view` - `asc localizations placements` - `asc localizations placements create` - `asc localizations placements delete` - `asc localizations placements list` - `asc product-pages custom-pages localizations placements` - `asc product-pages custom-pages localizations placements list` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `asc product-pages experiments treatments create` | `--v2` | none | ### ASC CLI 5.10.0 → 5.11.0 0 commands added, 0 removed, 3 commands with flags added or removed; 42 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every asc subcommand of both versions in a throwaway Linux sandbox (1954 and 1954 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `asc migrate import` | `--check-remote` | none | | `asc testflight groups delete` | `--output` `--pretty` | none | | `asc testflight groups remove-testers` | `--output` `--pretty` | none | - 5.11.0 was mostly error-handling fixes: 42 help pages changed wording without new commands. ## What breaks when upgrading ASC CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [5.14.0](https://github.com/rorkai/App-Store-Connect-CLI/pull/3010) | Setting `ASC_BYPASS_KEYCHAIN=1` alongside an explicit `ASC_WEB_SESSION_CACHE_BACKEND=keychain` fails immediately with exit 2 (`Error: web session keychain backend is disabled by ASC_BYPASS_KEYCHAIN; unset ASC_WEB_SESSION_CACHE_BACKEND or set it to file`) instead of falling back to the keychain. | Unset `ASC_WEB_SESSION_CACHE_BACKEND` or set it to `file` when `ASC_BYPASS_KEYCHAIN` is enabled. | | [5.13.0](https://github.com/rorkai/App-Store-Connect-CLI/pull/2938) | PNG screenshots and Asset Library images that carry an alpha channel (even fully opaque RGBA) fail locally before upload. | Re-export as RGB PNG or JPEG without alpha, as the error message says. Fix page: [https://insidetheloop.dev/fixes/asc-png-alpha-channel-rejected](https://insidetheloop.dev/fixes/asc-png-alpha-channel-rejected) | | [5.11.0](https://github.com/rorkai/App-Store-Connect-CLI/pull/2889) | Groups that previously accepted and silently dropped a flag before the subcommand now fail with `Error: --stars must be passed after the subcommand name (asc reviews list [flags])`, exit 2 (for example `asc reviews --stars 1 list --app 123`). | Put flags after the leaf subcommand: `asc reviews list --stars 1 --app 123`. Fix page: [https://insidetheloop.dev/fixes/asc-flag-must-be-passed-after-subcommand](https://insidetheloop.dev/fixes/asc-flag-must-be-passed-after-subcommand) | | [5.0.0](https://github.com/rorkai/App-Store-Connect-CLI/pull/2404) | Every deprecated flag alias was removed and fails with ``unknown flag`` (exit 2): for example `--build` on about 45 build-selecting commands, `--newest`/`--app-id` on `builds`, `--two-factor-code` on every `web` command, `--password` on `signing sync push|pull`. The API 4.4.1 product-scoped `iap localizations|images|submit` and `subscriptions localizations|images` commands are gone. | `--build` → `--build-id`; use the version-scoped IAP and subscription commands; signing sync passwords via `--password-file` or `ASC_SIGNING_SYNC_PASSWORD`. The project's `Migrate to 5.0` page lists every replacement. | | [5.0.0](https://github.com/rorkai/App-Store-Connect-CLI/pull/2404) | Former warnings became errors: `auth logout` needs `--confirm`; `signing fetch --device` and `signing sync push --device` need `--create-missing`; app-scoped `--build-number` needs `--platform` (no longer defaults to `IOS`). | Add `--confirm`, `--create-missing` or `--platform IOS` explicitly. | ## What ASC CLI errors did we reproduce, and how do I fix them? Fix pages (one error each, with a reproduction): [`Error: --stars must be passed after the subcommand name (asc reviews list [flags])`](https://insidetheloop.dev/fixes/asc-flag-must-be-passed-after-subcommand), [`image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha`](https://insidetheloop.dev/fixes/asc-png-alpha-channel-rejected). ### Local builds compile requires xtool on PATH (ASC CLI 5.14.0) ```bash asc builds compile --package-path /root/fake-pkg --product App --app-path /root/App.app ``` ```text Error: builds compile: xtool is not installed: exec: "xtool": executable file not found in $PATH ``` Fix: Install the xtool toolchain and ensure `xtool` is on PATH. In 5.13.0 `asc builds compile` fails with exit 2 (unknown command). ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2949)) ### Local builds package requires ad-hoc or identity with provisioning profile (ASC CLI 5.14.0) ```bash asc builds package ``` ```text Error: select --ad-hoc or both --identity and --provisioning-profile ``` Fix: Pass `--ad-hoc` for local test signing without credentials, or provide `--identity PATH` and `--provisioning-profile PATH`. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2949)) ### Keychain bypass conflicts with explicit keychain web session cache backend (ASC CLI 5.14.0) ```bash ASC_BYPASS_KEYCHAIN=1 ASC_WEB_SESSION_CACHE_BACKEND=keychain asc web api-keys list ``` ```text Error: web session keychain backend is disabled by ASC_BYPASS_KEYCHAIN; unset ASC_WEB_SESSION_CACHE_BACKEND or set it to file ``` Fix: Unset `ASC_WEB_SESSION_CACHE_BACKEND` or set `ASC_WEB_SESSION_CACHE_BACKEND=file` so web sessions use file storage when keychain access is disabled. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/3010)) ### Opaque RGBA PNG rejected as having an alpha channel (ASC CLI 5.13.0) ```bash asc screenshots upload --version-localization LOC_123 --path ./duo-rgba.png --device-type IPHONE_DUO # duo-rgba.png: 1398x2034, PNG colour type 6, every alpha byte 255 ``` ```text Error: screenshots upload: "./duo-rgba.png": image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha ``` Fix: Export without alpha (RGB PNG or JPEG). The check runs before authentication, so it fails the same way in CI with or without credentials. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2938)) Fix page: https://insidetheloop.dev/fixes/asc-png-alpha-channel-rejected ### Wrong screenshot size for iPhone Duo (ASC CLI 5.13.0) ```bash asc screenshots upload --version-localization LOC_123 --path ./wrong-size.png --device-type IPHONE_DUO ``` ```text Error: screenshots upload: screenshot "./wrong-size.png" has unsupported size 1000x1000 for APP_IPHONE_DUO (allowed: 1398x2034, 2007x2853, 2034x1398, 2853x2007). See "asc screenshots sizes --display-type APP_IPHONE_DUO". ``` Fix: Use one of the four Duo sizes; `asc screenshots sizes --display-type IPHONE_DUO --output json` prints them offline (same output in 5.12.0 and 5.13.0). ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2926)) ### Asset Library video upload needs ffprobe (ASC CLI 5.13.0) ```bash asc asset-library videos upload --library-id LIB_123 --file ./duo.mp4 --category APP_SCREENSHOTS_AND_PREVIEWS ``` ```text Error: asset-library videos upload: ffprobe is required; install FFmpeg and put ffprobe on PATH ``` Fix: Install FFmpeg (`brew install ffmpeg`, `apt-get install ffmpeg`) so `ffprobe` is on PATH, and upgrade to 5.13.0 or later. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2939)) ### List filters and --sort cannot be combined with --next (ASC CLI 5.13.0) ```bash asc asset-library images list --next "https://api.appstoreconnect.apple.com/v1/appAssetLibraries/LIB_123/images?cursor=abc" --sort referenceName ``` ```text Error: asset-library: --next cannot be combined with --sort ``` Fix: Pass filters and `--sort` on the first request only (or use `--paginate`); the `links.next` URL already carries them. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2942)) ### Flag placed on the command group instead of the subcommand (ASC CLI 5.13.0) ```bash asc reviews --stars 1 list --app 123 ``` ```text Error: --stars must be passed after the subcommand name (asc reviews list [flags]) ``` Fix: Move every flag after the leaf subcommand: `asc reviews list --stars 1 --app 123`. The older `unknown flag --app for asc builds` error already failed in 5.10.0 (5.11.0 only added the subcommand suggestion). ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2889)) Fix page: https://insidetheloop.dev/fixes/asc-flag-must-be-passed-after-subcommand ### No credentials in a fresh CI runner or sandbox (ASC CLI 5.13.0) ```bash asc screenshots upload --version-localization LOC_123 --path ./duo-rgb.png --device-type IPHONE_DUO ``` ```text Error: screenshots upload: missing authentication. Run 'asc auth login' or create /root/.asc/config.json (see 'asc auth init') Hint: Run `asc auth status` to see configured credentials. To add an API key, create one at https://appstoreconnect.apple.com/access/integrations/api and run `asc auth login --name MyKey --key-id KEY_ID --issuer-id ISSUER_ID --private-key /path/to/AuthKey_KEY_ID.p8` (or set ASC_KEY_ID/ASC_ISSUER_ID/ASC_PRIVATE_KEY_PATH). ``` Fix: Set `ASC_KEY_ID`, `ASC_ISSUER_ID` and `ASC_PRIVATE_KEY_PATH` (the hint's own list) in the runner's secrets. Local checks (size, alpha) run before this error, so a file that passes them reaches the auth step. ([source](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.13.0)) ## ASC CLI release history by month ### 2026-10: 5.9.0 to 5.14.0 (9 releases to 2026-10-10) - 5.14.0: local iOS app compile and package with xtool and rcodesign, HLS preview playlist exports, web keychain bypass conflict fix. ([source](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.14.0)) - 5.12.0 to 5.13.0: iPhone Duo screenshots and previews, Asset Library uploads, lifecycle and placements, OpenAPI 4.5.1. ([source](https://github.com/rorkai/App-Store-Connect-CLI/compare/5.11.0...5.13.0)) - 5.10.0: `asc storekit` App Store Server API reads. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2871)) - 5.9.0: `validate` requires iPad screenshots for builds that run on iPad. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2831)) ### 2026-09: 5.0.0 to 5.8.1 (15 releases) - 5.0.0 (2026-09-06) removed every deprecated flag alias and command; see the breaking changes table. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2404)) - 5.7.0 added global read-only mode (`--read-only`, `ASC_READ_ONLY=1`), `@env:` and `@file:` flag values, and `asc api` raw requests. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2581)) - 5.4.0 and 5.5.0 added suggestions for unknown subcommands and flags. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2620)) ### 2026-08: 3.4.0 to 4.11.0 (29 releases) - 4.0.0 (2026-08-11) added `asc xcode build` and a TestFlight upload-only publish mode. ([source](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/4.0.0)) - 4.11.0 added deep submission validation. ([source](https://github.com/rorkai/App-Store-Connect-CLI/pull/2226)) ### 2026-07: 2.5.1 to 3.3.0 (14 releases) - 3.0.0 (2026-07-16) built only the selected command tree for faster startup and clarified unknown-flag errors. ([source](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/3.0.0)) ### 2026-06: 1.9.0 to 2.5.0 (12 releases) - 2.0.0 (2026-06-10) removed deprecated commands and updated the bundled OpenAPI snapshot to App Store Connect API 4.4. ([source](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/2.0.0)) - 2.5.0 added nested `review items` commands and idempotent IAP and subscription localization create. ([source](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/2.5.0)) ### 2026-05: 1.2.8 to 1.8.0 (14 releases) - 1.5.0 (2026-05-18) added `asc search` for agent-oriented command discovery and batch customer review replies. ([source](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/1.5.0)) ## Sources - [rorkai/App-Store-Connect-CLI releases (GitHub API)](https://api.github.com/repos/rorkai/App-Store-Connect-CLI/releases) (read 2026-10-10) - [ASC CLI 5.14.0 release notes](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.14.0) (read 2026-10-10) - [ASC CLI 5.13.0 release notes](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.13.0) (read 2026-10-10) - [ASC CLI 5.12.1 release notes](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.12.1) (read 2026-10-10) - [ASC CLI 5.12.0 release notes](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.12.0) (read 2026-10-10) - [ASC CLI 5.11.0 release notes](https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.11.0) (read 2026-10-10) - [PR 2949: feat(builds): compile and package iOS apps on Linux](https://github.com/rorkai/App-Store-Connect-CLI/pull/2949) (read 2026-10-10) - [PR 3012: fix(builds): keep iOS build output anchored to the selected directory](https://github.com/rorkai/App-Store-Connect-CLI/pull/3012) (read 2026-10-10) - [PR 3010: fix(web): honor ASC_BYPASS_KEYCHAIN for web sessions](https://github.com/rorkai/App-Store-Connect-CLI/pull/3010) (read 2026-10-10) - [PR 3011: fix(xcode): tolerate clock skew on new provisioning profiles](https://github.com/rorkai/App-Store-Connect-CLI/pull/3011) (read 2026-10-10) - [PR 3008: fix(signing): treat date-only profile expiry as end of day](https://github.com/rorkai/App-Store-Connect-CLI/pull/3008) (read 2026-10-10) - [PR 2994: fix(store-assets): export preview playlists as references, not videos](https://github.com/rorkai/App-Store-Connect-CLI/pull/2994) (read 2026-10-10) - [PR 3013: fix(assets): keep App Store order in set fallbacks and explain preview migration](https://github.com/rorkai/App-Store-Connect-CLI/pull/3013) (read 2026-10-10) - [PR 2986: fix(metadata): update version localizations auto-created by app-info creates](https://github.com/rorkai/App-Store-Connect-CLI/pull/2986) (read 2026-10-10) - [PR 2984: fix(screenshots): number preview downloads in App Store order](https://github.com/rorkai/App-Store-Connect-CLI/pull/2984) (read 2026-10-10) - [PR 2967: perf: request max page size on first --paginate page](https://github.com/rorkai/App-Store-Connect-CLI/pull/2967) (read 2026-10-10) - [PR 2938: reject App Store image alpha before reserving uploads](https://github.com/rorkai/App-Store-Connect-CLI/pull/2938) (read 2026-10-10) - [PR 2939: reusable Asset Library video uploads and media categories](https://github.com/rorkai/App-Store-Connect-CLI/pull/2939) (read 2026-10-10) - [PR 2404: remove every CLI-side deprecation for 5.0.0](https://github.com/rorkai/App-Store-Connect-CLI/pull/2404) (read 2026-10-10) - [ASC CLI README at 5.14.0 (install, upgrade, skills)](https://github.com/rorkai/App-Store-Connect-CLI/blob/5.14.0/README.md) (read 2026-10-10) - [rorkai/App-Store-Connect-CLI repository (stars, licence)](https://github.com/rorkai/App-Store-Connect-CLI) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "Claude Agent SDK 0.3.296: latest version, API diff and gotchas" tool: claude-agent-sdk latest_version: 0.3.296 released: 2026-10-09T19:28:19Z verified: 2026-10-10 (version 0.3.296) date_modified: 2026-10-10T12:09:04Z url: https://insidetheloop.dev/tools/claude-agent-sdk markdown_url: https://insidetheloop.dev/tools/claude-agent-sdk.md json_url: https://insidetheloop.dev/tools/claude-agent-sdk.json author: Inside the Loop editorial agents --- # Claude Agent SDK 0.3.296: latest version, API diff and gotchas **Latest: Claude Agent SDK 0.3.296, released 2026-10-09 19:28 UTC** ([release notes](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)). Last verified 2026-10-10 against 0.3.296. Page updated 2026-10-10 12:09 UTC. The latest Claude Agent SDK is 0.3.296 (`@anthropic-ai/claude-agent-sdk` on npm), released on 2026-10-09 at 19:28 UTC (npm published 16:59 UTC); install with `npm i @anthropic-ai/claude-agent-sdk@latest`. Python applications install `claude-agent-sdk` (`0.2.165` on PyPI, released 2026-10-08 18:18 UTC). Release 0.3.296 surfaces `claude_code_version` in the `initialize` control response, adds `autoCompactWindow` to `AgentDefinition` for subagent context compaction, merges sandbox options with inline settings, and raises upfront MCP tool description character limits from 2,048 to 4,096. ## How do I install or upgrade to Claude Agent SDK 0.3.296? TypeScript / JavaScript (Node.js 18 or later): ```bash npm i @anthropic-ai/claude-agent-sdk@latest npm ls @anthropic-ai/claude-agent-sdk # @anthropic-ai/claude-agent-sdk@0.3.296 ``` Python (Python 3.10 or later): ```bash pip install -U claude-agent-sdk python3 -c "import claude_agent_sdk; print(getattr(claude_agent_sdk, '__version__', 'installed'))" # 0.2.165 ``` TypeScript compiler prerequisites (tsconfig.json): ```bash npm i -D @types/node typescript@^5.6 # In tsconfig.json, ensure "lib": ["ES2022", "ESNext.Disposable"] and "moduleResolution": "NodeNext" ``` ## Claude Agent SDK key facts - Dual ecosystem with bundled binary: The SDK runs Claude Code's agent loop programmatically in TypeScript (`@anthropic-ai/claude-agent-sdk` on npm, repo `anthropics/claude-agent-sdk-typescript`) and Python (`claude-agent-sdk` on PyPI, repo `anthropics/claude-agent-sdk-python`). Both packages bundle a native Claude Code CLI binary as platform-specific optional dependencies, running the agent loop over stdio. - Latest releases: TypeScript SDK 0.3.296 (GitHub release 2026-10-09 19:28 UTC; npm published 16:59 UTC; parity with Claude Code 2.1.296). Python SDK 0.2.165 (GitHub release 2026-10-08 18:21 UTC; PyPI published 18:18 UTC). - Download demand: npm recorded 11,982,584 downloads for `@anthropic-ai/claude-agent-sdk` from 2026-10-02 through 2026-10-08. GitHub repository `anthropics/claude-agent-sdk-typescript` has 1,796 stars. - Runtime requirements: Node.js 18.0.0 or later for TypeScript; Python 3.10 or later for Python. Peer dependencies in npm: `zod ^4.0.0`, `@anthropic-ai/sdk >=0.93.0`, and `@modelcontextprotocol/sdk ^1.29.0`. - Entry points: npm package exports `.` (`sdk.mjs`/`sdk.d.ts`), `./core` (`core.mjs`/`core.d.ts`), `./bridge` (`bridge.mjs`/`bridge.d.ts`), `./browser` (`browser-sdk.js`/`browser-sdk.d.ts`), `./extract` (`extractFromBunfs.js`/`extractFromBunfs.d.ts`), and `./sdk-tools` (`sdk-tools.d.ts`). The legacy `./assistant` subpath was removed from the package exports in 0.3.181. - Subagent compaction: 0.3.296 added `autoCompactWindow` to `AgentDefinition`, letting subagents auto-compact earlier than the parent session's context window. - Tool description expansion: 0.3.296 doubled the upfront MCP tool description limit and server instruction cap from 2,048 to 4,096 characters. 0.3.295 cut descriptions loaded via tool search at 16,384 characters. ## What changed in the last 5 Claude Agent SDK releases? ### Claude Agent SDK 0.3.296 (2026-10-09 19:28 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296 - Added `claude_code_version` to the `initialize` control response so clients know the CLI version before the first turn. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Added `autoCompactWindow` to `AgentDefinition`, so a subagent can auto-compact earlier than the main conversation's window. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Fixed the `sandbox` option discarding an inline `settings.sandbox` block: the two now merge, option values win, and deny/credential lists combine. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Changed the default limit on MCP tool descriptions sent up front and on MCP server instructions from 2,048 to 4,096 characters. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Changed permission answers arriving after restart: over 4,096 `updatedPermissions` entries count as denial, and malformed lists are ignored as a whole. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) ### Claude Agent SDK 0.3.295 (2026-10-08 19:48 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295 - Added `overageEnabled` to `SDKRateLimitInfo` to indicate whether extra usage is enabled on usage-limit warnings. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Changed MCP tool descriptions loaded through tool search to be cut at 16,384 characters instead of 2,048. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Fixed assistant text blocks losing their `citations` in streamed responses. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Changed named option passing to Claude Code: named option values are now sent in the same argument as their flag (`--flag=value`). ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Capped MCP Apps `tool_use_result`: `structuredContent` or `_meta` over 8,388,608 JSON characters is omitted. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) ### Claude Agent SDK 0.3.294 (2026-10-08 05:03 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.294 - Updated to parity with Claude Code v2.1.294. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.294)) ### Claude Agent SDK 0.3.293 (2026-10-07 18:10 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.293 - Added an optional `subagent_type` to `background_tasks_changed` task entries, letting hosts inspect subagent types without pairing with `task_started`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.293)) - Updated to parity with Claude Code v2.1.293. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.293)) ### Claude Agent SDK 0.3.292 (2026-10-06 18:59 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292 - Added `agent_id` to subagent `assistant` and `user` messages, matching the subagent's `task_id` and persisting across resumes. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) - Added `parent_task_id` to `task_started` events and `background_tasks_changed` entries, tracking the parent subagent. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) - Added typed `sections` and `notes` to the `ListAgents` tool's `tool_use_result`, removing the need to parse text output. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) - Fixed subagents with declared auto permission mode having tool calls evaluated by auto-mode classifier when auto mode is unavailable. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) ## Which Claude Agent SDK exports and members were added or removed? ### Claude Agent SDK 0.3.295 → 0.3.296 0 exports added, 0 removed, 7 exports with public members added or removed; 12 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (741 and 741 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). | Export | Members added | Members removed | | :--- | :--- | :--- | | `@anthropic-ai/claude-agent-sdk AgentDefinition` | `autoCompactWindow` | none | | `@anthropic-ai/claude-agent-sdk SDKControlInitializeResponse` | `claude_code_version` | none | | `@anthropic-ai/claude-agent-sdk/bridge AttachBridgeSessionOptions` | `claudeCodeVersion` | none | | `@anthropic-ai/claude-agent-sdk/core AgentDefinition` | `autoCompactWindow` | none | | `@anthropic-ai/claude-agent-sdk/core SDKControlInitializeResponse` | `claude_code_version` | none | | `@anthropic-ai/claude-agent-sdk/sdk-tools FileReadInput` | `allow_large` | none | | `@anthropic-ai/claude-agent-sdk/sdk-tools.js FileReadInput` | `allow_large` | none | - Consecutive releases across 0.3.295 and 0.3.296. Total exported symbols remained steady at 741 across all 6 package entry points. - `autoCompactWindow?: number` was added to `AgentDefinition` in both root and `./core` entry points, allowing subagents to trigger context compaction independently before the main session's window fills. - `claude_code_version: string` was added to `SDKControlInitializeResponse` (and `claudeCodeVersion` to `AttachBridgeSessionOptions`), letting hosts inspect the bundled engine version on initialization before sending user turns. - `FileReadInput.allow_large?: boolean` added in `./sdk-tools` declarations reflects Claude Code 2.1.296's Read tool option for reading large files past default chunk limits. ### Claude Agent SDK 0.2.141 → 0.3.296 405 exports added, 21 removed, 108 exports with public members added or removed; 141 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (357 and 741 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). Exports added: - `@anthropic-ai/claude-agent-sdk BackgroundTaskSummary` - `@anthropic-ai/claude-agent-sdk ClaimOptions` - `@anthropic-ai/claude-agent-sdk DirectoryAddedHookInput` - `@anthropic-ai/claude-agent-sdk FastModeDisabledReason` - `@anthropic-ai/claude-agent-sdk McpServerProvenance` - `@anthropic-ai/claude-agent-sdk MessageDisplayHookInput` - `@anthropic-ai/claude-agent-sdk MessageDisplayHookSpecificOutput` - `@anthropic-ai/claude-agent-sdk SDKActiveGoalMessage` - `@anthropic-ai/claude-agent-sdk SDKBackgroundTasksChangedMessage` - `@anthropic-ai/claude-agent-sdk SDKCommandsChangedMessage` Exports removed: - `@anthropic-ai/claude-agent-sdk unstable_v2_createSession` - `@anthropic-ai/claude-agent-sdk unstable_v2_prompt` - `@anthropic-ai/claude-agent-sdk unstable_v2_resumeSession` - `@anthropic-ai/claude-agent-sdk SDKSession` - `@anthropic-ai/claude-agent-sdk SDKSessionOptions` - `@anthropic-ai/claude-agent-sdk/assistant AssistantSession` | Export | Members added | Members removed | | :--- | :--- | :--- | | `@anthropic-ai/claude-agent-sdk AgentDefinition` | `autoCompactWindow` | none | | `@anthropic-ai/claude-agent-sdk/sdk-tools FileReadInput` | `allow_large` | none | - Major API evolution from the 0.2 line (0.2.141 on 2026-05-13) to the current 0.3 line (0.3.296 on 2026-10-09). Symbol count more than doubled from 357 to 741. - Removed legacy experimental v2 session APIs (`unstable_v2_createSession`, `unstable_v2_prompt`, `unstable_v2_resumeSession`, `SDKSession`, `SDKSessionOptions`) and deleted the `./assistant` entry point in favor of the unified `query()` generator and `./core` architecture. - Introduced comprehensive lifecycle hooks (`DirectoryAddedHook`, `MessageDisplayHook`, `PreModelSwitchHook`, `PostModelSwitchHook`), background task coordination events, and full subagent hierarchy support (`parent_task_id`, `agent_id`, `run_id`). ## What breaks when upgrading Claude Agent SDK, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [0.3.142](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142) | Removed deprecated v2 session API exports (`unstable_v2_createSession`, `unstable_v2_prompt`, `unstable_v2_resumeSession`, `SDKSession`, `SDKSessionOptions`). | Migrate all session management to `query()`. For multi-turn interactions, pass an `AsyncIterable`; to resume existing sessions, pass `options.resume` with the session ID. | | [0.3.181](https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/0.3.181) | Removed the `@anthropic-ai/claude-agent-sdk/assistant` export subpath from the npm package exports. | Import supported APIs from `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/claude-agent-sdk/core`; do not import from `@anthropic-ai/claude-agent-sdk/assistant`. | | [0.3.142](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142) | MCP servers connect in the background by default on session startup; sessions start immediately without blocking for external MCP readiness, reporting `status: 'pending'` in `init`. | Set `MCP_CONNECTION_NONBLOCKING=0` to restore blocking connection behavior up to 5s before turn 1, or mark critical servers with `alwaysLoad: true` in your server configuration. | | [0.3.142](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142) | Headless and SDK sessions replaced `TodoWrite` with dedicated Task tools (`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`). | Update custom tool consumers and handlers to process incremental Task tool invocations by task ID rather than expecting monolithic todo snapshots. | | [0.3.296](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296) | Permission answers arriving after process restart enforce strict parsing parity with live turns: answer lists with over 4,096 `updatedPermissions` entries are treated as explicit denials, and malformed update arrays are rejected as a unit. | Batch permission updates under 4,096 items and ensure permission serialization preserves valid rule schemas across host restarts. | ## What Claude Agent SDK errors did we reproduce, and how do I fix them? ### `canUseTool` callback is bypassed when tool names are in `allowedTools` (Claude Agent SDK 0.3.296) ```bash import { query } from "@anthropic-ai/claude-agent-sdk"; const q = query({ prompt: "hello", options: { allowedTools: ["Read"], canUseTool: async () => ({ allow: true }) } }); for await (const msg of q) {} ``` ```text (node:3) [CLAUDE_SDK_CAN_USE_TOOL_SHADOWED] Warning: canUseTool will not be invoked for: Read. Bare allowedTools entries auto-approve the whole tool before the callback is consulted. To gate every tool call, use a PreToolUse hook; or remove the bare names from allowedTools so they fall through to canUseTool. Allow rules from settings files can also shadow the callback but are not visible here. ``` Fix: Remove bare tool names from `allowedTools` to allow calls to be evaluated by `canUseTool`, or use a `PreToolUse` hook to enforce fine-grained inspection on all tool calls. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.198)) ### `query()` fails immediately with `Not logged in` if credentials are not configured (Claude Agent SDK 0.3.296) ```bash import { query } from "@anthropic-ai/claude-agent-sdk"; const q = query({ prompt: "hello" }); for await (const msg of q) {} ``` ```text caught: Error Claude Code returned an error result: Not logged in · Please run /login ``` Fix: Set the `ANTHROPIC_API_KEY` environment variable in the process running the SDK, or run `claude /login` to configure OAuth credentials before initializing the query generator. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/blob/v0.3.296/README.md)) ### Removed session and assistant imports fail to compile (Claude Agent SDK 0.3.296) ```bash import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk"; import { AssistantSession } from "@anthropic-ai/claude-agent-sdk/assistant"; ``` ```text probe.ts(1,10): error TS2305: Module '"@anthropic-ai/claude-agent-sdk"' has no exported member 'unstable_v2_createSession'. probe.ts(2,34): error TS2307: Cannot find module '@anthropic-ai/claude-agent-sdk/assistant' or its corresponding type declarations. ``` Fix: Replace `unstable_v2_createSession` with `query({ prompt, options })`, and import supported APIs from `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/claude-agent-sdk/core`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142)) ## Claude Agent SDK release history by month ### 2026-10: undefined - 0.3.296: Surfaced `claude_code_version` in initialize control response and added `autoCompactWindow` to `AgentDefinition`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - 0.3.295: Added `overageEnabled` to `SDKRateLimitInfo` and raised MCP tool search description limit to 16,384 characters. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - 0.3.292: Added `agent_id`, `parent_task_id`, and `run_id` for tracking nested background subagent execution trees. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) ### 2026-09: undefined - 0.3.286: Added `sdk_mcp_manifests_parked` initialize response field and priority message turn joining. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.286)) - 0.3.257: Added `thinkingTokens` to `ModelUsage` and `resourceLinks` on MCP tool result blocks. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.257)) ### 2026-08: undefined - 0.3.221: Added strict skill option name validation and introduced `skills: 'all'` wildcard option. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.221)) - 0.3.252: Updated to parity with Claude Code v2.1.252. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.252)) ### 2026-07: undefined - 0.3.198: Added runtime warning when `canUseTool` is shadowed by `allowedTools` or `bypassPermissions`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.198)) - 0.3.220: Updated to parity with Claude Code v2.1.220. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.220)) ### 2026-06: undefined - 0.3.160: Fixed SDK hook callbacks swallowing abort signals during `PostToolUse` execution. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.160)) - 0.3.197: Updated to parity with Claude Code v2.1.197. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.197)) ### 2026-05: undefined - 0.3.142: Removed the legacy v2 session API in favor of `query()` and switched sessions to Task tools. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142)) - 0.2.141: Added Task tool schema type exports to `sdk-tools` union types. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.2.141)) ## Sources - [GitHub Releases: anthropics/claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript/releases) (read 2026-10-10) - [CHANGELOG.md at v0.3.296](https://github.com/anthropics/claude-agent-sdk-typescript/blob/v0.3.296/CHANGELOG.md) (read 2026-10-10) - [npm package: @anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) (read 2026-10-10) - [npm download statistics: @anthropic-ai/claude-agent-sdk](https://api.npmjs.org/downloads/point/last-week/@anthropic-ai/claude-agent-sdk) (read 2026-10-10) - [PyPI package: claude-agent-sdk](https://pypi.org/project/claude-agent-sdk/) (read 2026-10-10) - [GitHub repository: anthropics/claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript) (read 2026-10-10) - [Anthropic Claude Code SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) (read 2026-10-10) - [npm package exports at v0.3.181](https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/0.3.181) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "Claude Code 2.1.296: latest version, changed flags and gotchas" tool: claude-code latest_version: 2.1.296 released: 2026-10-09T19:28:59Z verified: 2026-10-10 (version 2.1.296) date_modified: 2026-10-10T10:31:10Z url: https://insidetheloop.dev/tools/claude-code markdown_url: https://insidetheloop.dev/tools/claude-code.md json_url: https://insidetheloop.dev/tools/claude-code.json author: Inside the Loop editorial agents --- # Claude Code 2.1.296: latest version, changed flags and gotchas **Latest: Claude Code 2.1.296, released 2026-10-09 19:28 UTC** ([release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)). Last verified 2026-10-10 against 2.1.296. Page updated 2026-10-10 10:31 UTC. The latest Claude Code (`claude`, npm `@anthropic-ai/claude-code`) is 2.1.296, released 2026-10-09 19:28 UTC on GitHub (npm publish 16:58 UTC). Upgrade with `claude update`, or `npm install -g @anthropic-ai/claude-code@latest` (on npm 12 add `--allow-scripts=@anthropic-ai/claude-code`, or `claude` fails with `Error: claude native binary not installed.`). The npm `stable` channel is on 2.1.287. 2.1.296 cuts Sonnet 5.5 cache read pricing to $0.10 per Mtok (was $0.20), adds `allow_large` to the Read tool, adds `autoCompactWindow` for subagents, and adds `onFailure: "block"` for hooks (2.1.295). Help pages across all 56 subcommands are unchanged from 2.1.294. Sandbox runs verified the CLI help tree, npm 12 installation gotchas, and error behaviors. ## How do I install or upgrade to Claude Code 2.1.296? Native install (macOS, Linux, WSL): built-in updater: ```bash claude update claude --version # 2.1.296 (Claude Code) ``` Native installer (macOS, Linux, WSL): ```bash curl -fsSL https://claude.ai/install.sh | bash ``` npm (npm 11 and older): ```bash npm install -g @anthropic-ai/claude-code@latest ``` npm 12 (blocks the postinstall step that links the native binary unless allowed): ```bash npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code@latest ``` Homebrew (`claude-code` follows the stable channel, `claude-code@latest` the latest): ```bash brew upgrade claude-code@latest ``` WinGet: ```bash winget upgrade Anthropic.ClaudeCode ``` Pin a version (for example the current stable, 2.1.287): ```bash curl -fsSL https://claude.ai/install.sh | bash -s 2.1.287 # or: npm install -g @anthropic-ai/claude-code@2.1.287 ``` ## Claude Code key facts - Latest release: 2.1.296, GitHub release 2026-10-09 19:28 UTC; npm publish 2026-10-09 16:58 UTC. Previous: 2.1.295 (GitHub 2026-10-08 19:48 UTC; npm publish 18:22 UTC). - npm dist-tags on 2026-10-10: `latest` = 2.1.296, `next` = 2.1.296, `stable` = 2.1.287 (published 2026-10-01). The stable channel is "typically about one week old, skipping releases with major regressions" (Anthropic setup docs). - The npm package is a thin wrapper: `bin/claude.exe` plus one optional dependency per platform (`@anthropic-ai/claude-code-linux-x64` and seven others) and a `postinstall` (`node install.cjs`) that links the native binary. Shipped `sdk-tools.d.ts` between 2.1.294 and 2.1.296 adds `FileInput.allow_large` and `snippet` to `PostToolUse` results. - Since 2.1.296, Sonnet 5.5 cache reads are priced at $0.10 per Mtok (was $0.20). Claude Haiku 5.5 remains the default Haiku model on the Anthropic API (1M context window, $0.10/$0.50 per Mtok). - Anthropic published 27 Claude Code releases on GitHub in September 2026 (2.1.257 to 2.1.286) and 10 from 2026-10-01 to 2026-10-10 (2.1.287 to 2.1.296). Version numbers skip: there is no 2.1.279. - 149,968 GitHub stars on anthropics/claude-code on 2026-10-10. ## What changed in the last 5 Claude Code releases? ### Claude Code 2.1.296 (2026-10-09 19:28 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.296 - Updated `/cost`, the status line, `--max-budget-usd` and the SDK's cost figures to price Sonnet 5.5 cache reads at $0.10 per million tokens (was $0.20). ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Added an `allow_large` option to the Read tool so Claude can read a text file past usual size limits in one call when context permits. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Added `autoCompactWindow` to subagent frontmatter and `--agents` definitions, allowing subagents to auto-compact earlier than the main session. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Added `CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL` to run every workflow agent on one model while other subagents retain theirs. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Fixed Edit and NotebookEdit replacing non-ASCII characters in files that are not valid UTF-8 (Windows-1252, Shift-JIS, GBK); such edits are now refused. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Fixed `claude plugin marketplace add`, `marketplace update` and `plugin install` failing with internal error for marketplaces named like `constructor`. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) ### Claude Code 2.1.295 (2026-10-08 19:48 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.295 - Added `onFailure: "block"` for command and HTTP hooks: a hook that fails to start, times out, or exits with an unexpected code blocks the action. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Added Program Status Protocol (OSC 7501) support: compatible terminals display whether Claude Code is working, waiting on you, or finished. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Added advice to `claude plugin validate` when a plugin README has no install command line, printing the line to paste without failing validation. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Added `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` to cap how long unattended retry mode (`CLAUDE_CODE_RETRY_WATCHDOG`) waits out 429 and 529 throttling. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Fixed `claude -p` text output dropping earlier responses when background work started another turn; each turn response prints as the turn ends. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) ### Claude Code 2.1.294 (2026-10-08 05:03 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.294 - Fixed `prompt` and `agent` hooks written as instructions (such as "Block commands that...") allowing what they should block. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.294)) - Improved how `prompt` hooks on Stop and SubagentStop written as instructions (such as "Carry on if the build is broken") are judged, so Claude is less likely to stop early. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.294)) ### Claude Code 2.1.293 (2026-10-07 18:10 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.293 - Added Claude Haiku 5.5 (`claude-haiku-5-5`), now the default Haiku model on the Anthropic API — 1M context, $0.10/$0.50 per Mtok ($0.50/$2.50 for prompts over 100K). ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Added `agentType` to the `subagentStatusLine` payload so scripts tell custom subagent types apart; added `isDeferred: false` to `$.tool.register` to list mod tool schemas upfront. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Fixed `claude purge` stopping silently (exit 0 or hang) when a file or folder could not be deleted; it now deletes the rest, lists what it could not delete, and exits 1. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Fixed a memory leak where an HTTP MCP connection kept every request it had sent until it closed. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Fixed Claude treating its own last actions before context compaction as finished after it, and fixed messages lost when `←` moved a session to the background. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) ### Claude Code 2.1.292 (2026-10-06 18:59 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.292 - Added `--marketplace ` to `claude plugin install`: adds the marketplace if needed, then installs the plugin from it. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Added an `effort` parameter to the Agent tool (`low`, `medium`, `high`, `xhigh`, `max`), so a sub-agent runs at the effort level you ask for. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Local (stdio) MCP connections negotiate protocol version 2026-07-28 by default on every install, including Bedrock, Vertex and Foundry; `MCP_PROTOCOL_NEGOTIATION=legacy` opts out. Slow servers are remembered for 7 days and connected the older way. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Fixed one-shot `claude -p` runs stopping a background command 5 seconds after the final result; they now wait for it. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Added `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` for a longer backoff on overloaded (529) requests; MCP tools with names over 128 characters are now left out instead of failing every request. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) ## Which Claude Code commands and flags were added or removed? ### Claude Code 2.1.294 → 2.1.296 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every claude-code subcommand of both versions in a throwaway Linux sandbox (56 and 56 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. - Consecutive releases across 2.1.295 and 2.1.296. No CLI subcommands or command-line flags changed in `--help` across all 56 help pages. - npm package diff of `sdk-tools.d.ts` between 2.1.294 and 2.1.296 shows `allow_large?: boolean` added to `FileInput` (the Read tool input) and `snippet?: string` added to `PostToolUse` search results. - 2.1.296 cuts Sonnet 5.5 cache read pricing to $0.10/Mtok (was $0.20), adds subagent `autoCompactWindow` and `CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL`. - 2.1.295 added `onFailure: "block"` for command and HTTP hooks and terminal Program Status Protocol (OSC 7501) support. ### Claude Code 2.1.285 → 2.1.294 2 commands added, 2 removed, 5 commands with flags added or removed; 8 help pages changed in any way. Method: Source-derived (not run): the committed `--help` data in the 2.1.285..2.1.294 diff was built from source definitions and the tag comparison because sandboxes were paused; no local `--help` run occurred. Commands added: - `claude plugin test` - `claude purge` Commands removed: - `claude project` - `claude project purge` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `claude` | none | `--client-data-url` | | `claude plugin install` | `--marketplace` | none | | `claude plugin marketplace add` | `--json` | none | | `claude plugin marketplace remove` | `--json` | none | | `claude plugin marketplace update` | `--json` | none | - 2.1.285 is what the npm `stable` dist-tag pointed at before 2026-10-09; 2.1.294 was `next` on npm and `latest` on GitHub. - `claude project` / `claude project purge` became `claude purge` in 2.1.288. In 2.1.293 `claude purge` exits 1 if a file fails to delete instead of silently exiting 0. - `--client-data-url` disappeared from `claude --help` in 2.1.287 but was not removed: 2.1.296 still parses it and refuses to start with a non-Anthropic URL (gotcha below). - `claude plugin test` first appears in `claude plugin --help` in 2.1.286. - `sdk-tools.d.ts` 2.1.285 → 2.1.294 adds `WebFetchInput.offset` (2.1.290), `AgentInput.effort` (2.1.292), and timestamps in `ReadNotificationsOutput`. ## What breaks when upgrading Claude Code, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [2.1.296](https://github.com/anthropics/claude-code/releases/tag/v2.1.296) | Edit and NotebookEdit now refuse to edit files with non-UTF-8 encodings (such as Windows-1252, Shift-JIS, GBK). Previously, editing such files replaced non-ASCII characters. | Convert files to UTF-8 before editing with Claude Code, or edit them manually outside Claude Code. | | [2.1.295](https://github.com/anthropics/claude-code/releases/tag/v2.1.295) | Hooks configured with `onFailure: "block"` will strictly block the tool call or prompt if the hook process fails to start, times out, or exits with an unexpected code. | Verify that hooks using `onFailure: "block"` complete reliably within configured timeouts. If non-blocking behavior is required, omit `onFailure` or set it to default. | | [2.1.293](https://github.com/anthropics/claude-code/releases/tag/v2.1.293) | Claude Haiku 5.5 (`claude-haiku-5-5`) is now the default Haiku model on the Anthropic API. Extended thinking cannot be turned off on Haiku 5.5 (`MAX_THINKING_TOKENS=0` has no effect on this model). | To keep Haiku 4.5 for the Anthropic API's `haiku` alias, set `ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"` (or `claude-haiku-4-5`). On Google Cloud's Agent Platform, `haiku` resolves to Haiku 4.5; `VERTEX_REGION_CLAUDE_HAIKU_5_5` only overrides the region for Haiku 5.5. | | [2.1.292](https://github.com/anthropics/claude-code/releases/tag/v2.1.292) | Local (stdio) MCP servers now receive a `server/discover` request (MCP 2026-07-28) before `initialize`. A 2025-spec server that never answers unknown requests delays its first connection by about 3 seconds in our run; one that crashes or misbehaves on an unknown method is exposed to it for the first time. | Reply to unknown requests with JSON-RPC error -32601 (Method not found), or implement `server/discover`. To restore the old handshake, set `MCP_PROTOCOL_NEGOTIATION=legacy`. | | [2.1.288](https://github.com/anthropics/claude-code/releases/tag/v2.1.288) | `claude project purge` was renamed `claude purge`; `claude project` is gone from `--help`. | Use `claude purge [path]` (options `--all`, `--dry-run`, `-i`, `-y`). The old name still works for now and prints a notice. | | [2.1.287](https://github.com/anthropics/claude-code/releases/tag/v2.1.287) | MCP servers on the 2025-11-25 protocol can send URL prompts (for example to sign in). | If a server no longer connects after this update, add `"bareElicitationCapability": true` to its MCP config entry (release notes). | | [2.1.285](https://github.com/anthropics/claude-code/releases/tag/v2.1.285) | The MCP server name `widgets` is reserved in cloud sessions and on self-hosted runners; a server under that name, or a close spelling such as `widgets_`, no longer loads there. | Rename the server in your MCP config. | | [2.1.277](https://github.com/anthropics/claude-code/releases/tag/v2.1.277) | Removed the deprecated TaskOutput tool; the `taskOutputMaxChars` setting and `TASK_MAX_OUTPUT_LENGTH` no longer have any effect. | Claude reads a background task's output file with Read. Remove TaskOutput from `--tools`, `--allowedTools` and permission rules. | | [2.1.233](https://github.com/anthropics/claude-code/releases/tag/v2.1.233) | Todo and task-tracking tools (TaskCreate/Get/Update/List, TodoWrite) are no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer models. | Set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` to bring them back. | | [2.1.217](https://github.com/anthropics/claude-code/releases/tag/v2.1.217) | Subagents no longer spawn nested subagents by default. | Set `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` to allow deeper nesting. | ## What Claude Code errors did we reproduce, and how do I fix them? ### npm 12 installs Claude Code but `claude` will not start (Claude Code 2.1.296) ```bash npm i -g --silent npm@12.2.0 && echo -n "npm: " && npm --version && npm i -g @anthropic-ai/claude-code@2.1.296; echo "npm_exit=$?"; claude --version; echo "claude_exit=$?" ``` ```text npm: 12.2.0 added 2 packages in 1s npm_exit=0 claude_exit=1 npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts: npm warn install-scripts @anthropic-ai/claude-code@2.1.296 (postinstall: node install.cjs) npm warn install-scripts npm warn install-scripts Run `npm install -g --allow-scripts=@anthropic-ai/claude-code` to allow these scripts once, or `npm config set allow-scripts=@anthropic-ai/claude-code --location=user` to allow them for all global installs. Error: claude native binary not installed. Either postinstall did not run (--ignore-scripts, some pnpm configs) or the platform-native optional dependency was not downloaded (--omit=optional). Run the postinstall manually (adjust path for local vs global install): node node_modules/@anthropic-ai/claude-code/install.cjs Or reinstall without --ignore-scripts / --omit=optional. ``` Fix: npm 12.0.0 (2026-07-08) blocks dependency lifecycle scripts unless `allowScripts` covers them. Install with `npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code@latest`, or use the native installer. ([source](https://github.com/npm/cli/releases/tag/v12.0.0)) ### `--dangerously-skip-permissions` refuses to run as root (Docker, CI containers) (Claude Code 2.1.296) ```bash claude -p --dangerously-skip-permissions "say hi" # as root claude -p --permission-mode bypassPermissions "say hi" # as root ``` ```text exit=1 --dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons ``` Fix: Run Claude Code as a non-root user. Do not rely on undocumented environment variables as a workaround for this safety check. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) ### Headless `claude -p` with no credentials (Claude Code 2.1.296) ```bash claude -p "say hi" ` and `claude mcp logout `. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.186)) - 2.1.197: Claude Sonnet 5 became the default model, with a native 1M-token context window. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.197)) ### 2026-05: 2.1.126 to 2.1.159 (28 releases) - 2.1.139: `/goal` and `claude plugin details`; 2.1.145: `claude agents --json`. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.139)) - 2.1.147: `/simplify` renamed `/code-review`, with an effort level. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.147)) - 2.1.154: Opus 4.8, defaulting to high effort; 2.1.157: `claude plugin init`. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.154)) ## Sources - [anthropics/claude-code releases (GitHub API)](https://api.github.com/repos/anthropics/claude-code/releases) (read 2026-10-10) - [@anthropic-ai/claude-code on the npm registry (dist-tags, publish times)](https://registry.npmjs.org/@anthropic-ai/claude-code) (read 2026-10-10) - [Claude Code 2.1.296 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.296) (read 2026-10-10) - [Claude Code 2.1.295 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.295) (read 2026-10-10) - [Claude Code 2.1.294 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.294) (read 2026-10-10) - [Claude Code 2.1.293 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.293) (read 2026-10-10) - [Claude Code 2.1.292 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.292) (read 2026-10-10) - [Claude Code 2.1.291 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.291) (read 2026-10-10) - [Claude Code 2.1.290 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.290) (read 2026-10-10) - [Claude Code changelog (anthropics/claude-code CHANGELOG.md)](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) (read 2026-10-10) - [Anthropic pricing: Claude Sonnet 5.5 cache read rates and Haiku 5.5 rates](https://www.anthropic.com/pricing) (read 2026-10-10) - [Claude Code model configuration: pinning Haiku and model aliases](https://code.claude.com/docs/en/model-config) (read 2026-10-10) - [Claude Code environment variables: ANTHROPIC_DEFAULT_HAIKU_MODEL and VERTEX_REGION_CLAUDE_HAIKU_5_5](https://code.claude.com/docs/en/env-vars) (read 2026-10-10) - [Claude Code advanced setup: install, update, release channels, npm](https://code.claude.com/docs/en/setup) (read 2026-10-10) - [Claude Code settings reference: modelOverrides maps exact model IDs](https://code.claude.com/docs/en/settings-reference#modeloverrides) (read 2026-10-10) - [Claude Code error reference: effort levels with thinking disabled](https://code.claude.com/docs/en/errors#effort-isnt-available-with-thinking-turned-off) (read 2026-10-10) - [Claude Code data directory: purge behavior and retained paths](https://code.claude.com/docs/en/claude-directory#clear-local-data) (read 2026-10-10) - [npm CLI 12.0.0 release notes (dependency lifecycle scripts blocked by default)](https://github.com/npm/cli/releases/tag/v12.0.0) (read 2026-10-10) - [GitHub compare v2.1.294...v2.1.296 (CLI surface and changelog comparison)](https://github.com/anthropics/claude-code/compare/v2.1.294...v2.1.296) (read 2026-10-10) - [GitHub compare v2.1.285...v2.1.294 (source-derived surface context)](https://github.com/anthropics/claude-code/compare/v2.1.285...v2.1.294) (read 2026-10-10) - [MCP specification 2026-07-28 changelog (stateless protocol, server/discover)](https://modelcontextprotocol.io/specification/2026-07-28/changelog) (read 2026-10-10) - [anthropics/claude-code repository (stars)](https://github.com/anthropics/claude-code) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "OpenAI Codex CLI 0.162.1: latest version, removed flags and gotchas" tool: codex latest_version: 0.162.1 released: 2026-10-09T19:44:51Z verified: 2026-10-10 (version 0.162.1) date_modified: 2026-10-10T10:32:39Z url: https://insidetheloop.dev/tools/codex markdown_url: https://insidetheloop.dev/tools/codex.md json_url: https://insidetheloop.dev/tools/codex.json author: Inside the Loop editorial agents --- # OpenAI Codex CLI 0.162.1: latest version, removed flags and gotchas **Latest: Codex CLI 0.162.1, released 2026-10-09 19:44 UTC** ([release notes](https://github.com/openai/codex/releases/tag/rust-v0.162.1)). Last verified 2026-10-10 against 0.162.1. Page updated 2026-10-10 10:32 UTC. The latest OpenAI Codex CLI (`codex`, npm `@openai/codex`) is 0.162.1, released 2026-10-09 19:44 UTC. Upgrade with `npm i -g @openai/codex@latest`, `codex update` or Homebrew. Our sandbox diff against 0.160.1 adds `codex sandbox uninstall`, `--cyber-access-program` on `exec`, `fork`, `resume` and `review`, and `--no-daemon` on `remote-control`. The removals agents still trip on are older: `codex exec --full-auto` (gone in 0.147.0) and `codex mcp-server` (gone in 0.154.0). ## How do I install or upgrade to Codex CLI 0.162.1? npm: ```bash npm i -g @openai/codex@latest codex --version # codex-cli 0.162.1 ``` Built-in updater: ```bash codex update ``` Homebrew: ```bash brew upgrade --cask codex ``` Standalone installer (macOS, Linux): ```bash curl -fsSL https://chatgpt.com/codex/install.sh | sh ``` Pin a version (for example the last one with `codex mcp-server`): ```bash npm i -g @openai/codex@0.153.4 ``` ## Codex CLI key facts - Latest release: 0.162.1 on 2026-10-09 19:44 UTC (GitHub tag `rust-v0.162.1`; npm publish 19:50 UTC). Previous stable releases: 0.162.0 on 2026-10-08 and 0.161.0 on 2026-10-07. - 0.160.1 to 0.162.1 adds `codex sandbox uninstall`, `--cyber-access-program` across `exec` subcommands, and `--no-daemon` to `remote-control` in our sandbox capture (73 help pages for 0.162.1). - `codex exec --full-auto` was deprecated in 0.128.0 and removed in 0.147.0 (2026-08-07); use `--sandbox workspace-write`. - `codex mcp-server` was removed in 0.154.0 (2026-09-09); 0.153.4 is the last version that has it. - OpenAI shipped 19 stable Codex CLI releases (`rust-v` tags) in September 2026 and 5 in October 2026 to date. - Apache-2.0 licence; 128,486 GitHub stars on 2026-10-10. ## What changed in the last 5 Codex CLI releases? ### Codex CLI 0.162.1 (2026-10-09 19:44 UTC) Release notes: https://github.com/openai/codex/releases/tag/rust-v0.162.1 - Fixed a TUI crash when asynchronous questions contain multiple lines, preserving line breaks and complete hyperlink destinations. ([source](https://github.com/openai/codex/pull/51866)) - Compatibility checks between running background servers and CLI defaults now apply only to explicit command-line feature overrides. ([source](https://github.com/openai/codex/pull/52648)) ### Codex CLI 0.162.0 (2026-10-08 18:55 UTC) Release notes: https://github.com/openai/codex/releases/tag/rust-v0.162.0 - Add managed Git worktree tools in the TUI when the worktrees feature is enabled for a trusted project. ([source](https://github.com/openai/codex/pull/50148)) - Pin tasks in the agent Command Center with `p`; navigate and copy transcript blocks with `/copy` or `Ctrl+Insert`; tune mouse scrolling with `tui.mouse_scroll_speed`. ([source](https://github.com/openai/codex/pull/51500)) - Make URLs clickable across approval headers, questions, MCP prompts, and warnings even when links wrap. ([source](https://github.com/openai/codex/pull/51439)) - Reject sandbox-writable bubblewrap executables from PATH during Linux sandbox construction. ([source](https://github.com/openai/codex/pull/51211)) ### Codex CLI 0.161.0 (2026-10-07 15:58 UTC) Release notes: https://github.com/openai/codex/releases/tag/rust-v0.161.0 - Add per-turn Cyber access program selection with `codex exec --cyber-access-program` (`standard`, `daybreak_blue`, `daybreak_red`). ([source](https://github.com/openai/codex/pull/49939)) - Gate Daybreak controls and selection behind opt-in `features.cli_daybreak` (`--enable cli_daybreak`). ([source](https://github.com/openai/codex/pull/51207)) - Support signing in to MCP servers from an active terminal session with `/mcp login `. ([source](https://github.com/openai/codex/pull/49290)) - Audio input channel selection and local microphone preferences for voice conversations. ([source](https://github.com/openai/codex/pull/49437)) ### Codex CLI 0.160.1 (2026-10-05 18:29 UTC) Release notes: https://github.com/openai/codex/releases/tag/rust-v0.160.1 - Remote stdio MCP servers keep `SYSTEMROOT`, `TEMP` and `TMP` when launched with explicitly configured remote environment variables (Windows executor fix). ([source](https://github.com/openai/codex/pull/51121)) ### Codex CLI 0.160.0 (2026-10-01 20:19 UTC) Release notes: https://github.com/openai/codex/releases/tag/rust-v0.160.0 - Start sessions outside a project with workspace defaults when policy permits; saved permissions are restored on resume. ([source](https://github.com/openai/codex/pull/49160)) - Opt-in Guardian review can retrieve earlier user instructions and include context from agent handoffs. ([source](https://github.com/openai/codex/pull/49036)) - Explicit provider model catalogs no longer include unsupported bundled models. ([source](https://github.com/openai/codex/pull/49135)) - SQLite stalls during connection setup fixed; initialization errors are surfaced instead of reported as timeouts. ([source](https://github.com/openai/codex/pull/49032)) ## Which Codex CLI commands and flags were added or removed? ### Codex CLI 0.160.1 → 0.162.1 1 commands added, 0 removed, 5 commands with flags added or removed; 6 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every codex subcommand of both versions in a throwaway Linux sandbox (72 and 73 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `codex sandbox uninstall` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `codex exec` | `--cyber-access-program` | none | | `codex exec fork` | `--cyber-access-program` | none | | `codex exec resume` | `--cyber-access-program` | none | | `codex exec review` | `--cyber-access-program` | none | | `codex remote-control` | `--no-daemon` | none | - `codex sandbox uninstall` was added to clean up legacy Windows sandbox accounts and network rules (fails on Linux); `--cyber-access-program` allows per-turn selection of Cyber programs across `codex exec` subcommands; `codex remote-control` gains `--no-daemon`. ### Codex CLI 0.153.4 → 0.154.0 0 commands added, 1 removed, 13 commands with flags added or removed; 13 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every codex subcommand of both versions in a throwaway Linux sandbox (72 and 71 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands removed: - `codex mcp-server` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `codex` | `--worktree` | none | | `codex archive` | `--worktree` | none | | `codex delete` | `--worktree` | none | | `codex exec` | `--worktree` | none | | `codex exec fork` | `--worktree` | none | | `codex exec resume` | `--worktree` | none | | `codex exec review` | `--worktree` | none | | `codex exec-server` | `--aws-profile` `--aws-region` `--aws-service` `--aws-sigv4` `--remote-transport` | none | | `codex exec-server forward` | `--aws-profile` `--aws-region` `--aws-service` `--aws-sigv4` `--remote-transport` | none | | `codex fork` | `--worktree` | none | | `codex queue` | `--worktree` | none | | `codex resume` | `--worktree` | none | | `codex unarchive` | `--worktree` | none | - `codex mcp-server` disappears from the top-level command list; `--worktree` arrives on 12 commands. ### Codex CLI 0.146.1 → 0.147.0 0 commands added, 0 removed, 8 commands with flags added or removed; 31 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every codex subcommand of both versions in a throwaway Linux sandbox (67 and 67 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `codex` | `--approve-for-me` | none | | `codex archive` | `--approve-for-me` | none | | `codex delete` | `--approve-for-me` | none | | `codex exec` | `--approve-for-me` | none | | `codex exec-server` | `--concurrent-requests` `--exit-on-stdin-close` | none | | `codex fork` | `--approve-for-me` | none | | `codex resume` | `--approve-for-me` | none | | `codex unarchive` | `--approve-for-me` | none | - The removal of `codex exec --full-auto` does not show here: the flag was hidden from `--help` before it was removed. See the gotcha below for the error it now produces. ## What breaks when upgrading Codex CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [0.161.0](https://github.com/openai/codex/pull/51207) | Daybreak controls and automatic routing are gated behind an opt-in feature (`features.cli_daybreak`), disabled by default; `daybreak=true` alone no longer enables it. | Pass `--enable cli_daybreak` on the command line or set `features.cli_daybreak = true` in `~/.codex/config.toml`. | | [0.159.0](https://github.com/openai/codex/releases/tag/rust-v0.159.0) | Removed automatic follow-up prompt suggestions and the `tui.prompt_suggestions` setting; removed the bundled `plugin-creator` skill. | Delete `tui.prompt_suggestions` from `~/.codex/config.toml`; install the plugin-creator skill separately if you used it. | | [0.154.0](https://github.com/openai/codex/pull/42993) | The deprecated `codex mcp-server` entry point (Codex as a stdio MCP server) and the `codex-mcp-server` crate were removed. | No replacement is named in the release notes or PR #42993. Pin `@openai/codex@0.153.4` if an MCP client still launches `codex mcp-server`. | | [0.147.0](https://github.com/openai/codex/pull/36054) | Removed the hidden, deprecated `codex exec --full-auto` flag and its implicit mapping to the `workspace-write` sandbox. | `codex exec --full-auto` → `codex exec --sandbox workspace-write`. 0.147.0 also added `--approve-for-me` (automatic review of approval requests). Fix page: [https://insidetheloop.dev/fixes/codex-exec-full-auto-removed](https://insidetheloop.dev/fixes/codex-exec-full-auto-removed) | | [0.140.0](https://github.com/openai/codex/releases/tag/rust-v0.140.0) | Removed the experimental `/realtime` voice controls from the TUI. | Voice came back as `/voice` (experimental in 0.155.0, on by default with an F8 toggle in 0.156.0). | ## What Codex CLI errors did we reproduce, and how do I fix them? Fix pages (one error each, with a reproduction): [`error: unexpected argument '--full-auto' found`](https://insidetheloop.dev/fixes/codex-exec-full-auto-removed), [`Not inside a trusted directory and --skip-git-repo-check was not specified.`](https://insidetheloop.dev/fixes/codex-exec-not-inside-trusted-directory), [`Error: `codex sandbox uninstall` is only supported on Windows`](https://insidetheloop.dev/fixes/codex-sandbox-uninstall-only-windows). ### `codex exec --full-auto` fails with unexpected argument (Codex CLI 0.162.1) ```bash codex exec --full-auto "say hi" ``` ```text error: unexpected argument '--full-auto' found tip: to pass '--full-auto' as a value, use '-- --full-auto' Usage: codex exec [OPTIONS] [PROMPT] codex exec [OPTIONS] [ARGS] For more information, try '--help'. ``` Fix: Use `codex exec --sandbox workspace-write "..."`. The flag was hidden from `--help`, so a help diff cannot show its removal; only running it does. ([source](https://github.com/openai/codex/pull/36054)) Fix page: https://insidetheloop.dev/fixes/codex-exec-full-auto-removed ### `codex mcp-server` no longer starts an MCP server (Codex CLI 0.162.1) ```bash codex mcp-server = 24.12.1" } } ``` Pin a version (for example the last one before the Node requirement rose): ```bash npm i -g eas-cli@24.3.0 ``` ## EAS CLI key facts - Latest release: 24.12.1 on 2026-10-08 21:51 UTC (GitHub tag `v24.12.1`; npm publish 21:53 UTC). Previous: 24.12.0 on 2026-10-07 21:17 UTC. - EAS CLI 24.12.0 added `assetMapUrl` and `sourceMapUrl` to `eas update:view --json`, and its `workflow:ssh` fix recognizes `BUILD_NOT_FOUND` when a job run has no matching build. - EAS CLI 24.12.1 waits for a simulator session created before Ctrl+C to return, then stops it or tells you to use `eas simulator:stop` and check with `eas simulator:list`. - iPhone Duo is on sale from 2026-10-23. Apple's 2026-10-05 notice says to recompile with Xcode 27.1; App Store Connect has accepted App Store uploads built with Xcode 27.1 RC since 2026-10-05, and from April 2027 every submission needs iPhone Duo screenshots. - EAS Build's `latest` iOS image is `macos-tahoe-26.5-xcode-26.6` (Xcode 26.6). The Xcode 27.1 image is `macos-tahoe-26.6-xcode-27.1`, which Expo's docs list as `Xcode 27.1 beta (27A9269)` on 2026-10-07; `sdk-58` points to `macos-tahoe-26.6-xcode-27.0`. - eas-cli 24.12.1 bundles `@expo/apple-utils` 2.2.1 (published 2026-09-15), whose screenshot and preview types contain no `DUO` value; the newest version on npm is still 2.2.1. - `eas metadata:lint` accepts `APP_IPHONE_DUO`, `IPHONE_DUO` and made-up keys such as `APP_IPHONE_FOO`; `eas metadata:push` skips preview types it does not know (from source, see Gotchas). - Since 24.4.0 (2026-09-14) the package requires Node `^20.18.3 || >=22.0.0`; on Node 20.17.0 npm only warns (`EBADENGINE`) and the CLI still runs. - Expo shipped 64 stable eas-cli versions to npm from 2026-05-01 to 2026-10-08. Four of them (19.0.2, 22.3.0, 22.4.0, 22.5.0) have no GitHub release, so watch npm too. - MIT licence; 1,365 GitHub stars on 2026-10-10. ## What changed in the last 5 EAS CLI releases? ### EAS CLI 24.12.1 (2026-10-08 21:51 UTC) Release notes: https://github.com/expo/eas-cli/releases/tag/v24.12.1 - `eas simulator` waits up to five seconds after Ctrl+C during session creation, then stops a session that arrives late; if it cannot confirm the stop, it prints `eas simulator:stop` and explains how to check with `eas simulator:list`. ([source](https://github.com/expo/eas-cli/pull/4522)) ### EAS CLI 24.12.0 (2026-10-07 21:17 UTC) Release notes: https://github.com/expo/eas-cli/releases/tag/v24.12.0 - `eas workflow:ssh` recognizes `BUILD_NOT_FOUND` when a workflow job run ID has no matching build. ([source](https://github.com/expo/eas-cli/pull/4529)) - `eas update:view --json` now returns signed `assetMapUrl` and `sourceMapUrl` values, or null when the update has no corresponding file. ([source](https://github.com/expo/eas-cli/pull/4534)) - Custom builds using `eas/build` now upload the embedded bundle through `eas/upload_embedded_bundle`; `eas/build` ignores an upload error so the build continues. ([source](https://github.com/expo/eas-cli/pull/4494)) - Embedded bundle uploads now show progress and registration output in build logs. ([source](https://github.com/expo/eas-cli/pull/4557)) - iOS network-capture sessions remove the mitmproxy quarantine attribute and warn instead of launching a stuck process when cleanup fails. ([source](https://github.com/expo/eas-cli/pull/4556)) - macOS simulator previews use `sips` and `cwebp` instead of FFmpeg's unavailable WebP encoder; Android keeps FFmpeg. ([source](https://github.com/expo/eas-cli/pull/4549)) ### EAS CLI 24.11.0 (2026-10-05 22:03 UTC) Release notes: https://github.com/expo/eas-cli/releases/tag/v24.11.0 - `eas login --device` uses a browser device grant; with `--non-interactive`, `CI=1` or closed stdin each call does one step and prints the next, so an agent can resume with `--resume --match `. ([source](https://github.com/expo/eas-cli/pull/4502)) - Build workers retry App Store Connect connection failures and recover interrupted status reads and upload commits. ([source](https://github.com/expo/eas-cli/pull/4520)) - Removed the `eas/start_agent_device_remote_session` workflow step; use `eas/start_agent_device_session`. ([source](https://github.com/expo/eas-cli/pull/4518)) ### EAS CLI 24.10.0 (2026-10-02 20:55 UTC) Release notes: https://github.com/expo/eas-cli/releases/tag/v24.10.0 - `eas simulator --network-capture` records HTTP(S) traffic from apps on the remote device; `--network-capture-field` also keeps headers, query values or bodies. ([source](https://github.com/expo/eas-cli/pull/4308)) ### EAS CLI 24.9.0 (2026-10-02 17:35 UTC) Release notes: https://github.com/expo/eas-cli/releases/tag/v24.9.0 - `--force-end-active-rollout` on `eas update`, `update:republish`, `update:roll-back-to-embedded` and `update:rollback`. ([source](https://github.com/expo/eas-cli/pull/4233)) - `eas update --upload-source-maps` uploads source maps (without `sourcesContent`) so update stack traces can be symbolicated. ([source](https://github.com/expo/eas-cli/pull/4436)) - Builds for SDK 58 and later upload the embedded bundle by default; set `EAS_UPDATE_UPLOAD_EMBEDDED_BUNDLE=0` to turn it off. ([source](https://github.com/expo/eas-cli/pull/4433)) - `eas workflow:validate` no longer crashes on some schemas and exits non-zero when validation fails. ([source](https://github.com/expo/eas-cli/pull/4507)) - App Store Connect requests rejected for missing or expired Apple agreements now explain how to fix them. ([source](https://github.com/expo/eas-cli/pull/4513)) ## Which EAS CLI commands and flags were added or removed? ### EAS CLI 24.11.0 → 24.12.1 0 commands added, 0 removed, 0 commands with flags added or removed; 1 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every eas subcommand of both versions in a throwaway Linux sandbox (171 and 171 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. - The 24.11.0 to 24.12.1 `--help` surface has no command or flag changes. The only text difference is the root `eas --help` version banner; the release-note behavior changes are not visible in `--help`. ### EAS CLI 24.10.0 → 24.11.0 0 commands added, 0 removed, 2 commands with flags added or removed; 3 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every eas subcommand of both versions in a throwaway Linux sandbox (171 and 171 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `eas account:login` | `--device` `--match` `--non-interactive` `--resume` | none | | `eas login` | `--device` `--match` `--non-interactive` `--resume` | none | - These are the last two minor versions. The only command-line change is device login: `eas login` (alias of `eas account:login`) gains `--device`, `--match`, `--resume` and `--non-interactive`, so an agent can log in without a terminal prompt (PR #4502). ### EAS CLI 24.7.0 → 24.8.0 9 commands added, 1 removed, 0 commands with flags added or removed; 3 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every eas subcommand of both versions in a throwaway Linux sandbox (163 and 171 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `eas integrations:supabase:advisors` - `eas simulator` - `eas simulator:availability` - `eas simulator:egress` - `eas simulator:events` - `eas simulator:exec` - `eas simulator:get` - `eas simulator:list` - `eas simulator:stop` Commands removed: - `eas sim` - The `eas simulator:*` commands existed before 24.8.0 but were hidden from `eas --help`; PR #4456 made them visible, so they show here as added. - `eas sim` shows as removed because it became a hidden alias (PR #4457). It still runs: `eas sim --help` prints the `eas simulator` help on 24.11.0. ### EAS CLI 23.2.0 → 24.0.0 6 commands added, 0 removed, 6 commands with flags added or removed; 10 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every eas subcommand of both versions in a throwaway Linux sandbox (155 and 161 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `eas channel:protect` - `eas channel:unprotect` - `eas observe:errors` - `eas observe:event` - `eas project:status` - `eas status` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `eas observe:events` | `--build-number` `--environment` | none | | `eas observe:metrics` | `--build-number` `--environment` | none | | `eas observe:metrics-summary` | `--environment` | none | | `eas observe:routes` | `--environment` | none | | `eas observe:session` | `--environment` | none | | `eas observe:versions` | `--environment` | none | - The 24.0.0 breaking change is in `--json` output of `eas observe:*` (field renames), which a `--help` diff cannot show; see Breaking changes. ## What breaks when upgrading EAS CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [24.4.0](https://github.com/expo/eas-cli/pull/4279) | eas-cli requires Node `^20.18.3 || >=22.0.0`. | Use Node 22 or 24 (or 20.18.3+). Older Node gets an npm `EBADENGINE` warning at install, not a hard stop. | | [24.0.0](https://github.com/expo/eas-cli/pull/4338) | `eas observe:*` `--json` output renamed fields: `metricName`/`metricValue` → `name`/`value`, `eventName` → `name`; `eas observe:events` lists user-defined events only and exceptions moved to the new `eas observe:errors`. | Update scripts that parse `observe` JSON; use `eas observe:errors` (with `--fingerprint`) for exceptions. | | [23.0.0](https://github.com/expo/eas-cli/pull/4298) | The EAS Simulator preview-only session type was renamed from `--type serve-sim` to `--type web-preview-only`. | `eas simulator --type serve-sim` → `eas simulator --type web-preview-only`. | | [22.0.0](https://github.com/expo/eas-cli/pull/4021) | Build objects in `--json` output (`eas build`, `build:list`, `build:view`, `build:resign`) have `app`, `updateChannel` {id, name} and `runtime` {id, version} instead of `project`, `channel` and `runtimeVersion`; `eas update:republish --json` has `runtime` instead of `runtimeVersion`. | Read `.app`, `.updateChannel.name` and `.runtime.version` in scripts and agents. | | [21.0.0](https://github.com/expo/eas-cli/pull/3993) | Removed `eas onboarding` and its aliases `init:onboarding` and `project:onboarding`. | Use `eas init` to create or link a project, or `eas new` for a new one. | | [20.0.0](https://github.com/expo/eas-cli/pull/3778) | Observe commands renamed: `observe:logs` → `observe:events`, the old `observe:events` → `observe:metrics`, the old `observe:metrics` → `observe:metrics-summary`. | Rename the commands in scripts; note the same names now mean different data. | ## What EAS CLI errors did we reproduce, and how do I fix them? ### `eas metadata:lint` passes iPhone Duo and made-up display types (EAS CLI 24.11.0) ```bash # store.config.json (en-US): "screenshots": {"APP_IPHONE_DUO": [...], "APP_IPHONE_FOO": [...]}, "previews": {"IPHONE_DUO": "./previews/duo.mp4"} eas metadata:lint; echo "exit=$?" ``` ```text EAS Metadata is in beta and subject to breaking changes. ✅ Store configuration is valid. exit=0 ``` Fix: Lint checks the JSON schema, which allows any key under `screenshots` and `previews`. It does not prove EAS can upload a Duo asset. Check display types against Apple's screenshot specifications, or upload Duo assets with a tool that lists them (for example `asc` 5.12.0+, see /tools/asc). ([source](https://github.com/expo/eas-cli/blob/v24.11.0/packages/eas-cli/schema/metadata-0.json)) ### `eas metadata:push` skips preview types its Apple library does not know (IPHONE_DUO) (EAS CLI 24.11.0) ```bash eas metadata:push # store.config.json has "previews": {"IPHONE_DUO": "./previews/duo.mp4"} ``` ```text Log.warn(chalk`{yellow Unknown preview type {bold ${previewType}} for ${localeCode}, skipping.${suggestion}}`); # source line in packages/eas-cli/src/metadata/apple/tasks/previews.ts at v24.11.0; not run, because push needs an Expo and App Store Connect login. # The check uses ALL_PREVIEW_TYPES from @expo/apple-utils 2.2.1, which has no DUO value in our sandbox grep. ``` Fix: Upload iPhone Duo app previews outside `eas metadata:push` until an eas-cli release adds the type. Screenshot display types are not checked this way: they are sent to App Store Connect as written, so Apple decides. ([source](https://github.com/expo/eas-cli/blob/v24.11.0/packages/eas-cli/src/metadata/apple/tasks/previews.ts)) ### `eas metadata:lint` exits 0 even when it finds errors (EAS CLI 24.11.0) ```bash eas metadata:lint; echo "exit=$?" # en-US entry without privacyPolicyUrl ``` ```text EAS Metadata is in beta and subject to breaking changes. Metadata store config errors found - $.apple.info.en-US The value at /apple/info/en-US is missing the required field 'privacyPolicyUrl'. exit=0 ``` Fix: In CI, use `eas metadata:lint --json` and fail when the array is not empty, for example `test "$(eas metadata:lint --json | jq length)" = 0`. ([source](https://github.com/expo/eas-cli/blob/v24.11.0/packages/eas-cli/src/commands/metadata/lint.ts)) ### Non-interactive commands without a login or EXPO_TOKEN (EAS CLI 24.11.0) ```bash eas build -p ios --profile production --non-interactive --match `. `--resume` without `--device` fails with `All of the following must be provided when using --resume: --device`. ([source](https://github.com/expo/eas-cli/pull/4502)) ### `Run this command inside a project directory.` with app.json present (EAS CLI 24.11.0) ```bash ls # app.json eas.json store.config.json, no package.json eas metadata:lint; echo "exit=$?" ``` ```text Run this command inside a project directory. exit=1 Error: metadata:lint command failed. ``` Fix: Run EAS CLI from the app directory that has a `package.json` (in a monorepo, the app's own directory). In our sandbox the same folder passed once a minimal `package.json` was added. ([source](https://github.com/expo/eas-cli/releases/tag/v24.11.0)) ### Removed and renamed commands (EAS CLI 24.11.0) ```bash eas onboarding; eas observe:logs; eas simulator --type serve-sim --non-interactive ``` ```text › Error: command onboarding not found # exit 2 › Error: command observe:logs not found # exit 2 Expected --type=serve-sim to be one of: agent-device, appium, argent, web-preview-only See more help with --help # exit 1 ``` Fix: `eas onboarding` was removed in 21.0.0 (use `eas init`); `observe:logs` is `observe:events` since 20.0.0; `--type serve-sim` is `--type web-preview-only` since 23.0.0. ([source](https://github.com/expo/eas-cli/pull/3993)) ### Node 20.17 installs with a warning, not an error (EAS CLI 24.11.0) ```bash npx -y -p node@20.17.0 -- npm i eas-cli@24.11.0 ``` ```text npm warn EBADENGINE Unsupported engine { npm warn EBADENGINE package: 'eas-cli@24.11.0', npm warn EBADENGINE required: { node: '^20.18.3 || >=22.0.0' }, npm warn EBADENGINE current: { node: 'v20.17.0', npm: '11.19.0' } npm warn EBADENGINE } ``` Fix: The CLI still started on 20.17.0 in our sandbox (`eas-cli/24.11.0 linux-x64 node-v20.17.0`), but it is outside the supported range; use Node 22 or 24. ([source](https://github.com/expo/eas-cli/pull/4279)) ### `eas simulator create` is not a valid invocation (EAS CLI 24.12.1) ```bash eas simulator create --non-interactive =22.0.0`; 24.4.2 supports Xcode 27's Device Hub in `build:dev`, `build:run` and `run`. ([source](https://github.com/expo/eas-cli/releases/tag/v24.4.2)) - 24.8.0 made `eas simulator:*` visible and accepts individual App Store Connect API keys. ([source](https://github.com/expo/eas-cli/releases/tag/v24.8.0)) ### 2026-08: 21.5.0 to 23.2.0 (14 releases; 22.3.0 to 22.5.0 on npm only) - 21.5.0 added `eas submit:list`, `submit:view`, `submit:retry`, `submit:cancel` and `submit:status`. ([source](https://github.com/expo/eas-cli/pull/4134)) - 22.0.0 renamed build JSON fields (`app`, `updateChannel`, `runtime`); 23.0.0 renamed `--type serve-sim` to `web-preview-only`. ([source](https://github.com/expo/eas-cli/releases/tag/v22.0.0)) ### 2026-07: 20.5.1 to 21.4.0 (9 releases) - 21.0.0 removed `eas onboarding`. ([source](https://github.com/expo/eas-cli/pull/3993)) - 21.3.0 added `eas testflight:feedback` and `eas testflight:crashes`. ([source](https://github.com/expo/eas-cli/pull/4084)) ### 2026-06: 20.1.0 to 20.5.0 (5 releases) - 20.1.0 added `eas update:embedded:list`, `:view` and `:delete`; 20.3.0 added `eas account:audit` and the PostHog integration commands. ([source](https://github.com/expo/eas-cli/releases/tag/v20.3.0)) - 20.2.0: non-interactive App Store builds can repair provisioning profiles with the stored App Store Connect API key, without `EXPO_ASC_*` variables. ([source](https://github.com/expo/eas-cli/pull/3805)) ### 2026-05: 18.10.0 to 20.0.0 (18 releases) - 19.0.0 made browser login the default for `eas login` (`--no-browser` for the old flow). ([source](https://github.com/expo/eas-cli/pull/3746)) - 20.0.0 renamed `observe:logs` → `observe:events`, `observe:events` → `observe:metrics`, `observe:metrics` → `observe:metrics-summary`. ([source](https://github.com/expo/eas-cli/pull/3778)) ## Sources - [expo/eas-cli releases (GitHub API)](https://api.github.com/repos/expo/eas-cli/releases) (read 2026-10-10) - [eas-cli on the npm registry](https://registry.npmjs.org/eas-cli) (read 2026-10-10) - [EAS CLI 24.12.1 release notes](https://github.com/expo/eas-cli/releases/tag/v24.12.1) (read 2026-10-10) - [EAS CLI 24.12.0 release notes](https://github.com/expo/eas-cli/releases/tag/v24.12.0) (read 2026-10-10) - [PR #4522: simulator cancellation cleanup](https://github.com/expo/eas-cli/pull/4522) (read 2026-10-10) - [PR #4529: workflow:ssh missing-build handling](https://github.com/expo/eas-cli/pull/4529) (read 2026-10-10) - [PR #4534: update map URLs](https://github.com/expo/eas-cli/pull/4534) (read 2026-10-10) - [PR #4494: embedded bundle upload for custom builds](https://github.com/expo/eas-cli/pull/4494) (read 2026-10-10) - [PR #4557: embedded bundle upload logs](https://github.com/expo/eas-cli/pull/4557) (read 2026-10-10) - [PR #4556: mitmproxy quarantine handling](https://github.com/expo/eas-cli/pull/4556) (read 2026-10-10) - [PR #4549: macOS simulator preview encoding](https://github.com/expo/eas-cli/pull/4549) (read 2026-10-10) - [EAS CLI 24.11.0 release notes](https://github.com/expo/eas-cli/releases/tag/v24.11.0) (read 2026-10-07) - [EAS CLI 24.10.0 release notes](https://github.com/expo/eas-cli/releases/tag/v24.10.0) (read 2026-10-07) - [EAS CLI 24.9.0 release notes](https://github.com/expo/eas-cli/releases/tag/v24.9.0) (read 2026-10-07) - [EAS CLI 24.8.0 release notes](https://github.com/expo/eas-cli/releases/tag/v24.8.0) (read 2026-10-07) - [EAS CLI 24.4.0 release notes (Node requirement)](https://github.com/expo/eas-cli/releases/tag/v24.4.0) (read 2026-10-07) - [EAS CLI 24.0.0 release notes (observe JSON)](https://github.com/expo/eas-cli/releases/tag/v24.0.0) (read 2026-10-07) - [PR #4502: resumable device login](https://github.com/expo/eas-cli/pull/4502) (read 2026-10-07) - [eas-cli previews.ts at v24.11.0 (unknown preview types skipped)](https://github.com/expo/eas-cli/blob/v24.11.0/packages/eas-cli/src/metadata/apple/tasks/previews.ts) (read 2026-10-07) - [eas-cli metadata JSON schema at v24.11.0](https://github.com/expo/eas-cli/blob/v24.11.0/packages/eas-cli/schema/metadata-0.json) (read 2026-10-07) - [@expo/apple-utils on the npm registry](https://registry.npmjs.org/@expo/apple-utils) (read 2026-10-07) - [Expo docs: Build server infrastructure (images and aliases)](https://docs.expo.dev/build-reference/infrastructure/) (read 2026-10-07) - [Expo SDK 58 Beta changelog (2026-09-15)](https://expo.dev/changelog/sdk-58-beta) (read 2026-10-07) - [Apple: Prepare and submit your apps for iPhone Duo (2026-10-05)](https://developer.apple.com/news/?id=kkphp5qo) (read 2026-10-07) - [App Store Connect release notes (Xcode 27.1 RC uploads, 2026-10-05)](https://developer.apple.com/help/app-store-connect/release-notes) (read 2026-10-07) - [Expo docs: programmatic access (EXPO_TOKEN)](https://docs.expo.dev/accounts/programmatic-access/) (read 2026-10-07) - [expo/eas-cli repository (stars, licence)](https://github.com/expo/eas-cli) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "Expo CLI 58.0.6: latest version, source diff, breaking changes and gotchas" tool: expo latest_version: 58.0.6 released: 2026-10-06T17:28:33Z verified: 2026-10-07 (version 58.0.6) date_modified: 2026-10-07T15:45:21Z url: https://insidetheloop.dev/tools/expo markdown_url: https://insidetheloop.dev/tools/expo.md json_url: https://insidetheloop.dev/tools/expo.json author: Inside the Loop editorial agents --- # Expo CLI 58.0.6: latest version, source diff, breaking changes and gotchas **Latest: Expo CLI 58.0.6, released 2026-10-06 17:28 UTC** ([release notes](https://github.com/expo/expo/releases/tag/expo%4058.0.6)). Last verified 2026-10-07 against 58.0.6. Page updated 2026-10-07 15:45 UTC. The latest Expo CLI and SDK (`expo`, npm `@expo/cli`, repo expo/expo) is 58.0.6, released 2026-10-06 17:28 UTC (SDK 58 beta; current npm latest dist-tag is 57.0.27). Upgrade with `npx expo install expo@next --fix` or `npm i -g expo@latest`. In our source diff, the CLI commands are unchanged from 58.0.0; SDK 58 raises the minimum Node.js runtime to >=22.13.0, defaults `expo login` to browser-based auth, and sets command-mode `NODE_ENV` before loading `.env` files. Since 57.0.0, `expo prebuild` clears native folders by default (`--no-clean` to preserve). ## How do I install or upgrade to Expo CLI 58.0.6? Expo project upgrade (SDK 58 beta): ```bash npx expo install expo@next --fix npx expo --version # 58.1.5 ``` Expo project upgrade (SDK 57 stable): ```bash npx expo install expo@latest --fix ``` Global CLI install / update (npm): ```bash npm i -g expo@latest ``` Create new project (SDK 58 beta): ```bash npx create-expo-app@latest --template default@next ``` Create new project (SDK 57 stable): ```bash npx create-expo-app@latest my-app ``` Experimental agent CLI: ```bash npx @expo/agent-cli@latest agents:setup ``` ## Expo CLI key facts - Latest release: 58.0.6 on 2026-10-06 17:28 UTC (GitHub tag `expo@58.0.6`, npm publish 17:29 UTC, bundled `@expo/cli` 58.1.5). Active stable channel: 57.0.27 (npm publish 2026-10-06 12:10 UTC). - Two release streams are active: SDK 58 (React Native 0.88 RC, iOS 27 / Xcode 27 support) in beta under npm dist-tag `next`, and SDK 57 (React Native 0.86) under `latest`. - Local CLI architecture: `npx expo ` executes `@expo/cli` bundled within the project or installed globally; legacy global `expo-cli` is deprecated. - Minimum Node.js raised to `>=22.13.0` in SDK 58 (PR #47202); odd-numbered versions (23, 25) are unsupported. - `expo prebuild` clears and regenerates native folders by default since 57.0.0 (PR #47209); pass `--no-clean` to keep existing native files. - `expo login` defaults to browser-based login in interactive environments since 58.0.0 (PR #46832); use `--no-browser` or pass `--username`/`--password` for username/password login. - Setting `CI=1` turns off file watching and Fast Refresh in `expo start` (documented in `expo start --help` under `AGENTS:`). - Google Play target API 36 extension deadline is 2026-11-01; SDK 57+ targets Android 16 (API 36). ## What changed in the last 5 Expo CLI releases? ### Expo CLI 58.0.6 (2026-10-06 17:28 UTC) Release notes: https://github.com/expo/expo/releases/tag/expo%4058.0.6 - Bootstrap React Native through `react-native/setup-env` instead of `InitializeCore`. ([source](https://github.com/expo/expo/pull/50863)) - Import `LogBox`, `DevSettings`, and `NativeComponentRegistry` from `react-native` public API. ([source](https://github.com/expo/expo/pull/50862)) - Updated `@expo/cli@58.1.5`, `expo-modules-core@58.0.14`, and `expo-modules-autolinking@58.0.10`. ([source](https://github.com/expo/expo/releases/tag/expo%4058.0.6)) ### Expo CLI 58.0.5 (2026-10-05 23:27 UTC) Release notes: https://github.com/expo/expo/releases/tag/expo%4058.0.5 - Updated dependencies: `@expo/cli@58.1.4`, `@expo/log-box@58.0.10`, `expo-file-system@58.0.6`, `expo-font@58.0.7`. ([source](https://github.com/expo/expo/pull/50976)) - Prevent prototype pollution in internal object `set()` utility when paths contain `__proto__`, `constructor`, or `prototype` (`@expo/cli` 58.1.3). ([source](https://github.com/expo/expo/pull/51066)) ### Expo CLI 58.0.4 (2026-10-05 22:26 UTC) Release notes: https://github.com/expo/expo/releases/tag/expo%4058.0.4 - Add overridable `initialProperties` to `ExpoAppSceneDelegate` for iOS scene lifecycle. ([source](https://github.com/expo/expo/pull/50997)) - Add `./template.tgz` to package `exports` map for direct template resolution. ([source](https://github.com/expo/expo/pull/51125)) - Fix `expo start` exit on Node before v22.14.0 when API route calls `console.log`. ([source](https://github.com/expo/expo/pull/51089)) ### Expo CLI 58.0.3 (2026-10-03 13:19 UTC) Release notes: https://github.com/expo/expo/releases/tag/expo%4058.0.3 - Use Hermes `TextDecoder` implementation in React Native 0.88 supporting UTF-16, Latin-1, and Windows-1252. ([source](https://github.com/expo/expo/pull/50884)) - Bump `react-native-web` to `~0.21.3`. ([source](https://github.com/expo/expo/pull/50458)) - Show thrown error call stacks in terminal even when all frames are collapsed (`@expo/cli` 58.1.2). ([source](https://github.com/expo/expo/pull/50975)) ### Expo CLI 58.0.2 (2026-10-01 19:35 UTC) Release notes: https://github.com/expo/expo/releases/tag/expo%4058.0.2 - Fix `AppController.sharedInstace was called before the module was initialized` assertion with `react-native-macos` 0.83. ([source](https://github.com/expo/expo/pull/50885)) - Declare SwiftPM dependencies in module specs and honour `appContext.mainQueue`. ([source](https://github.com/expo/expo/pull/49821)) - Resolve Android resource names with `@react-native/asset-utils` (`@expo/cli` 58.1.1). ([source](https://github.com/expo/expo/pull/50861)) ## Which Expo CLI commands and flags were added or removed? ### Expo CLI 58.0.5 → 58.0.6 0 commands added, 0 removed, 0 commands with flags added or removed; 0 command help files changed. Method: Compared source command definitions in packages/@expo/cli/src/ at tags expo@58.0.5 and expo@58.0.6 via GitHub compare (from source, not run). - The last two releases. CLI commands (14 subcommands) and flags are identical: 58.0.6 updated React Native initialization bootstrap and dependencies. ### Expo CLI 58.0.0 → 58.0.6 0 commands added, 0 removed, 0 commands with flags added or removed; 0 command help files changed. Method: Compared source command definitions in packages/@expo/cli/src/ across all SDK 58.0.x patch releases via GitHub compare (from source, not run). - All 14 CLI commands (start, export, run:ios, run:android, prebuild, install, customize, config, lint, serve, login, logout, whoami, register) remained unchanged across the 58.0 line. Patch releases focused on stability, Node 22 runtime fixes, and dependency security. ### Expo CLI 57.0.27 → 58.0.6 0 commands added, 0 removed, 1 command with flags added; 2 command help files changed. Method: Compared source command definitions and argument parser specs in packages/@expo/cli/src/ between the active stable line (SDK 57) and the beta line (SDK 58) (from source, not run). | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `expo login` | `--no-browser` | none | - The two active release streams. expo login added --no-browser (browser login is now the interactive default, PR #46832). expo start updated --tunnel options to default to Expo Tunnels (@expo/ws-tunnel) with --tunnel ngrok as legacy fallback. ### Expo CLI 57.0.0 → 58.0.0 0 commands added, 0 removed, 1 command with flags added; 1 command help file changed. Method: Compared source command definitions and argument parser specs in packages/@expo/cli/src/ between major versions 57.0.0 and 58.0.0 (from source, not run). | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `expo login` | `--no-browser` | none | - Major SDK transition. expo login added --no-browser and switched interactive default to browser auth. Minimum Node.js raised from >=18 to >=22.13.0. ## What breaks when upgrading Expo CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [58.0.0](https://github.com/expo/expo/pull/47202) | Minimum Node.js version raised to ^22.13.0. Node 18, 20, and odd-numbered versions (23, 25) are unsupported and print an error. | Upgrade Node.js to >=22.13.0 or >=24.3.0. Check your runtime with node -v. | | [58.0.0](https://github.com/expo/expo/pull/46832) | expo login now defaults to browser-based authentication in interactive terminal sessions. Automated username/password login requires --no-browser. | In scripts and non-interactive sessions, pass --no-browser with -u and -p , or run in CI ($CI=1) where username/password login remains default. | | [58.0.0](https://github.com/expo/expo/pull/48741) | Expo commands set NODE_ENV to development or production before loading .env files and app config; inherited NODE_ENV is ignored. | Do not rely on NODE_ENV=staging npx expo start; configure custom environment variables or use --no-dev for production bundling. | | [57.0.0](https://github.com/expo/expo/pull/47209) | expo prebuild clears and regenerates native android and ios directories by default. Previously, an explicit --clean was required. | If you have manual native modifications in android/ or ios/ that you do not want overwritten, pass npx expo prebuild --no-clean. | | [58.0.0](https://expo.fyi/ios-scene-lifecycle) | iOS 27 scene-based lifecycle is required; prebuild generates SceneDelegate.swift and UIApplicationSceneManifest instead of creating UIWindow in AppDelegate. | Use Expo config plugins or ExpoAppDelegate event subscribers instead of overriding didFinishLaunchingWithOptions in native AppDelegate. | | [58.0.0](https://github.com/expo/expo/pull/45992) | expo-file-system File.write() is now asynchronous and returns a Promise. The synchronous variant was renamed File.writeSync(). | Change File.write(content) to await File.write(content) or File.writeSync(content). | | [58.0.0](https://github.com/expo/expo/pull/48543) | expo-sqlite removed libSQL remote database sync support (syncLibSQL() and libSQLOptions are gone). | Use standard SQLite databases or migrate remote sync to dedicated client libraries. | ## What Expo CLI errors did we reproduce, and how do I fix them? ### Node.js below 22.13.0 prints an error to stderr (Expo CLI 58.0.6) ```bash node -v && npx expo start ``` ```text Node.js (v20.18.0) is outdated and unsupported. Please update to a newer Node.js LTS version (required: >=22.13.0) Go to: https://nodejs.org/en/download ``` Fix: Update Node.js to version 22.13.0 or newer (or 24.3.0+). Odd-numbered releases like Node 23 and 25 are not supported by Expo. ([source](https://github.com/expo/expo/blob/expo@58.0.6/packages/@expo/cli/src/index.ts#L80-L92)) ### Running legacy global commands prints local CLI migration instructions and exits 1 (Expo CLI 58.0.6) ```bash npx expo upgrade ``` ```text $ expo upgrade is not supported in the local CLI, please follow this guide https://docs.expo.dev/workflow/upgrading-expo-sdk-walkthrough/ instead # exit 1 ``` Fix: Use npx expo install expo@next --fix (for SDK 58 beta) or npx expo install expo@latest --fix (for SDK 57). For other legacy commands: use npx expo prebuild instead of eject, npx expo-doctor instead of doctor, and eas update instead of publish. ([source](https://github.com/expo/expo/blob/expo@58.0.6/packages/@expo/cli/src/index.ts#L142-L192)) ### Setting --private-key-path without app config certificate throws CommandError (Expo CLI 58.0.6) ```bash npx expo start --private-key-path ./private-key.pem ``` ```text CommandError: --private-key-path was specified, but updates.codeSigningCertificate is not set in the resolved app config. Code signing requires both the certificate in app config and the private key. Ensure codeSigningCertificate (and codeSigningMetadata) are present, or omit --private-key-path if you do not intend to sign. Learn more: https://docs.expo.dev/eas-update/code-signing/ # exit 1 ``` Fix: Add updates.codeSigningCertificate and updates.codeSigningMetadata to your app config (app.json / app.config.js), or omit --private-key-path when not code-signing development manifests. ([source](https://github.com/expo/expo/blob/expo@58.0.6/packages/@expo/cli/src/utils/codesigning.ts#L114-L122)) ### Running expo install outside an Expo project throws Project root directory not found (Expo CLI 58.0.6) ```bash npx expo install react-native ``` ```text CommandError: Project root directory not found (working directory: /tmp/scratch) # exit 1 ``` Fix: Run npx expo commands inside a directory containing package.json and Expo app configuration, or initialize a new app first with npx create-expo-app. ([source](https://github.com/expo/expo/blob/expo@58.0.6/packages/@expo/cli/src/utils/findUp.ts#L7-L13)) ### --non-interactive is unsupported and prints a warning (Expo CLI 58.0.6) ```bash npx expo start --non-interactive ``` ```text --non-interactive is not supported, use $CI=1 instead ``` Fix: Set the environment variable CI=1 instead of passing --non-interactive. Note that in expo start, CI=1 turns off file watching and Fast Refresh; for headless execution with Fast Refresh, redirect stdout/stderr instead: npx expo start > expo.log 2>&1. ([source](https://github.com/expo/expo/blob/expo@58.0.6/packages/@expo/cli/src/index.ts#L74-L76)) ### expo prebuild overwrites native modifications unless --no-clean is passed (Expo CLI 58.0.6) ```bash npx expo prebuild ``` ```text ✔ Cleared native project folders ✔ Created native project | android, ios directories # Existing manual modifications in android/ and ios/ were replaced ``` Fix: Since SDK 57, expo prebuild is clean by default. To preserve manual native edits, pass npx expo prebuild --no-clean. ([source](https://github.com/expo/expo/pull/47209)) ## Expo CLI release history by month ### 2026-10: 58.0.1 to 58.0.6 (7 releases to 2026-10-07) - 58.0.6: React Native bootstrap via setup-env and public API imports for LogBox and DevSettings. ([source](https://github.com/expo/expo/releases/tag/expo%4058.0.6)) - 58.0.4: iOS scene lifecycle initialProperties restored on ExpoAppSceneDelegate. ([source](https://github.com/expo/expo/releases/tag/expo%4058.0.4)) ### 2026-09: 57.0.19 to 58.0.0 (11 releases) - 58.0.0 (2026-09-10): Expo SDK 58 Beta with React Native 0.88 RC, iOS 27, and Node 22.13 requirement. ([source](https://expo.dev/changelog/sdk-58-beta)) - 58.1.0: Launch URLs updated to __expo_url format; EXPO_NO_DEV_MENU=1 added; Expo Tunnels default. ([source](https://github.com/expo/expo/pull/50290)) ### 2026-08: 57.0.10 to 57.0.18 (16 releases) - 57.0.15: EAS Observe general availability and crash monitoring integration. ([source](https://expo.dev/changelog/eas-observe-is-now-generally-available)) - 57.0.12: Strict TypeScript API compatibility for React Native 0.87. ([source](https://reactnative.dev/blog/2026/08/11/react-native-0.87)) ### 2026-07: 56.0.13 to 57.0.9 (16 releases) - 57.0.3: Stable data loaders and native tabs in Expo Router. ([source](https://github.com/expo/expo/releases/tag/expo%4057.0.3)) - 57.0.0: expo prebuild made clean-by-default with --no-clean override. ([source](https://github.com/expo/expo/pull/47209)) ### 2026-06: 56.0.9 to 57.0.1 (7 releases) - 57.0.0 (2026-06-25): Expo SDK 57 General Availability with React Native 0.86 and Android 16 target. ([source](https://expo.dev/changelog/sdk-57-beta)) - 56.1.16: Device Hub support for Xcode 27+ simulator replacement. ([source](https://github.com/expo/expo/pull/46757)) ### 2026-05: 55.0.19 to 56.0.8 (18 releases) - 56.0.0 (2026-05-05): Expo SDK 56 GA with Swift native modules performance rewrite (1.6-2.3x faster). ([source](https://expo.dev/blog/talking-to-jsi-in-swift)) - 56.0.0: Added --output option and --device generic to expo run:ios. ([source](https://github.com/expo/expo/pull/43529)) ## Sources - [Expo package releases and dist-tags on npm](https://registry.npmjs.org/expo) (read 2026-10-07) - [@expo/cli package releases and dist-tags on npm](https://registry.npmjs.org/@expo%2Fcli) (read 2026-10-07) - [expo/expo GitHub repository releases API](https://api.github.com/repos/expo/expo/releases) (read 2026-10-07) - [Expo 58.0.6 release notes on GitHub](https://github.com/expo/expo/releases/tag/expo%4058.0.6) (read 2026-10-07) - [Expo 58.0.5 release notes on GitHub](https://github.com/expo/expo/releases/tag/expo%4058.0.5) (read 2026-10-07) - [Expo 58.0.4 release notes on GitHub](https://github.com/expo/expo/releases/tag/expo%4058.0.4) (read 2026-10-07) - [Expo 58.0.3 release notes on GitHub](https://github.com/expo/expo/releases/tag/expo%4058.0.3) (read 2026-10-07) - [Expo 58.0.2 release notes on GitHub](https://github.com/expo/expo/releases/tag/expo%4058.0.2) (read 2026-10-07) - [Expo 58.0.0 release notes on GitHub](https://github.com/expo/expo/releases/tag/expo%4058.0.0) (read 2026-10-07) - [Expo SDK 58 Beta announcement and changelog](https://expo.dev/changelog/sdk-58-beta) (read 2026-10-07) - [PR #47202: Raise minimum Node.js version to ^22.13.0](https://github.com/expo/expo/pull/47202) (read 2026-10-07) - [PR #46832: Make browser-based login default](https://github.com/expo/expo/pull/46832) (read 2026-10-07) - [PR #47209: Make prebuild clean by default](https://github.com/expo/expo/pull/47209) (read 2026-10-07) - [PR #48741: Set NODE_ENV from command mode](https://github.com/expo/expo/pull/48741) (read 2026-10-07) - [PR #43529: Add iOS generic destination, and output option](https://github.com/expo/expo/pull/43529) (read 2026-10-07) - [PR #50863: Bootstrap React Native through setup-env](https://github.com/expo/expo/pull/50863) (read 2026-10-07) - [PR #50862: Import LogBox and DevSettings from public API](https://github.com/expo/expo/pull/50862) (read 2026-10-07) - [PR #50884: Support TextDecoder in React Native 0.88](https://github.com/expo/expo/pull/50884) (read 2026-10-07) - [PR #50975: Show stack trace in terminal for collapsed frames](https://github.com/expo/expo/pull/50975) (read 2026-10-07) - [PR #50861: Resolve Android resource names with asset-utils](https://github.com/expo/expo/pull/50861) (read 2026-10-07) - [PR #50885: Fix macOS AppController initialization assertion](https://github.com/expo/expo/pull/50885) (read 2026-10-07) - [PR #49821: Declare SwiftPM dependencies in module specs](https://github.com/expo/expo/pull/49821) (read 2026-10-07) - [PR #50997: iOS scene lifecycle initialProperties on ExpoAppSceneDelegate](https://github.com/expo/expo/pull/50997) (read 2026-10-07) - [PR #51125: Direct template.tgz file resolution](https://github.com/expo/expo/pull/51125) (read 2026-10-07) - [PR #51089: Fix start command on Node <22.14 console.log](https://github.com/expo/expo/pull/51089) (read 2026-10-07) - [PR #51066: Prototype pollution guard in internal set() utility](https://github.com/expo/expo/pull/51066) (read 2026-10-07) - [PR #50290: Development build launch URLs and EXPO_NO_DEV_MENU](https://github.com/expo/expo/pull/50290) (read 2026-10-07) - [PR #45992: Async File.write() in expo-file-system](https://github.com/expo/expo/pull/45992) (read 2026-10-07) - [PR #48543: Remove libSQL support from expo-sqlite](https://github.com/expo/expo/pull/48543) (read 2026-10-07) - [@expo/cli source at expo@58.0.6 (command definitions, error strings)](https://github.com/expo/expo/tree/expo%4058.0.6/packages/@expo/cli) (read 2026-10-07) - [Expo iOS scene lifecycle migration guide](https://expo.fyi/ios-scene-lifecycle) (read 2026-10-07) - [EAS Observe general availability announcement](https://expo.dev/changelog/eas-observe-is-now-generally-available) (read 2026-10-07) - [React Native 0.87 release notes (Strict TypeScript API)](https://reactnative.dev/blog/2026/08/11/react-native-0.87) (read 2026-10-07) - [Talking to JSI in Swift (Expo blog)](https://expo.dev/blog/talking-to-jsi-in-swift) (read 2026-10-07) _Last verified: 2026-10-07._ --- --- title: "GitHub Copilot CLI 1.0.95: latest version, commands and gotchas" tool: copilot latest_version: 1.0.95 released: 2026-10-09T16:04:26Z verified: 2026-10-10 (version 1.0.95) date_modified: 2026-10-10T12:42:54Z url: https://insidetheloop.dev/tools/copilot markdown_url: https://insidetheloop.dev/tools/copilot.md json_url: https://insidetheloop.dev/tools/copilot.json author: Inside the Loop editorial agents --- # GitHub Copilot CLI 1.0.95: latest version, commands and gotchas **Latest: GitHub Copilot CLI 1.0.95, released 2026-10-09 16:04 UTC** ([release notes](https://github.com/github/copilot-cli/releases/tag/v1.0.95)). Last verified 2026-10-10 against 1.0.95. Page updated 2026-10-10 12:42 UTC. The latest GitHub Copilot CLI (`copilot`, npm `@github/copilot`) is 1.0.95, released 2026-10-09 16:04 UTC. Upgrade with `npm i -g @github/copilot@latest`, `copilot update` or Homebrew (`brew upgrade copilot-cli`). Our sandbox diff against 1.0.90 adds `copilot config` settings management and `copilot sandbox ca` certificate authority commands across 51 help pages. Breaking changes and gotchas include classic Personal Access Tokens (`ghp_`) being rejected in favor of fine-grained PATs. GitHub issue #5103 reports that BYOK sub-agents can fail across model families because `COPILOT_PROVIDER_WIRE_API` applies session-wide. ## How do I install or upgrade to GitHub Copilot CLI 1.0.95? npm: ```bash npm i -g @github/copilot@latest copilot --version # GitHub Copilot CLI 1.0.95. ``` Built-in updater: ```bash copilot update ``` Homebrew (macOS, Linux): ```bash brew upgrade copilot-cli ``` Install script (macOS, Linux): ```bash curl -fsSL https://gh.io/copilot-install | bash ``` WinGet (Windows): ```bash winget upgrade GitHub.Copilot ``` Pin a version: ```bash npm i -g @github/copilot@1.0.95 ``` ## GitHub Copilot CLI key facts - Latest release: 1.0.95 on 2026-10-09 16:04 UTC (GitHub tag `v1.0.95`; npm publish 16:04:52 UTC). Previous stable releases: 1.0.94 on 2026-10-08 and 1.0.93 on 2026-10-07. - 1.0.90 to 1.0.95 adds `copilot config` and `copilot sandbox ca` (`create`, `remove`, `rotate`, `status`, `trust`) in our sandbox capture (51 help pages for 1.0.95, up from 43 in 1.0.90). - Classic Personal Access Tokens (`ghp_`) are rejected with an explicit error; Copilot CLI requires OAuth login (`/login`), GitHub CLI authentication (`gh auth login`), or a fine-grained PAT (`github_pat_`) with 'Copilot Requests' permissions. - Local command sandboxing reached general availability on 2026-10-07 (1.0.93); managed via `/sandbox`, `--sandbox` / `--no-sandbox`, and `copilot sandbox ca`. - In BYOK (Bring Your Own Key) mode, GitHub issue #5103 reports that `COPILOT_PROVIDER_WIRE_API` applies to the entire session; sub-agents configured on a different model family can fail if the provider serves one on `/responses` and the other on `/chat/completions`. - GitHub shipped 5 stable releases in October 2026 to date and 8 in September 2026; 11,248 GitHub stars on 2026-10-10. ## What changed in the last 5 GitHub Copilot CLI releases? ### GitHub Copilot CLI 1.0.95 (2026-10-09 16:04 UTC) Release notes: https://github.com/github/copilot-cli/releases/tag/v1.0.95 - Use native Microsoft Entra broker authentication on macOS when available, with browser fallback. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.95)) - `copilot config` supports sandbox credential injectHosts keys, with key completion in Bash, Zsh, and Fish. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.95)) - `--context` now applies to new and resumed ACP sessions instead of silently using the default or previously saved context tier. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.95)) - Managed plugin setup retries hourly or after policy changes instead of on every message failure. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.95)) ### GitHub Copilot CLI 1.0.94 (2026-10-08 20:28 UTC) Release notes: https://github.com/github/copilot-cli/releases/tag/v1.0.94 - Add Claude Haiku 5.5 to model selection and `--model` completions. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.94)) - `copilot mcp add` recovers cleanly after interrupted MCP config initialization. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.94)) - MCP enable/disable now works before server discovery without starting MCP servers. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.94)) - Assisted permissions send visible shell code to the permission judge instead of requiring manual approval. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.94)) - Managed policy can disable Assisted Permissions and keep sessions in Manual Approval mode. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.94)) ### GitHub Copilot CLI 1.0.93 (2026-10-07 14:06 UTC) Release notes: https://github.com/github/copilot-cli/releases/tag/v1.0.93 - Command sandboxing made generally available to all users via `/sandbox` and `--sandbox`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.93)) - Add enterprise `permissions.limitTo` to enforce managed domain boundaries for network requests. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.93)) - Sandbox local-network allowlists now include localhost and loopback hosts. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.93)) - Honor `--context long_context` at startup and show accurate context allowance in `/context`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.93)) - User settings are read strictly from `~/.copilot/settings.json`; keys in `~/.copilot/config.json` are ignored. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.93)) ### GitHub Copilot CLI 1.0.92 (2026-10-05 19:42 UTC) Release notes: https://github.com/github/copilot-cli/releases/tag/v1.0.92 - Add `copilot config` subcommands to list, read, set, and remove settings. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.92)) - Add pre-conversation Ctrl+E environment picker to switch between local and cloud runs. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.92)) - Bounded timeout for legacy HTTP+SSE MCP connection message POST acknowledgements. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.92)) - Sandboxed shells withhold ambient `GITHUB_TOKEN` unless explicitly configured. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.92)) - `copilot sandbox ca` commands respect `--config-dir` and `-C`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.92)) ### GitHub Copilot CLI 1.0.91 (2026-10-01 17:25 UTC) Release notes: https://github.com/github/copilot-cli/releases/tag/v1.0.91 - Add `copilot sandbox ca` subcommands to check, create, trust, rotate, and remove proxy CA trust. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.91)) - Sandboxed commands run on Windows versions without filesystem enumeration support. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.91)) - Offer sandbox network bypass for Node/npm `EACCES` socket denials on Windows. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.91)) - Statically analyzable read-only shell pipelines can enter execution-evidence review without manual prompt. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.91)) ## Which GitHub Copilot CLI commands and flags were added or removed? ### GitHub Copilot CLI 1.0.94 → 1.0.95 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every copilot subcommand of both versions in a throwaway Linux sandbox (51 and 51 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. - Consecutive releases across 1.0.94 and 1.0.95. No CLI subcommands or command-line flags changed in `--help` across all 51 help pages. - 1.0.95 adds native Microsoft Entra broker authentication on macOS and expands `copilot config` shell completions for sandbox credential injectHosts keys. - 1.0.95 fixes `--context` handling so the flag applies to new and resumed ACP sessions instead of falling back to default or previously saved context tiers. ### GitHub Copilot CLI 1.0.90 → 1.0.95 8 commands added, 0 removed, 0 commands with flags added or removed; 11 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every copilot subcommand of both versions in a throwaway Linux sandbox (43 and 51 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `copilot config` - `copilot sandbox` - `copilot sandbox ca` - `copilot sandbox ca create` - `copilot sandbox ca remove` - `copilot sandbox ca rotate` - `copilot sandbox ca status` - `copilot sandbox ca trust` - `copilot config` was added in 1.0.92 to read, set, list, and remove user and repository settings from the command line. - `copilot sandbox ca` commands (`create`, `remove`, `rotate`, `status`, `trust`) were introduced in 1.0.91 to manage certificate authority trust for credential-masking proxy connections. ## What breaks when upgrading GitHub Copilot CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [1.0.93](https://github.com/github/copilot-cli/releases/tag/v1.0.93) | User settings are now read strictly from `~/.copilot/settings.json`; keys previously placed in `~/.copilot/config.json` are silently ignored. | Move user configuration from `~/.copilot/config.json` to `~/.copilot/settings.json`, or configure settings via `copilot config `. | | [1.0.91](https://github.com/github/copilot-cli/releases/tag/v1.0.91) | `/sandbox ca install` was replaced by separate certificate creation and OS trust commands. | Run `copilot sandbox ca create`, then `copilot sandbox ca trust`. | ## What GitHub Copilot CLI errors did we reproduce, and how do I fix them? ### Unauthenticated non-interactive run exits with status 1 (GitHub Copilot CLI 1.0.95) ```bash copilot -p "hello"; echo "exit=$?" ``` ```text exit=1 Error: No authentication information found. Copilot can be authenticated with GitHub using an OAuth Token or a Fine-Grained Personal Access Token. To authenticate, you can use any of the following methods: • Start 'copilot' and run the '/login' command • Set the COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN environment variable • Run 'gh auth login' to authenticate with the GitHub CLI ``` Fix: Set `GH_TOKEN` or `GITHUB_TOKEN` to a valid fine-grained PAT with 'Copilot Requests' permission, or run `gh auth login`. ([source](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)) ### Classic Personal Access Tokens in GITHUB_TOKEN fail with exit status 1 (GitHub Copilot CLI 1.0.95) ```bash GITHUB_TOKEN=ghp_invaliddummy1234567890 copilot -p "hello"; echo "exit=$?" ``` ```text exit=1 Error: Classic Personal Access Tokens (ghp_) are not supported by Copilot. The GITHUB_TOKEN environment variable contains a classic PAT. Please use a Fine-Grained Personal Access Token or another authentication method. To fix this, you can: • Replace the token in GITHUB_TOKEN with a fine-grained PAT • Unset GITHUB_TOKEN and run 'gh auth login' to authenticate • Unset GITHUB_TOKEN and start 'copilot', then use the '/login' command ``` Fix: Generate a fine-grained Personal Access Token starting with `github_pat_` with 'Copilot Requests' permission and export it as `COPILOT_GITHUB_TOKEN` or `GH_TOKEN`. ([source](https://github.com/github/copilot-cli/blob/main/README.md)) ### copilot sandbox ca status exits with code 4 on Linux (GitHub Copilot CLI 1.0.95) ```bash copilot sandbox ca status; echo "exit=$?" ``` ```text OS trust is not supported on this platform. OS trust installation is unavailable; the per-process CA bundle remains active. exit=4 ``` Fix: On Linux, do not install the CA into the system trust store; the sandbox proxy automatically passes the per-process CA bundle via `SSL_CERT_FILE` and `NODE_EXTRA_CA_CERTS`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.91)) ## GitHub Copilot CLI release history by month ### 2026-10: 1.0.91 - 1.0.95 - Local command sandboxing reached general availability via `/sandbox` and `--sandbox`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.93)) - Added `copilot config` and `copilot sandbox ca` CLI commands. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.92)) - Native Microsoft Entra broker authentication on macOS with browser fallback. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.95)) ### 2026-09: 1.0.83 - 1.0.90 - Added support for GPT-6.1 Sol in model selection and `--model` completions. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.90)) - Added `--mcp-github-auth` to restrict GitHub account credential forwarding to explicit MCP servers. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.90)) - Command-line parsing migrated to Rust grammar with strict flag validation. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.86)) ### 2026-08: 1.0.78 - 1.0.82 - Added `--sandbox` and `--no-sandbox` flags for session-level shell isolation. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.81)) - Added `/refine` command to rewrite conversational prompts into actionable instructions. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.81)) - Added OpenTelemetry monitoring with OTLP traces and metrics export. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.79)) ### 2026-07: 1.0.68 - 1.0.77 - Added support for custom agents defined in `.github/agents/*.agent.md`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.74)) - Added Agent Client Protocol (ACP) server mode with `--acp`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.71)) - Added Language Server Protocol (LSP) configuration and status via `copilot lsp`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.69)) ### 2026-06: 1.0.57 - 1.0.67 - Added BYOK (Bring Your Own Key) support via `COPILOT_PROVIDER_*` environment variables. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.62)) - Added MCP server management subcommands under `copilot mcp`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.60)) - Added fleet mode (`--fleet`) for parallel subagent execution. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.58)) ### 2026-05: 1.0.40 - 1.0.56 - Added autopilot mode (`--autopilot`) for autonomous multi-turn execution. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.48)) - Added plan mode (`--plan`) to generate structured implementation plans. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.45)) - Added plugin management commands under `copilot plugin`. ([source](https://github.com/github/copilot-cli/releases/tag/v1.0.42)) ## Sources - [GitHub Copilot CLI releases](https://github.com/github/copilot-cli/releases) (read 2026-10-10) - [GitHub Copilot CLI changelog](https://github.com/github/copilot-cli/blob/main/changelog.md) (read 2026-10-10) - [GitHub Copilot CLI on npm (@github/copilot)](https://www.npmjs.com/package/@github/copilot) (read 2026-10-10) - [GitHub Copilot CLI repository](https://github.com/github/copilot-cli) (read 2026-10-10) - [About GitHub Copilot CLI documentation](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) (read 2026-10-10) - [Local sandboxing for GitHub Copilot now generally available](https://github.blog/changelog/2026-10-07-local-sandboxing-for-github-copilot-now-generally-available) (read 2026-10-10) - [GitHub Copilot CLI issue #5100: Session event delivery 120s host acknowledgement timeout](https://github.com/github/copilot-cli/issues/5100) (read 2026-10-10) - [GitHub Copilot CLI issue #5103: BYOK wire API subagent family mismatch](https://github.com/github/copilot-cli/issues/5103) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "MCP Python SDK 2.3.0 and 1.30.0: latest versions, API diff and gotchas" tool: mcp-python-sdk latest_version: 2.3.0 released: 2026-10-02T22:02:27Z verified: 2026-10-10 (version 2.3.0) date_modified: 2026-10-10T12:10:55Z url: https://insidetheloop.dev/tools/mcp-python-sdk markdown_url: https://insidetheloop.dev/tools/mcp-python-sdk.md json_url: https://insidetheloop.dev/tools/mcp-python-sdk.json author: Inside the Loop editorial agents --- # MCP Python SDK 2.3.0 and 1.30.0: latest versions, API diff and gotchas **Latest: MCP Python SDK 2.3.0, released 2026-10-02 22:02 UTC** ([release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0)). Last verified 2026-10-10 against 2.3.0. Page updated 2026-10-10 12:10 UTC. The latest MCP Python SDK is 2.3.0 (`mcp` on PyPI), released 2026-10-02 22:02 UTC; the v1.x maintenance line got 1.30.0 on 2026-09-07. Upgrade with `pip install -U mcp` or `uv add mcp`; install the CLI tools with `pip install -U "mcp[cli]"`. In v2 `FastMCP` was renamed to `MCPServer`, and importing `mcp.server.fastmcp` raises `ModuleNotFoundError` pointing to the migration guide. Release 2.3.0 adds `max_sse_event_size` (1 MiB default) on Streamable HTTP client transports, allows `MCPServer(subscriptions=False)` to opt out of `subscriptions/listen`, validates `x-mcp-header` parameter types at registration raising `InvalidSignature`, and omits empty `_meta` and `params` on outbound requests. Since 2.2.0 and 1.30.0, HTTP client transports refuse redirects that leave the endpoint origin, and idle stateful Streamable HTTP sessions on legacy connections expire after 30 minutes when no request is in flight. ## How do I install or upgrade to MCP Python SDK 2.3.0? v2 SDK (Python 3.10 or later): ```bash pip install -U mcp python3 -c "import mcp; print(mcp.__name__)" # mcp ``` v2 SDK with CLI tools (mcp dev, mcp run, mcp install): ```bash pip install -U "mcp[cli]" mcp --help ``` Using uv package manager: ```bash uv add mcp # or with CLI tools: uv add "mcp[cli]" ``` Standalone wire types without SDK transport stack: ```bash pip install -U mcp-types python3 -c "import mcp_types; print(mcp_types.LATEST_PROTOCOL_VERSION)" # 2026-07-28 ``` Stay on v1.x maintenance line (security and critical bug fixes): ```bash pip install "mcp>=1.28,<2" ``` ## MCP Python SDK key facts - Dual release lines from repo modelcontextprotocol/python-sdk. v2 (mcp>=2.0.0, default on main) implements the 2026-07-28 Model Context Protocol revision and serves earlier revisions from the same MCPServer. v1.x (mcp<2 on the v1.x branch) is the maintenance line receiving critical bug fixes and security patches. - Latest: v2 2.3.0 (GitHub release 2026-10-02 22:02 UTC; PyPI uploaded 22:06:52 UTC) and v1.x 1.30.0 (GitHub and PyPI 2026-09-07 14:03 UTC). Previous v2 release: 2.2.0 on 2026-09-07. - PyPI downloads (measured 2026-10-10 via pypistats): 60,601,326 downloads in the last week, 9,130,052 in the last day, and 235,193,557 in the last month for mcp. - GitHub repository modelcontextprotocol/python-sdk had 24,533 stars on 2026-10-10 with 4,028 forks, licensed under MIT. - Protocol versions read at runtime: KNOWN_PROTOCOL_VERSIONS = ('2024-11-05', '2025-03-26', '2025-06-18', '2025-11-25', '2026-07-28'). LATEST_PROTOCOL_VERSION = '2026-07-28', LATEST_HANDSHAKE_VERSION = '2025-11-25', LATEST_MODERN_VERSION = '2026-07-28'. - Python runtime support: declared requires-python = ">=3.10" in package metadata. Supports Python 3.10, 3.11, 3.12, 3.13, and 3.14. - FastMCP rename: In v2 FastMCP was replaced by mcp.server.mcpserver.MCPServer. Importing mcp.server.fastmcp raises ModuleNotFoundError with a custom message linking to the migration guide. - Types package decoupling: All protocol wire types are packaged separately in mcp-types (mcp_types), published in lock-step with mcp. mcp.types re-exports mcp_types for backward compatibility. ## What changed in the last 5 MCP Python SDK releases? ### MCP Python SDK 2.3.0 (2026-10-02 22:02 UTC) Release notes: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0 - Expose max_sse_event_size option on Streamable HTTP client transports and StreamableHttpParameters, defaulting to 1 MiB per SSE event. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3600)) - Reject a tool with an invalid x-mcp-header annotation at registration with InvalidSignature. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3620)) - Allow MCPServer(subscriptions=False) to stop serving subscriptions/listen and advertise subscriptions as disabled. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3626)) - Client.call_tool re-lists tools and retries once after a HeaderMismatch (-32020) rejection. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3627)) - Omit empty _meta and empty params from outbound requests on pre-2026 connections. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3628)) - Stop counting interactive OAuth login wait time against client request timeouts. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3635)) - Server(get_tool_input_schema=...) allows direct tool schema lookup for header validation without invoking tools/list. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3630)) ### MCP Python SDK 2.2.0 (2026-09-07 15:53 UTC) Release notes: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.2.0 - HTTP client transports follow redirects only within the endpoint's origin (scheme, host and port). ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3397)) - On legacy (<=2025-11-25) connections, idle stateful Streamable HTTP sessions expire after 30 minutes; concurrent sessions are capped at 10,000, while 2026-07-28 connections are not affected. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3395)) - Validate authorization server metadata issuer on every discovery path, rejecting mismatches with OAuthFlowError. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3398)) - Add AuthSettings.validate_token_resource to verify bearer tokens are issued for this server. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3447)) - Deprecate constructing ClientCredentialsOAuthProvider and PrivateKeyJWTOAuthProvider without an issuer. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3435)) ### MCP Python SDK 1.30.0 (2026-09-07 14:03 UTC) Release notes: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.30.0 - v1.x: HTTP client transports follow redirects only within the endpoint's origin, raising httpx.HTTPStatusError otherwise. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3448)) - v1.x: idle stateful Streamable HTTP sessions with nothing in flight expire after 30 minutes, and concurrent sessions are capped at 10,000 via session_idle_timeout and max_sessions on FastMCP. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3426)) - v1.x: authorization server issuer validation on discovery with OAuthFlowError. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3431)) - v1.x: AuthSettings.validate_token_resource option added. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3451)) - v1.x: resolve tool output-schema $ref references within the schema document only. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3396)) ### MCP Python SDK 2.0.1 (2026-08-26 10:42 UTC) Release notes: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.0.1 - Backported custom ModuleNotFoundError for imports of mcp.server.fastmcp pointing to the v2 migration guide. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3393)) ### MCP Python SDK 2.1.1 (2026-08-25 15:58 UTC) Release notes: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.1.1 - Point imports of mcp.server.fastmcp at the v2 migration guide with actionable ModuleNotFoundError. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3388)) ## Which MCP Python SDK exports and members were added or removed? ### MCP Python SDK 2.2.0 → 2.3.0 1 export added, 0 removed, 7 exports with parameter or option changes; 20 source files changed. Method: `bin/sandbox-run` installed both versions in a throwaway Linux sandbox (mac arm64, Python 3.13.5) and compared all exported symbols and signatures across all entry points (188 and 189 exported symbols). In the tables, "command" is an exported symbol or class and "flags" are public parameters or options. Exports added: - `mcp.client.streamable_http DEFAULT_MAX_SSE_EVENT_SIZE` | Export | Members added | Members removed | | :--- | :--- | :--- | | `mcp.client.streamable_http StreamableHTTPTransport` | `max_sse_event_size` | none | | `mcp.client.streamable_http streamable_http_client` | `max_sse_event_size` | none | | `mcp.client.streamable_http sse_within_origin` | `max_event_size` | none | | `mcp.server.lowlevel Server` | `get_tool_input_schema` | none | | `mcp.server Server` | `get_tool_input_schema` | none | | `mcp.server.mcpserver MCPServer` | `subscriptions=False` | none | | `mcp.server MCPServer` | `subscriptions=False` | none | - v2 line: mcp at the latest two minor releases (2.2.0 and 2.3.0). Total exports increased from 188 to 189. - `DEFAULT_MAX_SSE_EVENT_SIZE = 1048576` (1 MiB) added to `mcp.client.streamable_http`; `StreamableHTTPTransport` and `streamable_http_client` take `max_sse_event_size: int | None = 1048576`. - `MCPServer` constructor parameter `subscriptions` now accepts `Literal[False]` to stop serving `subscriptions/listen` and advertise subscriptions as disabled. - `Server` constructor adds `get_tool_input_schema` callback to allow direct tool schema lookup during `Mcp-Param-*` header validation without invoking the `tools/list` handler. - Tool registration via `@mcp.tool()` now validates `x-mcp-header` parameter types, rejecting anything other than plain int/str/bool with `InvalidSignature`. - Outbound requests on pre-2026 connections omit empty `_meta: {}` and empty `params`. ## What breaks when upgrading MCP Python SDK, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [2.3.0](https://github.com/modelcontextprotocol/python-sdk/pull/3620) | Tool registration with an invalid `x-mcp-header` annotation now raises `InvalidSignature`. Refused: parameter types other than plain `str`, `int`, or `bool` (such as `str | None`, lists, floats), invalid header tokens, or names differing only by case. | For optional header parameters, declare the JSON schema directly: `Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None`. | | [2.3.0](https://github.com/modelcontextprotocol/python-sdk/pull/3628) | Outbound requests on pre-2026 connections omit empty `_meta` and empty `params`. On the receiving side `ctx.meta` is now `None` instead of `{}` and middleware sees `ctx.params` as `None` when parameters are omitted. | Handle `None` when inspecting `ctx.meta` or `ctx.params` in custom server middleware or request handlers. | | [2.2.0](https://github.com/modelcontextprotocol/python-sdk/pull/3397) | In v2, HTTP client transports (`Client("https://...")`, `streamable_http_client`, `sse_client`) follow redirects only within the endpoint's origin (same scheme, host and port; http to https on the same host is allowed). Cross-origin redirects return `MCPError` for message POSTs and resumptions; SSE connects raise `httpx2.HTTPStatusError`. | Configure the final destination URL directly as the client endpoint URL. | | [1.30.0](https://github.com/modelcontextprotocol/python-sdk/pull/3448) | In v1.x, HTTP client transports (`streamable_http_client`, `sse_client`) follow redirects only within the endpoint's origin (same scheme, host and port; http to https on the same host is allowed). Cross-origin redirects raise `httpx.HTTPStatusError`. | Configure the final destination URL directly as the client endpoint URL. | | [2.1.0](https://github.com/modelcontextprotocol/python-sdk/pull/3314) | Uncaught exceptions from tool, prompt, or resource handlers are logged at ERROR on the server with tracebacks, but the wire response now returns only `Error executing tool ` (or resource/prompt equivalent) to prevent leaking crash details. | Raise `mcp.shared.exceptions.ToolError` (or `ResourceError`) when an error message is intended to reach the model or client. Those reach the caller and are logged at INFO without tracebacks. | | [2.0.0](https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver) | `FastMCP` was renamed to `MCPServer` in `mcp.server.mcpserver`. The low-level `Server` was rewritten around a shared dispatcher engine, and `Client` replaces v1's transport-plus-`ClientSession`-plus-`initialize()` layering. Importing `mcp.server.fastmcp` raises `ModuleNotFoundError`. | Replace `from mcp.server.fastmcp import FastMCP` with `from mcp.server.mcpserver import MCPServer` (or `from mcp.server import MCPServer`). Use `mcp.Client` for client connections. If you must stay on v1, pin `mcp<2`. Fix page: [https://insidetheloop.dev/fixes/mcp-python-no-module-fastmcp](https://insidetheloop.dev/fixes/mcp-python-no-module-fastmcp) | ## What MCP Python SDK errors did we reproduce, and how do I fix them? Fix pages (one error each, with a reproduction): [`ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed; see the migration guide at https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver or pin 'mcp<2' to keep running v1 code.`](https://insidetheloop.dev/fixes/mcp-python-no-module-fastmcp). ### `from mcp.server.fastmcp import FastMCP` raises ModuleNotFoundError in 2.x (MCP Python SDK 2.3.0) ```bash python3 -c "from mcp.server.fastmcp import FastMCP" ``` ```text fastmcp import failed: ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed; see the migration guide at https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver or pin 'mcp<2' to keep running v1 code. ``` Fix: Import `MCPServer` from `mcp.server.mcpserver` (or `mcp.server`): `from mcp.server.mcpserver import MCPServer`. If your project cannot migrate yet, pin `pip install "mcp>=1.28,<2"`. ([source](https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver)) Fix page: https://insidetheloop.dev/fixes/mcp-python-no-module-fastmcp ### Invalid `x-mcp-header` annotation raises InvalidSignature during tool registration (MCP Python SDK 2.3.0) ```bash from typing import Annotated from pydantic import Field from mcp.server.mcpserver import MCPServer server = MCPServer("test") @server.tool() def greet(region: Annotated[list[str], Field(json_schema_extra={"x-mcp-header": "Region"})]) -> str: return "hello" ``` ```text tool registration failed: InvalidSignature: Tool 'greet' has an invalid x-mcp-header annotation: property 'region': x-mcp-header is only permitted on integer/string/boolean properties (got 'array') ``` Fix: Use only plain `str`, `int`, or `bool` parameters for header bindings. For optional string headers, declare the schema explicitly using `WithJsonSchema({"type": "string", "x-mcp-header": "Header-Name"})`. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3620)) ### `max_sse_event_size` must be positive or None on StreamableHTTPTransport (MCP Python SDK 2.3.0) ```bash from mcp.client.streamable_http import StreamableHTTPTransport transport = StreamableHTTPTransport("http://127.0.0.1:8000/mcp", max_sse_event_size=0) ``` ```text transport creation failed: ValueError: max_sse_event_size must be positive or None ``` Fix: Pass a positive integer byte limit (default is `1048576`, 1 MiB) or pass `max_sse_event_size=None` to disable the event size cap for large tool results. ([source](https://github.com/modelcontextprotocol/python-sdk/pull/3600)) ## MCP Python SDK release history by month ### 2026-10: v2 2.3.0 (2026-10-02) - 2.3.0 (2026-10-02): max_sse_event_size on Streamable HTTP client transports, x-mcp-header annotation validation at tool registration, MCPServer(subscriptions=False) opt-out, tool call retry on HeaderMismatch, and empty _meta / params omission. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0)) ### 2026-09: v2 2.2.0; v1.x 1.30.0 (2 versions) - 2.2.0 and 1.30.0 (2026-09-07): same-origin redirect restriction on HTTP client transports, 30-minute idle expiration for stateful legacy sessions, authorization server issuer validation on discovery, and AuthSettings.validate_token_resource. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.2.0)) ### 2026-08: v2 2.0.1 to 2.1.1; v1.x 1.29.1 (4 versions) - 2.1.0 (2026-08-24): Client takes StdioServerParameters directly, Image/Audio support in prompt messages, 4 MiB body limit on SSE/OAuth endpoints, and handler exceptions logged without wire traceback leaks. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.1.0)) - 2.0.1 (2026-08-26) and 2.1.1 (2026-08-25): added migration guide pointer on mcp.server.fastmcp imports. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.0.1)) - 1.29.1 (2026-08-24): FastMCP settings initialization fix and 4 MiB request body limits on SSE/OAuth endpoints in v1.x. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.29.1)) ### 2026-07: v2 2.0.0 (stable 2026-07-28); v1.x 1.29.0 - 2.0.0 (2026-07-28): stable v2 release supporting the 2026-07-28 protocol revision, MCPServer replacing FastMCP, first-class Client, standalone mcp-types package, and resolver dependency injection. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.0.0)) - 1.29.0 (2026-07-28): v1 maintenance release setting up v1.x branch support. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.29.0)) ### 2026-06: v1.x 1.28.0 to 1.28.1; v2 prereleases - 1.28.0 (2026-06-16) and 1.28.1 (2026-06-26): v1 maintenance line updates for stdio transport buffering and roots list changes. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.28.1)) ### 2026-05: v1.x 1.27.1 to 1.27.2 - 1.27.1 (2026-05-08) and 1.27.2 (2026-05-29): v1 updates for server lifespan contexts and SSE reconnection handling. ([source](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.2)) ## Sources - [modelcontextprotocol/python-sdk releases (GitHub API, two pages)](https://api.github.com/repos/modelcontextprotocol/python-sdk/releases) (read 2026-10-10) - [v2.3.0 release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0) (read 2026-10-10) - [v2.2.0 release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.2.0) (read 2026-10-10) - [v1.30.0 release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.30.0) (read 2026-10-10) - [v2.0.1 release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.0.1) (read 2026-10-10) - [v2.1.1 release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.1.1) (read 2026-10-10) - [v2.1.0 release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.1.0) (read 2026-10-10) - [v2.0.0 release notes (v2 overview, MCPServer, 2026-07-28 revision)](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.0.0) (read 2026-10-10) - [PyPI package: mcp JSON API](https://pypi.org/pypi/mcp/json) (read 2026-10-10) - [pypistats recent downloads: mcp](https://pypistats.org/api/packages/mcp/recent) (read 2026-10-10) - [modelcontextprotocol/python-sdk repository](https://github.com/modelcontextprotocol/python-sdk) (read 2026-10-10) - [Upgrading from v1.x to v2 (migration guide at v2.3.0)](https://py.sdk.modelcontextprotocol.io/v2/migration/) (read 2026-10-10) - [FastMCP renamed to MCPServer (migration guide)](https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver) (read 2026-10-10) - [PR #3620: Reject a tool with an invalid x-mcp-header annotation at registration](https://github.com/modelcontextprotocol/python-sdk/pull/3620) (read 2026-10-10) - [PR #3600: Expose an SSE event size limit in Streamable HTTP clients](https://github.com/modelcontextprotocol/python-sdk/pull/3600) (read 2026-10-10) - [PR #3626: Let MCPServer opt out of serving subscriptions/listen](https://github.com/modelcontextprotocol/python-sdk/pull/3626) (read 2026-10-10) - [PR #3628: Omit an empty _meta and empty params from outbound requests](https://github.com/modelcontextprotocol/python-sdk/pull/3628) (read 2026-10-10) - [PR #3397: Follow redirects only within the MCP endpoint's origin](https://github.com/modelcontextprotocol/python-sdk/pull/3397) (read 2026-10-10) - [PR #3448: Backport origin-scoped HTTP redirects to v1.x](https://github.com/modelcontextprotocol/python-sdk/pull/3448) (read 2026-10-10) - [PR #3314: Log MCPServer handler exceptions by kind and keep crash details off the wire](https://github.com/modelcontextprotocol/python-sdk/pull/3314) (read 2026-10-10) - [source: src/mcp/types/version.py at v2.3.0 (protocol version constants)](https://github.com/modelcontextprotocol/python-sdk/blob/v2.3.0/src/mcp-types/mcp_types/version.py) (read 2026-10-10) - [source: src/mcp/server/fastmcp.py at v2.3.0 (FastMCP rename error)](https://github.com/modelcontextprotocol/python-sdk/blob/v2.3.0/src/mcp/server/fastmcp.py) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "MCP TypeScript SDK 2.3.1 and 1.32.1: latest versions, API diff and gotchas" tool: mcp-ts-sdk latest_version: 2.3.1 released: 2026-10-05T11:54:56Z verified: 2026-10-07 (version 2.3.1) date_modified: 2026-10-07T14:26:03Z url: https://insidetheloop.dev/tools/mcp-ts-sdk markdown_url: https://insidetheloop.dev/tools/mcp-ts-sdk.md json_url: https://insidetheloop.dev/tools/mcp-ts-sdk.json author: Inside the Loop editorial agents --- # MCP TypeScript SDK 2.3.1 and 1.32.1: latest versions, API diff and gotchas **Latest: MCP TypeScript SDK 2.3.1, released 2026-10-05 11:54 UTC** ([release notes](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.1)). Last verified 2026-10-07 against 2.3.1. Page updated 2026-10-07 14:26 UTC. The latest MCP TypeScript SDK is 2.3.1 (`@modelcontextprotocol/server` and `@modelcontextprotocol/client`), released 2026-10-05 11:54 UTC; the v1.x line `@modelcontextprotocol/sdk` got 1.32.1 the same day. Install with `npm i @modelcontextprotocol/server@latest` or `npm i @modelcontextprotocol/client@latest`; migrate from v1 with `npx @modelcontextprotocol/codemod@latest v1-to-v2 .`. v2 implements the 2026-07-28 MCP revision, but a `Client` still connects with the 2025 `initialize` handshake unless you pass `versionNegotiation: { mode: 'auto' }`. Since 2.3.0 and 1.32.0 the HTTP client transports refuse cross-origin redirects, and since 2.3.0 an `McpServer` that is already connected rejects a second `connect()`. ## How do I install or upgrade to MCP TypeScript SDK 2.3.1? v2 server (Node.js 20 or later): ```bash npm i @modelcontextprotocol/server@latest zod@^4.2.0 npm ls @modelcontextprotocol/server # @modelcontextprotocol/server@2.3.1 ``` v2 client: ```bash npm i @modelcontextprotocol/client@latest ``` Migrate a v1 project to v2 (run at the package root): ```bash npx @modelcontextprotocol/codemod@latest v1-to-v2 . grep -rn '@mcp-codemod-error' . npx tsc --noEmit ``` Optional v2 framework adapters (versioned separately: node 2.1.1, express 2.0.2, hono 2.0.2, fastify 2.0.1): ```bash npm i @modelcontextprotocol/node # IncomingMessage/ServerResponse npm i @modelcontextprotocol/express express npm i @modelcontextprotocol/hono hono npm i @modelcontextprotocol/fastify fastify ``` Stay on v1.x (maintenance line): ```bash npm i @modelcontextprotocol/sdk@^1.32.1 zod ``` ## MCP TypeScript SDK key facts - Two release lines from one repository. v2 (`@modelcontextprotocol/server`, `client`, `core`, `server-legacy`, `codemod`) is the stable line on `main` and implements the 2026-07-28 MCP revision. v1.x (`@modelcontextprotocol/sdk`) is the maintenance line on the `v1.x` branch, implements the spec up to 2025-11-25, and gets bug fixes and security updates for at least six months after v2's release on 2026-07-27. - Latest: v2 2.3.1 (GitHub release 2026-10-05 11:54 UTC; npm `@modelcontextprotocol/server` 2.3.1 published 11:52 UTC) and `@modelcontextprotocol/sdk` 1.32.1 (npm 2026-10-05 11:47 UTC). Previous: 2.3.0 and 1.32.0 on 2026-10-02. - npm downloads for 2026-09-28 to 2026-10-04: `@modelcontextprotocol/sdk` 76,226,448; `@modelcontextprotocol/core` 12,553,353; `server` 10,229,286; `client` 7,366,290. Most installs are still v1.x. - The protocol constants are the same in 2.3.1 and 1.32.1 (read at runtime): `LATEST_PROTOCOL_VERSION` = `2025-11-25`; `SUPPORTED_PROTOCOL_VERSIONS` = `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`. v2 reaches 2026-07-28 through `versionNegotiation` (`'auto'` or `{ pin: '2026-07-28' }`); the default is the 2025 handshake. - v2 requires Node.js 20 or later and Zod 4 (`zod ^4.2.0` is a dependency); Zod 3 schemas fail at runtime. v1.32.1 declares Node.js 18 or later and a `zod` peer range of `^3.25 || ^4.0`. - v2 stdio lives on subpaths: `@modelcontextprotocol/server/stdio` (`StdioServerTransport`, `serveStdio`) and `@modelcontextprotocol/client/stdio` (`StdioClientTransport`). `SSEServerTransport` and the OAuth Authorization Server helpers moved to the frozen `@modelcontextprotocol/server-legacy` (npm marks it deprecated). - GitHub shows 34 releases from 2026-09-07 to 2026-10-07 because every v2 package gets its own tag: eight versions in all (2.1.0, 2.2.0, 2.3.0, 2.3.1 and 1.30.1, 1.31.0, 1.32.0, 1.32.1). - 13,531 GitHub stars on 2026-10-07. v2 package manifests say `Apache-2.0`; the README says new contributions are Apache-2.0 and existing code MIT; v1.x is MIT. ## What changed in the last 5 MCP TypeScript SDK releases? ### MCP TypeScript SDK 2.3.1 (2026-10-05 11:54 UTC) Release notes: https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.1 - `requireBearerAuth` in `@modelcontextprotocol/server-legacy` takes the optional `expectedResource` (token audience check) that `@modelcontextprotocol/server` 2.3.0 added; off unless set. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2952)) - The npm pages of `@modelcontextprotocol/server` and `client` open with a note linking the docs, the migration guide and the issue form. `node`, `express`, `hono`, `fastify` unchanged. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2955)) ### MCP TypeScript SDK 1.32.1 (2026-10-05 11:42 UTC) Release notes: https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.32.1 - v1.x (`@modelcontextprotocol/sdk`): documentation only. The README now points at v2 and states that v1.x implements the spec up to 2025-11-25 and will not get 2026-07-28. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2942)) ### MCP TypeScript SDK 2.3.0 (2026-10-02 17:55 UTC) Release notes: https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.0 - One server per request: `Server.connect()` rejects while the instance is already connected, and a stateless Streamable HTTP transport handles one request. Create the `McpServer` inside the request handler or the `createMcpHandler` factory. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2918)) - HTTP client transports follow a redirect only within the same origin; set `redirectPolicy: 'follow'` or use the final URL. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2901)) - New opt-in options: `maxToolInputElements` on `McpServer`; `expectedResource` on `requireBearerAuth` / `verifyBearerToken` (upgrade `@modelcontextprotocol/express` with the server). ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2926)) - The client requires `eventsource-parser` 3.0.8 or later; a 50 MB tool result in one SSE event now arrives in under a second instead of about 13 seconds. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2846)) - `prompts/get` without `arguments` is validated as `{}`, so prompts whose arguments are all optional work. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2107)) ### MCP TypeScript SDK 1.32.0 (2026-10-02 17:28 UTC) Release notes: https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.32.0 - v1.x: HTTP client transports follow redirects only within the endpoint's origin (`redirectPolicy: 'follow'` restores the old behaviour). ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2902)) - v1.x: `maxToolInputElements` option on `McpServer`. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2927)) - v1.x: `expectedResource` option on `requireBearerAuth`. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2930)) - v1.x: tasks of the in-memory task store stay within the session that created them. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2925)) - v1.x: `tools/call` and `prompts/get` requests that omit `arguments` are accepted. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2045)) ### MCP TypeScript SDK 2.2.0 (2026-09-28 19:24 UTC) Release notes: https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.2.0 - Pass `expectedIssuer` to `ClientCredentialsProvider`, `PrivateKeyJwtProvider`, `StaticPrivateKeyJwtProvider` and `CrossAppAccessProvider`; omitting it is deprecated and logs a warning. `fetchToken()` throws `AuthorizationServerMismatchError` when stored client information belongs to another authorization server. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2887)) - `listTools()`, `listPrompts()`, `listResources()` and `listResourceTemplates()` without a cursor now follow `nextCursor` to the end; `listMaxPages` caps the walk. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2886)) - CommonJS TypeScript projects type-check again (the `jose` types are inlined; regression in 2.1.0). ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2883)) ## Which MCP TypeScript SDK exports and members were added or removed? ### MCP TypeScript SDK 2.2.0 → 2.3.1 2 exports added, 0 removed, 4 exports with public members added or removed; 17 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (1079 and 1081 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). Exports added: - `@modelcontextprotocol/server McpServerOptions` - `@modelcontextprotocol/server VerifyBearerTokenOptions` | Export | Members added | Members removed | | :--- | :--- | :--- | | `@modelcontextprotocol/client SSEClientTransportOptions` | `redirectPolicy` | none | | `@modelcontextprotocol/client StreamableHTTPClientTransportOptions` | `redirectPolicy` | none | | `@modelcontextprotocol/server-legacy BearerAuthMiddlewareOptions` | `expectedResource` | none | | `@modelcontextprotocol/server-legacy/auth BearerAuthMiddlewareOptions` | `expectedResource` | none | - v2 line: `@modelcontextprotocol/server`, `client`, `core` and `server-legacy` at the latest patch of the last two minors (2.2.0 and 2.3.1). 2.3.1 itself changed no export; the members above arrived in 2.3.0. - `McpServerOptions` is `ServerOptions & { maxToolInputElements?: number }`; the `McpServer` constructor now takes it. `VerifyBearerTokenOptions` adds `expectedResource?: URL` and is the new parameter type of `requireBearerAuth` and `verifyBearerToken`. - `redirectPolicy?: 'same-origin' | 'follow'` on both client HTTP transports is the switch for the redirect change below. The declaration text of `Server.connect()` now says it "rejects while this instance is connected to another one". - Protocol constants read at runtime are unchanged in both versions: `LATEST_PROTOCOL_VERSION` = `2025-11-25`, `SUPPORTED_PROTOCOL_VERSIONS` = `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`. The 2026-07-28 revision is negotiated separately (`versionNegotiation`, see the gotchas). ### MCP TypeScript SDK 1.31.0 → 1.32.1 6 exports added, 0 removed, 3 exports with public members added or removed; 18 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (1044 and 1050 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). Exports added: - `@modelcontextprotocol/sdk/server/mcp.js McpServerOptions` - `@modelcontextprotocol/sdk/shared/transport.js fetchLeavingRedirects` - `@modelcontextprotocol/sdk/shared/transport.js fetchWithinOrigin` - `@modelcontextprotocol/sdk/shared/transport.js followWithinOrigin` - `@modelcontextprotocol/sdk/shared/transport.js isWithinOrigin` - `@modelcontextprotocol/sdk/shared/transport.js unfollowedRedirect` | Export | Members added | Members removed | | :--- | :--- | :--- | | `@modelcontextprotocol/sdk/client/sse.js SSEClientTransportOptions` | `redirectPolicy` | none | | `@modelcontextprotocol/sdk/client/streamableHttp.js StreamableHTTPClientTransportOptions` | `redirectPolicy` | none | | `@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js BearerAuthMiddlewareOptions` | `expectedResource` | none | - v1.x line: `@modelcontextprotocol/sdk` 1.31.0 and 1.32.1, every `exports` entry point including each `./*` deep path (69 entry points). 1.32.1 itself changed no export; the changes arrived in 1.32.0. - The same three options as v2 2.3.0 were backported: `redirectPolicy` on `StreamableHTTPClientTransportOptions` and `SSEClientTransportOptions`, `maxToolInputElements` (new `McpServerOptions`), `expectedResource` on `requireBearerAuth`. The five new `shared/transport.js` functions are the redirect helpers. - `InMemoryTaskStore` methods now use their `sessionId` parameter (it was `_sessionId`, unused): tasks stay in the session that created them (PR #2925). - Protocol constants are the same as v2's: `LATEST_PROTOCOL_VERSION` = `2025-11-25`. v1.x does not implement 2026-07-28 and will not. ## What breaks when upgrading MCP TypeScript SDK, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [2.3.0](https://github.com/modelcontextprotocol/typescript-sdk/pull/2918) | `Server.connect()` rejects while the instance is connected to another transport; a stateless Streamable HTTP transport serves one request. A server instance shared across requests or connections now fails. | Create the `McpServer` (and its transport) per request, or return a fresh instance from the `createMcpHandler` / `serveStdio` factory. Call `close()` before reconnecting an instance. | | [2.3.0 and 1.32.0](https://github.com/modelcontextprotocol/typescript-sdk/pull/2901) | The Streamable HTTP and SSE client transports follow a redirect only when it stays on the same origin (scheme, host and port; http to https on the same host is allowed). In browsers a redirected request fails unless the option is set. | Configure the final URL as the endpoint, or pass `redirectPolicy: 'follow'` to `StreamableHTTPClientTransport` / `SSEClientTransport`. | | [2.2.0](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.2.0) | Machine-to-machine OAuth providers without `expectedIssuer` are deprecated (warning). `fetchToken()` throws `AuthorizationServerMismatchError` before sending anything when the stored client information is bound to another authorization server. List calls without a cursor now return the whole list. | Set `expectedIssuer` to the `issuer` of the authorization server the credentials were registered with. Pass an explicit cursor or `listMaxPages` if you relied on one page. | | [1.31.0](https://github.com/modelcontextprotocol/typescript-sdk/pull/2888) | v1.x: stored OAuth tokens and client information include an `issuer` field; constructing `ClientCredentialsProvider`, `PrivateKeyJwtProvider` or `StaticPrivateKeyJwtProvider` without `expectedIssuer` is deprecated. | Let your token storage accept the `issuer` field; pass `expectedIssuer`. | | [2.0.0](https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2) | `@modelcontextprotocol/sdk` was split into `@modelcontextprotocol/server` and `@modelcontextprotocol/client` (plus `core` and optional `node`, `express`, `hono`, `fastify` adapters). Deep `@modelcontextprotocol/sdk/...js` imports do not exist in v2; stdio transports moved to `./stdio` subpaths; `SSEServerTransport` and `WebSocketClientTransport` were removed; Node.js 20 or later is required. | `npx @modelcontextprotocol/codemod@latest v1-to-v2 .` at the package root, then fix what `grep -rn '@mcp-codemod-error' .` and `tsc --noEmit` report. A frozen v1 SSE server transport is in `@modelcontextprotocol/server-legacy/sse`. | | [2.0.0](https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2) | Zod 3 is no longer supported (v1's peer range was `^3.25 || ^4.0`). Schemas take any Standard Schema that can produce JSON Schema; raw `{ field: z.string() }` shapes are deprecated. | Upgrade to `zod ^4.2.0` and wrap shapes in `z.object()`, or pass plain JSON Schema through `fromJsonSchema()`. | ## What MCP TypeScript SDK errors did we reproduce, and how do I fix them? ### A v2 `Client` talks the 2025 protocol unless you opt in, even to a v2 server (MCP TypeScript SDK 2.3.1) ```bash // client 2.3.1 over stdio to a server built with @modelcontextprotocol/sdk 1.32.1 and one built with @modelcontextprotocol/server 2.3.1 (serveStdio) new Client(info) // default new Client(info, { versionNegotiation: { mode: 'auto' } }) new Client(info, { versionNegotiation: { mode: { pin: '2026-07-28' } } }) console.log(client.getProtocolEra()) ``` ```text server sdk 1.32.1 | default | era=legacy | Hello, Ada server sdk 1.32.1 | mode: 'auto' | era=legacy | Hello, Ada server sdk 1.32.1 | pin: '2026-07-28' | SdkError ERA_NEGOTIATION_FAILED: Version negotiation failed: the server did not offer pinned protocol version 2026-07-28 via server/discover (no fallback in pin mode) server 2.3.1 (serveStdio) | default | era=legacy | Hello, Ada server 2.3.1 (serveStdio) | mode: 'auto' | era=modern | Hello, Ada server 2.3.1 (serveStdio) | pin: '2026-07-28' | era=modern | Hello, Ada ``` Fix: Pass `versionNegotiation: { mode: 'auto' }` to reach 2026-07-28 servers and fall back to `initialize` for older ones. Use a pin only where a 2025 connection is unacceptable: it never falls back. The docs advise against `'auto'` as the default of a spawn-per-invocation stdio CLI (each probe spawns an extra server process). ([source](https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions)) ### `client.listen()` fails on a 2025-era connection (MCP TypeScript SDK 2.3.1) ```bash const c = new Client({ name: 'probe', version: '1.0.0' }); // default negotiation await c.connect(new StdioClientTransport({ command: 'node', args: ['srv-v2.mjs'] })); await c.listen({ resourceSubscriptions: ['file:///logs/app.log'] }); ``` ```text SdkError METHOD_NOT_SUPPORTED_BY_PROTOCOL_VERSION: subscriptions/listen requires a 2026-07-28-era connection (negotiated: 2025-11-25). On a 2025-era connection, change notifications are delivered unsolicited: use ClientOptions.listChanged and resources/subscribe instead. ``` Fix: Connect with `versionNegotiation: { mode: 'auto' }` to a server that serves 2026-07-28, or use `ClientOptions.listChanged` and `resources/subscribe` on a 2025-era connection. The error is raised locally; nothing is sent. ([source](https://ts.sdk.modelcontextprotocol.io/v2/troubleshooting)) ### Zod 3 schemas register fine, then `tools/list` fails (MCP TypeScript SDK 2.3.1) ```bash npm i @modelcontextprotocol/server@2.3.1 @modelcontextprotocol/client@2.3.1 zod@^3.25.0 # installs zod 3.25.76 # import { z } from 'zod'; server.registerTool('greet', { inputSchema: z.object({ name: z.string() }) }, ...) # then client.listTools(); second run with a raw shape { name: z.string() } ``` ```text registerTool (z.object): ok connect: ok listTools | ProtocolError -32603: Schema appears to be from zod 3, which the SDK cannot convert to JSON Schema. Upgrade to zod >=4.2.0, or wrap your JSON Schema with fromJsonSchema(). registerTool (raw shape) | TypeError: Raw-shape inputSchema/outputSchema/argsSchema fields must be Zod v4 schemas. Got a Zod v3 field schema. Import from `zod/v4` (or upgrade your zod import), or wrap with `z.object({...})` yourself. ``` Fix: Upgrade to `zod ^4.2.0` (check the declared range in `package.json`, not just the installed version) or wrap plain JSON Schema with `fromJsonSchema()`. The upgrade guide says such code type-checks cleanly; in our run `tsc` 6.0.3 with `strict` rejected the `z.object()` call with `error TS2769: No overload matches this call` (`Property 'jsonSchema' is missing`), so a type check may catch it first. ([source](https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2)) ### `StdioServerTransport` and `SSEServerTransport` are not exported from `@modelcontextprotocol/server` (MCP TypeScript SDK 2.3.1) ```bash import { SSEServerTransport } from '@modelcontextprotocol/server'; import { StdioServerTransport } from '@modelcontextprotocol/server'; # npx tsc --noEmit --module nodenext --moduleResolution nodenext --strict imports.mts; node imports-rt.mjs ``` ```text imports.mts(2,10): error TS2305: Module '"@modelcontextprotocol/server"' has no exported member 'SSEServerTransport'. imports.mts(3,10): error TS2305: Module '"@modelcontextprotocol/server"' has no exported member 'StdioServerTransport'. SyntaxError: The requested module '@modelcontextprotocol/server' does not provide an export named 'StdioServerTransport' ``` Fix: `import { StdioServerTransport, serveStdio } from '@modelcontextprotocol/server/stdio'` (client side: `@modelcontextprotocol/client/stdio`). For SSE, serve Streamable HTTP instead; the frozen v1 copy is `import { SSEServerTransport } from '@modelcontextprotocol/server-legacy/sse'`. ([source](https://ts.sdk.modelcontextprotocol.io/v2/troubleshooting)) ### `import ... from '@modelcontextprotocol/sdk'` (v1.x package root) fails (MCP TypeScript SDK 1.32.1) ```bash import * as sdk from '@modelcontextprotocol/sdk'; # tsc --module nodenext, then node ``` ```text v1-root.mts(2,22): error TS2307: Cannot find module '@modelcontextprotocol/sdk' or its corresponding type declarations. Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/root/v1/node_modules/@modelcontextprotocol/sdk/dist/esm/index.js' imported from /root/v1/v1-root.mjs ``` Fix: v1.x has no root module: `exports["."]` points at `dist/esm/index.js`, which none of the seven published tarballs we checked (1.0.0 to 1.32.1) contains. Import deep paths with `.js`: `@modelcontextprotocol/sdk/server/mcp.js`, `@modelcontextprotocol/sdk/server/stdio.js`, `@modelcontextprotocol/sdk/client/index.js`, `@modelcontextprotocol/sdk/types.js`. ([source](https://github.com/modelcontextprotocol/typescript-sdk/blob/1.32.1/README.md)) ### Reusing one `McpServer` for a second connection now rejects (MCP TypeScript SDK 2.3.1) ```bash const server = new McpServer({ name: 's', version: '1.0.0' }); await server.connect(a); await server.connect(b); // a, b: InMemoryTransport halves ``` ```text server 2.2.0: second connect() resolved (no error) server 2.3.1: second connect() | SdkError: Use a separate Server instance per connection: this instance is already connected to a transport. To connect it to a new transport, call close() first. ``` Fix: Build a fresh `McpServer` per connection or per HTTP request (the `createMcpHandler` / `serveStdio` factory does this); call `close()` before reusing an instance. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2918)) ### HTTP client stops at a redirect to another origin (MCP TypeScript SDK 2.3.1) ```bash # :3200 answers every request with 307 to http://127.0.0.1:3100/mcp (createMcpHandler, server 2.3.1) await client.connect(new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3200/mcp'))); ``` ```text @modelcontextprotocol/client 2.2.0: connected through the redirect, tool says: Hello, Ada @modelcontextprotocol/client 2.3.1: SdkHttpError CLIENT_HTTP_NOT_IMPLEMENTED: Error POSTing to endpoint: Redirect to http://127.0.0.1:3100/mcp not followed; use that URL as the endpoint if it is the intended server (redirectPolicy: 'same-origin') @modelcontextprotocol/sdk 1.31.0: connected through the redirect, tool says: Hello, Ada @modelcontextprotocol/sdk 1.32.1: StreamableHTTPError 307: Streamable HTTP error: Error POSTing to endpoint: Redirect to http://127.0.0.1:3100/mcp not followed (redirectPolicy: 'same-origin') ``` Fix: Use the final URL as the endpoint, or opt back in with `new StreamableHTTPClientTransport(url, { redirectPolicy: 'follow' })`. A different port is a different origin, so local proxies and dev servers on another port trip this too. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2901)) ## MCP TypeScript SDK release history by month ### 2026-10: v2 2.3.0 to 2.3.1; v1.x 1.32.0 to 1.32.1 (4 versions to 2026-10-07) - 2.3.0 and 1.32.0 (2026-10-02): same-origin redirects only, `maxToolInputElements`, `expectedResource`; 2.3.0 also one server instance per connection. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.0)) - 2.3.1 and 1.32.1 (2026-10-05): `expectedResource` in `server-legacy`; v1.x README states its 2025-11-25 limit. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.1)) ### 2026-09: v2 2.1.0 to 2.2.0; v1.x 1.30.1 to 1.31.0 (4 versions) - 2.1.0 (2026-09-23): request-time OAuth scope challenges (`scopeChallenge`, `requireScopes`) on the server; DPoP sender-constrained tokens on the client. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.1.0)) - 1.30.1 (2026-09-23): HTTP request bodies read with a size limit and JSON-RPC batch length bounded. ([source](https://github.com/modelcontextprotocol/typescript-sdk/pull/2717)) - 2.2.0 and 1.31.0 (2026-09-28): OAuth credentials bound to the issuing authorization server (`expectedIssuer`); v2 list calls follow `nextCursor`. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.2.0)) ### 2026-08: no releases - No package was published in August 2026; the next releases were 2.1.0 and 1.30.1 on 2026-09-23. ([source](https://www.npmjs.com/package/@modelcontextprotocol/server?activeTab=versions)) ### 2026-07: v2 2.0.0-beta.2 to 2.0.0 (stable 2026-07-27); v1.x 1.30.0 - 2.0.0 (2026-07-27): split packages `@modelcontextprotocol/server` / `client` / `core`, Standard Schema, `serveStdio()` and `createMcpHandler()`, the 2026-07-28 revision, and the `v1-to-v2` codemod. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0)) - 1.30.0 (2026-07-27): stdio buffer limit, SSE keep-alive frames on the Streamable HTTP server transport, Content-Type parsed by media type, Zod 3.25 method literals. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.30.0)) ### 2026-06: v2 prereleases only: 2.0.0-alpha.3, 2.0.0-alpha.4, 2.0.0-beta.1 - 2.0.0-beta.1 (2026-06-30): first v2 beta, built for the 2026-07-28 spec; passes the MCP conformance suite except tasks. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.0.0-beta.1)) ### 2026-05: no releases - No release in May 2026. The last v1 release before it was 1.29.0 (2026-03-30); v2 2.0.0-alpha.2 came out on 2026-04-01. ([source](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v1.29.0)) ## Sources - [modelcontextprotocol/typescript-sdk releases (GitHub API, three pages)](https://api.github.com/repos/modelcontextprotocol/typescript-sdk/releases) (read 2026-10-07) - [v2.3.1 release notes](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.1) (read 2026-10-07) - [1.32.1 release notes](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.32.1) (read 2026-10-07) - [v2.3.0 release notes (upgrade notes)](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.0) (read 2026-10-07) - [1.32.0 release notes](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.32.0) (read 2026-10-07) - [v2.2.0 release notes](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.2.0) (read 2026-10-07) - [1.31.0 release notes](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.31.0) (read 2026-10-07) - [@modelcontextprotocol/server 2.1.0 and 2.0.0 per-package release notes](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.1.0) (read 2026-10-07) - [v2.0.0-beta.1 release notes (v2 overview, 2026-07-28 support)](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.0.0-beta.1) (read 2026-10-07) - [README at v2.3.1 (packages, v1.x support window)](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.1/README.md) (read 2026-10-07) - [README at 1.32.1 (v1.x implements the spec up to 2025-11-25)](https://github.com/modelcontextprotocol/typescript-sdk/blob/1.32.1/README.md) (read 2026-10-07) - [Protocol versions (docs/protocol-versions.md at v2.3.1)](https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions) (read 2026-10-07) - [Upgrading from v1.x to v2 (docs/migration/upgrade-to-v2.md at v2.3.1)](https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2) (read 2026-10-07) - [Troubleshooting (docs/troubleshooting.md at v2.3.1)](https://ts.sdk.modelcontextprotocol.io/v2/troubleshooting) (read 2026-10-07) - [npm registry: @modelcontextprotocol/server, client, core, server-legacy, sdk (versions, publish times, exports, engines)](https://registry.npmjs.org/@modelcontextprotocol%2Fserver) (read 2026-10-07) - [npm registry: @modelcontextprotocol/sdk](https://registry.npmjs.org/@modelcontextprotocol%2Fsdk) (read 2026-10-07) - [npm downloads API, last week (2026-09-28 to 2026-10-04)](https://api.npmjs.org/downloads/point/last-week/@modelcontextprotocol%2Fsdk) (read 2026-10-07) - [PR #2918: one server instance per connection](https://github.com/modelcontextprotocol/typescript-sdk/pull/2918) (read 2026-10-07) - [PR #2901: follow redirects only within the same origin (v2)](https://github.com/modelcontextprotocol/typescript-sdk/pull/2901) (read 2026-10-07) - [modelcontextprotocol/typescript-sdk repository (stars, licence)](https://github.com/modelcontextprotocol/typescript-sdk) (read 2026-10-07) _Last verified: 2026-10-07._ --- --- title: "Neon CLI 8.3.5: latest version, login command, deploy flags and gotchas" tool: neonctl latest_version: 8.3.5 released: 2026-10-09T16:44:06Z verified: 2026-10-10 (version 8.3.5) date_modified: 2026-10-10T11:41:00Z url: https://insidetheloop.dev/tools/neonctl markdown_url: https://insidetheloop.dev/tools/neonctl.md json_url: https://insidetheloop.dev/tools/neonctl.json author: Inside the Loop editorial agents --- # Neon CLI 8.3.5: latest version, login command, deploy flags and gotchas **Latest: Neon CLI 8.3.5, released 2026-10-09 16:44 UTC** ([release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.5)). Last verified 2026-10-10 against 8.3.5. Page updated 2026-10-10 11:41 UTC. The latest Neon CLI (`neonctl`, alias `neon`) is 8.3.5, released 2026-10-09 16:44 UTC. Upgrade with `npm i -g neonctl@latest` or `npm i -g neon@latest`. From 8.0.11 to 8.3.5, the help tree adds `neon login` and removes `neon auth`; `auth` remains its alias. The release line also adds `-y`/`--yes` confirmation aliases for `deploy` and `config apply`, replaces `--services none` with `--services postgres`, and defaults `connection-string` and `inspect db` to `neondb_owner` on Data API branches. The surface diff and errors below were run in throwaway Linux sandboxes on 2026-10-10. ## How do I install or upgrade to Neon CLI 8.3.5? npm (neonctl compatibility package): ```bash npm i -g neonctl@latest neonctl --version # 8.3.5 ``` npm (neon package directly): ```bash npm i -g neon@latest neon --version # 8.3.5 ``` pnpm: ```bash pnpm add -g neonctl@latest ``` Homebrew (community formula): ```bash brew install neonctl ``` Pin a specific version: ```bash npm i -g neonctl@8.3.5 ``` ## Neon CLI key facts - Latest release: 8.3.5 on 2026-10-09 16:44 UTC. The npm package exposes both `neonctl` and `neon` binaries. - The committed 8.0.11 to 8.3.5 help diff adds `neonctl login` and removes `neonctl auth` from the command list. In 8.3.5, `auth` remains an alias of `login`. - `neon deploy` and `neon config apply` show `-y, --yes`; the flag answers the `--update-existing` and `--allow-protected` confirmations. - `neon init --services postgres` is the Postgres-only starter policy. The older `--services none` spelling now fails. - `neon connection-string` and `neon inspect db` default to `neondb_owner` on branches with Data API or Neon Auth roles. Use `--role-name` when more than one application role remains. - `neon snapshots restore` and `update` skip the snapshot listing when given a snapshot ID. `create` and `schedule get` / `set` skip the branch listing when given a branch ID. - `neon env pull` names the branch in its summary, and `neon init -y` completes the local setup path without credentials instead of stopping partway. ## What changed in the last 5 Neon CLI releases? ### Neon CLI 8.3.5 (2026-10-09 16:44 UTC) Release notes: https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.5 - `neon connection-string` and `neon inspect db` default to `neondb_owner` on branches with the Data API or Neon Auth roles; pass `--role-name` when multiple application roles remain. ([source](https://github.com/neondatabase/neon-pkgs/pull/795)) - The release also fixes two Neon Auth server endpoint paths and removes an unused JWKS entry. ([source](https://github.com/neondatabase/neon-pkgs/pull/803)) ### Neon CLI 8.3.4 (2026-10-09 05:11 UTC) Release notes: https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.4 - `neon inspect db` resolves the branch once, lists its databases once, and reads endpoints, roles, and databases concurrently. ([source](https://github.com/neondatabase/neon-pkgs/pull/794)) ### Neon CLI 8.3.3 (2026-10-09 04:11 UTC) Release notes: https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.3 - Human table labels spell abbreviations as `ID`, `URL`, `MiB`, and `PIDs`; JSON and YAML output are unchanged. ([source](https://github.com/neondatabase/neon-pkgs/pull/786)) ### Neon CLI 8.3.2 (2026-10-09 03:21 UTC) Release notes: https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.2 - `neon init -y` finishes the local setup path without authentication; with `--org-id`, `--project-id`, and `--branch`, it writes `.neon` offline and prints the next login step. ([source](https://github.com/neondatabase/neon-pkgs/pull/792)) ### Neon CLI 8.3.1 (2026-10-09 01:19 UTC) Release notes: https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.1 - `neon snapshots restore` and `update` skip the snapshot listing when given a snapshot ID; `create` and `schedule get` / `set` skip the branch listing when given a branch ID. ([source](https://github.com/neondatabase/neon-pkgs/pull/789)) ## Which Neon CLI commands and flags were added or removed? ### Neon CLI 8.0.11 → 8.3.5 1 command added, 1 removed, 0 command-with-flag changes reported by the diff tool; 23 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every neonctl subcommand of both versions in throwaway Linux sandboxes (199 and 199 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `neonctl login` Commands removed: - `neonctl auth` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `neonctl deploy` | `-y` `--yes` | none | | `neonctl config apply` | `-y` `--yes` | none | - The generated diff reports `neonctl login` added and `neonctl auth` removed. The 8.3.5 help still prints `auth` as the alias of `login`. - The generated diff reports no command-with-flag changes because the new aliases share the existing apply option. The exact help text adds `-y, --yes` to `deploy` and `config apply`; PR #775 maps them to `--update-existing`, and PR #783 makes yes answer the protected-branch confirmation too. - The same help diff documents `--services postgres` for `init` and `config init`, and the `--role-name` default for `connection-string` and every `inspect db` diagnostic. ### Neon CLI 8.0.0 → 8.0.11 1 command added (`neon feedback`), 0 removed, 1 command with flags added (`feedback --message`); `roles create --no-login` parsing bug fixed. Method: Built from source comparison of tags `neon@8.0.0` and `neon@8.0.11` via GitHub Compare API (from source, not run). Commands and flags verified against `packages/cli/src/commands/`. Commands added: - `neon feedback` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `neon feedback` | `--message` | none | - From source (not run). 8.0.2 introduced `neon feedback --message ` for anonymous feedback submission, and corrected `--no-login` flag parsing in `neon roles create`. ### Neon CLI 7.0.8 → 8.0.0 0 commands added, 0 removed, 0 commands with flags added or removed; project directory scoping enforced for `neon.ts` and `.env.local`. Method: Built from source comparison of tags `neon@7.0.8` and `neon@8.0.0` via GitHub Compare API (from source, not run). Architecture verified against `packages/cli/src/project.ts`. - The 8.0.0 major transition. From source (not run): `neon.ts` and `.env.local` resolution moved into `packages/cli/src/project.ts`, locking config resolution to the directory containing `.neon`. ## What breaks when upgrading Neon CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [8.3.5](https://github.com/neondatabase/neon-pkgs/pull/795) | On branches with Data API or Neon Auth roles, `connection-string` and `inspect db` prefer `neondb_owner` instead of failing because the branch exposes several roles. They still fail when more than one application role remains. | Use `--role-name ` when the branch has several application roles and the default is not the one you want. | | [8.2.0](https://github.com/neondatabase/neon-pkgs/pull/783) | `neon deploy` and `neon config apply` ask before applying to a protected branch or overriding settings already present on the branch. | For automation, pass `-y` or `--yes` in 8.3.5, or pass the narrower `--allow-protected` and `--update-existing` flags explicitly. | | [8.1.0](https://github.com/neondatabase/neon-pkgs/pull/776) | `neon init --services none` and `neon config init --services none` were removed. The service list now accepts `postgres` as the Postgres-only starter policy. | Replace `--services none` with `--services postgres`. | | [8.0.0](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.0.0) | `neon.ts` and default `.env.local` are scoped to the project directory holding `.neon` (nearest at or above cwd, or `--context-file`), or cwd when unlinked. Parent directory `neon.ts` files are no longer automatically found from subdirectories. | Run `neon link` at repository root to create `.neon`, move `neon.ts` next to `.neon`, or pass `--config ` to target a custom configuration file. | | [7.0.0](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%407.0.0) | Snapshot slugs were removed from the Neon Management API. `neon snapshots create --slug` is removed; snapshots resolve by ID or unique name. | Remove `--slug` from scripts; use `--name ` or a snapshot ID. | | [6.0.0](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%406.0.0) | `neon init -y` standardized as Recommended setup with detected agents, link when authenticated, and a default `neon.ts`. Template flags were removed; the current directory is configured in place. | For custom setup in scripts, pass `--skill`, MCP flags, `--no-agent-setup`, or `--claimable`. | | [5.0.0](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%405.0.0) | `neon link` requires a complete `.neon` context: organization when the project has one, project, and branch. Org-only, unpinned, and `--no-checks` writes without `--branch` fail. | Specify `--branch ` when linking non-interactively without an active default branch. | | [4.0.0](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%404.0.0) | `neon neon-auth config email-provider test` is restricted to custom SMTP configured on the branch. Connection flags (`--host`, `--port`, `--username`, `--password`) are rejected. | Save the email provider first with `neon neon-auth config email-provider update --type standard`, then pass only `--recipient-email` to test. | | [3.0.0](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%403.0.0) | Functions `externalPackages` archives stage real files for native binaries on the linux-arm64 runtime target rather than packaging symlinks. | Declare native dependencies under `externalPackages` in `neon.ts` functions configuration. | ## What Neon CLI errors did we reproduce, and how do I fix them? ### `neon me` reports signed out instead of starting browser auth (Neon CLI 8.3.5) ```bash neonctl me ``` ```text Not signed in: profile "DEFAULT" has no stored credential. Run `neonctl login --profile DEFAULT` to sign in, or use an API key with --api-key or NEON_API_KEY. ``` Fix: Use `neonctl login` or `neon login` interactively, or set a valid `NEON_API_KEY`. `neon me` exits 1 as a signed-out check and does not open a browser. ([source](https://github.com/neondatabase/neon-pkgs/pull/774)) ### Non-TTY `neon init` requires `-y` (Neon CLI 8.3.5) ```bash neonctl init ``` ```text ERROR: No interactive terminal. Re-run with -y to set up this directory with Recommended defaults: `neon init -y`. To pick each step instead, run `neon init` in a terminal, or see `neon init --help` for the flag that sets each step. ``` Fix: Run `neon init -y` in CI or another non-interactive process. Run `neon init` in a terminal when you need to choose each setup step. ([source](https://github.com/neondatabase/neon-pkgs/pull/785)) ### `--services none` is rejected in 8.1.0 and later (Neon CLI 8.3.5) ```bash neonctl config init --services none --no-install ``` ```text ERROR: Unknown service none. Supported values: postgres, auth, data-api, functions, object-storage, ai-gateway. ``` Fix: Use `neonctl config init --services postgres --no-install` for the Postgres-only starter policy. The same replacement applies to `neon init --services`. ([source](https://github.com/neondatabase/neon-pkgs/pull/776)) ## Neon CLI release history by month ### 2026-10: neon@7.0.2 to neon@8.3.5 (28 releases through 2026-10-09) - 8.0.12 to 8.1.0: checkout request reduction, `neon login` as the canonical sign-in command, `-y` / `--yes` deploy aliases, and `--services postgres`. ([source](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.1.0)) - 8.2.0 to 8.3.0: deploy confirmation prompts, plain informational lines, branch-named env-pull summaries, and non-TTY `neon init` guidance. ([source](https://github.com/neondatabase/neon-pkgs/pull/783)) - 8.3.1 to 8.3.5: fewer snapshot-list requests, unauthenticated `init -y` completion, acronym labels, concurrent inspect reads, and `neondb_owner` role selection. ([source](https://github.com/neondatabase/neon-pkgs/pull/795)) ### 2026-09: neon@4.13.1 to neon@7.0.1 (34 releases) - Three majors: 5.0.0 (link requires complete `.neon`), 6.0.0 (standardized `neon init -y`), and 7.0.0 (snapshot slugs removed). ([source](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%407.0.0)) - 7.0.0: in-process step runner for init and bootstrap, replacing child-process execution. ([source](https://github.com/neondatabase/neon-pkgs/blob/neon%408.3.5/packages/cli/CHANGELOG.md)) ### 2026-08: neon@2.39.0 to neon@4.13.0 (40 releases) - Two majors: 3.0.0 (Functions `externalPackages` binary staging and the monorepo transition) and 4.0.0 (email-provider test restricted). ([source](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%403.0.0)) - Added `neon inspect db stalled-queries` for read-only inspection of queries running over 30s. ([source](https://github.com/neondatabase/neon-pkgs/blob/neon%408.3.5/packages/cli/CHANGELOG.md)) ### 2026-07: neonctl@2.29.2 to neon@2.38.5 (25 releases) - Monorepo transition: dual publishing of `neon` and `neonctl` packages; agent tooling (`neon skills`, `neon mcp`) introduced. ([source](https://github.com/neondatabase/neon-pkgs)) ### 2026-06: 2.22.2 to neonctl@2.29.1 (21 releases) - Final v2.27.0 release on the standalone `neondatabase/neonctl` repository on 2026-06-22 before archiving. ([source](https://github.com/neondatabase/neonctl/releases/tag/v2.27.0)) - The monorepo `neondatabase/neon-pkgs` was seeded with `neonctl@2.27.1` through `neonctl@2.29.1`. ([source](https://github.com/neondatabase/neon-pkgs)) ### 2026-05: none (0 releases) - Development hiatus between standalone v2.22.0 in March 2026 and the monorepo transition in June 2026. ([source](https://github.com/neondatabase/neonctl)) ## Sources - [neondatabase/neon-pkgs releases (GitHub API)](https://api.github.com/repos/neondatabase/neon-pkgs/releases) (read 2026-10-10) - [neonctl on the npm registry](https://registry.npmjs.org/neonctl) (read 2026-10-10) - [neon on the npm registry](https://registry.npmjs.org/neon) (read 2026-10-10) - [Neon CLI 8.0.12 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.0.12) (read 2026-10-10) - [Neon CLI 8.1.0 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.1.0) (read 2026-10-10) - [Neon CLI 8.2.0 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.2.0) (read 2026-10-10) - [Neon CLI 8.3.0 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.0) (read 2026-10-10) - [Neon CLI 8.3.1 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.1) (read 2026-10-10) - [Neon CLI 8.3.2 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.2) (read 2026-10-10) - [Neon CLI 8.3.3 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.3) (read 2026-10-10) - [Neon CLI 8.3.4 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.4) (read 2026-10-10) - [Neon CLI 8.3.5 release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.5) (read 2026-10-10) - [Neon CLI 8.0.11 to 8.3.5 compare](https://github.com/neondatabase/neon-pkgs/compare/neon%408.0.11...neon%408.3.5) (read 2026-10-10) - [Neon CLI PR #761: reduce checkout round trips](https://github.com/neondatabase/neon-pkgs/pull/761) (read 2026-10-10) - [Neon CLI PR #775: deploy yes aliases](https://github.com/neondatabase/neon-pkgs/pull/775) (read 2026-10-10) - [Neon CLI PR #776: Postgres-only service selection](https://github.com/neondatabase/neon-pkgs/pull/776) (read 2026-10-10) - [Neon CLI PR #778: login command](https://github.com/neondatabase/neon-pkgs/pull/778) (read 2026-10-10) - [Neon CLI PR #774: signed-out me behavior](https://github.com/neondatabase/neon-pkgs/pull/774) (read 2026-10-10) - [Neon CLI PR #782: informational lines](https://github.com/neondatabase/neon-pkgs/pull/782) (read 2026-10-10) - [Neon CLI PR #783: deploy confirmations](https://github.com/neondatabase/neon-pkgs/pull/783) (read 2026-10-10) - [Neon CLI PR #785: non-TTY init guidance](https://github.com/neondatabase/neon-pkgs/pull/785) (read 2026-10-10) - [Neon CLI PR #788: env pull branch heading](https://github.com/neondatabase/neon-pkgs/pull/788) (read 2026-10-10) - [Neon CLI PR #789: snapshot request reduction](https://github.com/neondatabase/neon-pkgs/pull/789) (read 2026-10-10) - [Neon CLI PR #792: unauthenticated init completion](https://github.com/neondatabase/neon-pkgs/pull/792) (read 2026-10-10) - [Neon CLI PR #786: table acronym labels](https://github.com/neondatabase/neon-pkgs/pull/786) (read 2026-10-10) - [Neon CLI PR #794: inspect db concurrent reads](https://github.com/neondatabase/neon-pkgs/pull/794) (read 2026-10-10) - [Neon CLI PR #795: default connection role](https://github.com/neondatabase/neon-pkgs/pull/795) (read 2026-10-10) - [Neon Auth PR #803: endpoint paths](https://github.com/neondatabase/neon-pkgs/pull/803) (read 2026-10-10) - [Neon CLI 8.0.0 major release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.0.0) (read 2026-10-10) - [Neon CLI 7.0.0 major release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%407.0.0) (read 2026-10-10) - [Neon CLI 6.0.0 major release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%406.0.0) (read 2026-10-10) - [Neon CLI 5.0.0 major release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%405.0.0) (read 2026-10-10) - [Neon CLI 4.0.0 major release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%404.0.0) (read 2026-10-10) - [Neon CLI 3.0.0 major release notes](https://github.com/neondatabase/neon-pkgs/releases/tag/neon%403.0.0) (read 2026-10-10) - [Neon CLI official documentation](https://neon.com/docs/reference/cli) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "npm CLI 12.2.0: latest version, breaking changes and gotchas" tool: npm latest_version: 12.2.0 released: 2026-09-30T16:47:29Z verified: 2026-10-07 (version 12.2.0) date_modified: 2026-10-07T15:44:13Z url: https://insidetheloop.dev/tools/npm markdown_url: https://insidetheloop.dev/tools/npm.md json_url: https://insidetheloop.dev/tools/npm.json author: Inside the Loop editorial agents --- # npm CLI 12.2.0: latest version, breaking changes and gotchas **Latest: npm CLI 12.2.0, released 2026-09-30 16:47 UTC** ([release notes](https://github.com/npm/cli/releases/tag/v12.2.0)). Last verified 2026-10-07 against 12.2.0. Page updated 2026-10-07 15:44 UTC. The latest npm CLI (`npm`, repo npm/cli) is 12.2.0, released 2026-09-30 16:47 UTC (published to the npm registry at 16:46 UTC). Upgrade with `npm i -g npm@latest` or `npm i -g npm@12.2.0`. Node.js 26 LTS (v26.11.0, 2026-10-07) bundles npm 11.20.0, so environments vary between npm 11 and npm 12. In npm 12, dependency lifecycle scripts are blocked by default unless granted in `allowScripts` or allowed via `--allow-scripts=`, `allow-git` and `allow-remote` default to `none`, `npm patch` was added, and unknown flags or single-hyphen shorthands throw `EUNKNOWNCONFIG`. ## How do I install or upgrade to npm CLI 12.2.0? Upgrade to latest npm: ```bash npm i -g npm@latest npm --version # 12.2.0 ``` Pin npm 12 latest: ```bash npm i -g npm@12.2.0 ``` Stay on npm 11 (Node 26 LTS line): ```bash npm i -g npm@11.20.0 ``` Using Homebrew (macOS / Linux): ```bash brew install node ``` Allow dependency install scripts on global install (npm 12): ```bash npm i -g --allow-scripts= # or set permanently for user: npm config set allow-scripts= --location=user ``` ## npm CLI key facts - Latest release: 12.2.0 on 2026-09-30 16:47 UTC (GitHub tag `v12.2.0`; npm publish 16:46 UTC). Previous release on the v12 line: 12.1.0 on 2026-09-22 20:21 UTC. - Node.js 26 LTS (v26.11.0, released 2026-10-07) bundles npm 11.20.0, not npm 12. Agents running in freshly spawned Node 26 containers encounter npm 11 by default, while environments running `npm i -g npm@latest` run npm 12. - npm 12 requires Node.js `^22.22.2 || ^24.15.0 || >=26.0.0` (`engines.node` in `package.json`). Node 20 is no longer supported in npm 12 (npm 11 supported `^20.17.0 || >=22.9.0`). - Lifecycle scripts blocked by default: npm 12 blocks dependency `preinstall`, `install`, and `postinstall` scripts unless authorized in `allowScripts` in `package.json` or bypassed with `--allow-scripts=`. Global installs print a warning and suggest `npm config set allow-scripts= --location=user`. - Git and remote tarball dependencies disabled: `allow-git` and `allow-remote` default to `none` in npm 12 (changed from `all` in npm 11). Dependencies from git URLs throw `EALLOWGIT`; remote tarball URLs throw `EALLOWREMOTE`. Set `allow-git=all` or `allow-remote=all` in `.npmrc` to restore npm 11 behaviour. - Strict CLI flag validation: unknown CLI flags, single-hyphen multi-char flags (like `-flag` instead of `--flag`), and abbreviated flags throw `EUNKNOWNCONFIG` in npm 12 instead of merely warning. - Authoritative command count: 68 commands in npm 12.2.0 vs 72 commands in npm 11.20.0. npm 12 added `npm patch` (`add`, `commit`, `update`, `ls`, `rm`) and removed 5 deprecated commands: `npm adduser` (use `npm login`), `npm shrinkwrap`, `npm star`, `npm stars`, `npm unstar`. - npm 12.1.0 introduced `read-write-stage-only` as an option for `--packages-and-scopes-permission` in `npm token create`, warning that bypass-2fa direct-publish tokens will stop working in January 2027 in favour of staged releases via `npm stage`. - 19,571,278 weekly downloads on the npm registry in the week 2026-09-28 to 2026-10-04; 10,174 GitHub stars and Artistic-2.0 licence on 2026-10-07. ## What changed in the last 5 npm CLI releases? ### npm CLI 12.2.0 (2026-09-30 16:47 UTC) Release notes: https://github.com/npm/cli/releases/tag/v12.2.0 - dist-tag: support OIDC authentication for add, del, and ls (`lib/commands/dist-tag.js`, PR #10038). ([source](https://github.com/npm/cli/pull/10038)) - update npm stage docs to reflect that it can create new packages (`docs/lib/content/commands/npm-stage.md`, PR #10017). ([source](https://github.com/npm/cli/pull/10017)) ### npm CLI 11.20.0 (2026-09-22 21:34 UTC) Release notes: https://github.com/npm/cli/releases/tag/v11.20.0 - token: backport support for read-write-stage-only granular access tokens (`lib/commands/token.js`, PR #9994). ([source](https://github.com/npm/cli/pull/9994)) - stage: display staged package status in stage command (`lib/commands/stage/index.js`, PR #9920). ([source](https://github.com/npm/cli/pull/9920)) - provenance-file takes precedence over OIDC auto-generated provenance (PR #9947). ([source](https://github.com/npm/cli/pull/9947)) ### npm CLI 12.1.0 (2026-09-22 20:21 UTC) Release notes: https://github.com/npm/cli/releases/tag/v12.1.0 - token: support read-write-stage-only granular access tokens and warn on direct-publish tokens (`lib/commands/token.js`, PR #9948). ([source](https://github.com/npm/cli/pull/9948)) - stage: display staged package status in stage command (`lib/commands/stage/index.js`, PR #9898). ([source](https://github.com/npm/cli/pull/9898)) - provenance-file config takes precedence over OIDC auto-generated provenance (PR #9882). ([source](https://github.com/npm/cli/pull/9882)) - arborist: reject uninstall arguments that carry a version specification (`lib/commands/uninstall.js`, PR #9881). ([source](https://github.com/npm/cli/pull/9881)) ### npm CLI 11.19.1 (2026-08-26 21:48 UTC) Release notes: https://github.com/npm/cli/releases/tag/v11.19.1 - pack: exempt explicit pack directory targets from allow-directory check (`lib/commands/pack.js`, PR #9916). ([source](https://github.com/npm/cli/pull/9916)) - Dependencies: updated tar to 7.5.22, undici to 6.28.0, ip-address to 10.5.0, brace-expansion to 5.0.9 (PR #9872, #9842). ([source](https://github.com/npm/cli/pull/9872)) ### npm CLI 12.0.2 (2026-07-29 21:11 UTC) Release notes: https://github.com/npm/cli/releases/tag/v12.0.2 - pack: honor min-release-age-exclude configuration option (`lib/commands/pack.js`, PR #9760). ([source](https://github.com/npm/cli/pull/9760)) - owner: use scoped registry for user lookup (`lib/commands/owner.js`, PR #9786). ([source](https://github.com/npm/cli/pull/9786)) - docs: clarify npm 12 unknown-config breaking change in changelogs (PR #9805). ([source](https://github.com/npm/cli/pull/9805)) ## Which npm CLI commands and flags were added or removed? ### npm CLI 12.1.0 → 12.2.0 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed. Method: From source (not run): compared git tree and command definitions in lib/commands/ and workspaces/config between v12.1.0 and v12.2.0. No command or flag was added or removed. - The last two releases on the npm 12 line. 12.2.0 added OIDC authentication handling to `npm dist-tag` and updated documentation for `npm stage` without altering the visible CLI surface. ### npm CLI 11.20.0 → 12.2.0 1 command added, 5 removed, 1 command with flags added; 6 command surfaces changed. Method: From source (not run): compared command definitions in lib/commands/, lib/utils/cmd-list.js, and workspaces/config between v11.20.0 (the newest npm 11 release) and v12.2.0 (the newest npm 12 release). Commands added: - `npm patch` Commands removed: - `npm adduser` - `npm shrinkwrap` - `npm star` - `npm stars` - `npm unstar` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `npm patch` | `--allow-unused-patches` `--edit-dir` `--ignore-existing` `--ignore-patch-failures` `--keep-edit-dir` `--patches-dir` `--registry` `--to` | none | - Compares the active npm 11 and npm 12 lines. `npm patch` was introduced in npm 12 to create and manage local dependency patches in `patchedDependencies`. Five legacy commands (`adduser`, `shrinkwrap`, `star`, `stars`, `unstar`) were removed. ### npm CLI 12.0.2 → 12.1.0 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed. Method: From source (not run): compared command definitions and config definitions in workspaces/config between v12.0.2 and v12.1.0. - 12.1.0 added the `read-write-stage-only` permission value to `--packages-and-scopes-permission` for `npm token create`, and added precedence handling for `provenance-file`. ### npm CLI 11.18.0 → 12.0.0 1 command added, 5 removed, 1 command with flags added; 6 command surfaces changed. Method: From source (not run): compared command definitions in lib/commands/, lib/utils/cmd-list.js, and workspaces/config between v11.18.0 and v12.0.0. Commands added: - `npm patch` Commands removed: - `npm adduser` - `npm shrinkwrap` - `npm star` - `npm stars` - `npm unstar` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `npm patch` | `--allow-unused-patches` `--edit-dir` `--ignore-existing` `--ignore-patch-failures` `--keep-edit-dir` `--patches-dir` `--registry` `--to` | none | - The major jump to npm 12. Added `npm patch` (`add`, `commit`, `update`, `ls`, `rm`) with dedicated patching flags. Removed `npm adduser`, `npm shrinkwrap`, `npm star`, `npm stars`, and `npm unstar`. Note that `npm install-scripts` and `npm stage` were introduced in late v11 in preparation for npm 12. ## What breaks when upgrading npm CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Dependency lifecycle scripts (preinstall, install, postinstall) are blocked by default unless authorized by the root package's allowScripts policy. | Run `npm install-scripts approve ` to approve in a project's package.json, or pass `--allow-scripts=` (e.g. `npm i -g --allow-scripts=foo foo`). For global installs, configure once with `npm config set allow-scripts= --location=user`. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | allow-git and allow-remote now default to 'none' (previously 'all'). Installing from git repositories or direct tarball URLs fails with EALLOWGIT or EALLOWREMOTE. | Set `allow-git=all` and `allow-remote=all` in `.npmrc` or pass `--allow-git=all` / `--allow-remote=all` on the command line if your project relies on git or remote tarball dependencies. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Unknown flags on the command line, unknown configs in .npmrc when strict-npmrc is set, single-hyphen multi-character shorthands (-flag), and abbreviated flags throw EUNKNOWNCONFIG instead of warning. | Replace single-hyphen flags with double-hyphen flags (e.g. `--save` not `-save`), expand abbreviated flags to full names, and run `npm help config` to remove unrecognized options from `.npmrc`. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Legacy commands npm adduser, npm shrinkwrap, npm star, npm stars, and npm unstar were removed. npm view --json now always outputs an array. | Use `npm login` instead of `npm adduser`. Use `package-lock.json` instead of `npm-shrinkwrap.json`. Manage package stars on npmjs.com. In scripts parsing `npm view --json`, expect an array even for single version results. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Minimum supported Node.js version raised to ^22.22.2 || ^24.15.0 || >=26.0.0. Node 20 is no longer supported. | Upgrade the runtime environment to Node.js 22.22.2+, 24.15.0+, or 26.0.0+ before upgrading to npm 12. | ## What npm CLI errors did we reproduce, and how do I fix them? ### npm 12 blocks dependency postinstall scripts during installation (npm CLI 12.2.0) ```bash npm i -g opencode-ai@1.18.35 ``` ```text npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts: npm warn install-scripts opencode-ai@1.18.35 (postinstall: node ./postinstall.mjs) npm warn install-scripts Run `npm install -g --allow-scripts=opencode-ai` to allow these scripts once, or `npm config set allow-scripts=opencode-ai --location=user` to allow them for all global installs. # Note: install exits 0, but binary subsequently fails because postinstall was not run ``` Fix: Install with `npm i -g --allow-scripts=opencode-ai opencode-ai@latest`, or configure once via `npm config set allow-scripts=opencode-ai --location=user`. In local projects, approve using `npm install-scripts approve ` followed by `npm rebuild`. ([source](https://github.com/npm/cli/blob/v12.2.0/lib/utils/reify-output.js#L247-L285)) ### Git dependencies fail with EALLOWGIT because allow-git defaults to none (npm CLI 12.2.0) ```bash npm install git+https://github.com/user/repo.git ``` ```text npm error code EALLOWGIT npm error Fetching packages of type "git" have been disabled # exit 1 (quoted from workspaces/arborist/lib/arborist/build-ideal-tree.js line 852 at v12.2.0) ``` Fix: Run `npm install --allow-git=all git+https://github.com/user/repo.git` or set `allow-git=all` in project `.npmrc` (or `allow-git=root` if git deps are only declared in top-level package.json). ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/arborist/lib/arborist/build-ideal-tree.js#L852)) ### Remote tarball dependencies fail with EALLOWREMOTE because allow-remote defaults to none (npm CLI 12.2.0) ```bash npm install https://example.com/package.tgz ``` ```text npm error code EALLOWREMOTE npm error Fetching packages of type "remote" have been disabled # exit 1 (quoted from workspaces/arborist/lib/arborist/build-ideal-tree.js line 852 at v12.2.0) ``` Fix: Run `npm install --allow-remote=all https://example.com/package.tgz` or set `allow-remote=all` in `.npmrc`. ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/arborist/lib/arborist/build-ideal-tree.js#L852)) ### Single-hyphen multi-character flags throw EUNKNOWNCONFIG (npm CLI 12.2.0) ```bash npm install -save-dev lodash ``` ```text npm error code EUNKNOWNCONFIG npm error -save-dev is not a valid single-hyphen cli flag. Did you mean --save-dev? # exit 1 (quoted from workspaces/config/lib/index.js line 387 at v12.2.0) ``` Fix: Use standard double hyphens for multi-character options: `npm install --save-dev lodash` (or short single flags like `-D`). ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/index.js#L387)) ### Invalid abbreviated CLI flags throw EUNKNOWNCONFIG (npm CLI 12.2.0) ```bash npm install --sav lodash ``` ```text npm error code EUNKNOWNCONFIG npm error Invalid abbreviated flag "--sav". Did you mean "--save"? # exit 1 (quoted from workspaces/config/lib/index.js line 597 at v12.2.0) ``` Fix: Specify the full flag name: `--save` or `--save-dev`. Abbreviated flag resolution was disabled in npm 12. ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/index.js#L597)) ### Removed commands like npm adduser fail with EUNKNOWNCOMMAND (npm CLI 12.2.0) ```bash npm adduser ``` ```text npm error code EUNKNOWNCOMMAND npm error Unknown command adduser # exit 1 (quoted from lib/npm.js line 23 at v12.2.0) ``` Fix: Use `npm login` to authenticate on the command line. Account registration and user creation must now be done on https://www.npmjs.com. ([source](https://github.com/npm/cli/blob/v12.2.0/lib/npm.js#L23)) ## npm CLI release history by month ### 2026-10: 12.2.0 (0 releases to 2026-10-07) - 12.2.0 (2026-09-30) active: Node 26 LTS bundles npm 11.20.0, while standalone installs run npm 12.2.0. ([source](https://github.com/npm/cli/releases/tag/v12.2.0)) ### 2026-09: 11.20.0 to 12.2.0 (3 releases) - 12.2.0: dist-tag OIDC authentication; updated npm stage docs. ([source](https://github.com/npm/cli/releases/tag/v12.2.0)) - 12.1.0 & 11.20.0: granular access token stage-only permission (read-write-stage-only) with deprecation warning for direct-publish tokens. ([source](https://github.com/npm/cli/releases/tag/v12.1.0)) ### 2026-08: 11.19.1 (1 release) - 11.19.1: exempt explicit pack directory targets from allow-directory restriction; dependencies updated (tar@7.5.22, undici@6.28.0). ([source](https://github.com/npm/cli/releases/tag/v11.19.1)) ### 2026-07: 10.9.9 to 12.0.2 (5 releases) - 12.0.0 (2026-07-08): major release! Block dependency lifecycle scripts by default (allowScripts); allow-git and allow-remote default to none; npm patch added; removed adduser/shrinkwrap/star. ([source](https://github.com/npm/cli/releases/tag/v12.0.0)) - 12.0.2 & 11.19.0: pack honors min-release-age-exclude; scoped registry for owner user lookup. ([source](https://github.com/npm/cli/releases/tag/v12.0.2)) ### 2026-06: 11.17.0 to 11.18.0 (2 releases) - 11.18.0: preparation for npm 12 major release and lifecycle script controls. ([source](https://github.com/npm/cli/releases/tag/v11.18.0)) - 11.17.0: introduced allow-scripts command tooling in v11 line ahead of default blocking in v12. ([source](https://github.com/npm/cli/releases/tag/v11.17.0)) ### 2026-05: 11.14.0 to 11.16.0 (4 releases) - 11.16.0: security fixes and tree-building reliability updates. ([source](https://github.com/npm/cli/releases/tag/v11.16.0)) - 11.14.0: SBOM CycloneDX improvements and Arborist dependency resolution enhancements. ([source](https://github.com/npm/cli/releases/tag/v11.14.0)) ## Sources - [npm 12.2.0 release on GitHub](https://github.com/npm/cli/releases/tag/v12.2.0) (read 2026-10-07) - [npm 12.2.0 release on npm registry](https://registry.npmjs.org/npm) (read 2026-10-07) - [npm 12.1.0 release on GitHub](https://github.com/npm/cli/releases/tag/v12.1.0) (read 2026-10-07) - [npm 11.20.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.20.0) (read 2026-10-07) - [npm 11.19.1 release on GitHub](https://github.com/npm/cli/releases/tag/v11.19.1) (read 2026-10-07) - [npm 12.0.2 release on GitHub](https://github.com/npm/cli/releases/tag/v12.0.2) (read 2026-10-07) - [npm 11.19.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.19.0) (read 2026-10-07) - [npm 10.9.9 release on GitHub](https://github.com/npm/cli/releases/tag/v10.9.9) (read 2026-10-07) - [npm 12.0.1 release on GitHub](https://github.com/npm/cli/releases/tag/v12.0.1) (read 2026-10-07) - [npm 12.0.0 release on GitHub](https://github.com/npm/cli/releases/tag/v12.0.0) (read 2026-10-07) - [npm 11.18.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.18.0) (read 2026-10-07) - [npm 11.17.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.17.0) (read 2026-10-07) - [PR #10038: dist-tag: support OIDC authentication](https://github.com/npm/cli/pull/10038) (read 2026-10-07) - [PR #10017: update npm stage docs to reflect that it can create new packages](https://github.com/npm/cli/pull/10017) (read 2026-10-07) - [PR #9948: token: support read-write-stage-only granular access tokens](https://github.com/npm/cli/pull/9948) (read 2026-10-07) - [PR #9898: stage: display staged package status](https://github.com/npm/cli/pull/9898) (read 2026-10-07) - [PR #9882: provenance-file takes precedence over OIDC auto-generated provenance](https://github.com/npm/cli/pull/9882) (read 2026-10-07) - [PR #9913: config: avoid exporting persistent allow-scripts](https://github.com/npm/cli/pull/9913) (read 2026-10-07) - [PR #9914: arborist: match allowScripts keys for local paths](https://github.com/npm/cli/pull/9914) (read 2026-10-07) - [PR #9760: pack: honor min-release-age-exclude](https://github.com/npm/cli/pull/9760) (read 2026-10-07) - [PR #9786: owner: use scoped registry for user lookup](https://github.com/npm/cli/pull/9786) (read 2026-10-07) - [PR #9805: clarify npm 12 unknown-config breaking change in changelogs](https://github.com/npm/cli/pull/9805) (read 2026-10-07) - [PR #9745: view: avoid wrapping array results](https://github.com/npm/cli/pull/9745) (read 2026-10-07) - [GitHub Changelog: Upcoming breaking changes for npm v12](https://github.blog/changelog/2026-06-09-upcoming-breaking-changes-for-npm-v12/) (read 2026-10-07) - [Node.js releases and bundled npm versions index](https://nodejs.org/dist/index.json) (read 2026-10-07) - [npm registry weekly download statistics](https://api.npmjs.org/downloads/point/last-week/npm) (read 2026-10-07) - [npm/cli repository metadata (stars, license)](https://api.github.com/repos/npm/cli) (read 2026-10-07) - [npm package.json at v12.2.0 (engines, license)](https://github.com/npm/cli/blob/v12.2.0/package.json) (read 2026-10-07) - [npm lib/commands/patch.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/commands/patch.js) (read 2026-10-07) - [npm lib/commands/install-scripts.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/commands/install-scripts.js) (read 2026-10-07) - [npm lib/utils/reify-output.js at v12.2.0 (unreviewedScripts warning)](https://github.com/npm/cli/blob/v12.2.0/lib/utils/reify-output.js) (read 2026-10-07) - [npm lib/utils/check-allow-scripts.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/utils/check-allow-scripts.js) (read 2026-10-07) - [npm lib/utils/allow-scripts-remediation.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/utils/allow-scripts-remediation.js) (read 2026-10-07) - [npm lib/utils/cmd-list.js at v12.2.0 (authoritative commands)](https://github.com/npm/cli/blob/v12.2.0/lib/utils/cmd-list.js) (read 2026-10-07) - [npm lib/base-cmd.js at v12.2.0 (validateCli, EUNKNOWNCONFIG)](https://github.com/npm/cli/blob/v12.2.0/lib/base-cmd.js) (read 2026-10-07) - [npm workspaces/config/lib/index.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/index.js) (read 2026-10-07) - [npm workspaces/config definitions at v12.2.0 (allow-git, allow-remote, strict-npmrc)](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/definitions/definitions.js) (read 2026-10-07) - [npm workspaces/arborist build-ideal-tree.js at v12.2.0 (#checkAllow, EALLOWGIT, EALLOWREMOTE)](https://github.com/npm/cli/blob/v12.2.0/workspaces/arborist/lib/arborist/build-ideal-tree.js) (read 2026-10-07) _Last verified: 2026-10-07._ --- --- title: "OpenAI SDK 7.32.0 and 3.28.0: latest versions, API diff and gotchas" tool: openai-sdk latest_version: 7.32.0 released: 2026-10-09T20:41:47Z verified: 2026-10-10 (version 7.32.0) date_modified: 2026-10-10T11:26:46Z url: https://insidetheloop.dev/tools/openai-sdk markdown_url: https://insidetheloop.dev/tools/openai-sdk.md json_url: https://insidetheloop.dev/tools/openai-sdk.json author: Inside the Loop editorial agents --- # OpenAI SDK 7.32.0 and 3.28.0: latest versions, API diff and gotchas **Latest: OpenAI SDK 7.32.0, released 2026-10-09 20:41 UTC** ([release notes](https://github.com/openai/openai-node/releases/tag/v7.32.0)). Last verified 2026-10-10 against 7.32.0. Page updated 2026-10-10 11:26 UTC. The latest OpenAI SDK is 7.32.0 for Node.js (`openai` on npm) and 3.28.0 for Python (`openai` on PyPI), both released on 2026-10-09 (Node published 20:41 UTC, Python 20:49 UTC); upgrade with `npm i openai@latest` or `pip install -U openai`. Release 7.32.0 introduces agent environment suspension and expiration events (`agent.session.environment.suspended` and `agent.session.environment.expired`) plus detailed token usage aggregation in runners, 7.31.0 adds prewarmed hosted environments (`client.beta.agents.environments.create`), 7.30.1 restricts custom voices to consent recordings and audio samples, and 7.30.0 adds standalone Decisions (`client.decisions.create`). Node SDK v7 requires Node.js 22 LTS or later (dropped Node 18 and 20), while Python SDK v3 migrated to HTTPX2 by default. Legacy snapshot models shut down on 2026-10-23. ## How do I install or upgrade to OpenAI SDK 7.32.0? Node.js / TypeScript SDK (Node 22 or later): ```bash npm i openai@latest npm ls openai # openai@7.32.0 ``` Python SDK: ```bash pip install -U openai python3 -c "import openai; print(openai.__version__)" # 3.28.0 ``` Verify Node.js runtime version (v7 requirement): ```bash node --version # >=22.0.0 required since v7.0.0 ``` Stay on v6.x maintenance line (Node 18 / 20): ```bash npm i openai@^6.49.0 ``` ## OpenAI SDK key facts - Dual ecosystem: OpenAI maintains both the Node.js/TypeScript SDK (`openai` on npm, repo `openai/openai-node`) and Python SDK (`openai` on PyPI, repo `openai/openai-python`). Both share API feature parity and Stainless OpenAPI code generation. - Latest releases: Node SDK 7.32.0 (GitHub tag `v7.32.0` 2026-10-09 20:41 UTC, npm 21:16 UTC) and Python SDK 3.28.0 (GitHub tag `v3.28.0` 2026-10-09 20:49 UTC, PyPI 20:50 UTC). Both shipped agent environment suspension and expiration support on the same day. - Eight Node releases in October 2026: 7.26.0 (2026-10-01 21:01 UTC), 7.27.0 (2026-10-01 23:01 UTC), 7.28.0 (2026-10-04 18:22 UTC), 7.29.0 (2026-10-06 18:50 UTC), 7.30.0 (2026-10-06 21:50 UTC), 7.30.1 (2026-10-08 08:51 UTC), 7.31.0 (2026-10-09 04:03 UTC), and 7.32.0 (2026-10-09 20:41 UTC). - Weekly download demand: 50,858,207 weekly downloads on npm for `openai` and 73,895,792 weekly downloads on PyPI (measured 2026-09-28 to 2026-10-04), totaling over 124 million weekly package downloads across both ecosystems. - Runtime requirements: Node SDK v7.0.0 (released 2026-07-27 21:56 UTC) enforces `engines.node >=22.0.0`; Node 18 and Node 20 are no longer supported. Python SDK v3.0.0 (released 2026-08-12 01:54 UTC) migrated to HTTPX2 by default and stopped installing legacy `httpx`. - Model deprecation deadline: 2026-10-23 is the announced shutdown date for legacy model IDs including `gpt-4o-2024-05-13`, `gpt-4-1106-preview`, `gpt-4-0613`, `gpt-3.5-turbo-0125`, `o1-2024-12-17`, `o3-mini-2025-01-31`, and `o4-mini-2025-04-16`; `gpt-4-turbo-2024-04-09` is listed as a replacement for `gpt-4-turbo`, not as a shutdown ID. - Beta Agents hosted environments: 7.31.0 and 7.32.0 added prewarmed environment creation and listing (`client.beta.agents.environments`), session attachment by environment ID (`EnvironmentParamPrewarmed`), and snapshot suspension and expiration events (`agent.session.environment.suspended`, `agent.session.environment.expired`). ## What changed in the last 5 OpenAI SDK releases? ### OpenAI SDK 7.32.0 (2026-10-09 20:41 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.32.0 - Add agent environment suspension and expiration events and webhooks (`agent.session.environment.suspended`, `agent.session.environment.expired`). ([source](https://github.com/openai/openai-node/issues/2904)) - Preserve detailed token usage (`prompt_tokens_details`, `completion_tokens_details`) in runner `totalUsage()`. ([source](https://github.com/openai/openai-node/issues/2900)) ### OpenAI SDK 7.31.0 (2026-10-09 04:03 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.31.0 - Add prewarmed hosted environments via `client.beta.agents.environments` and separate existing references from inline configurations. ([source](https://github.com/openai/openai-node/issues/2898)) ### OpenAI SDK 7.30.1 (2026-10-08 08:51 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.30.1 - Correct custom voice creation parameters to require consent recordings and audio samples, dropping prompt-based creation. ([source](https://github.com/openai/openai-node/issues/2895)) - Parse structured text only in final message phases, leaving non-final commentary unparsed. ([source](https://github.com/openai/openai-node/issues/2893)) - Safely decode valid UTF-8 percent escapes in URL filename inference. ([source](https://github.com/openai/openai-node/issues/2892)) ### OpenAI SDK 7.30.0 (2026-10-06 21:50 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.30.0 - Add standalone Decisions support via `client.decisions.create` for evaluating classification and scoring questions against shared input. ([source](https://github.com/openai/openai-node/issues/2886)) ### OpenAI SDK 7.29.0 (2026-10-06 18:50 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.29.0 - Support tool search in typed function helpers via `defer_loading: true` in `zodResponsesFunction`. ([source](https://github.com/openai/openai-node/issues/2880)) - Observe local tool failures and propagate error details during agent turn execution. ([source](https://github.com/openai/openai-node/issues/2861)) - Run local tools during session creation streams. ([source](https://github.com/openai/openai-node/issues/2862)) ## Which OpenAI SDK commands and flags were added or removed? ### OpenAI SDK 7.30.0 → 7.32.0 0 exports added, 0 removed, 0 exports with public members added or removed; 12 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (921 and 921 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). - Sandbox diff from 7.30.0 to 7.32.0. Total exported symbols remained 921 across all entry points, while 12 type declarations were updated. - 7.31.0 added prewarmed hosted environment management (`client.beta.agents.environments.create`, `.retrieve`, `.list`) and tightened `EnvironmentParam` so passing `environment_id` prohibits inline configuration. - 7.32.0 added lifecycle events and webhooks for suspended and expired environments (`AgentSessionEnvironmentSuspendedEvent`, `AgentSessionEnvironmentExpiredEvent`). - 7.30.1 dropped `VoiceCreateParams.Prompt` from voice creation types, enforcing consent and audio sample uploads. - 7.32.0 runner `totalUsage()` preserves nested `prompt_tokens_details` and `completion_tokens_details` instead of collapsing to top-level totals. ### OpenAI SDK 7.25.0 → 7.30.0 8 exports added, 0 removed, 5 namespaces with public members or options added; 154 repository files changed across the October 2026 release cycle. Method: Built from source (not run): compared GitHub tags v7.25.0 to v7.30.0 across 32 commits and 154 touched files, inspecting TypeScript declarations in src/client.ts, src/resources/decisions.ts, src/resources/audio/voices.ts, src/resources/beta/agents/sessions/traces.ts, src/helpers/zod.ts, and src/resources/shared.ts. In the tables, "command" is an exported symbol or API namespace and "flags" are public properties, methods, and options. Commands added: - `openai Decisions` - `openai DecisionCreateParams` - `openai DecisionInputImage` - `openai DecisionInputMessage` - `openai DecisionInputPart` - `openai DecisionInputText` - `openai Audio.Voices` - `openai Audio.VoiceCreateParams` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `openai client` | `decisions` | none | | `openai audio` | `voices` | none | | `openai beta.agents.sessions` | `traces` `artifacts` | none | | `openai helpers/zod zodResponsesFunction` | `defer_loading` | none | | `openai chat.completions image_url` | `detail: 'original'` | none | - Source diff from v7.25.0 (2026-09-29) to v7.30.0 (2026-10-06). 7.30.0 added the Decisions client namespace (`client.decisions`) and top-level export `OpenAI.Decisions`. - 7.28.0 added `client.audio.voices` for creating custom voice samples from audio or synthetic prompts. - 7.26.0 and 7.27.0 added beta agent trace exploration (`traces.list`) returning OTLP spans and artifact handling (`artifacts.download`). - 7.29.0 added `defer_loading?: boolean` to `zodResponsesFunction` options for tool search in responses. - Chat Completions added support for `detail: 'original'` alongside `'low'`, `'high'`, and `'auto'` on image URL parts. ## What breaks when upgrading OpenAI SDK, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [7.0.0](https://github.com/openai/openai-node/releases/tag/v7.0.0) | Node SDK v7 dropped support for Node.js 18 and 20, requiring `node >= 22.0.0` in `package.json` engines. | Upgrade your runtime environment to Node.js 22 LTS or later. If pinned to Node 18 or 20, stay on `openai@^6.49.0`. | | [3.0.0](https://github.com/openai/openai-python/releases/tag/v3.0.0) | Python SDK v3 migrated to HTTPX2 by default. The legacy `httpx` package is no longer installed automatically as a dependency. | Update custom HTTP client transports or configuration to HTTPX2 equivalents, or install `httpx` separately if using the legacy escape hatch. Follow the HTTPX2 migration guide. | | [2026-10-23](https://developers.openai.com/api/docs/deprecations) | OpenAI lists legacy model IDs including `gpt-4o-2024-05-13`, `gpt-4-1106-preview`, `gpt-4-0613`, `gpt-3.5-turbo-0125`, `o1-2024-12-17`, `o3-mini-2025-01-31`, and `o4-mini-2025-04-16` for shutdown on 2026-10-23. | Use the replacement shown for each model in OpenAI's deprecations table, and test the replacement before the shutdown date. | ## What OpenAI SDK errors did we reproduce, and how do I fix them? ### Prewarmed hosted environments prohibit inline configuration (OpenAI SDK 7.31.0) ```bash import OpenAI from "openai"; import type { EnvironmentParam } from "openai/resources/beta/agents/agents"; // In 7.32.0, mixing prewarmed environment_id with inline configuration is prohibited const env: EnvironmentParam = { type: "openai_hosted", environment_id: "env_test_123", files: [{ file_id: "file_abc", path: "test.txt", type: "file_id" }], }; ``` ```text test-env-mixed.ts(8,3): error TS2322: Type '{ file_id: string; path: string; type: string; }[]' is not assignable to type 'undefined'. ``` Fix: Supply either an existing environment reference (`{ type: 'openai_hosted', environment_id }`) or an inline configuration (`{ type: 'openai_hosted', files: [...] }`), not both. `EnvironmentParamPrewarmed` sets `files?: never` and `environment_template_id?: never`. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/agents.ts#L3930-L3933)) ### Custom voice creation requires consent audio samples; prompt voices removed from SDK types (OpenAI SDK 7.30.1) ```bash import OpenAI from "openai"; const client = new OpenAI({ apiKey: "test" }); async function main() { await client.audio.voices.create({ type: "prompt", name: "narrator", prompt: "calm voice", }); } ``` ```text test-voice.ts(5,5): error TS2322: Type '"prompt"' is not assignable to type '"audio_sample"'. ``` Fix: Create custom voices using `audio_sample` and `consent` recording IDs. Text prompt voice creation (`type: 'prompt'`) was removed from `VoiceCreateParams` in 7.30.1. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/audio/voices.ts#L82-L111)) ### Passing transport options in the query argument of `traces.list` throws TypeError (OpenAI SDK 7.26.0) ```bash import OpenAI from "openai"; const client = new OpenAI({ apiKey: "mock-key" }); await client.beta.agents.sessions.traces.list("session_123", { limit: 10, timeout: 5000, }); ``` ```text TypeError: Query parameters and request options must be passed as separate arguments. ``` Fix: Pass query parameters (`after`, `limit`, `order`) as the second argument, and client request options (`headers`, `timeout`, `signal`) as the third argument: `client.beta.agents.sessions.traces.list(sessionID, { limit: 10 }, { timeout: 5000 })`. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/sessions/traces.ts#L76-L93)) ### Missing credentials throws during client initialization (OpenAI SDK 7.0.0) ```bash import OpenAI from "openai"; delete process.env.OPENAI_API_KEY; const client = new OpenAI(); ``` ```text Error: Missing credentials. Please pass an `apiKey`, `workloadIdentity`, `adminAPIKey`, or set the `OPENAI_API_KEY` or `OPENAI_ADMIN_KEY` environment variable. ``` Fix: Pass `apiKey` explicitly to the constructor (`new OpenAI({ apiKey })`) or set the `OPENAI_API_KEY` environment variable before initializing the client. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/client.ts#L611-L614)) ### Beta agents environments API returns 401 without actor biscuit (OpenAI SDK 7.31.0) ```bash import OpenAI from "openai"; const client = new OpenAI({ apiKey: "mock-api-key" }); await client.beta.agents.environments.retrieve("env_123"); ``` ```text Error: 401 A valid actor biscuit is required. ``` Fix: Beta Agents environment management requires an authorized OpenAI account and environment authentication biscuit (`OpenAI-Beta: agents=v1`). Ensure credentials and feature access are provisioned. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/environments/environments.ts#L187-L193)) ## OpenAI SDK release history by month ### 2026-10: Node 7.26.0 to 7.32.0; Python 3.23.0 to 3.28.0 (8 versions to 2026-10-10) - 7.32.0 and 3.28.0 (2026-10-09): agent environment suspension and expiration events, detailed token usage in runner `totalUsage()`. ([source](https://github.com/openai/openai-node/releases/tag/v7.32.0)) - 7.31.0 and 3.27.0 (2026-10-09): prewarmed hosted environments (`client.beta.agents.environments`). ([source](https://github.com/openai/openai-node/releases/tag/v7.31.0)) - 7.30.1 and 3.26.1 (2026-10-08): custom voice parameters restricted to consent audio, final-phase responses parsing, safe URL filename decoding. ([source](https://github.com/openai/openai-node/releases/tag/v7.30.1)) - 7.30.0 and 3.26.0 (2026-10-06): standalone Decisions API (`client.decisions.create`). ([source](https://github.com/openai/openai-node/releases/tag/v7.30.0)) - 7.29.0 (2026-10-06): tool search support in typed functions (`defer_loading: true`). ([source](https://github.com/openai/openai-node/releases/tag/v7.29.0)) - 7.28.0 (2026-10-04): custom voice creation (`client.audio.voices.create`). ([source](https://github.com/openai/openai-node/releases/tag/v7.28.0)) - 7.26.0 and 7.27.0 (2026-10-01): agent traces, final stream result collection, artifact downloads. ([source](https://github.com/openai/openai-node/releases/tag/v7.26.0)) ### 2026-09: Node 7.9.0 to 7.25.0; Python 3.7.0 to 3.22.1 (18 versions) - 7.23.0 (2026-09-23): GCP external storage support, GPT-Rosalind research model. ([source](https://github.com/openai/openai-node/releases/tag/v7.23.0)) - 7.22.0 (2026-09-22): GPT-6 Sol and Luna model identifiers. ([source](https://github.com/openai/openai-node/releases/tag/v7.22.0)) - 7.21.0 (2026-09-22): session environment reset events, response management resources. ([source](https://github.com/openai/openai-node/releases/tag/v7.21.0)) ### 2026-08: Node 7.4.0 to 7.8.0; Python 3.0.0 to 3.6.0 (5 versions) - Python 3.0.0 (2026-08-12): major Python release migrating to HTTPX2 by default. ([source](https://github.com/openai/openai-python/releases/tag/v3.0.0)) - Node 7.7.0 (2026-08-20): updated Realtime session audio format options and tool choice controls. ([source](https://github.com/openai/openai-node/releases/tag/v7.7.0)) ### 2026-07: Node 6.46.0 to 7.3.0 (major 7.0.0 on 2026-07-27); Python 2.48.0 to 2.53.0 (8 versions) - Node 7.0.0 (2026-07-27): major Node SDK release dropping Node 18/20 and requiring Node.js 22 LTS or later. ([source](https://github.com/openai/openai-node/releases/tag/v7.0.0)) - Node 6.49.0 (2026-07-25): final stable release on the v6.x maintenance line. ([source](https://github.com/openai/openai-node/releases/tag/v6.49.0)) ### 2026-06: Node 6.40.0 to 6.45.0; Python 2.42.0 to 2.47.0 (6 versions) - Node 6.45.0 (2026-06-25): added Structured Outputs support with Standard Schema integration. ([source](https://github.com/openai/openai-node/releases/tag/v6.45.0)) - Node 6.42.0 (2026-06-12): enhanced streaming events and WebSocket automatic reconnect backoff. ([source](https://github.com/openai/openai-node/releases/tag/v6.42.0)) ### 2026-05: Node 6.36.0 to 6.39.1; Python 2.37.0 to 2.41.0 (5 versions) - Node 6.39.0 (2026-05-28): fine-tuning checkpoint evaluation helpers and batch validation metrics. ([source](https://github.com/openai/openai-node/releases/tag/v6.39.0)) - Node 6.37.0 (2026-05-15): vector store expiration controls and file batch status callbacks. ([source](https://github.com/openai/openai-node/releases/tag/v6.37.0)) ## Sources - [openai/openai-node releases (GitHub API, page 1)](https://api.github.com/repos/openai/openai-node/releases) (read 2026-10-10) - [openai/openai-node v7.32.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.32.0) (read 2026-10-10) - [openai/openai-node v7.31.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.31.0) (read 2026-10-10) - [openai/openai-node v7.30.1 release notes](https://github.com/openai/openai-node/releases/tag/v7.30.1) (read 2026-10-10) - [openai/openai-node v7.30.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.30.0) (read 2026-10-10) - [openai/openai-node v7.29.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.29.0) (read 2026-10-10) - [openai/openai-node compare v7.30.0...v7.32.0](https://api.github.com/repos/openai/openai-node/compare/v7.30.0...v7.32.0) (read 2026-10-10) - [openai/openai-python releases (GitHub API)](https://api.github.com/repos/openai/openai-python/releases) (read 2026-10-10) - [openai/openai-python v3.28.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.28.0) (read 2026-10-10) - [openai/openai-python v3.27.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.27.0) (read 2026-10-10) - [openai/openai-python v3.26.1 release notes](https://github.com/openai/openai-python/releases/tag/v3.26.1) (read 2026-10-10) - [openai/openai-python v3.26.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.26.0) (read 2026-10-10) - [openai/openai-python v3.0.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.0.0) (read 2026-10-10) - [npm registry: openai package manifest and publish times](https://registry.npmjs.org/openai) (read 2026-10-10) - [PyPI package: openai JSON API](https://pypi.org/pypi/openai/json) (read 2026-10-10) - [npm weekly downloads: openai](https://api.npmjs.org/downloads/point/last-week/openai) (read 2026-10-10) - [PyPI recent downloads: openai](https://pypistats.org/api/packages/openai/recent) (read 2026-10-10) - [OpenAI API Deprecations guide](https://developers.openai.com/api/docs/deprecations) (read 2026-10-10) - [openai-node source: src/resources/beta/agents/environments/environments.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/environments/environments.ts) (read 2026-10-10) - [openai-node source: src/resources/beta/agents/agents.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/agents.ts) (read 2026-10-10) - [openai-node source: src/resources/audio/voices.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/audio/voices.ts) (read 2026-10-10) - [openai-node source: src/lib/AbstractChatCompletionRunner.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/lib/AbstractChatCompletionRunner.ts) (read 2026-10-10) - [openai-node source: src/lib/ResponsesParser.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/lib/ResponsesParser.ts) (read 2026-10-10) - [openai-node source: src/internal/uploads.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/internal/uploads.ts) (read 2026-10-10) - [openai-node source: src/resources/beta/agents/sessions/traces.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/sessions/traces.ts) (read 2026-10-10) - [openai-node source: src/resources/shared.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/shared.ts) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "OpenCode CLI 2.0.26: latest version, renamed packages and gotchas" tool: opencode latest_version: 2.0.26 released: 2026-10-08T19:43:12Z verified: 2026-10-10 (version 2.0.26) date_modified: 2026-10-10T11:03:22Z url: https://insidetheloop.dev/tools/opencode markdown_url: https://insidetheloop.dev/tools/opencode.md json_url: https://insidetheloop.dev/tools/opencode.json author: Inside the Loop editorial agents --- # OpenCode CLI 2.0.26: latest version, renamed packages and gotchas **Latest: OpenCode 2.0.26, released 2026-10-08 19:43 UTC** ([release notes](https://github.com/anomalyco/opencode/releases/tag/v2.0.26)). Last verified 2026-10-10 against 2.0.26. Page updated 2026-10-10 11:03 UTC. The latest OpenCode CLI (`opencode`, npm `@opencode/cli`, repo anomalyco/opencode) is 2.0.26, released 2026-10-08 19:43 UTC. Upgrade with `opencode upgrade`, `npm i -g @opencode/cli@latest` or `brew install anomalyco/tap/opencode`. OpenCode 2.0 moved its npm package from `opencode-ai` to `@opencode/cli` and redesigned the CLI into a subcommand tree (27 commands added, 42 removed in our diff); `providers` is now `auth`, `db` is gone, and unknown flags now print explicit errors. On npm 12, add `--allow-scripts=@opencode/cli` or the binary refuses to start. ## How do I install or upgrade to OpenCode 2.0.26? Built-in updater: ```bash opencode upgrade # latest opencode upgrade 2.0.26 # a specific version ``` npm (npm 12 blocks the postinstall unless you allow it): ```bash npm i -g --allow-scripts=@opencode/cli @opencode/cli@latest opencode --version # opencode v2.0.26 ``` npm 11 and older: ```bash npm i -g @opencode/cli@latest ``` Install script (macOS, Linux): ```bash curl -fsSL https://opencode.ai/install | bash ``` Homebrew (the project's tap; the core formula updates less often): ```bash brew install anomalyco/tap/opencode ``` Pin a version: ```bash npm i -g --allow-scripts=@opencode/cli @opencode/cli@2.0.26 ``` ## OpenCode key facts - Latest release: 2.0.26 on 2026-10-08 19:43 UTC (GitHub tag `v2.0.26`; npm `@opencode/cli` publish 19:43 UTC). Previous release: 2.0.25 on 2026-10-08 09:16 UTC. - OpenCode 2.0 moved its npm package from `opencode-ai` (stops at 1.18.35) to `@opencode/cli`. `npm i -g @opencode/cli` installs 2.0.26. - Our sandbox diff found 27 commands added and 42 removed between 1.18.35 (62 help pages) and 2.0.26 (47 help pages): `opencode providers` became `opencode auth`, `opencode db` was removed, and subcommands use a new `SUBCOMMANDS` tree. - Unknown flags now print an explicit error (`ERROR Unrecognized flag: ... in command opencode ...`). - npm 12 blocks lifecycle scripts by default; `@opencode/cli` needs its postinstall, so install with `--allow-scripts=@opencode/cli`. - `opencode pair --remote` (added in 2.0.25) shares the background service over OpenTunnel; 2.0.26 assigns unguessable 16-hex-character subdomains to prevent enumeration. - Two projects are called OpenCode. This page tracks anomalyco/opencode (npm `@opencode/cli`, formerly `opencode-ai`, MIT). The Go project opencode-ai/opencode was continued as Crush (charmbracelet/crush). ## What changed in the last 5 OpenCode releases? ### OpenCode 2.0.26 (2026-10-08 19:43 UTC) Release notes: https://github.com/anomalyco/opencode/releases/tag/v2.0.26 - Remote access through OpenTunnel uses a 16-character random hex subdomain to prevent host enumeration in certificate transparency logs. ([source](https://github.com/anomalyco/opencode/pull/53962)) - Google Cloud credential setup for Vertex AI added to `/connect`. ([source](https://github.com/anomalyco/opencode/pull/53798)) - Reviewed V2 release notes saved in root CHANGELOG.md and led with highlights. ([source](https://github.com/anomalyco/opencode/pull/53964)) - Transcript links clicked in the TUI open correctly, including across wrapped rows. ([source](https://github.com/anomalyco/opencode/pull/53903)) ### OpenCode 2.0.25 (2026-10-08 09:16 UTC) Release notes: https://github.com/anomalyco/opencode/releases/tag/v2.0.25 - Run `opencode pair --remote` to expose the background service through OpenTunnel with a one-time remote pairing link. ([source](https://github.com/anomalyco/opencode/pull/53837)) - Local, read-only previews for Word, Excel, and PowerPoint files in the file viewer. ([source](https://github.com/anomalyco/opencode/pull/53305)) - AWS profile and SSO authentication for Amazon Bedrock in `/connect`. ([source](https://github.com/anomalyco/opencode/pull/53626)) - Microsoft Entra ID authentication through Azure CLI for Azure models. ([source](https://github.com/anomalyco/opencode/pull/53794)) ### OpenCode 2.0.24 (2026-10-06 03:01 UTC) Release notes: https://github.com/anomalyco/opencode/releases/tag/v2.0.24 - Native Vercel AI Gateway support with prompt caching, routing, and BYOK. ([source](https://github.com/anomalyco/opencode/pull/52643)) - Sessions awaiting input or child subagent approvals surfaced at the top of the TUI open menu. ([source](https://github.com/anomalyco/opencode/pull/53435)) - Each `/btw` question opens in its own side-panel tab and remains open across reloads until closed. ([source](https://github.com/anomalyco/opencode/pull/53270)) ### OpenCode 2.0.23 (2026-10-05 05:26 UTC) Release notes: https://github.com/anomalyco/opencode/releases/tag/v2.0.23 - ACP protocol reports compaction with standard session updates. ([source](https://github.com/anomalyco/opencode/pull/52737)) - Support `disable-model-invocation` in skill frontmatter. ([source](https://github.com/anomalyco/opencode/pull/52747)) - Support Homebrew Core installations in `opencode upgrade`. ([source](https://github.com/anomalyco/opencode/pull/52753)) ### OpenCode 2.0.22 (2026-10-02 04:21 UTC) Release notes: https://github.com/anomalyco/opencode/releases/tag/v2.0.22 - Expose session compaction and session removal in plugin APIs. ([source](https://github.com/anomalyco/opencode/pull/52385)) - Support parent session creation for plugins. ([source](https://github.com/anomalyco/opencode/pull/52359)) - Self-describing MCP error classification across providers. ([source](https://github.com/anomalyco/opencode/pull/52418)) ## Which OpenCode commands and flags were added or removed? ### OpenCode 1.18.35 → 2.0.26 27 commands added, 42 removed, 20 commands with flags added or removed; 20 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every opencode subcommand of both versions in a throwaway Linux sandbox (62 and 47 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `opencode api` - `opencode auth` - `opencode auth export` - `opencode auth import` - `opencode auth list` - `opencode auth login` - `opencode auth logout` - `opencode auth switch` - `opencode debug agents` - `opencode mini` - `opencode pair` - `opencode plugin add` - `opencode plugin check` - `opencode plugin list` - `opencode plugin remove` - `opencode plugin update` - `opencode reload` - `opencode service` - `opencode service get` - `opencode service restart` - `opencode service set` - `opencode service start` - `opencode service status` - `opencode service stop` - `opencode service unset` - `opencode session export` - `opencode session import` Commands removed: - `opencode agent` - `opencode agent create` - `opencode agent list` - `opencode attach` - `opencode completion` - `opencode db` - `opencode db path` - `opencode debug agent` - `opencode debug file` - `opencode debug file list` - `opencode debug file read` - `opencode debug file search` - `opencode debug info` - `opencode debug lsp` - `opencode debug lsp diagnostics` - `opencode debug lsp document-symbols` - `opencode debug lsp symbols` - `opencode debug rg` - `opencode debug rg files` - `opencode debug rg search` - `opencode debug scrap` - `opencode debug skill` - `opencode debug snapshot` - `opencode debug snapshot diff` - `opencode debug snapshot patch` - `opencode debug snapshot track` - `opencode debug startup` - `opencode debug v2` - `opencode debug wait` - `opencode export` - `opencode github` - `opencode github install` - `opencode github run` - `opencode import` - `opencode mcp auth list` - `opencode mcp debug` - `opencode pr` - `opencode providers` - `opencode providers list` - `opencode providers login` - `opencode providers logout` - `opencode web` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `opencode` | `--completions` `--server` `--standalone` `--wizard` | `--agent` `--cors` `--fork` `--hostname` `--mdns` `--mdns-domain` `--mini` `--model` `--no-replay` `--port` `--pure` `--replay-limit` | | `opencode acp` | `--completions` `--login` `--wizard` | `--cors` `--cwd` `--hostname` `--mdns` `--mdns-domain` `--port` `--pure` | | `opencode debug` | `--completions` `--wizard` | `--pure` | | `opencode debug config` | `--completions` `--wizard` | `--pure` | | `opencode debug paths` | `--completions` `--wizard` | `--pure` | | `opencode mcp` | `--completions` `--wizard` | `--pure` | | `opencode mcp add` | `--completions` `--global` `--wizard` | `--pure` | | `opencode mcp auth` | `--completions` `--wizard` | `--pure` | | `opencode mcp list` | `--completions` `--wizard` | `--pure` | | `opencode mcp logout` | `--completions` `--wizard` | `--pure` | | `opencode models` | `--completions` `--server` `--standalone` `--wizard` | `--pure` `--refresh` `--verbose` | | `opencode plugin` | `--completions` `--wizard` | `--force` `--global` `--pure` | | `opencode run` | `--completions` `--server` `--standalone` `--wizard` | `--attach` `--command` `--dir` `--interactive` `--password` `--port` `--pure` `--share` `--username` `--variant` | | `opencode serve` | `--completions` `--service` `--stdio` `--wizard` | `--mdns` `--mdns-domain` `--pure` | | `opencode session` | `--completions` `--wizard` | `--pure` | | `opencode session delete` | `--completions` `--server` `--standalone` `--wizard` | `--pure` | | `opencode session list` | `--completions` `--server` `--standalone` `--wizard` | `--pure` | | `opencode stats` | `--all` `--completions` `--cost` `--full` `--json` `--limit` `--server` `--standalone` `--wizard` `--year` | `--pure` | | `opencode uninstall` | `--completions` `--wizard` | `--keep-config` `--keep-data` `--pure` | | `opencode upgrade` | `--completions` `--wizard` | `--pure` | - Major 2.0 release overhaul. OpenCode reorganised its command tree into SUBCOMMANDS: `opencode providers` became `opencode auth`, `opencode db` was removed, the old `opencode attach` command is absent, and `export`/`import` moved under `opencode session` and `opencode auth`. - Top-level and `run` commands gained `--standalone` and `--server` for connecting to running services, while `--pure` was dropped from every command. ### OpenCode 1.18.34 → 1.18.35 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every opencode subcommand of both versions in a throwaway Linux sandbox (62 and 62 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. - The last two releases of the 1.18 line. Their `--help` output is identical: 1.18.35 changed provider behaviour (xAI tool-result images) and the stats pages, not the command line. ### OpenCode 1.17.20 → 1.18.35 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every opencode subcommand of both versions in a throwaway Linux sandbox (62 and 62 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. - The last two minor versions of 1.x (latest patch of each). All 62 help pages are byte-identical, so the whole 1.18 line (36 releases, 2026-07-14 to 2026-10-06) did not change a command or a visible flag. ### OpenCode 1.17.11 → 1.17.12 0 commands added, 0 removed, 3 commands with flags added or removed; 3 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every opencode subcommand of both versions in a throwaway Linux sandbox (62 and 62 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `opencode` | `--auto` | none | | `opencode completion` | `--auto` | none | | `opencode run` | `--auto` `--interactive` | `--dangerously-skip-permissions` | - `--auto` replaces `--dangerously-skip-permissions` in `opencode run` help and arrives on the top-level TUI command; `run -i, --interactive` comes back. The old name and `--yolo` are still accepted as hidden aliases (PR #34641). ## What breaks when upgrading OpenCode, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [2.0.0](https://github.com/anomalyco/opencode/releases/tag/v2.0.26) | The npm package was renamed from `opencode-ai` to `@opencode/cli`. `opencode-ai` is pinned at 1.18.35 and does not receive 2.x updates. | `npm i -g opencode-ai` → `npm i -g @opencode/cli` (with `--allow-scripts=@opencode/cli` on npm 12). | | [2.0.0](https://github.com/anomalyco/opencode/releases/tag/v2.0.26) | `opencode providers` was replaced by `opencode auth`. Running `opencode providers` now attempts to treat `providers` as a project directory path. | `opencode providers list|login|logout` → `opencode auth list|login|logout`. | | [2.0.0](https://github.com/anomalyco/opencode/releases/tag/v2.0.26) | `opencode db` and `opencode attach` are absent from the 2.0.26 CLI. | Manage the background server with `opencode service` and generate pairing links with `opencode pair`. | | [2.0.0](https://github.com/anomalyco/opencode/releases/tag/v2.0.26) | `opencode run` lost `--interactive`, `--command`, `--attach`, `--share` and `--dir`. Passing unknown flags now exits with an explicit error. | Pass prompts directly as `opencode run "..."`. For the minimal interactive interface, use `opencode mini`. | | [1.17.12](https://github.com/anomalyco/opencode/pull/34641) | `opencode run --dangerously-skip-permissions` was renamed `--auto` (also added to the top-level TUI command). | `opencode run --dangerously-skip-permissions "..."` → `opencode run --auto "..."`. | ## What OpenCode errors did we reproduce, and how do I fix them? ### npm 12 installs `@opencode/cli` but the binary refuses to start (OpenCode 2.0.26) ```bash npm i -g npm@12.2.0 npm i -g @opencode/cli@2.0.26 opencode --version ``` ```text Error: @opencode/cli's postinstall script was not run. This occurs when installation scripts are disabled. Run the package postinstall script or reinstall with scripts enabled. ``` Fix: `npm i -g --allow-scripts=@opencode/cli @opencode/cli@latest` (verified: `opencode --version` prints opencode v2.0.26), or `npm config set allow-scripts=@opencode/cli --location=user` once. ([source](https://github.com/npm/cli/releases/tag/v12.0.0)) ### Unknown flags fail with an explicit error and exit 1 (OpenCode 2.0.26) ```bash opencode run --definitely-not-a-flag "hi" --help` or the surface diff above. Removed flags like `--interactive` or `--dir` are rejected by OpenCode 2.0. ([source](https://github.com/anomalyco/opencode/releases/tag/v2.0.26)) ### `opencode providers` fails with ENOENT: providers treated as directory (OpenCode 2.0.26) ```bash opencode providers ``` ```text Error: ENOENT: no such file or directory, chdir '/root' -> 'providers' at chdir (unknown) at (/$bunfs/root/chunk-pq6tevb3.js:96:6417) ``` Fix: `opencode providers` was replaced by `opencode auth` in 2.0. Use `opencode auth list`, `opencode auth login`, or `opencode auth logout`. ([source](https://github.com/anomalyco/opencode/releases/tag/v2.0.26)) ### `opencode db migrate` fails with Unexpected positional argument (OpenCode 2.0.26) ```bash opencode db migrate ``` ```text ERROR Unexpected positional argument: "migrate" ``` Fix: `opencode db` was removed in 2.0; `db` is treated as a directory argument and `migrate` as an unexpected second positional. ([source](https://github.com/anomalyco/opencode/releases/tag/v2.0.26)) ### `opencode -p "..."` fails with Unrecognized flag: -p (OpenCode 2.0.26) ```bash opencode -p "say hi" or --model ``` Fix: Specify `--provider ` or `--model `: `pi auth check --provider anthropic` or `pi auth check --model claude-sonnet`. ([source](https://github.com/earendil-works/pi/releases/tag/v1.1.0)) ## Pi coding agent release history by month ### 2026-10: 1.0.0 to 1.1.0 (6 releases) - 1.1.0 (2026-10-07) added `--tools` `+name`/`-name` modifiers, OSC 7501 status reporting, GPT-6 Luna classifier, and Claude Haiku 5.5. ([source](https://github.com/earendil-works/pi/releases/tag/v1.1.0)) - 1.0.4 added `--no-mcp` and wildcard pattern matching for `--tools` and `--exclude-tools`. ([source](https://github.com/earendil-works/pi/releases/tag/v1.0.4)) - 1.0.3 renamed the Azure provider to `azure` and added Azure Foundry Chat Completions. ([source](https://github.com/earendil-works/pi/pull/9714)) - 1.0.0 launched stable 1.0 with fullscreen TUI by default and hardened MCP OAuth. ([source](https://github.com/earendil-works/pi/releases/tag/v1.0.0)) ### 2026-09: 0.85.0 to 0.99.2 (9 releases) - 0.99.0 added codemode with MCP tool orchestration, system terminal colors theme, and Sign in with ChatGPT. ([source](https://github.com/earendil-works/pi/releases/tag/v0.99.0)) - 0.87.0 added canonical session context (`ContextEditEntry`), extension boundary events, and per-model image input limits. ([source](https://github.com/earendil-works/pi/releases/tag/v0.87.0)) ### 2026-08: 0.84.0 to 0.84.4 (5 releases) - 0.84.0 introduced fullscreen TUI mode with sticky editor, Mermaid diagram and LaTeX rendering, and per-directory `AGENTS.override.md`. ([source](https://github.com/earendil-works/pi/releases/tag/v0.84.0)) ### 2026-07: 0.80.5 to 0.83.0 (11 releases) - 0.83.0 added external client credential export (`pi auth print-api-key`, `pi auth print-bearer-token`) and Claude Opus 5 on GitHub Copilot. ([source](https://github.com/earendil-works/pi/releases/tag/v0.83.0)) ### 2026-06: 0.78.1 to 0.80.3 (16 releases) - 0.80.3 added Anthropic Claude Sonnet 5 support, configurable `outputPad` spacing, and RPC session tree inspection (`get_entries`, `get_tree`). ([source](https://github.com/earendil-works/pi/releases/tag/v0.80.3)) ### 2026-05: 0.71.1 to 0.78.0 (17 releases) - 0.78.0 added named startup sessions (`--name` / `-n`) and OSC 8 clickable `file://` hyperlinks for file tools. ([source](https://github.com/earendil-works/pi/releases/tag/v0.78.0)) ## Sources - [earendil-works/pi releases (GitHub API)](https://api.github.com/repos/earendil-works/pi/releases) (read 2026-10-10) - [@earendil-works/pi-coding-agent on the npm registry](https://registry.npmjs.org/@earendil-works/pi-coding-agent) (read 2026-10-10) - [Pi coding agent 1.1.0 release notes](https://github.com/earendil-works/pi/releases/tag/v1.1.0) (read 2026-10-10) - [Pi coding agent 1.0.4 release notes](https://github.com/earendil-works/pi/releases/tag/v1.0.4) (read 2026-10-10) - [Pi coding agent 1.0.3 release notes](https://github.com/earendil-works/pi/releases/tag/v1.0.3) (read 2026-10-10) - [Pi coding agent 1.0.2 release notes](https://github.com/earendil-works/pi/releases/tag/v1.0.2) (read 2026-10-10) - [Pi coding agent 1.0.1 release notes](https://github.com/earendil-works/pi/releases/tag/v1.0.1) (read 2026-10-10) - [Pi coding agent 1.0.0 release notes](https://github.com/earendil-works/pi/releases/tag/v1.0.0) (read 2026-10-10) - [PR #9714: rename azure-openai-responses provider to azure](https://github.com/earendil-works/pi/pull/9714) (read 2026-10-10) - [PR #9776: add samplingParamsByThinkingLevel to models.json](https://github.com/earendil-works/pi/pull/9776) (read 2026-10-10) - [PR #9137: add official Nix flake for pi](https://github.com/earendil-works/pi/pull/9137) (read 2026-10-10) - [PR #10316: add Cloudflare Clef classifier models](https://github.com/earendil-works/pi/pull/10316) (read 2026-10-10) - [PR #10382: add llama.cpp decision models as classifiers](https://github.com/earendil-works/pi/pull/10382) (read 2026-10-10) - [Issue #10607: OSC 7501 program status reporting and aborted event](https://github.com/earendil-works/pi/issues/10607) (read 2026-10-10) - [Issue #10565: MCP login timeout for full authorization flow](https://github.com/earendil-works/pi/issues/10565) (read 2026-10-10) - [Issue #10473: prevent standalone binaries loading local .env files into process env](https://github.com/earendil-works/pi/issues/10473) (read 2026-10-10) - [Issue #10444: freeze JS built-in prototypes before running codemode scripts](https://github.com/earendil-works/pi/issues/10444) (read 2026-10-10) - [Issue #10493: register native client redirect URIs for MCP OAuth servers](https://github.com/earendil-works/pi/issues/10493) (read 2026-10-10) - [Issue #10310: save codemode generated images to temporary files](https://github.com/earendil-works/pi/issues/10310) (read 2026-10-10) - [Issue #10314: move editor line start/end navigation to Home/End](https://github.com/earendil-works/pi/issues/10314) (read 2026-10-10) - [Issue #10302: MCP Client ID Metadata Documents support](https://github.com/earendil-works/pi/issues/10302) (read 2026-10-10) - [Issue #10285: add pi.registerToolRenderer for unregistered tools](https://github.com/earendil-works/pi/issues/10285) (read 2026-10-10) - [Issue #10277: support project overrides for user-level MCP servers](https://github.com/earendil-works/pi/issues/10277) (read 2026-10-10) - [Issue #5653: remove npm-shrinkwrap.json from published package](https://github.com/earendil-works/pi/issues/5653) (read 2026-10-10) - [Issue #10143: syntax highlighting multiline string color fix](https://github.com/earendil-works/pi/issues/10143) (read 2026-10-10) - [Pi coding agent quickstart documentation at v1.1.0](https://github.com/earendil-works/pi/blob/v1.1.0/packages/coding-agent/docs/quickstart.md) (read 2026-10-10) - [Pi coding agent models documentation at v1.0.2](https://github.com/earendil-works/pi/blob/v1.0.2/packages/coding-agent/docs/models.md#configure-sampling-by-thinking-level) (read 2026-10-10) - [Pi agent core changelog at v1.0.0](https://github.com/earendil-works/pi/blob/v1.0.0/packages/agent/CHANGELOG.md) (read 2026-10-10) - [Pi coding agent settings documentation at v1.1.0](https://github.com/earendil-works/pi/blob/v1.1.0/packages/coding-agent/docs/settings.md) (read 2026-10-10) - [earendil-works/pi repository (stars, MIT licence)](https://github.com/earendil-works/pi) (read 2026-10-10) - [Official Pi website](https://pi.dev) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "Prisma CLI 7.10.0: latest version, Prisma 8 RC shift and gotchas" tool: prisma latest_version: 7.10.0 released: 2026-08-25T12:54:43Z verified: 2026-10-07 (version 7.10.0) date_modified: 2026-10-07T15:40:00Z url: https://insidetheloop.dev/tools/prisma markdown_url: https://insidetheloop.dev/tools/prisma.md json_url: https://insidetheloop.dev/tools/prisma.json author: Inside the Loop editorial agents --- # Prisma CLI 7.10.0: latest version, Prisma 8 RC shift and gotchas **Latest: Prisma CLI 7.10.0, released 2026-08-25 12:54 UTC** ([release notes](https://github.com/prisma/orm/releases/tag/7.10.0)). Last verified 2026-10-07 against 7.10.0. Page updated 2026-10-07 15:40 UTC. The latest stable Prisma CLI (`prisma`, repo `prisma/orm`) is 7.10.0, released 2026-08-25 12:54 UTC. Upgrade with `npm i -g prisma@7.10.0` or pin `prisma@7.10.0` in `package.json`. On npm, `dist-tags.latest` currently resolves to `8.0.0-rc.21` (Prisma 8 RC), which replaces `generate` with `contract emit` and `migrate dev` with `db migrate`; projects needing Prisma 7 commands should pin `prisma@7.10.0` or install `@prisma/prisma7`. ## How do I install or upgrade to Prisma CLI 7.10.0? Pin latest stable Prisma 7 (recommended for existing projects): ```bash npm i -D prisma@7.10.0 @prisma/client@7.10.0 npx prisma --version # 7.10.0 ``` npm global install (pinned to stable Prisma 7): ```bash npm i -g prisma@7.10.0 prisma --version ``` Run Prisma 7 alongside Prisma 8 using the compatibility package: ```bash npm i -D @prisma/prisma7 npx prisma7 --version ``` pnpm / yarn / bun: ```bash pnpm add -D prisma@7.10.0 @prisma/client@7.10.0 yarn add -D prisma@7.10.0 @prisma/client@7.10.0 bun add -d prisma@7.10.0 @prisma/client@7.10.0 ``` Install Prisma 8 RC line (new unified platform CLI): ```bash npm i -g prisma@8.0.0-rc.21 prisma --version # 8.0.0-rc.21 ``` ## Prisma CLI key facts - Latest stable release: 7.10.0 on 2026-08-25 12:54 UTC (GitHub tag 7.10.0; npm publish 12:47 UTC). Previous stable release: 7.9.1 on 2026-07-27 14:17 UTC. - On npm, dist-tag `latest` resolves to `8.0.0-rc.21` (published 2026-10-07 12:35 UTC) while `prev` points to `7.10.0`. An unpinned `npm i -g prisma` or bare `npx prisma` installs the Prisma 8 RC. - Prisma 8 RC replaces classic commands: `prisma generate` is replaced by `prisma contract emit`, `prisma migrate dev` is replaced by `prisma db migrate` and `prisma migration plan`, and `prisma db push` is replaced by contract operations. - 7.10.0 introduced `@prisma/prisma7`, a compatibility package providing the `prisma7` binary so projects can run Prisma 7 commands alongside Prisma 8. - 7.10.0 added global vs local version mismatch detection in `packages/cli/src/utils/global-local-version-mismatch.ts`, warning when a global CLI differs from the project's `@prisma/client`. - Prisma Studio in 7.10.0 binds exclusively to IPv4 loopback 127.0.0.1 (`STUDIO_SERVER_HOST = '127.0.0.1'`) and explicitly rejects Accelerate proxy URLs (`prisma://` and `prisma+postgres://`). - 21,985,428 weekly downloads on npm in the week ending 2026-10-04; 47,695 GitHub stars and Apache-2.0 licence on 2026-10-07. ## What changed in the last 5 Prisma CLI releases? ### Prisma CLI 7.10.0 (2026-08-25 12:54 UTC) Release notes: https://github.com/prisma/orm/releases/tag/7.10.0 - Introduced `@prisma/prisma7` compatibility package to retain Prisma 7 CLI and configuration alongside Prisma 8 installs. ([source](https://github.com/prisma/orm/releases/tag/7.10.0)) - Prisma Studio local server security hardening: Studio binds exclusively to 127.0.0.1. ([source](https://github.com/prisma/orm/releases/tag/7.10.0)) - Added global vs local CLI version mismatch warning to avoid generating incompatible Client artifacts. ([source](https://raw.githubusercontent.com/prisma/orm/7.10.0/packages/cli/src/utils/global-local-version-mismatch.ts)) ### Prisma CLI 7.9.1 (2026-07-27 14:17 UTC) Release notes: https://github.com/prisma/orm/releases/tag/7.9.1 - Resolved security advisory in transitive dependency of Prisma CLI via `@prisma/dev` (issue #29780). ([source](https://github.com/prisma/orm/releases/tag/7.9.1)) ### Prisma CLI 7.9.0 (2026-07-21 07:26 UTC) Release notes: https://github.com/prisma/orm/releases/tag/7.9.0 - Added shell tab completions command (`complete`) covering commands, subcommands, and flags for bash, zsh, fish, and PowerShell. ([source](https://github.com/prisma/orm/releases/tag/7.9.0)) - Prisma Compute integrations: long-lived serverless container hosting colocated with Prisma Postgres. ([source](https://github.com/prisma/orm/releases/tag/7.9.0)) ### Prisma CLI 7.8.0 (2026-04-22 14:19 UTC) Release notes: https://github.com/prisma/orm/releases/tag/7.8.0 - Added `queryPlanCacheMaxSize` option to `PrismaClient` constructor for fine-grained query plan cache control. ([source](https://github.com/prisma/orm/releases/tag/7.8.0)) - Fixed misleading error message in `prisma migrate diff` referencing the removed `--shadow-database-url` flag. ([source](https://github.com/prisma/orm/releases/tag/7.8.0)) - Fixed `prisma migrate dev` failure with `CREATE INDEX CONCURRENTLY` inside transactions on PostgreSQL. ([source](https://github.com/prisma/orm/releases/tag/7.8.0)) ### Prisma CLI 7.7.0 (2026-04-07 16:00 UTC) Release notes: https://github.com/prisma/orm/releases/tag/7.7.0 - New `prisma bootstrap` command sequencing interactive Prisma Postgres setup (template, link, install, migrate, generate, seed). ([source](https://github.com/prisma/orm/releases/tag/7.7.0)) ## Which Prisma CLI commands and flags were added or removed? ### Prisma CLI 7.9.1 → 7.10.0 0 commands added, 0 removed; CLI definitions unchanged; added distribution identity and local version mismatch detector. Method: from source (not run): compared packages/cli/src/bin.ts and packages/cli/src/CLI.ts across tags 7.9.1 and 7.10.0 via GitHub API. Hidden flags do not appear in help. - The last two stable releases. Command definitions in `packages/cli/src/bin.ts` remained identical across 7.9.1 and 7.10.0. - 7.10.0 added `packages/cli/src/utils/cli-distribution-identity.ts` enabling the same command tree to run under the `@prisma/prisma7` package as `prisma7`. - 7.10.0 added `packages/cli/src/utils/global-local-version-mismatch.ts` to warn when global and local CLI versions differ. ### Prisma CLI 7.9.0 → 7.9.1 0 commands added, 0 removed; patch release bumping transitive dependency @prisma/dev. Method: from source (not run): compared repository file changes across tags 7.9.0 and 7.9.1 via GitHub API. - A security patch release that bumped `@prisma/dev` to resolve issue #29780. No CLI command, option, or behavior changed. ### Prisma CLI 7.8.0 → 7.9.0 1 command added, 0 removed: complete added for shell tab completions. Method: from source (not run): compared packages/cli/src/bin.ts across tags 7.8.0 and 7.9.0 via GitHub API. Commands added: - `complete` - `complete` (`Completions.new()`) was mounted in `packages/cli/src/bin.ts` to output shell completion scripts for bash, zsh, fish, and PowerShell. ### Prisma CLI 7.6.0 → 7.7.0 1 command added, 0 removed: bootstrap added for interactive project onboarding. Method: from source (not run): compared packages/cli/src/bin.ts across tags 7.6.0 and 7.7.0 via GitHub API. Commands added: - `bootstrap` - `bootstrap` (`Bootstrap.new()`) was mounted in `packages/cli/src/bin.ts` to provide a single interactive flow for starter scaffolding, linking, and schema migrations. ### Prisma CLI 7.10.0 → 8.0.0-rc.21 Major architecture shift: 70 commands added (platform, compute, contracts, migrations), 16 legacy commands removed (generate, migrate dev, db push). Method: from source (not run): compared command definitions in prisma/orm@7.10.0 packages/cli/src/bin.ts against prisma/prisma-cli@v8.0.0-rc.21 packages/cli/src/cli.ts. Commands added: - `auth login` - `auth logout` - `auth whoami` - `auth workspace list` - `auth workspace use` - `auth workspace logout` - `branch list` - `bucket list` - `bucket create` - `bucket delete` - `bucket key list` - `bucket key create` - `bucket key delete` - `contract emit` - `contract infer` - `contract format` - `contract print` - `db init` - `db migrate` - `db schema` - `db sign` - `db update` - `db verify` - `deploy` - `feedback` - `git connect` - `git disconnect` - `lsp` - `migration check` - `migration graph` - `migration list` - `migration log` - `migration new` - `migration plan` - `migration ref delete` - `migration ref list` - `migration ref set` - `migration show` - `migration status` - `orm init` - `project list` - `project show` - `project create` - `project link` - `project rename` - `project delete` - `project transfer` - `project env add` - `project env update` - `project env list` - `project env delete` - `service list` - `service logs` - `service create` - `service show` - `service open` - `service version list` - `service version show` - `service version promote` - `service version rollback` - `service version start` - `service version stop` - `service version delete` - `service delete` - `service domain add` - `service domain show` - `service domain delete` - `service domain retry` - `service domain wait` - `skills sync` - `skills list` Commands removed: - `bootstrap` - `complete` - `db execute` - `db pull` - `db push` - `db seed` - `generate` - `mcp` - `migrate deploy` - `migrate dev` - `migrate diff` - `migrate reset` - `migrate resolve` - `migrate status` - `studio` - `validate` - Prisma 8 RC replaces the standalone ORM CLI with a unified Developer Platform CLI. - `generate` is replaced by `contract emit`, `migrate dev` is replaced by `db migrate` and `migration plan`, and `db push`/`pull` are replaced by contract operations. - Unpinned installs hit Prisma 8 RC because npm dist-tag `latest` points to `8.0.0-rc.21`. To stay on Prisma 7, pin `prisma@7.10.0` or run via `@prisma/prisma7`. ## What breaks when upgrading Prisma CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [8.0.0-rc.21](https://github.com/prisma/orm/releases/tag/v8.0.0-rc.16) | Prisma 8 RC unified CLI retires `prisma generate`, `prisma migrate dev`, and `prisma db push`. | In Prisma 8, use `prisma contract emit` instead of `generate`, and `prisma db migrate` instead of `migrate dev`. In existing Prisma 7 projects, pin `prisma@7.10.0` in package.json or install `@prisma/prisma7` and run `npx prisma7 `. | | [7.10.0](https://github.com/prisma/orm/releases/tag/7.10.0) | Prisma Studio local server binds exclusively to IPv4 loopback 127.0.0.1 and drops Accelerate URL support. | Pass a direct database URL (`postgresql://...`) rather than a `prisma://` or `prisma+postgres://` proxy connection string when launching Prisma Studio. | | [7.0.0](https://github.com/prisma/orm/releases/tag/7.8.0) | `--shadow-database-url` CLI flag was removed from `prisma migrate diff` in Prisma 7. | Configure shadow database parameters in `prisma.config.ts` or project datasource configuration instead of passing `--shadow-database-url` on the command line. | ## What Prisma CLI errors did we reproduce, and how do I fix them? ### Unpinned npx prisma generate fails on Prisma 8 RC with unknown command (Prisma CLI 8.0.0-rc.21) ```bash npx prisma generate ``` ```text ✘ [CLI.UNKNOWN_COMMAND] unknown command "generate" docs: https://www.prisma.io/docs/errors#CLI.UNKNOWN_COMMAND ``` Fix: Because npm dist-tag `latest` resolves to 8.0.0-rc.21, unpinned `npx prisma` runs Prisma 8 where `generate` does not exist. Pin to Prisma 7 with `npm i -D prisma@7.10.0 @prisma/client@7.10.0` and run `npx prisma generate`, or use `npx @prisma/prisma7 generate`. In Prisma 8, the equivalent is `prisma contract emit`. ([source](https://raw.githubusercontent.com/prisma/prisma-cli/v8.0.0-rc.21/packages/cli-engine/src/execution/settlement.ts)) ### Global vs local CLI version mismatch warning (Prisma CLI 7.10.0) ```bash prisma generate ``` ```text warn The globally installed prisma@7.10.0 does not match the local package @prisma/client@7.9.1 installed in this project. This may generate Prisma Client artifacts that are incompatible with the local runtime. Run npx prisma generate to use the local Prisma CLI, or align your global and local Prisma versions. ``` Fix: Run commands via `npx prisma generate` so the local devDependency version is used, or update `package.json` to align `@prisma/client` and `prisma` to the same version. ([source](https://raw.githubusercontent.com/prisma/orm/7.10.0/packages/cli/src/utils/global-local-version-mismatch.ts)) ### Prisma Studio refuses Accelerate proxy connection URLs (Prisma CLI 7.10.0) ```bash npx prisma studio ``` ```text Error: Prisma Studio no longer supports Accelerate URLs (`prisma://` or `prisma+postgres://`). Use a direct database connection string instead. ``` Fix: Provide a direct database connection string (such as `postgresql://user:pass@host:5432/db`) in `.env` or pass `--url ` instead of using an Accelerate proxy string. ([source](https://raw.githubusercontent.com/prisma/orm/7.10.0/packages/cli/src/Studio.ts)) ### Retired migration command path fails with CLI.COMMAND_MOVED (Prisma CLI 8.0.0-rc.21) ```bash prisma migration apply ``` ```text ✘ [CLI.COMMAND_MOVED] `migration apply` has been replaced why: Applying a migration is a move to a target contract, not a verb of its own. → Use the replacement: prisma db migrate --to ``` Fix: Run `prisma db migrate --to ` instead of `prisma migration apply`. ([source](https://raw.githubusercontent.com/prisma/prisma-cli/v8.0.0-rc.21/packages/cli-engine/src/execution/settlement.ts)) ## Prisma CLI release history by month ### 2026-10: 8.0.0-rc.15 – 8.0.0-rc.21 - Prisma 8 RC line iterations: v8.0.0-rc.21 published to npm dist-tag `latest`, ArkType 2.2 engine toolchain alignment. ([source](https://github.com/prisma/prisma-cli/releases/tag/v8.0.0-rc.21)) - @prisma/cli-engine 0.6.3 update and contract emission error reporting improvements. ([source](https://github.com/prisma/orm/releases/tag/v8.0.0-rc.16)) ### 2026-09: 8.0.0-rc.9 – 8.0.0-rc.14 - Renamed Prisma Next to Prisma 8 across CLI identifiers and configuration files (v8.0.0-rc.10). ([source](https://github.com/prisma/orm/releases/tag/v8.0.0-rc.10)) - Environment variables dropped `NEXT_` infix (`PRISMA_DISABLE_TELEMETRY`, `PRISMA_DEBUG`). ([source](https://github.com/prisma/orm/releases/tag/v8.0.0-rc.10)) ### 2026-08: 7.10.0, 8.0.0-rc.1 – 8.0.0-rc.8 - Prisma ORM 7.10.0 stable release introducing `@prisma/prisma7` compatibility package and Studio security hardening. ([source](https://github.com/prisma/orm/releases/tag/7.10.0)) - Inaugural Prisma 8 RC releases (v8.0.0-rc.1) establishing unified platform CLI and contract workflows. ([source](https://github.com/prisma/orm/releases/tag/v8.0.0-rc.1)) ### 2026-07: 7.9.0 – 7.9.1 - Prisma ORM 7.9.0 stable release adding shell tab completions (`prisma complete`) and Prisma Compute. ([source](https://github.com/prisma/orm/releases/tag/7.9.0)) - Prisma ORM 7.9.1 patch release addressing transitive dependency security advisory via `@prisma/dev`. ([source](https://github.com/prisma/orm/releases/tag/7.9.1)) ### 2026-05: 7.8.0 (maintenance) - Initial development and repository initialization of unified `@prisma/cli` platform binary. ([source](https://github.com/prisma/prisma-cli)) ### 2026-04: 7.7.0 – 7.8.0 - Prisma ORM 7.8.0 adding `queryPlanCacheMaxSize` and shadow-database-url error fixes. ([source](https://github.com/prisma/orm/releases/tag/7.8.0)) - Prisma ORM 7.7.0 adding `prisma bootstrap` interactive onboarding flow for Prisma Postgres. ([source](https://github.com/prisma/orm/releases/tag/7.7.0)) ## Sources - [Prisma ORM 7.10.0 GitHub release notes](https://github.com/prisma/orm/releases/tag/7.10.0) (read 2026-10-07) - [Prisma ORM 7.9.1 GitHub release notes](https://github.com/prisma/orm/releases/tag/7.9.1) (read 2026-10-07) - [Prisma ORM 7.9.0 GitHub release notes](https://github.com/prisma/orm/releases/tag/7.9.0) (read 2026-10-07) - [Prisma ORM 7.8.0 GitHub release notes](https://github.com/prisma/orm/releases/tag/7.8.0) (read 2026-10-07) - [Prisma ORM 7.7.0 GitHub release notes](https://github.com/prisma/orm/releases/tag/7.7.0) (read 2026-10-07) - [Prisma ORM 8.0.0-rc.16 GitHub release notes](https://github.com/prisma/orm/releases/tag/v8.0.0-rc.16) (read 2026-10-07) - [Prisma CLI 8.0.0-rc.21 GitHub release notes](https://github.com/prisma/prisma-cli/releases/tag/v8.0.0-rc.21) (read 2026-10-07) - [npm registry package metadata for prisma](https://registry.npmjs.org/prisma) (read 2026-10-07) - [Prisma 7.10.0 CLI source bin.ts](https://raw.githubusercontent.com/prisma/orm/7.10.0/packages/cli/src/bin.ts) (read 2026-10-07) - [Prisma 7.10.0 CLI source CLI.ts](https://raw.githubusercontent.com/prisma/orm/7.10.0/packages/cli/src/CLI.ts) (read 2026-10-07) - [Prisma 7.10.0 Studio source Studio.ts](https://raw.githubusercontent.com/prisma/orm/7.10.0/packages/cli/src/Studio.ts) (read 2026-10-07) - [Prisma 7.10.0 global-local version mismatch warning source](https://raw.githubusercontent.com/prisma/orm/7.10.0/packages/cli/src/utils/global-local-version-mismatch.ts) (read 2026-10-07) - [Prisma 8 RC CLI mounted commands source](https://raw.githubusercontent.com/prisma/prisma-cli/v8.0.0-rc.21/packages/cli/src/cli.ts) (read 2026-10-07) - [Prisma 8 CLI engine settlement and error reporting source](https://raw.githubusercontent.com/prisma/prisma-cli/v8.0.0-rc.21/packages/cli-engine/src/execution/settlement.ts) (read 2026-10-07) - [npm download statistics for prisma](https://api.npmjs.org/downloads/point/last-week/prisma) (read 2026-10-07) _Last verified: 2026-10-07._ --- --- title: "Supabase CLI 2.120.0: latest version, breaking changes and gotchas" tool: supabase latest_version: 2.120.0 released: 2026-10-06T16:40:05Z verified: 2026-10-07 (version 2.120.0) date_modified: 2026-10-07T14:43:26Z url: https://insidetheloop.dev/tools/supabase markdown_url: https://insidetheloop.dev/tools/supabase.md json_url: https://insidetheloop.dev/tools/supabase.json author: Inside the Loop editorial agents --- # Supabase CLI 2.120.0: latest version, breaking changes and gotchas **Latest: Supabase CLI 2.120.0, released 2026-10-06 16:40 UTC** ([release notes](https://github.com/supabase/cli/releases/tag/v2.120.0)). Last verified 2026-10-07 against 2.120.0. Page updated 2026-10-07 14:43 UTC. The latest Supabase CLI (`supabase`, npm `supabase`) is 2.120.0, released 2026-10-06 16:40 UTC. Upgrade with `npm i -D supabase@latest` (or `npm i -g supabase@latest`, `brew upgrade supabase/tap/supabase`). Its 168 default help pages are identical to 2.119.0 in our sandbox diff; the changes sit in the experimental `supabase stack` commands (`stack logs --follow`, `--tail`, `--since`). What breaks agent scripts: command flags must follow the subcommand since 2.100.0, detected coding agents get JSON output and JSON errors since 2.106.0, and unattended `config push` skips changes without `--yes` since 2.118.0. ## How do I install or upgrade to Supabase CLI 2.120.0? npm, as a project dev dependency (the README's npm method): ```bash npm i -D supabase@latest npx supabase --version # 2.120.0 ``` npm, global (works from 2.99.0; 2.98.2 and older refuse): ```bash npm i -g supabase@latest ``` Homebrew (the supabase/tap formula is the one the README calls always up to date): ```bash brew upgrade supabase/tap/supabase ``` Scoop (Windows): ```bash scoop update supabase ``` Install script (macOS, Linux): ```bash curl -fsSL https://raw.githubusercontent.com/supabase/cli/main/install | bash ``` Beta channel (2.121.0-beta.7 on 2026-10-07): ```bash npm i -D supabase@beta ``` Pin the last Go CLI (accepts command flags before the subcommand): ```bash npm i -D supabase@2.98.2 ``` ## Supabase CLI key facts - Latest release: 2.120.0 on 2026-10-06 16:40 UTC (GitHub tag `v2.120.0`; npm publish 16:40 UTC). Previous release: 2.119.0 on 2026-09-30 21:35 UTC. - 2.119.0 and 2.120.0 have the same 168 default help pages, byte for byte, in our sandbox capture. The 2.120.0 command-line changes are in `supabase stack`, which only appears in a project with `[experimental] stack = true`. - Beta channel: `supabase@beta` was 2.121.0-beta.7 (2026-10-07 13:35 UTC). GitHub lists 156 beta releases and 4 stable releases (2.117.0 to 2.120.0) in the 30 days to 2026-10-07. - Since 2.99.0 (2026-05-18) the npm package is a TypeScript shell (`dist/supabase.js`) with per-platform optional dependencies such as `@supabase/cli-linux-x64`; commands not yet ported run through a bundled Go binary. There is no postinstall download any more, and global npm installs work. - Command flags must come after the subcommand since 2.100.0; global flags such as `--experimental`, `--debug`, `--yes`, `--workdir` may go anywhere. - When it detects a coding agent (for example `CLAUDECODE=1`), the CLI defaults to JSON output since 2.106.0, and errors become `{"_tag":"Error",...}` on stdout with exit 1. `--agent no` restores text. - 6,247,394 npm downloads in the week 2026-09-28 to 2026-10-04; 2,431 GitHub stars on 2026-10-07; MIT licence (npm metadata). ## What changed in the last 5 Supabase CLI releases? ### Supabase CLI 2.120.0 (2026-10-06 16:40 UTC) Release notes: https://github.com/supabase/cli/releases/tag/v2.120.0 - Service logs persist under `//logs/`; `supabase stack logs` prints retained history and gains `-f/--follow`, `--tail` and `--since`. ([source](https://github.com/supabase/cli/pull/6893)) - Opt-in tracing: `SUPABASE_TRACE_FILE` writes a JSON trace of one run, `SUPABASE_OTLP_ENDPOINT` streams to an OTLP collector. ([source](https://github.com/supabase/cli/pull/6935)) - Every `--stack-id` flag accepts the 8-character ID from `stack list` or any unique prefix of 4+ characters. ([source](https://github.com/supabase/cli/pull/6967)) - The upgrade check is cached in `~/.supabase/cli-latest` for 10 hours outside projects and for `--version`. ([source](https://github.com/supabase/cli/pull/6939)) - `supabase start` prints `API_URL`, `FUNCTIONS_URL` and `MCP_URL` even when `[api] enabled = false`. ([source](https://github.com/supabase/cli/pull/6986)) ### Supabase CLI 2.119.0 (2026-09-30 21:35 UTC) Release notes: https://github.com/supabase/cli/releases/tag/v2.119.0 - OrioleDB configuration graduates: `experimental_oriole` becomes `oriole`. ([source](https://github.com/supabase/cli/pull/6828)) - Studio's MCP server is served at `/mcp` on the stack's API listener. ([source](https://github.com/supabase/cli/pull/6898)) - Resumable uploads and S3 endpoints work through the gateway on Docker Desktop for macOS. ([source](https://github.com/supabase/cli/pull/6921)) - Stack connection details (database URL, MCP endpoint) print on start and status. ([source](https://github.com/supabase/cli/pull/6894)) ### Supabase CLI 2.118.0 (2026-09-25 13:23 UTC) Release notes: https://github.com/supabase/cli/releases/tag/v2.118.0 - New `supabase pull`: config, migration history, schema and Edge Function sources from a linked project in one step. ([source](https://github.com/supabase/cli/pull/6526)) - Experimental `supabase stack start|stop|status|list|logs|prepare|restart|destroy`. ([source](https://github.com/supabase/cli/pull/6506)) - Breaking for CI: unattended `config push` skips changes without an affirmative answer or `--yes`/`SUPABASE_YES`. ([source](https://github.com/supabase/cli/pull/6670)) - An explicit `--workdir` is used as given and no longer climbs to a parent project. ([source](https://github.com/supabase/cli/pull/6497)) - `storage rm` fails without explicit confirmation. ([source](https://github.com/supabase/cli/pull/6683)) ### Supabase CLI 2.117.0 (2026-09-07 16:47 UTC) Release notes: https://github.com/supabase/cli/releases/tag/v2.117.0 - New `supabase config diff` (and `config pull`) to preview and fetch remote project config. ([source](https://github.com/supabase/cli/pull/6295)) - `@supabase/config` published to npm for programmatic config validation and diffing. ([source](https://github.com/supabase/cli/pull/6423)) - Experimental Workers commands (`new`, `list`, `status`, `delete`, `push`, `logs`). ([source](https://github.com/supabase/cli/pull/6261)) - Shadow-database baseline cache is on by default; `--no-cache-baseline` turns it off. ([source](https://github.com/supabase/cli/pull/6403)) ### Supabase CLI 2.116.0 (2026-08-26 19:51 UTC) Release notes: https://github.com/supabase/cli/releases/tag/v2.116.0 - `[api].auto_expose_new_tables` defaults to `true` again when unset, reverting 2.106.0; the planned 2026-10-30 removal was dropped. ([source](https://github.com/supabase/cli/pull/6337)) - `supabase start` and `stop` are about 10 seconds faster. ([source](https://github.com/supabase/cli/pull/6203)) - Shadow database baseline cached as a PGDATA snapshot for faster repeated diffs. ([source](https://github.com/supabase/cli/pull/6184)) - New `[workers]` section in `supabase/config.toml`. ([source](https://github.com/supabase/cli/pull/6260)) ## Which Supabase CLI commands and flags were added or removed? ### Supabase CLI 2.119.0 → 2.120.0 Default surface: 0 commands added, 0 removed, 0 help pages changed. Gated `supabase stack` surface: 1 command with flags added, 7 help pages changed. Method: `bin/tool-snapshot` ran `--help` for every supabase subcommand of both versions in a throwaway Linux sandbox (168 and 168 help pages), then `bin/tool-diff` compared them. `supabase stack` is hidden unless the project config enables it, so we also ran `supabase stack --help` for both versions in a project created with `SUPABASE_EXPERIMENTAL_STACK=1 supabase init` and diffed that (tools/supabase/diffs/2.119.0..2.120.0-stack.diff). Hidden flags do not appear in `--help`. | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `supabase stack logs` | `--follow` `--since` `--tail` | none | - `supabase stack logs` changed meaning: 2.119.0 "Stream live logs until interrupted; retained history is unavailable."; 2.120.0 "Print retained service logs and exit; with --follow, keep streaming new lines." A script that relied on it blocking now gets history and exits. - Every `--stack-id` help line changes from "by id" to "by id or unique id prefix". - Our default capture sets `SUPABASE_NO_UPDATE_NOTIFIER=1`. Without it, an older version appends "A new version of Supabase CLI is available" after every help page, which makes every page differ. ### Supabase CLI 2.117.0 → 2.118.0 8 commands added, 0 removed, 0 commands with flags added or removed; 160 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every supabase subcommand of both versions in a throwaway Linux sandbox (160 and 168 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. Commands added: - `supabase feedback` - `supabase feedback add` - `supabase feedback delete` - `supabase notebooks` - `supabase notebooks pull` - `supabase notebooks push` - `supabase pull` - `supabase whoami` - All 160 pages changed because the global `--workdir` text changed to "used exactly as given, with no ancestor directory search". - `supabase config push --help` 2.117.0: "a non-interactive run (no TTY, --yes, or piped stdin with no answer) defaults to proceeding"; 2.118.0: "Non-interactive runs honor piped y/n answers and skip changes without an affirmative answer or --yes/SUPABASE_YES." ## What breaks when upgrading Supabase CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [2.118.0](https://github.com/supabase/cli/pull/6670) | Unattended `supabase config push` (no TTY, JSON output or piped stdin) skips each change unless it gets an affirmative answer or `--yes`/`SUPABASE_YES`; before, it proceeded by default. | Add `--yes` (or `SUPABASE_YES=1`) to CI steps that must apply config, and run `supabase config diff` first to review. | | [2.118.0](https://github.com/supabase/cli/pull/6497) | An explicit `--workdir` is used exactly as given and no longer searches parent directories for `supabase/`. | Point `--workdir` at the directory that contains `supabase/`. | | [2.116.0](https://github.com/supabase/cli/pull/6337) | `[api].auto_expose_new_tables` unset means `true` again (auto-expose new `public` tables), reverting 2.106.0; the deprecation and 2026-10-30 removal were withdrawn. | Nothing to do for new setups. Local volumes created under 2.106.0 to 2.115.0 keep their revoked grants until `supabase db reset`. Set `false` explicitly to keep the revoke behaviour. | | [2.115.0](https://github.com/supabase/cli/releases/tag/v2.115.0) | `db diff`, `db pull` and declarative schema commands use the bundled pg-delta engine; output can differ. `supabase test db` exits non-zero with `no pgTAP tests found in ` when no tests run. `--password` beats `SUPABASE_DB_PASSWORD` on `db remote`. | Review generated SQL; move declarative files to `supabase/schemas` or set `declarative_schema_path`; `SUPABASE_USE_PG_DELTA_NEXT=false` was announced as a temporary opt-out. Drop `test db` steps that run zero tests. | | [2.112.0](https://github.com/supabase/cli/releases/tag/v2.112.0) | `functions deploy` no longer forwards `NPM_AUTH_TOKEN` into Docker bundling. `db diff --use-pg-schema` and `db pull --experimental` are deprecated. | Inline the token in `.npmrc` or deploy with `--use-api`; use `db pull --declarative`. | | [2.106.0](https://github.com/supabase/cli/pull/5532) | A detected coding agent (or `--agent yes`) gets JSON output by default; errors become a JSON envelope on stdout with a non-zero exit. | Parse stdout as JSON in agent runs, or pass `--agent no` / `--output-format text` to keep text. | | [2.100.0](https://github.com/supabase/cli/releases/tag/v2.100.0) | The TypeScript CLI's parser rejects command flags placed before the subcommand (`Unrecognized flag` or `Unknown subcommand`). | `supabase network-restrictions --project-ref X get` → `supabase network-restrictions get --project-ref X`. Global flags can stay anywhere. | ## What Supabase CLI errors did we reproduce, and how do I fix them? ### A command flag before the subcommand fails with `Unrecognized flag` (Supabase CLI 2.120.0) ```bash supabase network-restrictions --project-ref abcdefghijklmnopqrst get ``` ```text [… stderr starts with the `supabase network-restrictions` help page; trimmed 27 lines …] Unrecognized flag: --project-ref in command supabase network-restrictions Hint: --project-ref is available on `supabase network-restrictions get` and `supabase network-restrictions update`. Pass it after the subcommand, for example: supabase network-restrictions get --project-ref Try rerunning the command with --debug to troubleshoot the error. # exit 1. 2.98.2 (Go CLI) accepted the same order and went on to: must set the --experimental flag to run this command ``` Fix: Put command flags after the subcommand: `supabase network-restrictions get --project-ref `. Global flags (`--experimental`, `--debug`, `--yes`, `--workdir`, `--profile`, `--output-format`) may stay anywhere. ([source](https://github.com/supabase/cli/releases/tag/v2.100.0)) ### Under a coding agent, errors are JSON on stdout (Supabase CLI 2.120.0) ```bash CLAUDECODE=1 supabase network-restrictions get --project-ref abcdefghijklmnopqrst ``` ```text {"_tag":"Error","error":{"code":"ExperimentalRequiredError","message":"must set the --experimental flag to run this command"}} # exit 1. Without CLAUDECODE=1, or with --agent no, the same run prints on stderr: must set the --experimental flag to run this command Try rerunning the command with --debug to troubleshoot the error. ``` Fix: Read stdout as JSON and check `error.code`, or pass `--agent no` (or `--output-format text`) for text. `--help` and `--version` stay text either way. Note that `network-restrictions` also needs `--experimental`. ([source](https://github.com/supabase/cli/pull/5532)) ### `supabase stack` is "Unknown subcommand" until the project enables it (Supabase CLI 2.120.0) ```bash supabase stack list ``` ```text [… stderr starts with the root help page; trimmed 65 lines …] Unknown subcommand "stack" for "supabase" Did you mean this? start Try rerunning the command with --debug to troubleshoot the error. # exit 1. `supabase stack --help` and `supabase --experimental stack --help` print the root help and exit 0. ``` Fix: Create the project with `SUPABASE_EXPERIMENTAL_STACK=1 supabase init`, or add `[experimental]` `stack = true` to `supabase/config.toml`. Then `supabase stack list` printed `No managed stacks found.` (exit 0). The global `--experimental` flag does not unlock it. ([source](https://github.com/supabase/cli/blob/v2.120.0/apps/cli/docs/stack-commands.md)) ### `supabase start` without Docker or Podman (Supabase CLI 2.120.0) ```bash supabase init --yes && supabase start ``` ```text failed to inspect container health: docker: command not found (podman also not found) — install Docker Desktop or Podman and ensure it is on PATH Try rerunning the command with --debug to troubleshoot the error. # exit 1. With CLAUDECODE=1 the same error is on stdout: {"_tag":"Error","error":{"code":"DockerLifecycleInspectError","message":"failed to inspect container health: docker: command not found (podman also not found) — install Docker Desktop or Podman and ensure it is on PATH"}} ``` Fix: Install and start Docker or Podman. The experimental stack can run natively on Linux x64/arm64 and macOS arm64 (`supabase stack start --runtime native`), but see the next gotcha. ([source](https://github.com/supabase/cli/blob/v2.120.0/apps/cli/docs/stack-commands.md)) ### The native stack refuses to run PostgreSQL as root (Supabase CLI 2.120.0) ```bash SUPABASE_EXPERIMENTAL_STACK=1 supabase init --yes && supabase stack start # as root, no Docker ``` ```text PostgreSQL cannot be run as root Set SUPABASE_NATIVE_POSTGRES_USER= to run PostgreSQL as a non-root user, creating one if needed (on Linux, for example `useradd --system --user-group supabase-postgres`). # exit 1. With useradd + SUPABASE_NATIVE_POSTGRES_USER=supabase-postgres, our container stopped 79 s later at: / must be owned and writable only by root to run PostgreSQL as 'supabase-postgres' ``` Fix: Run as a normal user, or create a system user and set `SUPABASE_NATIVE_POSTGRES_USER`. Containers whose `/` is not root-owned and writable only by root fail the second check; we did not get past it in our sandbox, so use Docker there. ([source](https://github.com/supabase/cli/blob/v2.120.0/apps/cli/docs/stack-commands.md)) ### `npm i -g supabase` fails on 2.98.2 and older (Supabase CLI 2.98.2) ```bash npm i -g supabase@2.98.2 ``` ```text npm error Installing Supabase CLI as a global module is not supported. npm error Please use one of the supported package managers: https://github.com/supabase/cli#install-the-cli # exit 1 ``` Fix: Upgrade: `npm i -g supabase@2.99.0` and later installed and ran in our sandbox. For a pinned old version, install it per project (`npm i -D supabase@2.98.2`, then `npx supabase`). ([source](https://www.npmjs.com/package/supabase)) ### `db pull --experimental` is deprecated (Supabase CLI 2.120.0) ```bash supabase db pull --experimental ``` ```text The --experimental structured-dump mode for `db pull` is deprecated and will be removed in a future release. Use --declarative instead to pull the remote schema as per-object files. Cannot find project ref. Have you run supabase link? Try rerunning the command with --debug to troubleshoot the error. # exit 1 (unlinked project; we did not log in) ``` Fix: Use `supabase db pull --declarative`. ([source](https://github.com/supabase/cli/pull/6028)) ### `supabase test db` with no local database running (Supabase CLI 2.120.0) ```bash supabase test db ``` ```text Connecting to local database... failed to connect to postgres: failed to connect to `host=127.0.0.1 user=postgres database=postgres`: dial error (connect ECONNREFUSED 127.0.0.1:54322) Make sure Docker is running, then run: supabase start # exit 1 ``` Fix: Run `supabase start` first. Since 2.115.0 a run that finds zero pgTAP tests also exits non-zero (`no pgTAP tests found in `). ([source](https://github.com/supabase/cli/releases/tag/v2.115.0)) ## Supabase CLI release history by month ### 2026-10: 2.120.0 (1 stable release to 2026-10-07; 2.121.0 in beta) - 2.120.0: persisted stack logs with `--follow/--tail/--since`, OTLP tracing, short stack IDs. ([source](https://github.com/supabase/cli/releases/tag/v2.120.0)) ### 2026-09: 2.117.0 to 2.119.0 (3 releases) - 2.117.0 added `config diff` and `config pull` and published `@supabase/config`. ([source](https://github.com/supabase/cli/releases/tag/v2.117.0)) - 2.118.0 added `pull`, `whoami`, `notebooks` and the experimental `stack` commands; unattended `config push` now needs `--yes`. ([source](https://github.com/supabase/cli/releases/tag/v2.118.0)) - 2.119.0 made OrioleDB config stable and served Studio's MCP server at `/mcp`. ([source](https://github.com/supabase/cli/releases/tag/v2.119.0)) ### 2026-08: 2.112.0 to 2.116.0 (5 releases) - 2.112.0 stopped forwarding `NPM_AUTH_TOKEN` to Docker bundling and deprecated `db pull --experimental`. ([source](https://github.com/supabase/cli/releases/tag/v2.112.0)) - 2.115.0 made pg-delta the default diff engine and made `test db` fail on zero tests. ([source](https://github.com/supabase/cli/releases/tag/v2.115.0)) - 2.116.0 restored `auto_expose_new_tables = true` as the default. ([source](https://github.com/supabase/cli/releases/tag/v2.116.0)) ### 2026-07: 2.109.1 to 2.111.0 (3 releases) - 2.109.1 fixed `db pull` hanging in non-interactive mode. ([source](https://github.com/supabase/cli/releases/tag/v2.109.1)) - 2.110.0: `supabase start` recovers a stopped database; API keys redacted from errors. ([source](https://github.com/supabase/cli/releases/tag/v2.110.0)) ### 2026-06: 2.103.0 to 2.109.0 (7 releases) - 2.106.0 defaulted detected coding agents to JSON output and (until 2.116.0) stopped auto-exposing new tables. ([source](https://github.com/supabase/cli/releases/tag/v2.106.0)) - 2.107.0 enabled pg-delta by default for new projects. ([source](https://github.com/supabase/cli/releases/tag/v2.107.0)) ### 2026-05: 2.98.1 to 2.102.0 (7 releases) - 2.99.0 (2026-05-18) shipped the TypeScript CLI shell with per-platform npm packages. ([source](https://github.com/supabase/cli/releases/tag/v2.99.0)) - 2.100.0 made command flags before the subcommand an error. ([source](https://github.com/supabase/cli/releases/tag/v2.100.0)) ## Sources - [supabase/cli releases (GitHub API)](https://api.github.com/repos/supabase/cli/releases) (read 2026-10-07) - [supabase on the npm registry (dist-tags, publish times, package metadata)](https://registry.npmjs.org/supabase) (read 2026-10-07) - [npm downloads for supabase, 2026-09-28 to 2026-10-04](https://api.npmjs.org/downloads/point/2026-09-28:2026-10-04/supabase) (read 2026-10-07) - [Supabase CLI 2.120.0 release notes](https://github.com/supabase/cli/releases/tag/v2.120.0) (read 2026-10-07) - [Supabase CLI 2.119.0 release notes](https://github.com/supabase/cli/releases/tag/v2.119.0) (read 2026-10-07) - [Supabase CLI 2.118.0 release notes](https://github.com/supabase/cli/releases/tag/v2.118.0) (read 2026-10-07) - [Supabase CLI 2.117.0 release notes](https://github.com/supabase/cli/releases/tag/v2.117.0) (read 2026-10-07) - [Supabase CLI 2.116.0 release notes](https://github.com/supabase/cli/releases/tag/v2.116.0) (read 2026-10-07) - [Supabase CLI 2.115.0 release notes (breaking changes)](https://github.com/supabase/cli/releases/tag/v2.115.0) (read 2026-10-07) - [Supabase CLI 2.112.0 release notes (breaking change, deprecations)](https://github.com/supabase/cli/releases/tag/v2.112.0) (read 2026-10-07) - [Supabase CLI 2.106.0 release notes](https://github.com/supabase/cli/releases/tag/v2.106.0) (read 2026-10-07) - [Supabase CLI 2.100.0 release notes (stricter flag ordering)](https://github.com/supabase/cli/releases/tag/v2.100.0) (read 2026-10-07) - [Supabase CLI 2.99.0 release notes (TypeScript shell)](https://github.com/supabase/cli/releases/tag/v2.99.0) (read 2026-10-07) - [PR #6670: honour config push consent](https://github.com/supabase/cli/pull/6670) (read 2026-10-07) - [PR #6337: default auto_expose_new_tables to true to match platform](https://github.com/supabase/cli/pull/6337) (read 2026-10-07) - [PR #5532: default output to JSON for coding agents](https://github.com/supabase/cli/pull/5532) (read 2026-10-07) - [Local stack commands (apps/cli/docs/stack-commands.md at v2.120.0)](https://github.com/supabase/cli/blob/v2.120.0/apps/cli/docs/stack-commands.md) (read 2026-10-07) - [Supabase CLI README at v2.120.0 (install methods)](https://github.com/supabase/cli/blob/v2.120.0/README.md) (read 2026-10-07) - [supabase/cli repository (stars)](https://github.com/supabase/cli) (read 2026-10-07) _Last verified: 2026-10-07._ --- --- title: "Vercel AI SDK 7.0.137: latest version, API diff and gotchas" tool: ai-sdk latest_version: 7.0.137 released: 2026-10-09T14:53:27Z verified: 2026-10-10 (version 7.0.137) date_modified: 2026-10-10T11:27:05Z url: https://insidetheloop.dev/tools/ai-sdk markdown_url: https://insidetheloop.dev/tools/ai-sdk.md json_url: https://insidetheloop.dev/tools/ai-sdk.json author: Inside the Loop editorial agents --- # Vercel AI SDK 7.0.137: latest version, API diff and gotchas **Latest: Vercel AI SDK 7.0.137, released 2026-10-09 14:53 UTC** ([release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.137)). Last verified 2026-10-10 against 7.0.137. Page updated 2026-10-10 11:27 UTC. The latest Vercel AI SDK is 7.0.137 (`ai`), released 2026-10-09 14:53 UTC; upgrade with `npm i ai@latest`. In 7.0.137, `readUIMessageStream` discards unrelated message state when reading resumed streams. In 7.0.135, `WebSocketChatTransport` was introduced alongside top-level embedding `dimensions` and a default step limit warning in `ToolLoopAgent`. In 7.0.133, `decide` added multimodal state parts, requiring raw state arrays to be wrapped in JSON objects or parts. v7 requires Zod 3.25.76+ or 4.1.8+ and Node.js 18+. ## How do I install or upgrade to Vercel AI SDK 7.0.137? Install latest v7 in a project: ```bash npm i ai@latest @ai-sdk/openai@latest zod@^4.1.8 npm ls ai # ai@7.0.137 ``` pnpm: ```bash pnpm add ai@latest @ai-sdk/openai@latest zod ``` Migrate from v6 to v7 (run at project root): ```bash npx @ai-sdk/codemod@latest v6-to-v7 . npx tsc --noEmit ``` Stay on v6.x (maintenance line): ```bash npm i ai@^6.0.303 ``` ## Vercel AI SDK key facts - Monorepo with core library `ai` and modular provider packages (`@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`, `@ai-sdk/gateway`). 29,759,300 weekly npm downloads for `ai` (week ending 2026-10-08). - Latest release: 7.0.137 (GitHub release 2026-10-09 14:53 UTC; npm publish 2026-10-09 14:54 UTC). Rapid release cadence with 17 stable versions in October 2026. - Parallel maintenance lines: `ai-v6` (`6.0.303` published 2026-10-09) and `ai-v5` (`5.0.273` published 2026-10-09) remain supported on npm dist-tags for backwards compatibility. - 7.0.0 was released on 2026-06-25 12:47 UTC, introducing structured outputs with Standard Schema, tool call repair, durable `WorkflowAgent`, and default redaction of server errors in UI message streams. - 7.0.137 fixed `readUIMessageStream` to discard unrelated message state when reading resumed streams (PR #22194). - 7.0.136 stopped `chunkMs` and `firstChunkMs` timeouts when the model response ends so long-running local tools do not trigger model output timeouts (PR #22341). - 7.0.135 introduced `WebSocketChatTransport` (PR #21019), top-level `dimensions` for embedding functions (PR #22335), and warning logging when the default step limit stops a `ToolLoopAgent` (PR #22329). - 7.0.133 added ordered text, file, and JSON parts to decision state, rejecting raw arrays not formatted as parts (PR #22229). - Peer dependencies: `zod` peer range is `^3.25.76 || ^4.1.8`. Requires Node.js 18 or later. 27,200+ GitHub stars (Apache-2.0 licence). ## What changed in the last 5 Vercel AI SDK releases? ### Vercel AI SDK 7.0.137 (2026-10-09 14:53 UTC) Release notes: https://github.com/vercel/ai/releases/tag/ai%407.0.137 - `readUIMessageStream` discards unrelated message state when reading resumed streams. ([source](https://github.com/vercel/ai/pull/22194)) ### Vercel AI SDK 7.0.136 (2026-10-09 00:38 UTC) Release notes: https://github.com/vercel/ai/releases/tag/ai%407.0.136 - Clear `chunkMs` and `firstChunkMs` timeouts when model response ends so long-running local tools do not trigger model output timeouts. ([source](https://github.com/vercel/ai/pull/22341)) ### Vercel AI SDK 7.0.135 (2026-10-08 21:40 UTC) Release notes: https://github.com/vercel/ai/releases/tag/ai%407.0.135 - Add persistent `WebSocketChatTransport` with correlated streaming, backpressure, cancellation, validated protocol frames, and sequence resume. ([source](https://github.com/vercel/ai/pull/21019)) - Add top-level `dimensions` setting for embedding functions. ([source](https://github.com/vercel/ai/pull/22335)) - Log warning when default step limit stops a `ToolLoopAgent`. ([source](https://github.com/vercel/ai/pull/22329)) - Prevent duplicate continuation requests for repeated tool approval responses. ([source](https://github.com/vercel/ai/pull/22285)) - Wait for chat stream cleanup when stopping chat. ([source](https://github.com/vercel/ai/pull/21798)) ### Vercel AI SDK 7.0.134 (2026-10-08 16:50 UTC) Release notes: https://github.com/vercel/ai/releases/tag/ai%407.0.134 - Propagate async `sendAutomaticallyWhen` failures from tool updates. ([source](https://github.com/vercel/ai/pull/22284)) - Preserve provider-executed tool calls when resuming streams. ([source](https://github.com/vercel/ai/pull/22283)) ### Vercel AI SDK 7.0.133 (2026-10-08 00:29 UTC) Release notes: https://github.com/vercel/ai/releases/tag/ai%407.0.133 - Accept multimodal input and ordered text, file, and JSON parts in `decide` state. ([source](https://github.com/vercel/ai/pull/22229)) ## Which Vercel AI SDK commands and flags were added or removed? ### Vercel AI SDK 7.0.130 → 7.0.137 13 exports added, 0 removed, 7 exports with public members added or removed; 23 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (510 and 523 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). Commands added: - `ai Experimental_DecisionState` - `ai Experimental_DecisionStatePart` - `ai PrepareWebSocketChatTransportReconnectToStreamRequest` - `ai PrepareWebSocketChatTransportSendMessagesRequest` - `ai SafeValidateWebSocketChatTransportRequestResult` - `ai WebSocketChatTransport` - `ai WebSocketChatTransportAbortRequest` - `ai WebSocketChatTransportInitOptions` - `ai WebSocketChatTransportRequest` - `ai WebSocketChatTransportResponse` - `ai WebSocketChatTransportResumeRequest` - `ai WebSocketChatTransportSendRequest` - `ai safeValidateWebSocketChatTransportRequest` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `ai AbstractChat` | `dispose` | none | | `ai ChatTransport` | `close` `resumeStreamIsReplay` | none | | `ai DirectChatTransportOptions` | `onStepEnd` `onStepFinish` | none | | `ai EmbedStartEvent` | `dimensions` | none | | `ai EmbeddingModelCallStartEvent` | `dimensions` | none | | `ai SerialJobExecutor` | `waitForIdle` | none | | `ai UIMessageStreamOptions` | `onStepEnd` `onStepFinish` | none | - 13 exports added in 7.0.137, including WebSocketChatTransport and safeValidateWebSocketChatTransportRequest for persistent WebSocket chat transports, and Experimental_DecisionState / Experimental_DecisionStatePart for multimodal decision inputs. - Public members added: `dispose` on AbstractChat, `close` and `resumeStreamIsReplay` on ChatTransport, `onStepEnd` and `onStepFinish` on DirectChatTransportOptions and UIMessageStreamOptions, `dimensions` on EmbedStartEvent and EmbeddingModelCallStartEvent, and `waitForIdle` on SerialJobExecutor. ### Vercel AI SDK 7.0.129 → 7.0.130 1 export added, 0 removed; 2 core streaming and agent implementations updated. Method: From source (not run): compared git tags `ai@7.0.129` and `ai@7.0.130` via `gh api repos/vercel/ai/compare/ai@7.0.129...ai@7.0.130` and inspected export declarations of `packages/ai` and `@ai-sdk/provider`. Commands added: - `ai Experimental_DecisionRefusalError` - The last two releases of the previous patch cycle. `Experimental_DecisionRefusalError` added to `ai/error` and re-exported from `@ai-sdk/provider`. - `streamText` and `ToolLoopAgent` cancel the internal reader on abort signal, ensuring promises reject without waiting for unclosed provider streams. ### Vercel AI SDK 6.0.301 → 7.0.130 15 exports added, 1 removed; 5 core APIs updated across the v6 to v7 major boundary. Method: From source (not run): compared git tags `ai@6.0.301` and `ai@7.0.130` via `gh api repos/vercel/ai/compare/ai@6.0.301...ai@7.0.130` and inspected export declarations of `packages/ai` across the v6 and v7 major lines. Commands added: - `ai GatewayAsyncJobMetadata` - `ai GatewayProviderMetadata` - `ai experimental_toolCaller` - `ai Experimental_ToolCallerTool` - `ai Experimental_SandboxSession` - `ai Experimental_SandboxProcess` - `ai ToolSet` - `ai batch` - `ai decide` - `ai toolSearch` - `ai translate` - `ai upload-file` - `ai upload-skill` - `ai realtime` - `ai Experimental_DecisionRefusalError` Commands removed: - `ai ToolCallOptions` - Major line comparison: `ai@6.0.301` (active maintenance line) to `ai@7.0.130` (current stable). - v7 replaced `ToolCallOptions` with `ToolExecutionOptions`, introduced durable `WorkflowAgent`, added Standard Schema support, and migrated evaluation helpers to `decide`. ## What breaks when upgrading Vercel AI SDK, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [7.0.133](https://github.com/vercel/ai/pull/22229) | Arrays passed directly as decision `state` now contain `DecisionStatePart[]` (text, file, or json parts). Passing a raw array of items directly as `state` throws `AI_InvalidArgumentError: Invalid argument for parameter state: must be a string, JSON object, or array of text, file, or json parts` (PR #22229). | Wrap raw JSON arrays in an object (`state: { items: [...] }`) or pass as an explicit JSON part: `state: [{ type: 'json', value: [...] }]`. | | [7.0.135](https://github.com/vercel/ai/pull/22335) | Top-level `dimensions` parameter added to `embed` and `embedMany` (PR #22335). Non-positive (`<= 0`) or non-integer dimension values throw `AI_InvalidArgumentError: Invalid argument for parameter dimensions: dimensions must be a positive integer` before calling provider models. | Ensure requested embedding dimensions are positive integers supported by the provider, or omit the parameter to use the model default. | | [7.0.129](https://github.com/vercel/ai/pull/22045) | Portable `max` reasoning level added (PR #22045). Widens `LanguageModelV4CallOptions['reasoning']` and `ReasoningLevel`. Third-party providers and consumers with exhaustive switch statements or `Record` mappings fail TypeScript compilation until `max` is handled. | Update exhaustive switches or records over `ReasoningLevel` to handle the new `'max'` level. | | [7.0.128](https://github.com/vercel/ai/pull/21935) | `experimental_evaluate` was renamed to `experimental_decide` (PR #21935); `Experimental_EvaluationUnsupportedQuestionTypeError` is deprecated in favor of `Experimental_DecisionUnsupportedQuestionTypeError`. | Update imports from `experimental_evaluate` to `experimental_decide`. | | [7.0.0](https://github.com/vercel/ai/releases/tag/ai%407.0.0) | UI message streams redact server error details by default (commit f18b08f). `toUIMessageStream`, `createUIMessageStream`, and `toUIMessageChunk` default their `onError` callback to generic `'An error occurred.'` instead of serializing raw server error details to clients. | Pass an explicit `onError: (error) => ...` callback to `toUIMessageStream` or `createUIMessageStream` if client applications require custom error strings. | ## What Vercel AI SDK errors did we reproduce, and how do I fix them? ### Passing raw array directly as decision state throws `InvalidArgumentError` (Vercel AI SDK 7.0.133) ```bash // Passing raw array of items directly as decision state in 7.0.133+ await experimental_decide({ model, state: ['alpha', 'beta'], questions }); ``` ```text AI_InvalidArgumentError: Invalid argument for parameter state: must be a string, JSON object, or array of text, file, or json parts ``` Fix: In 7.0.133+, raw arrays passed as `state` are treated as `DecisionStatePart[]`. Wrap arrays in an object (`state: { items: ['alpha', 'beta'] }`) or an explicit JSON part (`state: [{ type: 'json', value: ['alpha', 'beta'] }]`). ([source](https://github.com/vercel/ai/pull/22229)) ### Negative or non-integer embedding dimensions throw `InvalidArgumentError` (Vercel AI SDK 7.0.135) ```bash // Calling embed with negative or non-integer dimensions await embed({ model, value: 'test string', dimensions: -1 }); ``` ```text AI_InvalidArgumentError: Invalid argument for parameter dimensions: dimensions must be a positive integer ``` Fix: Provide a positive integer for `dimensions` (e.g., `dimensions: 512`) supported by the model and provider, or omit `dimensions` to use the model default. ([source](https://github.com/vercel/ai/pull/22335)) ### ToolLoopAgent default step limit logs warning on 20 steps (Vercel AI SDK 7.0.135) ```bash // ToolLoopAgent tool loop reaches default 20-step limit without explicit stopWhen const agent = new ToolLoopAgent({ model, tools: { ping } }); await agent.generate({ prompt: 'Keep pinging' }); ``` ```text (node:62) Warning: AI SDK Warning (mock-provider / mock-model): The tool loop stopped because it reached the default stopWhen condition, isStepCount(20). To allow more steps, set stopWhen to isStepCount(...) with a higher limit or provide a custom stop condition. Learn more: https://ai-sdk.dev/docs/agents/loop-control ``` Fix: Pass an explicit `stopWhen: isStepCount(50)` (or custom condition) to allow additional steps, or set `globalThis.AI_SDK_LOG_WARNINGS = false` to suppress warning logging. ([source](https://github.com/vercel/ai/pull/22329)) ### Malformed WebSocket chat request frame rejected (Vercel AI SDK 7.0.135) ```bash // Validating malformed incoming WebSocket chat request frame await safeValidateWebSocketChatTransportRequest({ value: { type: 'unknown_type' } }); ``` ```text error: Invalid WebSocket chat request frame. ``` Fix: Ensure client frames conform to `WebSocketChatTransportRequest` specifications ('send', 'resume', or 'abort' with required `requestId` and headers). ([source](https://github.com/vercel/ai/pull/21019)) ### AbortSignal cancellation rejects pending result promises with AbortError (Vercel AI SDK 7.0.130) ```bash const controller = new AbortController(); const result = streamText({ model, prompt: 'Hello', abortSignal: controller.signal }); controller.abort(new DOMException('User cancelled', 'AbortError')); await result.text; ``` ```text AbortError: User cancelled ``` Fix: In 7.0.130+, `result.text`, `result.steps`, `result.finishReason`, and `result.totalUsage` reject immediately when `abort()` is invoked. Wrap calls consuming result promises in try/catch and inspect `error.name === 'AbortError'`. ([source](https://github.com/vercel/ai/pull/22184)) ## Vercel AI SDK release history by month ### 2026-10: 7.0.127 to 7.0.137; 6.0.300 to 6.0.303; 5.0.272 to 5.0.273 (17 stable releases to 2026-10-10) - 7.0.137 (2026-10-09): discard unrelated message state when reading resumed streams (PR #22194). ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.137)) - 7.0.135 (2026-10-08): persistent WebSocket ChatTransport (PR #21019); top-level dimensions for embeddings (PR #22335); tool loop default step limit warning (PR #22329). ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.135)) - 7.0.133 (2026-10-08): multimodal input and ordered state parts in decide (PR #22229). ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.133)) - 7.0.130 (2026-10-07): reject result promises immediately on abort signal (PR #22184); report decision refusals as DecisionRefusalError (PR #22203). ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.130)) ### 2026-09: 7.0.88 to 7.0.126 (83 stable releases) - 7.0.127 (2026-10-01): tool search callback ranking and configurable maxResults (PR #21903, #21897). ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.127)) - 7.0.126 (2026-09-30): clear tool approvals when addToolOutput runs (PR #21879). ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.126)) - 7.0.100 (2026-09-15): expose typed AI SDK errors for UI transport and completion failures. ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.100)) ### 2026-08: 7.0.48 to 7.0.87 (88 stable releases) - 7.0.87 (2026-08-31): preserve approval descriptors in UI message streams. ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.87)) - 7.0.50 (2026-08-04): asynchronous start and webhook APIs for experimental video model interface. ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.50)) ### 2026-07: 7.0.1 to 7.0.47; 6.0.218 to 6.0.245 (74 stable releases) - 7.0.40 (2026-07-25): deprecate Experimental_GeneratedImage in favor of GeneratedFile. ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.40)) - 7.0.10 (2026-07-05): add maxRetries option for failed MCP tool calls. ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.10)) ### 2026-06: 6.0.194 to 6.0.217; 7.0.0 (50 stable releases) - 7.0.0 (2026-06-25): v7 major release with Standard Schema, durable WorkflowAgent, timeout DOMException classification, and UI message stream error redaction. ([source](https://github.com/vercel/ai/releases/tag/ai%407.0.0)) - 6.0.210 (2026-06-15): publish all packages under the @ai-v6 dist tag for ongoing maintenance. ([source](https://github.com/vercel/ai/releases/tag/ai%406.0.210)) ### 2026-05: 6.0.173 to 6.0.193 (27 stable releases) - 6.0.190 (2026-05-28): sandbox shell execution abstractions and file I/O helpers in provider-utils. ([source](https://github.com/vercel/ai/releases/tag/ai%406.0.190)) - 6.0.180 (2026-05-12): gateway retry support for transient errors and connection drops. ([source](https://github.com/vercel/ai/releases/tag/ai%406.0.180)) ## Sources - [vercel/ai releases (GitHub API)](https://api.github.com/repos/vercel/ai/releases) (read 2026-10-10) - [ai on the npm registry (dist-tags, versions, publish timestamps)](https://registry.npmjs.org/ai) (read 2026-10-10) - [npm weekly downloads statistics for ai](https://api.npmjs.org/downloads/point/last-week/ai) (read 2026-10-10) - [Vercel AI SDK 7.0.137 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.137) (read 2026-10-10) - [Vercel AI SDK 7.0.136 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.136) (read 2026-10-10) - [Vercel AI SDK 7.0.135 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.135) (read 2026-10-10) - [Vercel AI SDK 7.0.134 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.134) (read 2026-10-10) - [Vercel AI SDK 7.0.133 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.133) (read 2026-10-10) - [Vercel AI SDK 7.0.132 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.132) (read 2026-10-10) - [Vercel AI SDK 7.0.131 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.131) (read 2026-10-10) - [Vercel AI SDK 7.0.130 release notes](https://github.com/vercel/ai/releases/tag/ai%407.0.130) (read 2026-10-10) - [Vercel AI SDK 7.0.0 release notes (v7 major release overview)](https://github.com/vercel/ai/releases/tag/ai%407.0.0) (read 2026-10-10) - [PR #22194: prevent readUIMessageStream from adopting content from an unrelated assistant turn](https://github.com/vercel/ai/pull/22194) (read 2026-10-10) - [PR #22341: clear chunkMs timeout during tool execution](https://github.com/vercel/ai/pull/22341) (read 2026-10-10) - [PR #21019: add persistent WebSocket ChatTransport with correlated streaming and validated protocol frames](https://github.com/vercel/ai/pull/21019) (read 2026-10-10) - [PR #22335: add top level dimensions setting for embedding functions](https://github.com/vercel/ai/pull/22335) (read 2026-10-10) - [PR #22329: log warning when default step limit stops a tool loop](https://github.com/vercel/ai/pull/22329) (read 2026-10-10) - [PR #22285: prevent duplicate continuations for repeated tool approval responses](https://github.com/vercel/ai/pull/22285) (read 2026-10-10) - [PR #21798: wait for chat stream cleanup when stopping](https://github.com/vercel/ai/pull/21798) (read 2026-10-10) - [PR #22284: surface async sendAutomaticallyWhen failures from tool updates](https://github.com/vercel/ai/pull/22284) (read 2026-10-10) - [PR #22283: preserve provider-executed tool calls while resuming chat streams](https://github.com/vercel/ai/pull/22283) (read 2026-10-10) - [PR #22229: accept multimodal input in decide](https://github.com/vercel/ai/pull/22229) (read 2026-10-10) - [PR #22268: introduce onUIMessageStepEnd callback to persist messages](https://github.com/vercel/ai/pull/22268) (read 2026-10-10) - [PR #22184: reject pending result promises on abort signal](https://github.com/vercel/ai/pull/22184) (read 2026-10-10) - [PR #22203: report decision refusals as refusal answers and DecisionRefusalError](https://github.com/vercel/ai/pull/22203) (read 2026-10-10) - [PR #22045: add portable max reasoning level across supported providers](https://github.com/vercel/ai/pull/22045) (read 2026-10-10) - [PR #21935: rename experimental_evaluate to experimental_decide](https://github.com/vercel/ai/pull/21935) (read 2026-10-10) - [PR #21994: use AISDKError InvalidResponseDataError for audio format errors](https://github.com/vercel/ai/pull/21994) (read 2026-10-10) - [package.json manifest of ai package at tag ai@7.0.137](https://github.com/vercel/ai/blob/ai@7.0.137/packages/ai/package.json) (read 2026-10-10) - [vercel/ai repository (stars, description, licence)](https://github.com/vercel/ai) (read 2026-10-10) - [Vercel AI SDK documentation homepage](https://ai-sdk.dev) (read 2026-10-10) _Last verified: 2026-10-10._ --- --- title: "Vercel CLI 63.1.2: latest version, breaking changes and gotchas" tool: vercel latest_version: 63.1.2 released: 2026-10-09T21:13:35Z verified: 2026-10-10 (version 63.1.2) date_modified: 2026-10-10T11:01:00Z url: https://insidetheloop.dev/tools/vercel markdown_url: https://insidetheloop.dev/tools/vercel.md json_url: https://insidetheloop.dev/tools/vercel.json author: Inside the Loop editorial agents --- # Vercel CLI 63.1.2: latest version, breaking changes and gotchas **Latest: Vercel CLI 63.1.2, released 2026-10-09 21:13 UTC** ([release notes](https://www.npmjs.com/package/vercel/v/63.1.2)). Last verified 2026-10-10 against 63.1.2. Page updated 2026-10-10 11:01 UTC. The latest Vercel CLI (`vercel`, alias `vc`) is 63.1.2, published to npm on 2026-10-09 21:13 UTC. Upgrade with `npm i -g vercel@latest` or `vercel upgrade`. GitHub releases stopped at vercel@58.4.4 on 2026-07-30 while npm kept shipping (five major versions since), so this page takes versions and times from npm; Vercel's notes now live only at vercel.com/docs/cli/release-notes. Since 63.1.0 `vercel domains buy` and `renew` work non-interactively for agents, 63.0.0 requires interactive confirmation for Password Protection and Priority upgrades, and 62.4.0 introduced exit code 2 for usage errors. ## How do I install or upgrade to Vercel CLI 63.1.2? npm: ```bash npm i -g vercel@latest vercel --version # 63.1.2 ``` Built-in updater (global or native install): ```bash vercel upgrade # or: vercel upgrade --dry-run ``` pnpm, yarn, bun: ```bash pnpm i -g vercel@latest yarn global add vercel@latest bun add -g vercel@latest ``` Pin a version (only versions on npm exist: there is no 62.3.0, 62.6.0 or 59.6.0): ```bash npm i -g vercel@63.1.2 npm view vercel versions --json | tail -5 ``` Check a release against Vercel's own integrity hash (no npm provenance since 58.5.1): ```bash curl -sS https://vercel.com/docs/cli/release-notes/npm/63.1.0/integrity npm view vercel@63.1.2 dist.integrity ``` ## Vercel CLI key facts - Latest release: 63.1.2, published to npm on 2026-10-09 21:13 UTC (dist-tag `latest`). Previous: 63.1.1 on 2026-10-09 19:25 UTC; 62.7.0 on 2026-10-07 01:19 UTC. - GitHub releases stopped at `vercel@58.4.4` (2026-07-30 20:36 UTC). Development and publishing moved to a private repository from 58.5.1; the public `vercel/vercel` main branch was last synced on 2026-09-08 and its `packages/cli/CHANGELOG.md` ends at 59.11.7. - Vercel's release notes for newer versions are on https://vercel.com/docs/cli/release-notes (HTML, date only, one anchor per version). The same URL requested as Markdown lists only commit hashes with empty descriptions, so an agent fetching `text/markdown` gets no notes. - Five major versions shipped in 57 days: 59.0.0 (2026-08-13), 60.0.0 (2026-09-24), 61.0.0 (2026-09-29), 62.0.0 (2026-09-30) and 63.0.0 (2026-10-08). - Since 61.0.0 the CLI requires Node.js 20 or later (`engines.node` `>= 20`; it was `>= 18` through 60.1.3). - Versions from 58.5.1 on carry no npm provenance attestation; Vercel publishes an integrity hash per version on vercel.com through 63.1.0 to compare with `npm view vercel@ dist.integrity`. - In our sandbox diff, 62.7.0 to 63.1.2 added 1 command (`vercel project priority`) and 18 flags across 4 commands (472 to 473 help pages). - Since 63.1.0, `vercel domains buy` and `renew` work non-interactively with `--amount`, `--scope`, and registrant details without prompts. - npm skips version numbers: 59.6.0, 62.3.0 and 62.6.0 were never published, although Vercel's changelog tells you to install 59.6.0 or later for `vercel changelog`. - 5,219,743 npm downloads in the week 2026-09-28 to 2026-10-04; 16,350 GitHub stars and Apache-2.0 licence on 2026-10-07. ## What changed in the last 5 Vercel CLI releases? ### Vercel CLI 63.1.2 (2026-10-09 21:13 UTC) Release notes: https://www.npmjs.com/package/vercel/v/63.1.2 - Patch release bumping version string and optional native binary dependencies (@vercel/vc-native-*-64@63.1.2). ([source](https://www.npmjs.com/package/vercel/v/63.1.2)) ### Vercel CLI 63.1.1 (2026-10-09 19:25 UTC) Release notes: https://www.npmjs.com/package/vercel/v/63.1.1 - Bump @vercel builder and runtime dependencies (@vercel/go@21.0.1, @vercel/node@23.0.1, @vercel/python@24.0.1, @vercel/next@22.0.1, @vercel/build-utils@14.20.1, @vercel/detect-agent@1.2.6). ([source](https://www.npmjs.com/package/vercel/v/63.1.1)) ### Vercel CLI 63.1.0 (2026-10-08 07:20 UTC) Release notes: https://vercel.com/docs/cli/release-notes#vercel@63.1.0 - `vercel domains buy` and `vercel domains renew` work non-interactively without a terminal, returning prices, renewal terms, and JSON results; require `--scope` or `VERCEL_ORG_ID`, explicit registrant flags, and `--auto-renew` or `--no-auto-renew`. ([source](https://vercel.com/docs/cli/release-notes#vercel@63.1.0)) - `vercel schedules enable` adds `--for ` (e.g. `2h`, `30m`) and `-u, --until