{"id":17499,"library":"auth","title":"Better Auth CLI","description":"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.","status":"active","version":"1.6.8","language":"javascript","source_language":"en","source_url":"https://github.com/better-auth/better-auth","tags":["javascript","auth","cli","typescript","better-auth"],"install":[{"cmd":"npm install auth","lang":"bash","label":"npm"},{"cmd":"yarn add auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add auth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"import { $ } from 'bun'; // Using Bun's shell for demonstration; you can use Node.js child_process\n\nasync function runBetterAuthCli() {\n  console.log(\"Initializing Better Auth project...\");\n  try {\n    await $`npx auth@latest init`;\n    console.log(\"Better Auth project initialized successfully.\");\n\n    console.log(\"Generating Better Auth schema...\");\n    await $`npx auth@latest generate`;\n    console.log(\"Schema generated. Remember to apply ORM migrations if not using Kysely.\");\n\n    console.log(\"Generating a new secret key:\");\n    const secretResult = await $`npx auth@latest secret`;\n    const secret = await secretResult.text();\n    console.log(`Generated secret: ${secret.trim()}`);\n    console.log(\"Please add this secret to your environment variables (e.g., BETTER_AUTH_SECRET)\");\n\n  } catch (e) {\n    console.error(\"An error occurred during Better Auth CLI operations:\", e);\n    process.exit(1);\n  }\n}\n\nrunBetterAuthCli();","lang":"typescript","description":"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."},"warnings":[{"fix":"Update code handling the `enableTwoFactor` response to account for the new discriminated `method` field and potentially pass the `method` parameter when enabling 2FA.","message":"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.","severity":"breaking","affected_versions":">=1.7.0-beta.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.6.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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`).","cause":"Missing database migration for the two-factor authentication schema change introduced in `better-auth` v1.6.2.","error":"Column 'verified' does not exist on table 'twoFactor'"},{"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.","cause":"Attempting to `import` or `require` commands from the `auth` CLI package as if it were a standard library module.","error":"ReferenceError: generate is not defined"},{"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\" })`.","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`.","error":"APIError: Two-factor method 'otp' requires `otpOptions.sendOTP` to be configured on the server"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}