# CLI (/docs/concepts/cli)

了解 Better Auth CLI 命令，这些命令可用于生成、迁移和检查数据库架构、创建初始管理员、初始化项目、生成密钥，以及收集诊断信息。



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

## 生成 (Generate) [#生成-generate]

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

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="终端"
    npx auth@latest generate
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="终端"
    pnpm dlx auth@latest generate
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="终端"
    yarn dlx auth@latest generate
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="终端"
    bun x auth@latest generate
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 选项 [#选项]

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

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

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

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="Terminal"
    npx auth@latest generate --adapter prisma --dialect postgresql
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="Terminal"
    pnpm dlx auth@latest generate --adapter prisma --dialect postgresql
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="Terminal"
    yarn dlx auth@latest generate --adapter prisma --dialect postgresql
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="Terminal"
    bun x auth@latest generate --adapter prisma --dialect postgresql
    ```
  </CodeBlockTab>
</CodeBlockTabs>



<TypeTable type="schemaGeneratorOptions" />

<Callout type="info">
  Kysely 会检查配置的数据库，因此 `--adapter kysely` 不会受 `--dialect` 影响。
</Callout>

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

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

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="终端"
    npx auth@latest migrate
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="终端"
    pnpm dlx auth@latest migrate
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="终端"
    yarn dlx auth@latest migrate
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="终端"
    bun x auth@latest migrate
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 选项 [#选项-1]

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

<Callout type="info">
  **使用非默认架构的 PostgreSQL？**

  设置 `database.schemaName` 以显式选择架构。否则，migrate 命令会使用连接的 `search_path`。有关配置详情，请参阅 [PostgreSQL 适配器文档](/docs/adapters/postgresql#使用非默认模式)。
</Callout>

## 检查 [#检查]

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

```bash title="Terminal"
npx auth@latest check --config ./src/auth.ts
```

### 架构 [#架构]

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

```bash title="Terminal"
npx auth@latest check schema --config ./src/auth.ts
```

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

### 选项 [#选项-2]

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

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

## 创建管理员 [#创建管理员]

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

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="Terminal"
    npx auth@latest create-admin --email admin@example.com --name "Admin" --role admin
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="Terminal"
    pnpm dlx auth@latest create-admin --email admin@example.com --name "Admin" --role admin
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="Terminal"
    yarn dlx auth@latest create-admin --email admin@example.com --name "Admin" --role admin
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="Terminal"
    bun x auth@latest create-admin --email admin@example.com --name "Admin" --role admin
    ```
  </CodeBlockTab>
</CodeBlockTabs>

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

### 选项 [#选项-3]

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

## 初始化 (Init) [#初始化-init]

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

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="终端"
    npx auth@latest init
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="终端"
    pnpm dlx auth@latest init
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="终端"
    yarn dlx auth@latest init
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="终端"
    bun x auth@latest init
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 选项 [#选项-4]

* `--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`）不会被修改。

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="Terminal"
    npx auth@latest upgrade
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="Terminal"
    pnpm dlx auth@latest upgrade
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="Terminal"
    yarn dlx auth@latest upgrade
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="Terminal"
    bun x auth@latest upgrade
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 选项 [#选项-5]

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

## 信息 [#信息]

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

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="终端"
    npx auth@latest info
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="终端"
    pnpm dlx auth@latest info
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="终端"
    yarn dlx auth@latest info
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="终端"
    bun x auth@latest info
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 输出内容 [#输出内容]

该命令会显示以下信息：

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

### 选项 [#选项-6]

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

### 示例 [#示例]

```bash
# 基本用法
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) [#密钥-secret]

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

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash title="终端"
    npx auth@latest secret
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash title="终端"
    pnpm dlx auth@latest secret
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash title="终端"
    yarn dlx auth@latest secret
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash title="终端"
    bun x auth@latest secret
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## 常见问题 (常见问题) [#常见问题-常见问题]

**错误：无法找到模块 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`）。请不要将这些模块放入配置文件的导入依赖图中。