Railstart

Gem Version Documentation CI

Interactive CLI wizard for generating Rails 8 applications with customizable configuration and smart defaults.

Think of it as rails new with an opinion and a friendly interactive experience.

Installation

gem install railstart

Usage

Quick Start

# Generate config files (optional, for customization)
railstart init

# Generate a new Rails app
railstart new my_app

# Or run without arguments for help
railstart

This launches an interactive wizard that guides you through Rails app setup:

Which database?
1) SQLite (default)
2) PostgreSQL
3) MySQL
> 2

Which CSS framework?
1) Tailwind (default)
2) Bootstrap
3) Bulma
4) PostCSS
5) None
> 1

Which JavaScript bundler?
1) Importmap (default)
2) esbuild
3) Webpack
4) Rollup
> 1

Skip any features?
(space to select, enter when done)
‣ ⓞ Action Mailer
  ⓞ Action Mailbox
  ⓞ Action Text
  ...

Generate API-only app?
> No

... (more questions) ...

Summary
════════════════════════════════════════
App name: my_app
Database: postgresql
CSS: tailwind
JavaScript: importmap
Skipped: (none)
API: No
════════════════════════════════════════

Proceed with app generation? Yes

Running: rails new my_app --database=postgresql --css=tailwind ...

Creating Rails app...
✨ Rails app created successfully at ./my_app

Use Presets

Presets are configuration overlays that let you define different defaults and even different questions/post-actions for specific use cases.

