rails_pulse 0.4.2 → 0.5.0.pre.2

data/lib/rails_pulse/cli/install.rb

@@ -0,0 +1,145 @@
+require "fileutils"
+require_relative "base_command"
+
+module RailsPulse
+  module CLI
+    class Install < BaseCommand
+      AGENT_FILES_DIR = File.expand_path("agent_files", __dir__)
+
+      # Claude Code loads skills from ~/.claude/skills/<name>/SKILL.md; the
+      # file carries its own name and description in YAML front matter.
+      CLAUDE_SKILL_PATH = "~/.claude/skills/rails-pulse/SKILL.md".freeze
+
+      AGENTS_FILE = "agents.md".freeze
+
+      # Delimit the section so a re-run can replace exactly what a previous
+      # run wrote, leaving everything a project put around it untouched.
+      SECTION_START = "<!-- rails-pulse:start -->".freeze
+      SECTION_END = "<!-- rails-pulse:end -->".freeze
+      # Tolerates CRLF line endings and trailing spaces after a marker, which
+      # an editor or git's autocrlf can introduce between runs.
+      SECTION_PATTERN = /^#{Regexp.escape(SECTION_START)}[ \t]*\r?\n.*?^#{Regexp.escape(SECTION_END)}[ \t]*(?:\r?\n)?/m
+
+      INTEGRATIONS = {
+        "claude" => {
+          description: "Claude Code skill → #{CLAUDE_SKILL_PATH}",
+          source: "claude_skill.md"
+        },
+        "agents" => {
+          description: "Generic agent descriptor → ./#{AGENTS_FILE}",
+          source: "agents.md"
+        }
+      }.freeze
+
+      default_task :perform
+
+      desc "perform [INTEGRATION]", "Install an AI agent integration file"
+      long_desc <<~DESC
+        Copy a pre-built integration file to the correct location for the given agent framework.
+
+        Available integrations:
+          claude   Installs a Claude Code skill to #{CLAUDE_SKILL_PATH}.
+                   Claude Code then knows when and how to use the Rails Pulse MCP tools and CLI.
+                   An earlier copy of the skill is replaced.
+          agents   Installs a generic agent descriptor to ./#{AGENTS_FILE} in the current directory.
+                   Compatible with other AI agent frameworks, including Codex. When an agents.md
+                   or AGENTS.md already exists it is never overwritten: pass --append to add a
+                   delimited Rails Pulse section to the end of it, which a later --append
+                   replaces in place rather than duplicating.
+
+        Run --list to see all available integrations.
+      DESC
+      option :list, type: :boolean, desc: "List all available integrations and their destinations"
+      option :append, type: :boolean, default: false,
+                      desc: "For 'agents': add a delimited Rails Pulse section to an existing AGENTS.md"
+      def perform(integration = nil)
+        if options[:list]
+          say "Available integrations:"
+          INTEGRATIONS.each { |name, meta| say "  #{name.ljust(10)} #{meta[:description]}" }
+          return
+        end
+
+        case integration
+        when "claude"
+          install_claude
+        when "agents"
+          install_agents
+        else
+          say "Usage: rails-pulse install [claude|agents]", :yellow
+          say "       rails-pulse install --list"
+        end
+      end
+
+      private
+
+      def install_claude
+        dest = File.expand_path(CLAUDE_SKILL_PATH)
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(File.join(AGENT_FILES_DIR, "claude_skill.md"), dest)
+        say "Installed Claude Code skill to #{dest}", :green
+      end
+
+      # A project's own AGENTS.md is compared case-insensitively: on a
+      # case-insensitive filesystem (macOS by default) writing agents.md
+      # would silently replace it.
+      def install_agents
+        source = File.join(AGENT_FILES_DIR, "agents.md")
+        existing = Dir.children(Dir.pwd).find { |name| name.casecmp?(AGENTS_FILE) }
+
+        return append_to_agents(File.join(Dir.pwd, existing), source) if existing && options[:append]
+
+        if existing
+          say "#{File.join(Dir.pwd, existing)} already exists; not overwriting it.", :yellow
+          say "Run `rails-pulse install agents --append` to add a Rails Pulse section to it instead."
+          exit 1
+        end
+
+        # Written as a delimited section from the start, so a later --append
+        # recognises it and replaces it rather than adding a second copy.
+        dest = File.join(Dir.pwd, AGENTS_FILE)
+        File.write(dest, section(source, "\n"))
+        say "Installed agent descriptor to #{dest}", :green
+      end
+
+      # The project's own instructions are never rewritten: the Rails Pulse
+      # section is delimited, so a re-run replaces it where it sits and
+      # everything around it is left exactly as the project wrote it.
+      def append_to_agents(dest, source)
+        existing = File.read(dest)
+        newline = existing.include?("\r\n") ? "\r\n" : "\n"
+        section = section(source, newline)
+
+        if existing.match?(SECTION_PATTERN)
+          File.write(dest, existing.sub(SECTION_PATTERN) { section })
+          say "Updated the Rails Pulse section in #{dest}", :green
+        elsif existing.lstrip.start_with?(descriptor_title(source))
+          # A copy written before the section markers existed. Its end cannot
+          # be told from anything the project added after it, so it is left
+          # for a person to replace rather than guessed at or duplicated.
+          say "#{dest} starts with a Rails Pulse descriptor that has no section markers; not appending a second copy.", :yellow
+          say "Delete the Rails Pulse part of it (or the file, if nothing else is in it) and run this again."
+          exit 1
+        else
+          separator = if existing.empty? || existing.end_with?("#{newline}#{newline}")
+            ""
+          elsif existing.end_with?(newline)
+            newline
+          else
+            newline * 2
+          end
+          File.write(dest, "#{existing}#{separator}#{section}")
+          say "Appended a Rails Pulse section to #{dest}", :green
+        end
+      end
+
+      def section(source, newline)
+        body = File.read(source).strip.gsub(/\r?\n/, newline)
+        "#{SECTION_START}#{newline}#{body}#{newline}#{SECTION_END}#{newline}"
+      end
+
+      def descriptor_title(source)
+        File.foreach(source).first.to_s.strip
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/job_runs.rb

