Better Auth CLI

1.6.8 verified Thu Apr 23 auth: no javascript

The `auth` package provides the command-line interface (CLI) for Better Auth, an authentication solution. This CLI helps developers manage database schemas required for Better Auth's core functionality and its plugins. As of April 2026, the current stable version is 1.6.8, with a 1.7.0-beta.2 also available, indicating active development with frequent patch and minor releases, alongside pre-releases for upcoming features. Key differentiators include its ability to generate ORM-specific schemas for adapters like Prisma and Drizzle, as well as an SQL file for its built-in Kysely adapter. It also offers commands for initializing a project, applying migrations, and securely generating secret keys for Better Auth instances.

Common errors

error Column 'verified' does not exist on table 'twoFactor' ↓

cause Missing database migration for the two-factor authentication schema change introduced in `better-auth` v1.6.2.

fix

Apply the schema migration by running npx auth@latest generate and then your ORM's specific migration command (e.g., npx prisma migrate dev or npx drizzle-kit push:pg).

error ReferenceError: generate is not defined ↓

cause Attempting to `import` or `require` commands from the `auth` CLI package as if it were a standard library module.

fix

The auth package is a CLI tool. Execute its commands using npx auth@latest generate (or other commands) from your terminal, not by importing into your JavaScript/TypeScript code.

error APIError: Two-factor method 'otp' requires `otpOptions.sendOTP` to be configured on the server ↓

cause Attempted to enable OTP as a two-factor method using an API call without providing the necessary server-side `sendOTP` configuration in `better-auth`.

fix

Ensure your Better Auth server-side configuration includes the otpOptions.sendOTP function to handle sending OTPs to users. This error typically occurs after upgrading to better-auth v1.7.0-beta.0 or later and using enableTwoFactor({ method: "otp" }).

Warnings

breaking The `enableTwoFactor` API in `better-auth` (which the CLI manages configurations for) now accepts an optional `method` parameter (`"otp" | "totp"`) and returns a discriminated response, requiring updates to client-side logic handling two-factor authentication enablement. ↓

fix Update code handling the `enableTwoFactor` response to account for the new discriminated `method` field and potentially pass the `method` parameter when enabling 2FA.

breaking Version 1.6.2 introduced a schema migration requiring the addition of a `verified` column to the `twoFactor` table to prevent unverified TOTP enrollment from blocking sign-in. Failure to apply this migration will result in runtime errors. ↓

fix Run `npx auth@latest generate` followed by your ORM's migration command (e.g., `npx prisma migrate dev` for Prisma, `npx drizzle-kit push:pg` for Drizzle) or `npx auth@latest migrate` if using the built-in Kysely adapter.

gotcha The `auth` package is a CLI tool (`better-auth` CLI), not a library intended for direct `import` or `require` statements in application code. Its functions are executed via `npx` or a globally installed `auth` command. ↓

fix Always invoke the functionality using `npx auth@latest <command>` or by calling the globally installed `auth` executable. Do not attempt to `import { generate } from 'auth'` or similar.

gotcha When using database adapters like Prisma or Drizzle, the `npx auth@latest generate` command only creates the necessary schema files; it does *not* apply the schema to the database. Developers must use their ORM's specific migration tools to apply the generated schema changes. ↓

fix After running `npx auth@latest generate`, execute your ORM's migration command (e.g., `npx prisma migrate dev` or `npx prisma db push` for Prisma, `npx drizzle-kit push:pg` for Drizzle). The `npx auth@latest migrate` command is only for the built-in Kysely adapter.

Install

npm install auth

yarn add auth

pnpm add auth

Quickstart

Demonstrates how to initialize a Better Auth project, generate the necessary database schema, and generate a secret key using the `npx auth@latest` CLI commands.

import { $ } from 'bun'; // Using Bun's shell for demonstration; you can use Node.js child_process

async function runBetterAuthCli() {
  console.log("Initializing Better Auth project...");
  try {
    await $`npx auth@latest init`;
    console.log("Better Auth project initialized successfully.");

    console.log("Generating Better Auth schema...");
    await $`npx auth@latest generate`;
    console.log("Schema generated. Remember to apply ORM migrations if not using Kysely.");

    console.log("Generating a new secret key:");
    const secretResult = await $`npx auth@latest secret`;
    const secret = await secretResult.text();
    console.log(`Generated secret: ${secret.trim()}`);
    console.log("Please add this secret to your environment variables (e.g., BETTER_AUTH_SECRET)");

  } catch (e) {
    console.error("An error occurred during Better Auth CLI operations:", e);
    process.exit(1);
  }
}

runBetterAuthCli();