CLI

Better Auth Ruby uses Rails generators and Ruby tasks instead of the upstream Node CLI.

Generate

Generate Rails installation files:

bin/rails generate better_auth:install

Generate database migrations:

bin/rails generate better_auth:migration

The migration generator reads your Better Auth configuration and includes core tables, plugin tables, custom table names, custom fields, and optional rate limit schema.

Options

Rails generators accept standard Rails generator options, such as --skip options provided by Rails itself. Better Auth-specific schema is read from the configured initializer.

Migrate

Run migrations with Rails:

bin/rails db:migrate

For a non-Rails Rack app, use the SQL schema helpers from the core gem and apply the SQL with your own migration tool.

sql = BetterAuth::Schema::SQL.generate(auth.options, adapter: :postgres)
File.write("db/auth_schema.sql", sql)

Options

Use your database adapter or migration tool options when applying generated SQL outside Rails.

Init

The Rails install generator creates an initializer and route mounting code for a typical app.

mount BetterAuth::Rails.app => "/api/auth"

Rails.application.config.better_auth = BetterAuth.auth(
  base_url: "http://localhost:3000/api/auth",
  secret: Rails.application.credentials.fetch(:better_auth_secret),
  database: :active_record,
  email_and_password: {enabled: true}
)

Options

Configure base_url, secret, database, providers, plugins, and storage in the generated initializer.

Info

Inspect the active configuration from Ruby:

auth.options.base_path
auth.options.session
auth.api.endpoints.keys
BetterAuth::Schema.auth_tables(auth.options).keys

For route-level inspection, Rails can list the mounted auth routes:

bin/rails routes | grep auth

Output

The useful inspection output is the resolved Ruby configuration, registered endpoint names, and generated auth tables.

Options

Use the same Ruby object inspection patterns in console, tests, or diagnostics.

Examples

Basic usage:

auth.api.endpoints.keys

Custom config path:

require_relative "../config/auth"

JSON output:

puts JSON.pretty_generate(BetterAuth::Schema.auth_tables(auth.options))

Secret

Use a strong secret for token signing and encrypted cookies.

ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'

Store the value in your framework's credential or environment system:

secret: ENV.fetch("BETTER_AUTH_SECRET")

Common Issues

If generated migrations miss plugin tables, make sure the initializer includes the plugin before running the migration generator.

If callbacks generate untrusted callback URL errors, configure base_url and trusted_origins to match the public origin used by your app.

If requests do not keep sessions, forward Set-Cookie from auth responses and include the cookie header on later server-side calls.