CLI

Better Auth 内置了 CLI，可帮助你管理和检查数据库架构、创建初始管理员用户、初始化项目、为应用生成密钥，以及收集有关设置的诊断信息。

生成 (Generate)

generate 命令创建 Better Auth 所需的数据库架构。如果你使用的是 Prisma 或 Drizzle 等数据库适配器，该命令会为你的 ORM 生成正确的架构。如果你使用的是内置的 Kysely 适配器，它会生成一个 SQL 文件，可以直接在数据库上执行。

npx auth@latest generate

选项

• -c, --cwd - 工作目录。默认为当前目录。
• --output - 保存生成架构的位置。对于 Prisma，它将保存于 prisma/schema.prisma。对于 Drizzle，它将保存于项目根目录中的 schema.ts。对于 Kysely，它是一个保存于项目根目录中、名为 schema.sql 的 SQL 文件。
• --config - Better Auth 配置文件的路径。默认情况下，CLI 会在 ./、./utils、./lib 中，或 src 目录下的任意这些目录中搜索 auth.ts 文件。
• -y, --yes - 跳过确认提示并直接生成架构。
• --adapter - 要使用的架构生成器：prisma、drizzle 或 kysely。
• --dialect - 目标数据库提供商。与 --adapter drizzle 一起使用时必需。Prisma 默认为 postgresql。

在没有数据库连接的情况下生成

Prisma 和 Drizzle 可以在不使用已配置数据库适配器的情况下生成架构。CLI 仍会加载你的配置，以包含插件和架构自定义。

npx auth@latest generate --adapter prisma --dialect postgresql

如果省略 --adapter，CLI 将使用 Better Auth 配置文件中配置的适配器。单独传递 --dialect 不会产生任何影响。

migrate 命令直接将 Better Auth 架构应用到数据库。此功能适用于使用内置 Kysely 适配器的情况。其他适配器需要使用对应 ORM 的迁移工具来应用架构。

npx auth@latest migrate

选项

• --config - Better Auth 配置文件的路径。默认情况下，CLI 会在 ./、./utils、./lib 或 src 目录下的这些目录中搜索 auth.ts 文件。
• --yes - 跳过确认提示并直接应用架构。

检查

check 命令会运行所有可用的检查。无论是手动操作还是在自动化流程中，只要想验证 Better Auth 设置，都可以运行此命令：

npx auth@latest check --config ./src/auth.ts

架构

check schema 命令会验证配置的架构能否容纳 Better Auth 写入的数据。它不会创建架构文件或应用迁移。

npx auth@latest check schema --config ./src/auth.ts

对于 Kysely，架构检查会读取实时数据库；对于 Drizzle，则读取配置的架构对象；对于 Prisma，则读取生成的客户端模型。Drizzle 和 Prisma 检查不会确认迁移是否已应用到数据库。如果适配器不支持验证，该命令会失败，而不是静默跳过检查。即使通过 advanced.database.validateSchema: false 禁用了运行时验证，该检查仍会运行。

选项

check 和 check schema 均接受以下选项：

• -c, --cwd - 工作目录。默认为当前目录。
• --config - Better Auth 配置文件的路径。默认情况下，CLI 会在常见配置位置中搜索。

创建管理员

create-admin 命令通过你配置的 Better Auth 实例创建初始管理员用户。它要求使用 Admin 插件和持久化数据库，并且使用与 Admin 插件相同的服务器端 auth.api.createUser 路径，因此密码会被哈希处理，数据库钩子也仍然会运行。

npx auth@latest create-admin --email [email protected] --name "Admin" --role admin

如果已经存在用户，该命令会请求确认。使用 --force 或 --yes 可以跳过该提示。

选项

• --email - 管理员用户的电子邮件地址。
• --password - 管理员用户的密码。如果省略，CLI 会提示你输入。
• --name - 管理员用户的名称。默认为 Admin。
• --role - 要分配的角色。默认为 admin。
• --data - 以 JSON 对象形式提供的其他用户字段。
• --no-email-verified - 创建电子邮件未经验证的管理员用户。默认情况下，CLI 会将管理员电子邮件标记为已验证。
• --config - Better Auth 配置文件的路径。
• --force - 即使已经存在用户，也创建管理员用户。
• --yes - 跳过现有用户确认提示。

初始化 (Init)

init 命令允许你在项目中初始化 Better Auth。

npx auth@latest init

选项

• --name - 应用程序名称（默认为 package.json 中的 name 属性）。
• --framework - 代码库使用的框架。目前唯一支持的框架是 Next.js。
• --plugins - 要使用的插件，可以通过逗号分隔指定多个插件。
• --database - 要使用的数据库。目前唯一支持的数据库是 SQLite。
• --package-manager - 要使用的包管理器。目前唯一支持的包管理器是 npm、pnpm、yarn、bun（默认为初始化 CLI 时使用的包管理器）。

升级

upgrade 命令会将较旧的 better-auth 依赖项和参与同步发布流程的官方 @better-auth/* 软件包更新到当前运行的 CLI 版本。它会比较每个 package.json 版本说明符所允许的最低版本；最低版本相同或更高的说明符将保持不变。独立进行版本管理的软件包（例如 @better-auth/utils）不会被修改。

npx auth@latest upgrade

选项

• --cwd - 包含要更新的 package.json 的项目目录。默认为当前目录。
• --yes - 跳过确认提示，直接安装更新。

信息

info 命令提供 Better Auth 设置和环境的诊断信息，适合调试和寻求帮助时共享。

npx auth@latest info

输出内容

该命令会显示以下信息：

• 系统: 操作系统、CPU、内存、Node.js 版本
• 包管理器: 检测到的管理器及其版本
• Better Auth: 版本和配置（敏感数据自动脱敏）
• 框架: 检测到的框架（Next.js、React、Vue 等）
• 数据库: 数据库客户端和 ORM（Prisma、Drizzle 等）

选项

• --config - Better Auth 配置文件的路径
• --json - 以 JSON 格式输出，便于共享或程序化处理

示例

# 基本用法
npx auth@latest info

# 指定配置路径
npx auth@latest info --config ./config/auth.ts

# JSON 格式输出
npx auth@latest info --json > auth-info.json

敏感数据（如密钥、API 密钥、数据库 URL）会被自动替换为 [REDACTED]，确保安全共享。

密钥 (Secret)

CLI 还提供了生成 Better Auth 实例密钥的方法。

npx auth@latest secret

常见问题 (常见问题)

错误：无法找到模块 X

CLI 会为你解析大多数导入：tsconfig.json 路径别名、package.json 子路径导入（包括 SvelteKit 3 的 #lib），以及框架提供的虚拟模块存根（$env/*、$app/*、cloudflare:workers 和带有 ?raw 的 Vite 资源）。使用 SvelteKit 2 时，请先运行 svelte-kit sync，确保 .svelte-kit/tsconfig.json 存在并能解析 $lib。

有少数模块类型无法在其打包器环境之外加载（例如 .svelte 组件或 import.meta.glob）。请不要将这些模块放入配置文件的导入依赖图中。