@@ -0,0 +1,53 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class JobRuns < BaseCommand
+      COLUMNS = [
+        [ "ID",       8, :id ],
+        [ "Job",     35, :job_name ],
+        [ "Status",  10, :status ],
+        [ "Occurred", 25, :occurred_at ],
+        [ "Duration", 10, :duration ],
+        [ "Error",   35, :error_class ]
+      ].freeze
+
+      desc "list", "List individual background job runs"
+      long_desc <<~DESC
+        Returns job runs ordered by most recent first.
+
+        Filter by status:
+          --status failed     failed and discarded runs
+          --status success    exact status (enqueued, running, success, failed, discarded, retried)
+
+        Filter by job class:
+          --job GenerateReportJob
+
+        Filter by time window (ISO 8601):
+          --since 2026-06-01T00:00:00Z
+          --until 2026-06-01T23:59:59Z
+
+        Use --json to get error messages and the full response envelope.
+      DESC
+      option :limit,  type: :numeric, default: 25,    desc: "Max records to return (1–500)"
+      option :offset, type: :numeric, default: 0,     desc: "Number of records to skip (for pagination)"
+      option :since,  type: :string,                  desc: "Return runs at or after this time (ISO 8601)"
+      option :until,  type: :string,                  desc: "Return runs at or before this time (ISO 8601)"
+      option :status, type: :string,                  desc: "Filter by status (failed, success, discarded, ...)"
+      option :job,    type: :string,                  desc: "Filter by job class name"
+      option :json,   type: :boolean, default: false, desc: "Output raw JSON including meta envelope"
+      def list
+        with_error_handling do
+          params = { limit: options[:limit], offset: options[:offset] }
+          params[:since]  = options[:since]  if options[:since]
+          params[:until]  = options[:until]  if options[:until]
+          params[:status] = options[:status] if options[:status]
+          params[:job]    = options[:job]    if options[:job]
+          result = client.get("/job_runs", params)
+          Formatter.render(result, json: options[:json], columns: COLUMNS)
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/jobs.rb

