Use a generator for the feature you want, review its changes, and run the host checks afterward.
Before running a generator
Install the RubyGems package using the quickstart, then run these commands from your Rails app’s root directory. The host must have the Rails authentication generator’s account, session and authentication files. Make your host changes reviewable before generating migrations.
Start with the configuration file
bin/rails generate add_auth:installOpen config/initializers/add_auth.rb before enabling features. Install writes it only when absent; rerunning the command never refreshes or replaces your settings. Use the feature-enablement guide to choose the next generator and the values it needs.
The generated file leaves defaults active and alternatives commented out. See configuration setup for examples, password-only account setup and existing-initializer upgrades.
Choose a command
Command after bin/rails | What it changes |
|---|---|
generate add_auth:install | Checks host files, writes configuration if absent and runs doctor. Enables no features. |
generate add_auth:session_upgrade | Adds session migrations, lifecycle wiring, password sign-in and session-management routes. |
generate add_auth:email_link | Invokes session adoption and token persistence, adds delivery/binding migrations and email routes. |
generate add_auth:challenge turnstile | Writes provider configuration for Turnstile. |
generate add_auth:challenge recaptcha --version=v2 | Writes reCAPTCHA configuration for the selected version. |
generate add_auth:views --only=email_link | Copies sign-in partials and dedicated layouts, preserving existing files. |
generate add_auth:views --only=sessions | Copies session-management views, preserving existing files. |
Enable additional account features
Command after bin/rails | What it changes |
|---|---|
generate add_auth:step_up | Installs session/email prerequisites, proof persistence and reauthentication routes. Declare your host's purposes before use. |
generate add_auth:notifications | Installs hardened sessions and security-event persistence; enables security mail. |
generate add_auth:passkeys | Installs session/email/step-up/notification prerequisites, credential and ceremony tables, passkey management and recovery routes, and account policy fields. |
generate add_auth:email_tokens | Creates token persistence only. The email-link generator invokes it; it is not a standalone sign-in feature. |
Use the feature guides for reauthentication, passkeys, recovery and security emails. Configure each feature, apply migrations and restart the host before trying its routes.
Optional migration and native features
Command after bin/rails | What to review |
|---|---|
generate add_auth:devise_accounts | Adds canonical account columns while retaining source IDs and fields. Does not backfill or switch authority. Follow the migration procedure. |
generate add_auth:accounts | Prepares optional lifecycle persistence, delivery and routes. Review account policies before enabling account lifecycle. |
generate add_auth:external_identities | Prepares identity and transaction persistence. The host supplies maintained provider libraries and registrations; see provider sign-in. |
generate add_auth:mobile_sessions | Prepares mobile session and handoff persistence and configuration. Select explicit client and expiry settings in mobile authentication. |
Use bin/rails generate add_auth:accounts --no-email-link or bin/rails generate add_auth:step_up --no-email-link to install password-only dependencies. These options preserve an already-enabled email-link feature. Follow password-only setup for the final configuration checks.
Copy presentation files into your app
bin/rails generate add_auth:views --only=passkeys
bin/rails generate add_auth:views --only=step_up
bin/rails generate add_auth:controllers
bin/rails generate add_auth:javascript
bin/rails generate add_auth:mailer_viewsThe passkey view group includes recovery; the default view group is email_link. These generators preserve existing files and record an upstream baseline for upgrades. Follow styling and ejection before changing policy-related wiring.
Inspect the host with doctor
bin/rails add_auth:doctorDoctor checks enabled session, email, passkey, reauthentication, recovery, notification and challenge wiring, enabled lifecycle/provider/mobile prerequisites, plus generated-file drift. Fix reported issues and run it again. It does not replace delivered-email/browser checks or establish production readiness.
Recover pending delivery
bin/rails add_auth:deliver_pendingSchedule at least once a minute for deployed hosts. See maintenance and retention for retry, cancellation and monitoring responsibilities.
After generation
Review the file and migration diff, run bin/rails db:migrate, restart the app and check the actual route. Rerunning supported generators is intended to preserve your edits; inspect conflicts in customized Rails hosts rather than assuming an exact template match.