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

---
title: CLI
description: Learn about the Better Auth CLI commands for generating and migrating 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 the 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

* `--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.
* `--yes` - Skip the confirmation prompt and generate the schema directly.

## Migrate

The `migrate` command can inspect or apply the Better Auth schema directly to your database. It supports the built-in SQL database configuration and SQL-backed Drizzle or Prisma adapters. Use `generate` and your own migration tooling for other adapters.

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

### 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.
* `--json` - Print one deterministic JSON document instead of human-readable output.
* `--yes` - Skip the confirmation prompt for `migrate apply`.

### Inspect before applying

`migrate plan` only reads the database. Add `--json` in CI or when sharing the plan with a coding agent:

```package-install title="Terminal"
npx auth@latest migrate plan
npx auth@latest migrate plan --json > better-auth-migration-plan.json
```

The JSON plan includes the adapter, dialect, selected and detected account identity strategies, account counts, issuer-resolution coverage, projected collisions, sorted schema changes, blockers, and any release migration actions. A blocked plan exits with status `1`.

### Apply a migration

`migrate apply` confirms and applies the planned data and schema changes together. When a release migration needs decisions that the CLI cannot derive, it saves them to `better-auth-migration.json`; the file identifies the release transition and pins configuration-derived values so another run can review and replay the same choices. Pass the file positionally to either action:

```package-install title="Terminal"
npx auth@latest migrate plan better-auth-migration.json
npx auth@latest migrate apply better-auth-migration.json
```

For non-interactive JSON application, also pass `--yes`; otherwise the command exits without changing the database. Running plain `npx auth@latest migrate` invokes `migrate apply` and prints a deprecation warning. For the current release migration procedure, including Drizzle and Prisma preparation, see the [1.7 upgrade guide](/docs/guides/1-7-upgrade-guide#migrate-from-16-to-17).

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

  The migrate command automatically detects your configured `search_path` and creates tables in the correct schema. See the [PostgreSQL adapter documentation](/docs/adapters/postgresql#use-a-non-default-schema) for configuration details.
</Callout>

## 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 (including SvelteKit's `$lib`) and stubbed framework virtual modules (`$env/*`, `$app/*`, `cloudflare:workers`, Vite assets like `?raw`). For SvelteKit, run `svelte-kit sync` first so `.svelte-kit/tsconfig.json` exists.

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.