@@ -0,0 +1,71 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class Jobs < BaseCommand
+      COLUMNS = [
+        [ "Name",     35, :name ],
+        [ "Queue",    15, :queue_name ],
+        [ "Runs",      8, :runs_count ],
+        [ "Failures",  8, :failures_count ],
+        [ "Fail %",    8, :failure_rate ],
+        [ "Avg (ms)", 10, :avg_duration ]
+      ].freeze
+
+      # With a window each row's figures cover it, read from summaries.
+      WINDOW_COLUMNS = [
+        [ "Name",     35, :name ],
+        [ "Queue",    15, :queue_name ],
+        [ "Runs",      8, :runs_count ],
+        [ "Failures",  8, :failures_count ],
+        [ "Fail %",    8, :failure_rate ],
+        [ "Avg (ms)", 10, :avg_duration ],
+        [ "Max (ms)", 10, :max_duration ]
+      ].freeze
+
+      desc "list", "List background jobs with run counts and duration stats"
+      long_desc <<~DESC
+        Returns all tracked background jobs ordered by name.
+
+        Without a window each row shows lifetime stats: total runs, failure count,
+        failure rate (%), and average duration in milliseconds.
+
+        With --since and/or --until (ISO 8601) each row covers that window instead,
+        and only jobs that ran in it are listed. p95 and p99 appear in --json output
+        when one summary period covers the window:
+          --since 2026-06-01T00:00:00Z --until 2026-06-02T00:00:00Z
+
+        Filter to jobs that have failed (inside the window, when one is given):
+          --status failed
+
+        Restrict to one job class:
+          --job GenerateReportJob
+
+        Use --json to also see p95 and p99 duration percentiles and meta.window.
+      DESC
+      option :limit,  type: :numeric, default: 25,    desc: "Max records to return (1–500)"
+      option :offset, type: :numeric, default: 0,     desc: "Number of records to skip (for pagination)"
+      option :since,  type: :string,                  desc: "Window start (ISO 8601); rows then cover the window"
+      option :until,  type: :string,                  desc: "Window end (ISO 8601)"
+      option :job,    type: :string,                  desc: "Exact job class name"
+      option :status, type: :string,                  desc: "Filter by status — 'failed' returns only jobs with failures"
+      option :json,   type: :boolean, default: false, desc: "Output raw JSON including meta envelope and p95/p99 durations"
+      def list
+        with_error_handling do
+          params = { limit: options[:limit], offset: options[:offset] }
+          %i[status since until job].each { |key| params[key] = options[key] if options[key] }
+          result = client.get("/jobs", params)
+
+          # JSON keeps lifetime counters and the window's stats apart, as the
+          # API does; the table shows whichever the rows describe.
+          next Formatter.render(result, json: true) if options[:json]
+
+          windowed = result["data"].any? { |job| job["stats"] }
+          rows = result["data"].map { |job| job.merge(job["stats"] || {}) }
+          Formatter.render(result.merge("data" => rows), columns: windowed ? WINDOW_COLUMNS : COLUMNS)
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/main.rb