Important: When you use --default without --preset, Railstart automatically applies the default preset (from ~/.config/railstart/presets/default.yaml or the gem's built-in version). This means defaults may differ from the base rails8_defaults.yaml config.

Modes:

  • Interactive (default): prompts for each question from the config schema
  • With --default: skips questions, loads "default" preset, shows summary and confirms
  • With --preset: loads specified preset as config overlay (can be interactive or with --default)
# Interactive mode (builtin defaults)
railstart new my_app

# Non-interactive with "default" preset (asks no questions, shows summary + confirms)
# Note: --default automatically loads the "default" preset (user or gem)
railstart new my_app --default

# Interactive with custom preset
railstart new my_app --preset api-only

# Non-interactive with custom preset
railstart new my_app --preset api-only --default

Create custom presets at ~/.config/railstart/presets/my-preset.yaml:

Presets use the same YAML schema as config files - they can override question defaults, change choices, add new questions, or modify post-actions:

# ~/.config/railstart/presets/api-only.yaml
# Presets merge on top of user config (and built-in config)
questions:
  - id: database
    choices:
      - name: PostgreSQL
        value: postgresql
        default: true  # Different default for this preset

  - id: api_only
    default: true  # Override default to true for API preset

post_actions:
  - id: init_git
    enabled: false  # Disable git init for this preset

Then use it:

# Interactive with api-only config
railstart new my_app --preset api-only

# Non-interactive with api-only config
railstart new my_app --preset api-only --default

Creating Custom Presets

Presets are powerful tools for defining opinionated Rails configurations for specific stacks or team standards.

Quick Preset Creation

Create a new preset file in config/presets/{name}.yaml:

---
# My Team Preset - PostgreSQL + RSpec + Vite

questions:
  - id: database
    choices:
      - name: PostgreSQL
        value: postgresql
        default: true

  - id: javascript
    choices:
      - name: Vite (via vite_rails gem)
        value: vite
        default: true

  - id: test_framework
    choices:
      - name: RSpec
        value: rspec
        default: true

post_actions:
  - id: setup_vite
    enabled: true

  - id: setup_rspec
    enabled: true

Then use it:

# Interactive mode - prompts for each question
railstart new myapp --preset my-team

# Non-interactive mode - uses all preset defaults
railstart new myapp --preset my-team --default

Built-in Presets

Railstart includes several ready-to-use presets:

  • default - PostgreSQL + Tailwind + Importmap (sensible defaults)
  • api-only - Minimal Rails for JSON APIs (no views, no frontend)
  • vite-bun - Modern SPA with Vite + Bundlebun

Configuration

Initialize Configuration Files

The easiest way to get started with custom configuration is to generate template files:

railstart init

This creates:

  • ~/.config/railstart/config.yaml - Complete configuration template (copy of rails8_defaults.yaml with all available options)
  • ~/.config/railstart/presets/ - Directory for your presets
  • ~/.config/railstart/presets/example.yaml - Example preset to get started

The generated config.yaml shows all available questions, choices, flags, and post-actions. You can delete or comment out sections you don't want to customize, and modify the defaults for sections you do want to change.

Built-in Defaults

Railstart ships with sensible Rails 8 defaults defined in config/rails8_defaults.yaml. These drive the interactive questions and their defaults.

Customize for Your Team

You can create ~/.config/railstart/config.yaml manually or use railstart init to generate a complete template file. The template includes all available options, so you can simply modify the defaults you want to change:

# After running `railstart init`, your config.yaml will contain all options.
# Simply modify the defaults you want to change:

questions:
  - id: database
    choices:
      - name: PostgreSQL (recommended)
        value: postgresql
        default: true  # Changed from SQLite to PostgreSQL

  # ... other questions with their full configuration ...

post_actions:
  - id: bundle_install
    enabled: false  # Disabled - your team manages gems differently

  - id: setup_auth
    name: "Setup authentication"
    enabled: true
    command: "bundle exec rails generate devise:install"  # New custom action

Merge behavior:

  • User config (at ~/.config/railstart/config.yaml) overrides built-in config
  • By id: questions and post-actions are merged by their unique id
  • If you override a question's choices, the entire choice list is replaced
  • New questions/actions are appended in order

Configuration Schema

Questions

questions:
  - id: database                    # unique identifier
    type: select|multi_select|yes_no|input
    prompt: "User-facing question"
    help: "Optional inline help text"
    default: value_or_true_or_false

    # For select/multi_select
    choices:
      - name: "Display name"
        value: "internal_value"
        default: true              # at most one per select
        rails_flag: "--flag=%{value}"

    # For yes_no/input
    rails_flag: "--flag"            # or --flag=%{value}

    # Optional: only ask if condition is met
    depends_on:
      question: other_question_id
      value: expected_value

Question types:

  • select - Single choice; returns scalar value
  • multi_select - Multiple choices; returns array
  • yes_no - Boolean; returns true/false
  • input - Free text; returns string

Post-actions

post_actions:
  - id: my_action                   # unique identifier
    name: "Human readable name"
    enabled: true                   # can be disabled
    command: "shell command to run"

    # Optional: prompt user before running
    prompt: "Run this action?"
    default: true

    # Optional: only run if condition is met
    if:
      question: question_id
      equals: value                 # or includes: [array, values]

Template Post-Actions

Post-actions can now execute full Rails application templates (including RailsBytes scripts) instead of plain shell commands.

post_actions:
  - id: apply_tailwind_dash
    name: "Apply Tailwind dashboard template"
    type: template
    enabled: false             # keep disabled unless you trust the source
    prompt: "Run the sample template?"
    source: "https://railsbytes.com/script/zAasQK"
    variables:
      app_label: "internal-tools"  # optional instance variables available inside template

Key differences from command actions:

  • Set type: template and provide a source (local path or URL). Railstart streams that template into Rails' own apply helper, so all standard DSL commands (gem, route, after_bundle, etc.) are available.
  • variables is optional; when present, its keys become instance variables accessible from the template (e.g., @app_label). Railstart always exposes @app_name and @answers for convenience.
  • Template actions still honor prompt, default, and if just like command actions. Keep remote templates disabled by default unless you explicitly trust them.

Development

Setup

# Install dependencies
bundle install

# Or use the setup script
bin/setup

Testing the CLI

# Test the executable during development
bundle exec exe/railstart new my_app
bundle exec exe/railstart new my_app --default

# Interactive console for experimenting
bin/console
# Then in IRB:
# Railstart::CLI.start(["new", "my_app"])

# Install locally to test as a real gem
gem build railstart.gemspec
gem install railstart-[version].gem
railstart new my_app

Running Tests

# Run tests
bundle exec rake test

# Lint code
bundle exec rubocop

# Lint and auto-fix
bundle exec rubocop -a

# Full check
bundle exec rake test && bundle exec rubocop

Architecture

Three-Layer Configuration System

Railstart merges configuration from three sources (in order):

  1. Built-in config: config/rails8_defaults.yaml (shipped with gem)
  2. User config: ~/.config/railstart/config.yaml (optional global overrides)
  3. Preset (optional): ~/.config/railstart/presets/NAME.yaml (per-run overlay)

Each layer can:

  • Override question defaults
  • Replace choice lists entirely (by question ID)
  • Add new questions
  • Add/modify post-actions
  • Enable/disable post-actions

Merging is by id for both questions and post_actions, allowing surgical overrides without duplicating entire configs.

Core Components

  • Generator (lib/railstart/generator.rb) - Orchestrates interactive flow
  • Command Builder (lib/railstart/command_builder.rb) - Translates answers to rails new flags
  • CLI (lib/railstart/cli.rb) - Thor command interface with --preset option

AI Agent Skill

Railstart ships with an agent skill at .agents/skills/railstart-coder/ for Codex- and Claude-style coding agents. The skill is structured as a lean SKILL.md plus focused reference files covering CLI usage, config layering, preset authoring, template post-actions, and gem development.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/railstart.

License

The gem is available as open source under the terms of the MIT License.

Supported by Majestic Labs.