better-auth/docs/content/docs/concepts/cli.mdx

---
icon: conceptsCLI
title: CLI
description: Learn about the Better Auth CLI commands for generating, migrating, and checking database schemas, creating initial admins, initializing projects, generating secret keys, and gathering diagnostic info.
---

Better Auth comes with a built-in CLI to help you manage and check database schemas, create initial admin users, initialize your project, generate a secret key for your application, and gather diagnostic information about your setup.

## Generate

The `generate` command creates the schema required by Better Auth. If you're using a database adapter like Prisma or Drizzle, this command will generate the right schema for your ORM. If you're using the built-in Kysely adapter, it will generate an SQL file you can run directly on your database.

```package-install title="Terminal"
npx auth@latest generate
```

### Options

* `-c, --cwd` - The working directory. Defaults to the current directory.
* `--output` - Where to save the generated schema. For Prisma, it will be saved in prisma/schema.prisma. For Drizzle, it goes to schema.ts in your project root. For Kysely, it's an SQL file saved as schema.sql in your project root.
* `--config` - The path to your Better Auth config file. By default, the CLI will search for an auth.ts file in **./**, **./utils**, **./lib**, or any of these directories under the `src` directory.
* `-y, --yes` - Skip the confirmation prompt and generate the schema directly.
* `--adapter` - The schema generator to use: `prisma`, `drizzle`, or `kysely`.
* `--dialect` - The target database provider. It is required with `--adapter drizzle`. Prisma defaults to `postgresql`.

### Generate Without a Database Connection

Prisma and Drizzle can generate a schema without using the configured database adapter. The CLI still loads your config to include plugins and schema customizations.

```package-install title="Terminal"
npx auth@latest generate --adapter prisma --dialect postgresql
```

export const schemaGeneratorOptions = {
  adapter: {
    description: "The schema generator. Kysely still requires the configured database.",
    type: '"prisma" | "drizzle" | "kysely"',
    required: false,
  },
  dialect: {
    description: 'The Prisma or Drizzle provider. "mongodb" is only supported by Prisma. Drizzle maps "postgresql" to "pg".',
    type: '"postgresql" | "mysql" | "sqlite" | "mongodb"',
    required: false,
  },
}

<TypeTable type={schemaGeneratorOptions} />

<Callout type="info">
  Kysely introspects the configured database, so `--dialect` has no effect with `--adapter kysely`.
</Callout>

If `--adapter` is omitted, the CLI uses the adapter configured in your Better Auth config file. Passing `--dialect` by itself has no effect.

## Migrate

The migrate command applies the Better Auth schema directly to your database. This is available if you're using the built-in Kysely adapter. For other adapters, you'll need to apply the schema using your ORM's migration tool.

```package-install title="Terminal"
npx auth@latest migrate
```

### Options

* `--config` - The path to your Better Auth config file. By default, the CLI will search for an auth.ts file in **./**, **./utils**, **./lib**, or any of these directories under the `src` directory.
* `--yes` - Skip the confirmation prompt and apply the schema directly.

<Callout type="info">
  **Using PostgreSQL with a non-default schema?**

  Set `database.schemaName` to select the schema explicitly. Otherwise, the migrate command uses the connection's `search_path`. See the [PostgreSQL adapter documentation](/docs/adapters/postgresql#use-a-non-default-schema) for configuration details.
</Callout>

## Check

The `check` command runs all available checks. Run it whenever you want to verify your Better Auth setup, manually or in automation:

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

### Schema

The `check schema` command verifies that your configured schema can hold what Better Auth writes. It does not create schema files or apply migrations.

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

The schema check reads the live database for Kysely, the configured schema object for Drizzle, and the generated client model for Prisma. Drizzle and Prisma checks do not confirm that migrations have been applied to the database. If validation is unavailable for your adapter, the command fails instead of silently skipping it. It also runs when runtime validation is disabled with `advanced.database.validateSchema: false`.

### Options

Both `check` and `check schema` accept:

* `-c, --cwd` - The working directory. Defaults to the current directory.
* `--config` - The path to your Better Auth config file. By default, the CLI searches the usual config locations.

## Create Admin

The `create-admin` command creates an initial admin user through your configured Better Auth instance. It requires the Admin plugin and a persistent database, and it uses the same server-side `auth.api.createUser` path as the Admin plugin so passwords are hashed and database hooks still run.

```package-install title="Terminal"
npx auth@latest create-admin --email admin@example.com --name "Admin" --role admin
```

If users already exist, the command asks for confirmation. Use `--force` or `--yes` to skip that prompt.

### Options

* `--email` - The email address for the admin user.
* `--password` - The password for the admin user. If omitted, the CLI will prompt for it.
* `--name` - The name for the admin user. Defaults to `Admin`.
* `--role` - The role to assign. Defaults to `admin`.
* `--data` - Additional user fields as a JSON object.
* `--no-email-verified` - Create the admin user with an unverified email. By default, the CLI marks the admin email as verified.
* `--config` - The path to your Better Auth config file.
* `--force` - Create the admin user even when users already exist.
* `--yes` - Skip the existing-users confirmation prompt.

## Init

The `init` command allows you to initialize Better Auth in your project.

```package-install title="Terminal"
npx auth@latest init
```

### Options

* `--name` - The name of your application. (defaults to the `name` property in your `package.json`).
* `--framework` - The framework your codebase is using. Currently, the only supported framework is `Next.js`.
* `--plugins` - The plugins you want to use. You can specify multiple plugins by separating them with a comma.
* `--database` - The database you want to use. Currently, the only supported database is `SQLite`.
* `--package-manager` - The package manager you want to use. Currently, the only supported package managers are `npm`, `pnpm`, `yarn`, `bun` (defaults to the manager you used to initialize the CLI).

## Upgrade

The `upgrade` command updates older `better-auth` dependencies and official `@better-auth/*` packages that participate in the synchronized release train to the version of the CLI being run. It compares the minimum version allowed by each `package.json` specifier; specifiers whose minimum is the same or newer are left unchanged. Independently versioned packages, such as `@better-auth/utils`, are not changed.

```package-install title="Terminal"
npx auth@latest upgrade
```

### Options

* `--cwd` - The project directory containing the `package.json` to update. Defaults to the current directory.
* `--yes` - Skip the confirmation prompt and install the updates directly.

## Info

The `info` command provides diagnostic information about your Better Auth setup and environment. Useful for debugging and sharing when seeking support.

```package-install title="Terminal"
npx auth@latest info
```

### Output

The command displays:

* **System**: OS, CPU, memory, Node.js version
* **Package Manager**: Detected manager and version
* **Better Auth**: Version and configuration (sensitive data auto-redacted)
* **Frameworks**: Detected frameworks (Next.js, React, Vue, etc.)
* **Databases**: Database clients and ORMs (Prisma, Drizzle, etc.)

### Options

* `--config` - Path to your Better Auth config file
* `--json` - Output as JSON for sharing or programmatic use

### Examples

```bash
# Basic usage
npx auth@latest info

# Custom config path
npx auth@latest info --config ./config/auth.ts

# JSON output
npx auth@latest info --json > auth-info.json
```

Sensitive data like secrets, API keys, and database URLs are automatically replaced with `[REDACTED]` for safe sharing.

## Secret

The CLI also provides a way to generate a secret key for your Better Auth instance.

```package-install title="Terminal"
npx auth@latest secret
```

## Common Issues

**Error: Cannot find module X**

The CLI resolves most imports for you: `tsconfig.json` path aliases, `package.json` subpath imports (including SvelteKit 3's `#lib`), and stubbed framework virtual modules (`$env/*`, `$app/*`, `cloudflare:workers`, Vite assets like `?raw`). On SvelteKit 2, run `svelte-kit sync` first so `.svelte-kit/tsconfig.json` exists and `$lib` resolves.

A few module types can't load outside their bundler (e.g. `.svelte` components or `import.meta.glob`). Keep those out of your config file's import graph.