@@ -0,0 +1,76 @@
+require "thor"
+require_relative "configure"
+require_relative "install"
+require_relative "routes"
+require_relative "requests"
+require_relative "queries"
+require_relative "jobs"
+require_relative "job_runs"
+require_relative "exceptions"
+require_relative "deployments"
+require_relative "coverage"
+require_relative "insights"
+require_relative "mcp"
+
+module RailsPulse
+  module CLI
+    class Main < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      register(Configure, "configure", "configure",
+               "Prompt for URL and API token, test the connection, and write ~/.rails-pulse")
+      register(Install,   "install",   "install [INTEGRATION]",
+               "Install AI agent integration files (claude, agents). Use --list to see options")
+      register(Routes,    "routes",    "routes SUBCOMMAND",
+               "List tracked HTTP routes and their tags")
+      register(Requests,  "requests",  "requests SUBCOMMAND",
+               "List recorded HTTP requests with optional status and time filters")
+      register(Queries,   "queries",   "queries SUBCOMMAND",
+               "List tracked SQL queries and their analysis results")
+      register(Jobs,      "jobs",      "jobs SUBCOMMAND",
+               "List background jobs with run counts, failure rates, and duration stats")
+      register(JobRuns,   "job_runs",  "job_runs SUBCOMMAND",
+               "List individual job runs with status, job, and time filters")
+      register(Exceptions, "exceptions", "exceptions SUBCOMMAND",
+               "List exception groups with status, search, and time filters")
+      register(Deployments, "deployments", "deployments SUBCOMMAND",
+               "List recorded deployments with optional time filters")
+      register(Coverage,  "coverage",  "coverage SUBCOMMAND",
+               "What has been recorded, how recently, and any collection gaps")
+      register(Insights,  "insights",  "insights SUBCOMMAND",
+               "What needs attention over one period, and whether the thresholds fit it")
+      register(Mcp,       "mcp",       "mcp",
+               "Start MCP server for AI coding agents (Claude Code, Codex, Cursor)")
+
+      no_commands do
+        def help(command = nil, subcommand = false)
+          super
+          return if command
+
+          say ""
+          say "Examples:"
+          say "  rails-pulse configure                                       # Set up credentials interactively"
+          say "  rails-pulse routes list                                     # List all tracked routes"
+          say "  rails-pulse requests list --status 5xx --limit 10          # Last 10 server errors"
+          say "  rails-pulse requests list --since 2026-06-01T00:00:00Z     # Requests since a timestamp"
+          say "  rails-pulse queries list --json                             # Queries with full analysis fields"
+          say "  rails-pulse jobs list --status failed                      # Jobs with at least one failure"
+          say "  rails-pulse jobs list --since 2026-06-01T00:00:00Z         # Job stats for a window"
+          say "  rails-pulse job_runs list --status failed --job ReportJob   # Recent failed runs of one job"
+          say "  rails-pulse exceptions list --status open                  # Open exception groups, most recent first"
+          say "  rails-pulse exceptions show 42                             # One group with backtraces and params"
+          say "  rails-pulse deployments list                                # Recorded deploys, most recent first"
+          say "  rails-pulse coverage show                                   # What is recorded, how recently, any gaps"
+          say "  rails-pulse insights show --period day                      # What needs attention yesterday, threshold fit"
+          say "  rails-pulse install claude                                  # Install Claude Code skill file"
+          say "  rails-pulse mcp                                             # Start MCP server for AI agents"
+          say ""
+          say "Credentials are read from RAILS_PULSE_URL / RAILS_PULSE_TOKEN env vars or ~/.rails-pulse."
+          say "Run 'rails-pulse configure' to set them up, or 'rails-pulse help COMMAND' for detailed flags."
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/mcp.rb

@@ -0,0 +1,47 @@
+require_relative "base_command"
+
+module RailsPulse
+  module CLI
+    class Mcp < BaseCommand
+      default_task :start
+
+      desc "start", "Start the Rails Pulse MCP server (stdio transport)"
+      long_desc <<~DESC
+        Starts a Model Context Protocol (MCP) server over stdio.
+
+        The MCP server exposes Rails Pulse performance data as structured tools
+        for AI coding agents (Claude Code, Codex, Cursor, etc.).
+
+        Configure your MCP client to run:
+          rails-pulse mcp
+
+        The server uses the same credentials as the CLI — set them with
+        `rails-pulse configure` or via RAILS_PULSE_URL / RAILS_PULSE_TOKEN
+        environment variables.
+
+        Available tools:
+          rails_pulse_routes                — Discover endpoints with traffic and latency
+          rails_pulse_slow_requests         — Slowest endpoints for a period
+          rails_pulse_errors                — Recent errors grouped by endpoint
+          rails_pulse_endpoint              — Deep profile of a single endpoint
+          rails_pulse_queries               — Expensive and N+1 SQL queries
+          rails_pulse_jobs                  — Background job health and recent failures
+          rails_pulse_exceptions            — Exception groups with status, count, and latest message
+          rails_pulse_exception             — One group's recent occurrences with backtraces and params
+          rails_pulse_deployments           — Recent deployments with revision, timing and metadata
+          rails_pulse_coverage              — What has been recorded, how recently, and any collection gaps
+      DESC
+      def start
+        require_relative "../mcp/server"
+        RailsPulse::Mcp::Server.start!
+      rescue RailsPulse::CLI::Config::ConfigError => e
+        # Write errors to stderr — stdout is reserved for MCP JSON-RPC
+        $stderr.puts "Rails Pulse MCP error: #{e.message}"
+        exit 1
+      rescue RailsPulse::Mcp::Server::MissingDependencyError => e
+        $stderr.puts "Rails Pulse MCP error: #{e.message}"
+        exit 1
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/queries.rb

