Stable CLI

Stable is a cross-platform CLI tool to manage local Rails applications with automatic Caddy setup, local trusted HTTPS certificates, and easy start/stop functionality. Supports macOS, Linux, and Windows.

• Add and remove Rails apps.
• Automatically generate and manage local HTTPS certificates using mkcert.
• Automatically assign .test domains.
• Start Rails apps with integrated Caddy reverse proxy.
• Stop and restart Rails apps.
• Reload Caddy after adding/removing apps.
• List all registered apps.
• Upgrade, downgrade, or switch Ruby versions for apps.
• Run multiple apps with different Ruby versions simultaneously.

gem install stable-cli-rails

gem "stable-cli-rails"

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Stable CLI
gem install stable-cli-rails

# Run setup
stable setup

# Update package lists and install build tools
sudo apt update
sudo apt install -y build-essential curl

# Install Ruby (if not already installed)
sudo apt install -y ruby ruby-dev

# Install Stable CLI
gem install stable-cli-rails

# Run setup
stable setup

# Install build tools
sudo yum install -y gcc gcc-c++ make curl

# Install Ruby (if not already installed)
sudo yum install -y ruby ruby-devel

# Install Stable CLI
gem install stable-cli-rails

# Run setup
stable setup

# Install Ruby from https://rubyinstaller.org/
# Install Git for Windows (includes Git Bash)
# Install dependencies manually:
# - Caddy: https://caddyserver.com/docs/install
# - mkcert: https://github.com/FiloSottile/mkcert/releases
# - PostgreSQL: https://www.postgresql.org/download/windows/
# - MySQL: https://dev.mysql.com/downloads/mysql/

# Install Stable CLI
gem install stable-cli-rails

# Run setup (may require manual dependency installation)
stable setup

Initialize Caddy home and required directories:

stable setup

This will create:

• ~/StableCaddy/ for Caddy configuration.
• ~/StableCaddy/certs for generated certificates.
• ~/StableCaddy/projects for Rails applications.
• ~/StableCaddy/Caddyfile for Caddy configuration.

# List all registered apps
stable list

Lists all registered apps and their domains.

stable setup

Initializes the Stable environment by creating required directories and installing dependencies. This is required before using other Stable commands.

# Create a new Rails app with options
stable new myapp [--ruby 3.4.4] [--rails 8.1.1] [--skip-ssl] [--db --mysql] [--db --postgres]

# Create a new Rails app with default sqlite
stable new myapp

Creates a new Rails app, generates .ruby-version, installs Rails, adds the app to Stable, and optionally secures it with HTTPS.

You can create Rails apps with integrated database support using the --mysql or --postgres flags. Stable will handle gem installation, database creation, and configuration automatically.

# Create a new Rails app with PostgreSQL
stable new myapp --db --postgres

# Create a new Rails app with MySQL
stable new myapp --db --mysql

• The CLI will prompt for the database root username and password during setup.
• The corresponding gem (pg for PostgreSQL or mysql2 for MySQL) will be added to the Gemfile automatically.
• database.yml will be configured for development, test, and production environments.
• The database will be created and prepared (rails db:prepare) automatically.

stable add /path/to/rails_app

This will:

• Register the app.
• Add a /etc/hosts entry.
• Generate local trusted HTTPS certificates.
• Add a Caddy reverse proxy block.
• Reload Caddy.

stable remove app_name

This will:

• Remove the app from registry.
• Remove /etc/hosts entry.
• Remove the Caddy reverse proxy block.
• Reload Caddy.

Note: This only removes the app from Stable management. The project files remain intact.

stable destroy app_name

⚠️ DANGER: This permanently deletes the application and ALL its files!

This command requires confirmation - you must type the exact app name to proceed. It will:

• Stop the app if it's running
• Remove the app from registry
• Remove /etc/hosts entry
• Remove the Caddy reverse proxy block
• Clean up RVM gemset (e.g., 3.4.7@appname) on macOS/Linux
• Delete the entire project directory and all files
• Reload Caddy

Example:

$ stable destroy my-app
⚠️  WARNING: This will permanently delete the application 'my-app'
   Path: /Users/user/stable/projects/my-app
   Domain: my-app.test
   This action CANNOT be undone!

Type 'my-app' to confirm destruction: my-app

🗑️  Destroying my-app...
   Deleting project directory...
✅ Successfully destroyed my-app

stable start app_name

Starts the Rails server on the assigned port and ensures Caddy is running with the proper reverse proxy. Rails logs can be viewed in your terminal.

