rails-dev 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d79ed132a36f779c8025cd306d4e75f80360de8cfb65409295b8da11bc2badcd
+  data.tar.gz: a9db8f42cb70536b5c49adfc58d65bc0736a9483e23473abc6e571f8e98812a0
+SHA512:
+  metadata.gz: 323b6bae902098dc3536f66eb643d7b7fadcaeca488a26862a65ad6f3bd4ca469b45e199f137c3025cfb975081a182011b678fd0b720a2610f98dfe482083484
+  data.tar.gz: 92deea7d90f997e1d7b6af91d2614c68a133a760fdd49da0f058a65cf100be20c1959eff44cb230e166d61df031dbd4e8918c4e3cc67520edbb06c389aee45cc

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 - 2026-09-24
+
+- Run app Procfiles through Foreman on available ports, including multiple instances from the same checkout.
+- Provide local HTTPS URLs and optional Tailscale sharing.
+- Start and reuse Docker Compose services on available loopback ports with explicit connection mappings.
+- Support global and app configuration, lifecycle hooks, optional processes, and configurable readiness checks.
+- Configure Rails hostnames, URLs, cookies, and PID files, with an optional helper for Rails Vite apps.
+- List instances across projects and recover interrupted runs while preserving shared services.
+- Support Ruby 3.4 and newer on macOS and Linux, with ERB or Vite apps.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ali Hamdi Ali Fadel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# rails-dev
+
+Run Rails on an available port, get a local HTTPS URL, and share it through Tailscale when needed. Start several instances from the same checkout; each gets its own URL.
+
+Works on macOS and Linux with ERB or Vite apps. Foreman runs your Procfile. Your app chooses its tools and preparation commands; rails-dev handles ports, HTTPS, and optional Docker Compose services.
+
+## Install
+
+| Requirement | When you need it |
+| --- | --- |
+| Ruby 3.4+ | Always; Foreman is included as a dependency |
+| Node.js 24+ and npm | Local HTTPS |
+| Docker Compose 2.24.4+ | Managed Docker services |
+| Connected Tailscale client | Sharing over your tailnet |
+
+Install using the same Ruby as your app:
+
+```sh
+gem install rails-dev
+```
+
+For a bundled installation, use `bundle add` below and prefix rails-dev commands with `bundle exec`.
+
+## Set up your app
+
+Use your app's usual shell environment and install its dependencies first. Mise is optional.
+
+**1. Add the Rails helper to your app:**
+
+```sh
+bundle add rails-dev --group development,test --require rails_dev/railtie
+```
+
+The helper configures hostnames, route and mailer URLs, and cookies for each instance. Apps using `rails_vite` also need the [Vite setup](docs/reference.md#vite).
+
+**2. Put your server command in `Procfile.dev`:**
+
+```procfile
+web: bin/rails server -b 127.0.0.1
+```
+
+Keep your existing workers and asset watchers there too. Let commands use the supplied ports; fixed ports in commands or `.env` can override them.
+
+Configure [Docker services](#add-docker-services) or [preparation hooks](docs/reference.md#hooks) before starting if your app needs them.
+
+**3. Set up local HTTPS once per machine, then start from your app directory:**
+
+```sh
+rails-dev setup
+rails-dev start
+```
+
+`setup` installs the Portless proxy and certificate trust. `start` picks a free port starting at 3000 and prints a URL such as `https://my-app-3001.localhost`.
+
+Startup waits for `GET /up` to return HTTP 200. [Change the readiness check](docs/reference.md#readiness) if your app uses another health endpoint.
+
+Run `start` in another terminal for a second instance. **Ctrl+C stops that instance**; shared Docker services stay running.
+
+## Everyday commands
+
+| Task | Command |
+| --- | --- |
+| Start an instance | `rails-dev start` |
+| List your instances across projects | `rails-dev list` |
+| List one checkout's instances | `rails-dev list --root .` |
+| Stop an instance using its listed ID | `rails-dev stop INSTANCE` |
+| Check local HTTPS | `rails-dev doctor` |
+| See command options | `rails-dev --help` |
+
+If a terminal or launcher exits unexpectedly, use `list` and `stop` to recover the instance. [Status and recovery details](docs/reference.md#instances-and-recovery).
+
+## Add Docker services
+
+Create `config/rails_dev.rb` in your app. For PostgreSQL:
+
+```ruby
+RailsDev.configure do |config|
+  config.compose_file = "dev-docker-compose.yml"
+  config.connect "postgres", port: 5432,
+    env: { "PGHOST" => "%{host}", "PGPORT" => "%{port}" }
+
+  config.before_start { |run| run.run("bin/rails", "db:prepare") }
+end
+```
+
+Use your Compose filename and service name. Rails-dev starts enabled services and publishes their declared ports on available loopback ports. It supplies the connection variables you map; your app provides database names and credentials.
+
+If your app uses `DATABASE_URL`, map it instead of leaving a fixed URL that overrides `PGHOST` and `PGPORT`. See [Compose configuration](docs/reference.md#docker-compose) for Redis, ClickHouse, profiles, and exclusions.
+
+```sh
+rails-dev services exec -- bin/rails console
+RAILS_ENV=test rails-dev services exec -- bin/rails test
+```
+
+These commands start or reuse services and pass their connections to the host command. Rails does not need to be running.
+
+## Share through Tailscale
+
+Connect Tailscale and enable HTTPS in your tailnet's DNS settings, then run:
+
+```sh
+rails-dev start --tailscale
+```
+
+Open the printed URL from another device allowed to reach your machine on the tailnet. Each instance uses its own HTTPS port. [Tailscale permissions and setup](docs/reference.md#tailscale).
+
+## Customize
+
+App settings live in `config/rails_dev.rb` and override global defaults. Keep personal overrides in `config/rails_dev.local.rb` and add that file to your app's ignore list.
+
+| What you want to change | Guide |
+| --- | --- |
+| App name, ports, Procfile, or defaults | [Configuration](docs/reference.md#configuration) |
+| Environment and process commands | [Processes and environment](docs/reference.md#processes-and-environment) |
+| More HTTP servers | [Additional HTTP servers](docs/reference.md#additional-http-servers) |
+| Preparation and lifecycle hooks | [Hooks](docs/reference.md#hooks) |
+| Optional processes, such as Stripe | [Optional processes](docs/reference.md#optional-processes) |
+| Vite URLs and hot reload | [Vite](docs/reference.md#vite) |
+| Independent restarts and shared assets | [Multiple runs](docs/reference.md#multiple-runs-from-one-checkout) |
+| Plain HTTP or a different HTTPS proxy port | [Local HTTPS](docs/reference.md#local-https) |
+
+OAuth relay, public webhook relay, and direct LAN HTTPS are deferred.
+
+## Development
+
+```sh
+mise ci
+mise run test:docker
+mise run test:https
+```
+
+Without Mise, use `bundle exec rake test rubocop build`, `bundle exec rake test_docker`, and `bundle exec rake test_https`.
+
+Tests use Minitest. CI covers Ruby 3.4 and 4.0 on Linux and macOS.

data/docs/reference.md

@@ -0,0 +1,220 @@
+# Configuration reference
+
+See the [README](../README.md) for installation and everyday commands. Ruby examples below belong in `config/rails_dev.rb` unless another file is named.
+
+## Configuration
+
+Settings load in order:
+
+1. Gem defaults.
+2. `$XDG_CONFIG_HOME/rails-dev/config.rb`, defaulting to `~/.config/rails-dev/config.rb`.
+3. Your app's `config/rails_dev.rb`.
+4. Your app's optional `config/rails_dev.local.rb`.
+
+Later assignments replace earlier values. Arrays and hooks can be extended or cleared. Repeated `http` declarations merge options, including readiness settings.
+
+| Setting | Default |
+| --- | --- |
+| `name` | Derived from the checkout directory name |
+| `procfile` | `"Procfile.dev"` |
+| `web` | `"web"`, the primary HTTP process |
+| `https` | `true` |
+| `startup_timeout` | 90 seconds |
+| `shutdown_timeout` | 5 seconds |
+| `compose_file` | Unset; Docker management is off |
+
+Use `--root PATH` to select the working directory, even when the Procfile lives in a subdirectory.
+
+## Processes and environment
+
+Foreman runs your original Procfile and handles sibling shutdown when a process exits. Its normal `.env` behavior applies. Values loaded by Foreman are unavailable to earlier preparation hooks; the app must supply those separately.
+
+| Variable | Meaning |
+| --- | --- |
+| `PORT` | Selected port in the primary web process; other processes follow Foreman's usual numbering |
+| `RAILS_PORT` | Primary web port, available to every process |
+| `RAILS_DEV_URL` | Primary public URL |
+| `RAILS_DEV_RUNTIME` | This instance's runtime directory |
+
+Procfile commands have no terminal input. Use `services exec` for interactive commands. Rails-dev inherits your shell environment and removes the launcher's Bundler settings from child processes.
+
+## Docker Compose
+
+Extend the [PostgreSQL example](../README.md#add-docker-services) with the connections and service selections your app needs:
+
+```ruby
+RailsDev.configure do |config|
+  config.connect "redis", port: 6379,
+    env: { "REDIS_URL" => "redis://%{host}:%{port}/0" }
+  config.connect "clickhouse", port: 8123,
+    env: { "CLICKHOUSE_URL" => "http://%{host}:%{port}" }
+  config.profiles = ["debug"]
+  config.exclude_services = ["mail"]
+  config.publish_ports["internal"] = [6379]
+end
+```
+
+Templates accept `%{host}` and `%{port}`. Credentials and database names remain app settings. An inherited `DATABASE_URL` with a PGPORT-only mapping is rejected; map the URL or remove it from the launch environment.
+
+- All Compose-enabled services start, respecting dependencies and profiles. Any service type can use explicit connection mappings.
+- Declared publications and requested ports receive available loopback ports. Existing containers are reused.
+- Healthchecks determine readiness where present; otherwise running status is enough.
+- Required dependencies cannot be excluded. Host networking, scaled services, and conflicting or non-loopback publications are unsupported.
+
+`rails-dev services start` starts shared services. `rails-dev services stop` stops them for **every instance**, keeping containers and volumes. Both require Compose configuration.
+
+`services exec` preserves arguments, terminal input, and exit status. It skips web hooks and preserves `RAILS_ENV`. Without Compose configured, it uses the existing environment.
+
+## Additional HTTP servers
+
+Match the endpoint name to its Procfile process and declare the port variable that command consumes:
+
+```ruby
+RailsDev.configure do |config|
+  config.http :js, port: 5173, env: "VITE_PORT",
+                  url_env: "RAILS_DEV_VITE_URL", readiness: "/@vite/client"
+end
+```
+
+Add to `Procfile.dev`:
+
+```procfile
+js: pnpm exec vite --host 127.0.0.1 --port ${VITE_PORT:-5173} --strictPort
+```
+
+Here, `js` is the process name. Vite's `--strictPort` makes a taken port fail; rails-dev retries confirmed bind conflicts without repeating preparation hooks.
+
+Each endpoint gets a URL such as `https://my-app-3001-js.localhost`. `url_env` defaults to `RAILS_DEV_<PROCESS>_URL`, using uppercase and replacing hyphens with underscores. Processes that do not serve HTTP need no endpoint declaration.
+
+## Hooks
+
+```ruby
+RailsDev.configure do |config|
+  config.around_run do |run, continue|
+    continue.call
+  ensure
+    run.say("Run finished")
+  end
+end
+```
+
+| Hook | When it runs |
+| --- | --- |
+| `before_start` | After services and connection mapping, before Foreman |
+| `after_ready` | After enabled readiness checks pass |
+| `around_run` | Around preparation, startup, and the app run; call its continuation once |
+| `after_stop` | After processes stop and around hooks unwind, including on errors and interrupts |
+
+Hooks run once per invocation. Before/ready hooks run in registration order; stop hooks run in reverse order and all are attempted. Cleanup errors do not replace an earlier failure. Clear inherited hooks with `config.before_start.clear`.
+
+The context exposes `root`, `runtime`, `env`, `url(process = primary_web)`, `error`, and `enabled?(name)`. URLs become available after networking is allocated.
+
+`run(*argv)` streams output; `capture(*argv)` returns stdout. Both use argument arrays without a shell and run in the app directory with `run.env`. Use `say(message)` for output and `check_for_interrupt` during long custom work.
+
+## Optional processes
+
+Declare a Procfile process with `config.optional` and select it through `--with`. For Stripe, install its CLI and run `stripe login` first:
+
+```ruby
+RailsDev.configure do |config|
+  config.optional :stripe
+  config.before_start do |run|
+    next unless run.enabled?(:stripe)
+
+    run.env["STRIPE_SIGNING_SECRET"] = run.capture("stripe", "listen", "--print-secret").strip
+  end
+end
+```
+
+Add to `Procfile.dev`, using your app's webhook path:
+
+```procfile
+stripe: stripe listen --skip-update --forward-to http://127.0.0.1:${RAILS_PORT}/pay/webhooks/stripe
+```
+
+Start with `rails-dev start --with stripe`. Foreman starts selected processes together, so webhooks can arrive before Rails is ready.
+
+- `config.optional :listener, with: :payments` lets a selection enable a differently named process. Several processes can share one selection.
+- For optional hook work alone, add a name to `config.integrations` and check `run.enabled?`. Unknown selections fail before startup.
+
+## Readiness
+
+The primary endpoint defaults to `GET /up`, expecting HTTP 200; other endpoints need an explicit check. Requests use loopback HTTP with the public hostname in the Host header.
+
+```ruby
+RailsDev.configure do |config|
+  config.readiness = { request_timeout: 1, interval: 0.1 }
+  config.http :web, readiness: { path: "/health", success: 200, timeout: 30 }
+end
+```
+
+| Option | Meaning |
+| --- | --- |
+| `path`, `method`, `headers`, `body` | Request settings; method defaults to `GET` |
+| `success` | Status code, array of codes, or callable receiving the response; defaults to `200` |
+| `timeout` | Endpoint timeout, also bounded by `startup_timeout` |
+| `request_timeout` | Timeout for each connection, read, or write; defaults to 1 second |
+| `interval` | Polling interval; defaults to 0.1 seconds |
+
+`config.readiness` supplies shared defaults; endpoint settings override them. Use `readiness: false` to disable a check or `readiness: ->(endpoint) { ... }` for a custom check. The endpoint exposes `name`, `port`, and `url`.
+
+Custom checks must return promptly and manage their own timeouts. Checks gate `after_ready` and the Ready message, not process launch order or ongoing health. A timeout stops owned processes and removes their routes.
+
+## Vite
+
+For `rails_vite` and `rails-vite-plugin`, load both helpers in your Gemfile's development/test group:
+
+```ruby
+gem "rails-dev", require: ["rails_dev/railtie", "rails_dev/rails_vite"]
+```
+
+Declare the [HTTP endpoint](#additional-http-servers) with `url_env: "RAILS_DEV_VITE_URL"`. Add the helper to your existing Vite configuration, keeping your other plugins. Its returned options can be customized:
+
+```js
+export default defineConfig(async ({ command }) => {
+  const runtime = command === 'serve' ? process.env.RAILS_DEV_RUNTIME : undefined
+  const development = runtime ? (await import(`${runtime}/vite.mjs`)).default() : undefined
+
+  return {
+    plugins: [development?.plugin, rails(development?.rails)],
+  }
+})
+```
+
+## Multiple runs from one checkout
+
+Ports, URLs, Rails PID files, cookies, Vite metadata, and Vite caches are separate per run. Compiled JavaScript and CSS remain shared.
+
+For independent restarts, make Puma's shared restart watcher conditional in `config/puma.rb`:
+
+```ruby
+plugin :tmp_restart unless ENV["RAILS_DEV_RUNTIME"]
+```
+
+## Local HTTPS
+
+Use `rails-dev setup --port 8443` for another proxy port, or `config.https = false` for loopback HTTP. `.localhost` URLs work only on the developer's own machine.
+
+## Tailscale
+
+Follow the [Tailscale setup](../README.md#share-through-tailscale). On Linux, an administrator may need to grant operator access:
+
+```sh
+sudo tailscale set --operator="$USER"
+```
+
+Tailscale mode needs no local Portless setup. Each endpoint gets an HTTPS port on the machine's tailnet hostname. Existing Serve routes and tailnet permissions are preserved; Funnel is not enabled.
+
+## Instances and recovery
+
+| Status | Meaning |
+| --- | --- |
+| `starting` | Preparation or startup checks are running |
+| `ready` | Startup and ready hooks completed |
+| `orphaned` | The launcher exited, but verified processes remain |
+| `stale` | No processes remain in the recorded groups |
+| `interrupted` | Process ownership cannot be verified |
+
+Status and saved URLs are not ongoing health checks. Use `rails-dev stop INSTANCE` for recovery; cleanup is not automatic after a forced launcher exit.
+
+Unverified ownership keeps the record for inspection. Detached daemons and unrecorded processes cannot be recovered this way. Shared Docker services and the HTTPS proxy stay running.

data/exe/rails-dev

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rails_dev"
+$stdout.sync = true
+exit RailsDev::CLI.run(ARGV)

data/lib/rails_dev/child.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RailsDev
+  class Child
+    attr_reader :pid, :name, :stdout, :stderr, :status
+
+    def initialize(name, argv, env:, root:, output: nil, ready_message: nil, keep_stdin_open: false)
+      @name = name
+      @output = output
+      @stdout = +""
+      @stderr = +""
+      @readers = {}
+      @ready_message = ready_message
+      @ready = ready_message.nil?
+      spawn(argv, env, root, keep_stdin_open)
+    end
+
+    def poll
+      @readers.each { |reader, buffer| drain(reader, buffer) unless reader.closed? }
+      @status ||= Process.waitpid2(pid, Process::WNOHANG)&.last
+      @status
+    end
+
+    def running?
+      poll.nil?
+    end
+
+    def ready?
+      @ready
+    end
+
+    def failure_message
+      detail = stderr.strip.empty? ? stdout.strip : stderr.strip
+      ["#{name} failed (#{exit_reason}).", detail].reject(&:empty?).join("\n")
+    end
+
+    def exit_reason
+      return "exit status #{status.exitstatus}" unless status.signaled?
+
+      "signal #{Signal.signame(status.termsig) || status.termsig}"
+    end
+
+    def startup_conflict?
+      output.match?(/EADDRINUSE|Address already in use|Port \d+ is already in use/i) ||
+        (name.start_with?("tailscale-") &&
+          output.match?(/listener already exists for port|Another client is changing the serve config/))
+    end
+
+    def reap
+      @status ||= Process.waitpid2(pid).last
+      poll
+    end
+
+    def group_alive?
+      !!signal(0)
+    end
+
+    def signal(value)
+      Process.kill(value, -pid)
+    rescue Errno::ESRCH
+      nil
+    rescue Errno::EPERM
+      raise unless ProcessTable.new.members([pid]).empty?
+    end
+
+    def output
+      "#{stdout}\n#{stderr}"
+    end
+
+    def close
+      @readers.each_key { |reader| reader.close unless reader.closed? }
+      @input&.close
+    end
+
+    private
+
+    def spawn(argv, env, root, keep_stdin_open)
+      in_read, @input = IO.pipe if keep_stdin_open
+      out_read, out_write = IO.pipe
+      err_read, err_write = IO.pipe
+      @readers = { out_read => @stdout, err_read => @stderr }
+      command = [argv.first, argv.first]
+      @pid = Process.spawn(env, command, *argv.drop(1), chdir: root, unsetenv_others: true, pgroup: true,
+                                                        in: in_read || File::NULL, out: out_write, err: err_write)
+    rescue Errno::ENOENT
+      close
+      raise Error, "Command not found: #{argv.first}. Make it available on PATH before starting rails-dev."
+    ensure
+      in_read&.close
+      out_write&.close
+      err_write&.close
+    end
+
+    def drain(reader, buffer)
+      loop do
+        chunk = reader.read_nonblock(8192, exception: false)
+        break if chunk == :wait_readable
+        return reader.close if chunk.nil?
+
+        record_output(buffer, chunk)
+      end
+    end
+
+    def record_output(buffer, chunk)
+      buffer << chunk
+      @ready ||= buffer.include?(@ready_message) if @ready_message
+      @output&.write("[#{name}] #{chunk}")
+      buffer.replace(buffer.byteslice(-32_768, 32_768)) if @output && buffer.bytesize > 32_768
+    end
+  end
+end

data/lib/rails_dev/cli/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsDev
+  module CLI
+    class Base < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      remove_command :tree
+      check_unknown_options!
+
+      class_option :root, type: :string, banner: "PATH",
+                          desc: "App directory (default: current directory; list/stop: all projects)"
+      class_option :help, type: :boolean, aliases: "-h", desc: "Show help"
+      class_option :version, type: :boolean, aliases: "-v", desc: "Print version"
+
+      no_commands do
+        def invoke_command(command, *arguments)
+          if options[:version]
+            say VERSION
+          elsif options[:help]
+            help(command.name == "help" ? nil : command.name)
+          else
+            super
+          end
+        end
+      end
+
+      private
+
+      def root
+        @root ||= File.realpath(options[:root] || Dir.pwd)
+      end
+
+      def configuration
+        Configuration.load(root)
+      end
+    end
+  end
+end

data/lib/rails_dev/cli/main.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RailsDev
+  module CLI
+    class Main < Base
+      desc "setup", "Install the pinned Portless version, trust its CA, and start the shared HTTPS proxy"
+      option :port, type: :numeric, default: 443, desc: "HTTPS proxy port"
+      def setup
+        Portless.new(Commands.new(root, output: shell.output)).setup(port: options[:port])
+      end
+
+      desc "doctor", "Check the shared proxy, certificates, and hostname resolution"
+      def doctor
+        Portless.new(Commands.new(root, output: shell.output)).doctor
+      end
+
+      desc "start", "Run the app's Procfile with available ports and HTTPS"
+      option :with, type: :array, banner: "NAME [NAME...]", desc: "Enable optional integrations declared by the app"
+      option :tailscale, type: :boolean, default: false, desc: "Share this run over HTTPS on your tailnet"
+      def start
+        config = configuration
+        config.enable_integrations(options[:with])
+        Session.new(root, config, tailscale: options[:tailscale], output: shell.output).start
+      end
+
+      desc "list", "List your active and interrupted instances across projects"
+      def list
+        selected_root = root if options[:root]
+        runs = State.new.runs
+        runs.select! { |run| run.fetch("root") == selected_root } if selected_root
+        return say("No instances.") if runs.empty?
+
+        rows = runs.flat_map { |run| instance_rows(run) }
+        print_table([%w[INSTANCE APP PID STATUS CHECKOUT ENDPOINT URL], *rows], truncate: false)
+      end
+
+      desc "stop INSTANCE", "Stop one instance and recover its interrupted processes"
+      def stop(instance)
+        State.new.stop(instance, root: options[:root] ? root : nil)
+        say "Stopped #{instance}."
+      end
+
+      desc "services COMMAND", "Manage Compose services and run host commands"
+      subcommand "services", Services
+      stop_on_unknown_option! :services
+
+      no_commands do
+        remove_method :services
+
+        def services(*arguments)
+          raise Thor::InvocationError, "Specify a command. See rails-dev services --help." if arguments.empty?
+
+          Services.start(arguments, debug: true, shell: shell, class_options: options)
+        end
+      end
+
+      private
+
+      def instance_rows(run)
+        urls = run.fetch("urls")
+        urls = { "" => "" } if urls.empty?
+        urls.each_with_index.map do |(name, url), index|
+          fields = index.zero? ? run.values_at("id", "name", "pid", "status", "root") : Array.new(5, "")
+          fields + [name, url]
+        end
+      end
+    end
+  end
+end

data/lib/rails_dev/cli/services.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsDev
+  module CLI
+    class Services < Base
+      desc "start", "Start or reuse Compose services"
+      def start
+        run("start")
+      end
+
+      desc "stop", "Stop Compose services, keeping containers and volumes"
+      def stop
+        run("stop")
+      end
+
+      desc "exec -- COMMAND [ARGS]", "Run a host command with service connection settings"
+      def exec(command, *arguments)
+        run("exec", [command, *arguments])
+      end
+
+      private
+
+      def run(action, arguments = [])
+        RailsDev::Services.new(root, configuration, output: shell.output).run(action, arguments)
+      end
+    end
+  end
+end

data/lib/rails_dev/cli/shell.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsDev
+  module CLI
+    class Shell < Thor::Shell::Basic
+      attr_reader :output
+
+      def initialize(output, error)
+        super()
+        @output = output
+        @error = error
+      end
+
+      private
+
+      def stdout
+        @output
+      end
+
+      def stderr
+        @error
+      end
+    end
+  end
+end