@@ -0,0 +1,67 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class Queries < BaseCommand
+      COLUMNS = [
+        [ "ID",       10, :id ],
+        [ "SQL",      60, :normalized_sql ],
+        [ "Analyzed", 25, :analyzed_at ]
+      ].freeze
+
+      STATS_COLUMNS = [
+        [ "ID",     8, :id ],
+        [ "SQL",   50, :normalized_sql ],
+        [ "Execs",  7, :executions ],
+        [ "Avg ms", 8, :avg_duration_ms ],
+        [ "Max ms", 8, :max_duration_ms ],
+        [ "Total ms", 10, :total_duration_ms ],
+        [ "N+1",    5, :max_repetition_count ]
+      ].freeze
+
+      desc "list", "List tracked SQL queries"
+      long_desc <<~DESC
+        Returns normalized SQL queries Rails Pulse has observed, ordered by ID.
+
+        Filter by the time window in which the query was executed (ISO 8601).
+        The filter matches against operation timestamps, not the query creation time,
+        and adds per-query timing stats for the window:
+          --since 2026-06-01T00:00:00Z
+          --until 2026-06-01T23:59:59Z
+
+        Order by a stat (defaults the window to the last 24 hours when --since is omitted):
+          --sort total_duration | avg_duration | executions | max_duration
+
+        Look up one query by its hashed_sql, as listed with --json or by Rails Pulse Cloud:
+          --hashed-sql e4d909c2290d0fb1ca068ffaddf22cbd
+
+        Use --json to see analysis fields (issues, suggestions, n_plus_one) in full.
+      DESC
+      option :limit,  type: :numeric, default: 25,    desc: "Max records to return (1–500)"
+      option :offset, type: :numeric, default: 0,     desc: "Number of records to skip (for pagination)"
+      option :since,  type: :string,                  desc: "Return queries executed at or after this time (ISO 8601)"
+      option :until,  type: :string,                  desc: "Return queries executed at or before this time (ISO 8601)"
+      option :sort,   type: :string,                  desc: "Order by total_duration, avg_duration, executions, or max_duration"
+      option :hashed_sql, type: :string,              desc: "Exact hashed_sql of one query"
+      option :json,   type: :boolean, default: false, desc: "Output raw JSON including meta envelope and analysis fields"
+      def list
+        with_error_handling do
+          params = { limit: options[:limit], offset: options[:offset] }
+          params[:since] = options[:since] if options[:since]
+          params[:until] = options[:until] if options[:until]
+          params[:sort]  = options[:sort]  if options[:sort]
+          params[:hashed_sql] = options[:hashed_sql] if options[:hashed_sql]
+          result = client.get("/queries", params)
+
+          if result["data"].any? { |q| q["stats"] }
+            rows = result["data"].map { |q| q.merge(q["stats"] || {}) }
+            Formatter.render(result.merge("data" => rows), json: options[:json], columns: STATS_COLUMNS)
+          else
+            Formatter.render(result, json: options[:json], columns: COLUMNS)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/requests.rb

@@ -0,0 +1,57 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class Requests < BaseCommand
+      COLUMNS = [
+        [ "ID",         10, :id ],
+        [ "Status",      6, :status ],
+        [ "Duration",   10, :duration ],
+        [ "Occurred",   25, :occurred_at ],
+        [ "Controller", 35, :controller_action ],
+        [ "Path",       35, :path ]
+      ].freeze
+
+      desc "list", "List recorded HTTP requests"
+      long_desc <<~DESC
+        Returns HTTP requests ordered by most recent first.
+
+        Filter by status code or class:
+          --status 500      exact code
+          --status 5xx      any 5xx response
+          --status 4xx      any 4xx response
+
+        Filter by the start of the path. A trailing * is ignored, so a Rails Pulse Cloud
+        path_prefix can be passed as it is; requests no route matched are stored under
+        their raw path:
+          --path-prefix /wp-admin/ --status 404
+
+        Filter by time window (ISO 8601):
+          --since 2026-06-01T00:00:00Z
+          --until 2026-06-01T23:59:59Z
+
+        Both --since and --until can be combined.
+        Use --json to get the full response envelope including meta.total.
+      DESC
+      option :limit,  type: :numeric, default: 25,    desc: "Max records to return (1–500)"
+      option :offset, type: :numeric, default: 0,     desc: "Number of records to skip (for pagination)"
+      option :since,  type: :string,                  desc: "Return requests at or after this time (ISO 8601)"
+      option :until,  type: :string,                  desc: "Return requests at or before this time (ISO 8601)"
+      option :status, type: :string,                  desc: "Filter by status code or class (e.g. 500, 5xx, 4xx)"
+      option :path_prefix, type: :string,             desc: "Only paths starting with this (e.g. /wp-admin/)"
+      option :json,   type: :boolean, default: false, desc: "Output raw JSON including meta envelope"
+      def list
+        with_error_handling do
+          params = { limit: options[:limit], offset: options[:offset] }
+          params[:since]  = options[:since]  if options[:since]
+          params[:until]  = options[:until]  if options[:until]
+          params[:status] = options[:status] if options[:status]
+          params[:path_prefix] = options[:path_prefix] if options[:path_prefix]
+          result = client.get("/requests", params)
+          Formatter.render(result, json: options[:json], columns: COLUMNS)
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/routes.rb