stable stop app_name

Stops the Rails server running on the assigned port.

stable restart app_name

Stops and then starts the Rails server, useful for reloading code changes or configuration updates.

stable open app_name

Opens an app in the browser.

stable workdir app_name [--editor vscode]

Opens the app folder in a code editor (defaults to vscode). Supported editors include vscode, sublime, atom, etc.

stable share app_name [provider] [--qrcode]

Shares the app via a public tunnel using the specified provider (ngrok or stable, defaults to ngrok). Optionally generates a QR code for the shared URL.

stable secure app_name.test

Generates or updates trusted local HTTPS certificates and reloads Caddy.

stable caddy_reload

Reloads Caddy configuration after changes.

stable doctor

Checks the environment, RVM/Ruby, Caddy, mkcert, and app readiness.

stable upgrade-ruby myapp 3.4.7

Changes the Ruby version for a specific app (upgrade, downgrade, or switch). Automatically handles gemset cleanup and recreation for clean environment transitions.

• macOS/Linux: Full automation with RVM gemsets and automatic gem installation
• Windows: Updates app configuration and provides instructions for manual Ruby/bundle installation

# Upgrade Ruby version
stable upgrade-ruby myapp 3.4.7

# Downgrade Ruby version
stable upgrade-ruby myapp 3.3.0

# Patch version switch
stable upgrade-ruby myapp 3.4.5

macOS/Linux: Creates fresh RVM gemsets and installs gems automatically Windows: Updates .ruby-version file and provides manual installation instructions

The command updates .ruby-version, cleans up old gemsets (on Unix), creates fresh environments, and ensures gem compatibility.

Stable uses RSpec for testing. To run the test suite:

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/commands/new_spec.rb

# Run with Rake (same as bundle exec rspec)
rake spec

The test suite includes:

• Unit tests for all services and commands
• Integration tests for CLI functionality
• Cross-platform compatibility tests
• Database integration tests

spec/
├── cli/                    # CLI integration tests
├── commands/              # Command-specific tests
├── services/              # Service layer tests
│   └── database/          # Database-specific tests
├── spec_helper.rb         # Test configuration
└── spec.opts             # RSpec options

• Caddy home: ~/StableCaddy
• Caddyfile: ~/StableCaddy/Caddyfile
• Certificates: ~/StableCaddy/certs
• Projects directory: ~/StableCaddy/projects
• App configurations: ~/StableCaddy/projects/{app_name}/{app_name}.yml

• macOS: Homebrew
• Linux: APT (Ubuntu/Debian), YUM/DNF (CentOS/RHEL), or Pacman (Arch)
• Windows: Manual installation required

• Caddy: Web server and reverse proxy
• mkcert: Local HTTPS certificate generation
• Ruby version manager: RVM, rbenv, or chruby
• PostgreSQL: Database server (optional)
• MySQL: Database server (optional)

stable setup will attempt to install missing dependencies automatically on macOS and Linux. On Windows, manual installation is required.

• Make sure to run stable setup initially.
• macOS/Linux: Requires sudo to modify /etc/hosts.
• Windows: Requires administrator privileges to modify C:\Windows\System32\drivers\etc\hosts.
• Rails apps are started on ports assigned by Stable (default 3000+).
• Domains are automatically suffixed with .test.
• Windows: Some features may have limited support. Manual installation of dependencies is required.

We welcome contributions to Stable! Here's how to get started:

1. Clone the repository

   git clone https://github.com/your-username/stable-cli.git
   cd stable-cli

2. Install dependencies

   bundle install

3. Run tests

   bundle exec rspec

4. Install locally for testing

   gem build stable-cli-rails.gemspec
   gem install stable-cli-rails-*.gem

1. Create a feature branch

   git checkout -b feature/your-feature-name

2. Make your changes and ensure tests pass

   bundle exec rspec

3. Follow the coding standards

   • Use bundle exec rubocop to check code style
   • Write tests for new features
   • Update documentation as needed

4. Submit a pull request

   • Ensure all tests pass
   • Update CHANGELOG.md if applicable
   • Provide a clear description of changes

Since Stable supports multiple platforms, please test on:

• macOS (primary development platform)
• Linux (Ubuntu/Debian recommended)
• Windows (if possible, or document limitations)

When reporting bugs, please include:

• Your operating system and version
• Ruby version (ruby -v)
• Steps to reproduce the issue
• Expected vs actual behavior

MIT License