Railwyrm is a Ruby CLI that bootstraps Rails apps with an opinionated default stack and an interactive feature wizard.
Project page: docs/index.html (Tailwind CSS / GitHub Pages-ready)
- Deterministic Rails app generation
- Interactive wizard for auth/features
- Reproducible defaults for local development
See VISION.md for broader product direction.
Every generated app includes:
- PostgreSQL (
rails new --database=postgresql) - Tailwind CSS (
rails new --css=tailwind+./bin/rails tailwindcss:install) - RSpec (
gem "rspec-rails"+bin/rails generate rspec:install) - Dotenv (
gem "dotenv-rails"in development/test) - Ruby LSP (
gem "ruby-lsp", require: falsein development) - Brakeman (
gem "brakeman", require: falsein development/test) - RuboCop (
gem "rubocop"+gem "rubocop-rails"in development/test) - Bullet (
gem "bullet"in development + auto-configured inconfig/environments/development.rb) - GitHub Actions CI (
.github/workflows/ci.ymlrunning RSpec, RuboCop, and Brakeman) - Devise (
gem "devise"+ install + user generation by default) - Active Storage (
bin/rails active_storage:install) - ActionText (
bin/rails action_text:install)
Rails compatibility behavior:
- Railwyrm targets Ruby
3.4for generated apps:.ruby-versiongets3.4.0, and the Gemfile getsruby "~> 3.4.0"so any 3.4.x patch release can bundle. - Railwyrm generates with a Rails version it chooses rather than whatever happens to be installed:
it runs
rails _8.1.3.1_ new, so the Gemfile it produces is already correct instead of being rewritten afterwards. Install it withgem install rails -v 8.1.3.1;railwyrm doctorchecks for it. - Override with
--rails_version 8.0.3if you need an older one.
During railwyrm new, the wizard can configure:
- Devise user generation (on/off)
- Devise optional modules:
confirmablelockabletimeoutabletrackablemagic_link(viadevise-passwordless)passkeys(viadevise-webauthn)
Magic-link behavior:
- Installs
devise-passwordless - Adds passwordless sign-in routes and UI
- Enables
Devise.paranoid = true - Auto-enables
trackable - Configures development mail delivery to file output at
tmp/mails - Installs a plain-text magic-link template for copy/paste-friendly URLs in development
Passkeys behavior:
- Installs
devise-webauthn - Runs
bin/rails generate devise:webauthn:install --force - Adds
:passkey_authenticatableto the Devise model - Configures
config/initializers/webauthn.rbdefaults forrp_name(generated app name),rp_id, and localhost origins - Populates
.env.examplewithWEBAUTHN_RP_NAME,WEBAUTHN_RP_ID, andWEBAUTHN_ALLOWED_ORIGINS - Ensures WebAuthn JavaScript is loaded as an ES module
- Adds passkey sign-in button on Devise sign-in page
- Redirects first sign-in users (without passkeys) to passkey enrollment
- Runs migrations for the generated WebAuthn tables
Passkeys production checklist:
- Run the app under HTTPS in production.
- Set
WEBAUTHN_RP_IDto your real domain (for exampleapp.example.com). - Set
WEBAUTHN_ALLOWED_ORIGINSto your exact HTTPS origin list (for examplehttps://app.example.com).
Passkeys smoke test checklist (generated app):
- Sign in with email/password and verify you are redirected to the passkey enrollment page on first sign-in.
- Create a passkey and confirm the page no longer forces enrollment on next sign-in.
- Sign out and use "Sign in with passkey" from the sign-in page to confirm passwordless passkey authentication works.
CI behavior:
- Generates
.github/workflows/ci.ymlby default for new apps - Provides
railwyrm feature install ci --app /path/to/appfor existing apps - Workflow runs database prep, RSpec, RuboCop, and Brakeman on push/pull_request
- Generator normalizes default Bullet/Devise config formatting to keep RuboCop green in fresh apps
Quality feature behavior:
- Provides
railwyrm feature install quality --app /path/to/appfor existing apps - Automatically installs dependency
ci(workflow setup) when missing - Ensures
brakeman,rubocop,rubocop-rails, andbulletgems are present - Injects Bullet development config (
Bullet.enable, alerts, and Rails logger hooks)
git clone https://github.com/kurenn/railwyrm
cd railwyrm
./install.shThat builds the gem and installs it for the current user, putting railwyrm in
~/.local/bin (override with RAILWYRM_BIN_DIR, or set
RAILWYRM_INSTALL_SCOPE=system to install system-wide). Add the bin directory to
your PATH if it isn't already, then:
railwyrm doctordoctor checks for Ruby, Bundler, git, and the exact Rails version Railwyrm
generates with — install that one with gem install rails -v 8.1.3.1.
railwyrm newNon-interactive example:
railwyrm new my_app --interactive=false --path /tmp --devise_magic_linkInstall features into an existing app:
railwyrm feature list
railwyrm feature status --app /path/to/existing_app
railwyrm feature sync --app /path/to/existing_app
railwyrm feature install magic_link --app /path/to/existing_app
railwyrm feature install ci --app /path/to/existing_app
railwyrm feature install quality --app /path/to/existing_appTo run from a clone without installing, prefix any command with
bundle exec ruby exe/railwyrm instead of railwyrm.
Feature state tracking:
- Railwyrm records installed features in
.railwyrm/features.ymlinside each generated app. feature installuses tracked state plus app detection to skip already-installed features safely.feature statusshowsinstalled,tracked_only, anddetected_onlyfeature sets for diagnostics.feature syncrebuilds.railwyrm/features.ymlfrom detected app state.
railwyrm new [APP_NAME]
railwyrm feature list
railwyrm feature status --app /path/to/app
railwyrm feature sync --app /path/to/app
railwyrm feature install FEATURE [FEATURE ...] --app /path/to/app
railwyrm serve
railwyrm doctor
railwyrm versionCommon flags:
--no-bannerhide mascot/banner--verbosestream command output--dry_runprint commands without executing--skip_devise_userskip Devise model generation--devise_confirmableenable Devise confirmable--devise_lockableenable Devise lockable--devise_timeoutableenable Devise timeoutable--devise_trackableenable Devise trackable--devise_magic_linkenable magic-link sign-in--devise_passkeysenable passkeys sign-in (WebAuthn)--rails_versionRails version used to generate the app (default8.1.3.1)
Server mode (railwyrm serve):
- Binds
0.0.0.0by default; pass--host 127.0.0.1to keep it local. POST /api/appsrunsrails newandbundle installon the host, so only serve on networks you trust.- Generation is confined to
--workspace; paths outside it are rejected with422.
Feature install options:
--apppath to the existing Rails app--devise_user_modelDevise model name (defaultUser)--dry_runshow commands without executing--verbosestream command output
Installable features:
confirmablelockabletimeoutabletrackablemagic_link(automatically installstrackable)passkeysciquality(automatically installsci)
Run tests:
bundle exec rspecThe end-to-end spec generates a real Rails app, so it is excluded by default. It
needs PostgreSQL running and the Rails version from railwyrm doctor:
RUN_E2E=1 bundle exec rspec spec/e2eCI runs it nightly, and builds and installs the gem on every push so a packaging mistake cannot reach users.
- Bump
Railwyrm::VERSIONinlib/railwyrm/version.rb. bundle exec rspecandRUN_E2E=1 bundle exec rspec spec/e2e.- Merge to
mainand confirm theBuilt gem is usablejob passes. - Tag it:
git tag v$(ruby -Ilib -rrailwyrm/version -e 'print Railwyrm::VERSION') && git push --tags. - Publish if desired:
gem build railwyrm.gemspec && gem push railwyrm-*.gem.
exe/railwyrmCLI entrypointlib/railwyrm/cli.rbThor commandslib/railwyrm/generator.rbnew-app generation workflowlib/railwyrm/feature_installer.rbfeature installs for existing appslib/railwyrm/app_patcher.rbthe in-place edits both of those sharelib/railwyrm/rails_blueprint.rbstack defaults and setup commandsspec/e2e/generates a real Rails app; run withRUN_E2E=1 bundle exec rspec spec/e2elib/railwyrm/templates/devise/{passkeys,passwordless}magic-link and passkey auth templatesAGENTS.mdCodex repo instructions