@@ -0,0 +1,73 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class Routes < BaseCommand
+      COLUMNS = [
+        [ "Method",   8, :http_methods ],
+        [ "Path",    40, :path ],
+        [ "Action",  35, :controller_action ],
+        [ "Created", 25, :created_at ]
+      ].freeze
+
+      STATS_COLUMNS = [
+        [ "Method",    8, :http_methods ],
+        [ "Path",     40, :path ],
+        [ "Action",   35, :controller_action ],
+        [ "Requests",  8, :request_count ],
+        [ "Avg ms",    8, :avg_duration_ms ],
+        [ "Errors",    6, :error_count ]
+      ].freeze
+
+      desc "list", "List all tracked HTTP routes"
+      long_desc <<~DESC
+        Returns every route Rails Pulse has recorded, ordered by path.
+
+        Search by path or controller action (case-insensitive substring):
+          --search checkout
+
+        Match one route exactly by its path and controller action:
+          --path /orders/:id --controller-action orders#show
+
+        Add request stats for a time window (ISO 8601). Only routes with traffic
+        in the window are returned, ordered by request count:
+          --since 2026-06-01T00:00:00Z
+          --until 2026-06-01T23:59:59Z
+
+        Order stats by another column (defaults the window to the last 24 hours when --since is omitted):
+          --sort request_count | avg_duration | error_count
+
+        Use --limit and --offset to paginate through large route sets.
+        Use --json to get the full response envelope including meta.total.
+      DESC
+      option :limit,  type: :numeric, default: 25,    desc: "Max records to return (1–500)"
+      option :offset, type: :numeric, default: 0,     desc: "Number of records to skip (for pagination)"
+      option :since,  type: :string,                  desc: "Include request stats at or after this time (ISO 8601)"
+      option :until,  type: :string,                  desc: "Include request stats at or before this time (ISO 8601)"
+      option :search, type: :string,                  desc: "Filter by path or controller action substring"
+      option :path,   type: :string,                  desc: "Exact route path"
+      option :controller_action, type: :string,       desc: "Exact controller action"
+      option :sort,   type: :string,                  desc: "Order stats by request_count, avg_duration, or error_count"
+      option :json,   type: :boolean, default: false, desc: "Output raw JSON including meta envelope"
+      def list
+        with_error_handling do
+          params = { limit: options[:limit], offset: options[:offset] }
+          params[:since]  = options[:since]  if options[:since]
+          params[:until]  = options[:until]  if options[:until]
+          params[:search] = options[:search] if options[:search]
+          params[:path]   = options[:path]   if options[:path]
+          params[:controller_action] = options[:controller_action] if options[:controller_action]
+          params[:sort]   = options[:sort]   if options[:sort]
+          result = client.get("/routes", params)
+
+          rows = result["data"].map do |route|
+            route.merge("http_methods" => Array(route["http_methods"]).join("|")).merge(route["stats"] || {})
+          end
+          columns = result["data"].any? { |r| r["stats"] } ? STATS_COLUMNS : COLUMNS
+          Formatter.render(result.merge("data" => rows), json: options[:json], columns: columns)
+        end
+      end
+    end
+  end
+end