Better Auth CLI#

The Better Auth CLI (better-auth / auth) is a developer tool for scaffolding, managing, and upgrading Better Auth projects. It is distributed as the @better-auth/cli package and implemented using Commander.js. The CLI entry point is at packages/cli/src/index.ts and exposes the following commands 1:

upgrade Command#

The upgrade command scans package.json for any package matching better-auth or the @better-auth/ scope (excluding workspace: pinned packages) and upgrades them to the latest stable version.

Flow:

1. Reads dependencies and devDependencies from the project's package.json 2.
2. For each candidate package, calls fetchLatestVersion() to resolve the target version.
3. Uses semver.lt() to filter packages where the installed version is behind the resolved version 3.
4. Prompts for confirmation (skippable with --yes) then installs upgrades via the detected package manager 4.

Options:

• -c, --cwd <cwd> — working directory (defaults to process.cwd())
• -y, --yes — skip confirmation prompt

Key Limitation: Stable-Only Upgrades#

fetchLatestVersion() queries the NPM registry's /latest dist-tag endpoint (https://registry.npmjs.org/{package}/latest) 5. NPM's latest tag is always a stable release — it never points to RC, alpha, beta, or any other pre-release version.

Consequence: Running better-auth upgrade will never upgrade to an RC or pre-release version, even if a newer pre-release exists. For example, if the installed version is 1.2.0 and 1.3.0-rc.1 is published but 1.2.3 is the latest stable, the command will upgrade to 1.2.3 and ignore 1.3.0-rc.1.

Workaround: To install a pre-release version, install it directly via your package manager using an explicit dist-tag or version:

npm install better-auth@rc
# or
npm install better-auth@1.3.0-rc.1

There is no --tag or --pre-release flag in the current upgrade command implementation 6.

Related Source Files#