raygatherer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9324c6a164aa329514f237d51e7942f8d2399e698fcb500de86440aef9320f0
-  data.tar.gz: 5412fc1973d54829b42684ea37d73df8ab4cf6a85a2ecfd2b1248e9c45833817
+  metadata.gz: 19099779bda496591260a273c3d6db20c9203f1c046393c2ce6b7c6b90b77db5
+  data.tar.gz: 7105312abb9d3d27aafbd452e386f87343b8ebce08308e30e4b7330128d260aa
 SHA512:
-  metadata.gz: e34d2c21750b31b1d0e33c8334233748b6d7aca62eb6879912226e644f8cc7f2076b815937a3f05b1853595b8aa28f25b61ae06f5e3e13d0ce8fe794ee58fe73
-  data.tar.gz: e7e7c1bbb88a75a9b588713dfec1692fcbf2f9e0bbf126a82dc517b86d1d7279cf48ccd8a3e1fba7b210d89e2507d64777ca17b14617fba88e9bc52e27aa80f7
+  metadata.gz: 68524f1ebfc17554e8fed101331eca036e25217f23c8ada0922e0da5c9f257257314126bebf671a37bb7a8a50ebffca355d2df24cd7dbf8d677951414d865288
+  data.tar.gz: d5453cb08bbe54cc9d07fbd1a32d05bce51f9e25ba866ced69bd657fcd3d067c3fe5210aec77f6e193c7a3421867fb0cc4cdfc26eefb61a9f1b8792f4e124c39

data/README.md

@@ -17,6 +17,9 @@ Currently implemented:
 - system stats and raw log output
 - device clock show and sync
 - config show/set/test-notification
+- rayhunter update status, with a dedicated exit code for scripting
+- GPS position show/set (requires the device's gps_mode config to be set to Api)
+- wifi client status and network scan
 - JSON output mode for scriptable commands
 - optional basic auth and config file support
 - debug utilities (display-state)
@@ -31,6 +34,10 @@ gem install raygatherer
 
 Requires Ruby >= 3.2.
 
+## Compatibility
+
+Tested against [rayhunter](https://github.com/EFForg/rayhunter/) v0.12.0 (last synced 2026-09-07). Older rayhunter versions may be missing some fields or endpoints raygatherer expects — commands that already have the connected daemon's version on hand (`stats`, `update status`) print a one-line warning to stderr when it's older than that, without blocking anything.
+
 ### From source
 
 ```bash
@@ -161,6 +168,11 @@ Main commands:
 - `config test-notification`
 - `stats`
 - `log`
+- `update status`
+- `gps show`
+- `gps set LAT LON` (requires gps_mode=Api on the device)
+- `wifi show`
+- `wifi scan`
 - `debug display-state <recording|paused|warning> [--severity low|medium|high]`
 
 For command-specific help:
@@ -195,6 +207,21 @@ code=$?
 [ "$code" -ge 11 ] && echo "medium or high alert"
 ```
 
+## Update Status Exit Codes
+
+`update status` returns a dedicated code so a cron job can react without parsing output:
+
+- `0`: up to date (or `auto_check_updates` is disabled on the device)
+- `1`: error
+- `20`: update available
+
+Example:
+
+```bash
+raygatherer --host http://192.168.1.1 update status
+[ $? -eq 20 ] && echo "rayhunter update available"
+```
+
 ## JSON Output
 
 Commands that support `--json` return machine-readable output to `stdout`. This is intended for `jq` and/or scripts.

data/lib/raygatherer/api_client.rb

@@ -79,6 +79,32 @@ module Raygatherer
       end
     end
 
+    def fetch_gps
+      get_optional("/api/gps") { |body| parse_json(body) }
+    end
+
+    def set_gps(latitude, longitude)
+      post("/api/gps", expected_code: "200",
+        body: ::JSON.generate({latitude: latitude, longitude: longitude}),
+        content_type: "application/json")
+    end
+
+    def fetch_wifi_status
+      get("/api/wifi-status") do |body|
+        parse_json(body)
+      end
+    end
+
+    def scan_wifi
+      parse_json(post("/api/wifi-scan", expected_code: "200"))
+    end
+
+    def fetch_update_status
+      get("/api/update-status") do |body|
+        parse_json(body)
+      end
+    end
+
     def set_time_offset(offset_seconds)
       post("/api/time-offset", expected_code: "200",
         body: ::JSON.generate({offset_seconds: offset_seconds}),
@@ -151,6 +177,26 @@ module Raygatherer
       raise
     end
 
+    def get_optional(path, not_found_code: "404")
+      response, body = request(:get, path, ok_code: "200", ok_status_text: "OK")
+
+      return nil if response.code == not_found_code
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise ApiError, server_error_message(response, body)
+      end
+
+      yield body
+    rescue ParseError => e
+      log_verbose "Parse failed: #{e.message}"
+      raise
+    end
+
+    # expected_code defaults to "202" (Accepted), matching the daemon's behavior for most POST
+    # actions (recordings, analysis, config). A handful of endpoints (gps, wifi-scan, time-offset,
+    # test-notification, display-state) respond "200" instead — pass expected_code: "200" for
+    # those. This isn't documented by rayhunter anywhere; it's observed per-endpoint behavior, so
+    # verify against the real device if you're adding a new one and unsure which applies.
     def post(path, expected_code: "202", body: nil, content_type: nil)
       ok_status_text = (expected_code == "202") ? "Accepted" : "OK"
       response, resp_body = request(:post, path, ok_code: expected_code,
@@ -164,16 +210,20 @@ module Raygatherer
     end
 
     def request(method, path, ok_code:, ok_status_text:, body: nil, content_type: nil)
-      url = "#{@host}#{path}"
-      uri = URI.parse(url)
+      with_connection_error_handling do
+        url = "#{@host}#{path}"
+        uri = URI.parse(url)
 
-      log_verbose "HTTP #{method.to_s.upcase} #{url}"
-      log_verbose "Basic Auth: user=#{@username}" if @username
+        log_verbose "HTTP #{method.to_s.upcase} #{url}"
+        log_verbose "Basic Auth: user=#{@username}" if @username
 
-      req = build_request(method, uri, body: body, content_type: content_type)
-      response, resp_body = execute_request(uri, req, ok_code: ok_code, ok_status_text: ok_status_text)
+        req = build_request(method, uri, body: body, content_type: content_type)
+        execute_request(uri, req, ok_code: ok_code, ok_status_text: ok_status_text)
+      end
+    end
 
-      [response, resp_body]
+    def with_connection_error_handling
+      yield
     rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
       log_verbose "Connection error: #{e.class} - #{e.message}"
       raise ConnectionError, "Failed to connect to #{@host}: #{e.message}"
@@ -220,28 +270,26 @@ module Raygatherer
       start_time = Time.now
       log_verbose "Request started at: #{start_time.utc}"
 
-      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
-        request = Net::HTTP::Get.new(uri.request_uri)
-        request.basic_auth(@username, @password) if @username && @password
+      with_connection_error_handling do
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          req = build_request(:get, uri)
 
-        http.request(request) do |response|
-          elapsed = Time.now - start_time
-          status_text = (response.code == "200") ? "OK" : response.message.to_s
-          log_verbose "Response received: #{response.code} #{status_text} (#{format("%.3f", elapsed)}s)"
+          http.request(req) do |response|
+            elapsed = Time.now - start_time
+            status_text = (response.code == "200") ? "OK" : response.message.to_s
+            log_verbose "Response received: #{response.code} #{status_text} (#{format("%.3f", elapsed)}s)"
 
-          unless response.is_a?(Net::HTTPSuccess)
-            error_body = response.read_body
-            raise ApiError, server_error_message(response, error_body)
-          end
+            unless response.is_a?(Net::HTTPSuccess)
+              error_body = response.read_body
+              raise ApiError, server_error_message(response, error_body)
+            end
 
-          response.read_body do |chunk|
-            io.write(chunk)
+            response.read_body do |chunk|
+              io.write(chunk)
+            end
           end
         end
       end
-    rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
-      log_verbose "Connection error: #{e.class} - #{e.message}"
-      raise ConnectionError, "Failed to connect to #{@host}: #{e.message}"
     end
 
     def server_error_message(response, body)

data/lib/raygatherer/cli.rb

@@ -16,23 +16,28 @@ module Raygatherer
     end
 
     ROUTES = {
-      ["log", nil] => {file: "commands/log", klass: "Commands::Log", json: false},
-      ["stats", nil] => {file: "commands/stats", klass: "Commands::Stats", json: true},
-      ["alerts", nil] => {file: "commands/alerts", klass: "Commands::Alerts", json: true},
-      ["recording", "list"] => {file: "commands/recording/list", klass: "Commands::Recording::List", json: true},
-      ["recording", "download"] => {file: "commands/recording/download", klass: "Commands::Recording::Download", json: false},
-      ["recording", "delete"] => {file: "commands/recording/delete", klass: "Commands::Recording::Delete", json: false},
-      ["recording", "stop"] => {file: "commands/recording/stop", klass: "Commands::Recording::Stop", json: false},
-      ["recording", "start"] => {file: "commands/recording/start", klass: "Commands::Recording::Start", json: false},
-      ["analysis", "status"] => {file: "commands/analysis/status", klass: "Commands::Analysis::Status", json: true},
-      ["analysis", "run"] => {file: "commands/analysis/run", klass: "Commands::Analysis::Run", json: true},
-      ["analysis", "report"] => {file: "commands/analysis/report", klass: "Commands::Analysis::Report", json: true},
-      ["config", "show"] => {file: "commands/config/show", klass: "Commands::Config::Show", json: true},
-      ["config", "set"] => {file: "commands/config/set", klass: "Commands::Config::Set", json: false},
-      ["config", "test-notification"] => {file: "commands/config/test_notification", klass: "Commands::Config::TestNotification", json: false},
-      ["debug", "display-state"] => {file: "commands/debug/display_state", klass: "Commands::Debug::DisplayState", json: false},
-      ["time", "show"] => {file: "commands/time/show", klass: "Commands::Time::Show", json: true},
-      ["time", "sync"] => {file: "commands/time/sync", klass: "Commands::Time::Sync", json: false}
+      ["log", nil] => {klass: "Commands::Log", json: false},
+      ["stats", nil] => {klass: "Commands::Stats", json: true},
+      ["alerts", nil] => {klass: "Commands::Alerts", json: true},
+      ["recording", "list"] => {klass: "Commands::Recording::List", json: true},
+      ["recording", "download"] => {klass: "Commands::Recording::Download", json: false},
+      ["recording", "delete"] => {klass: "Commands::Recording::Delete", json: false},
+      ["recording", "stop"] => {klass: "Commands::Recording::Stop", json: false},
+      ["recording", "start"] => {klass: "Commands::Recording::Start", json: false},
+      ["analysis", "status"] => {klass: "Commands::Analysis::Status", json: true},
+      ["analysis", "run"] => {klass: "Commands::Analysis::Run", json: true},
+      ["analysis", "report"] => {klass: "Commands::Analysis::Report", json: true},
+      ["config", "show"] => {klass: "Commands::Config::Show", json: true},
+      ["config", "set"] => {klass: "Commands::Config::Set", json: false},
+      ["config", "test-notification"] => {klass: "Commands::Config::TestNotification", json: false},
+      ["debug", "display-state"] => {klass: "Commands::Debug::DisplayState", json: false},
+      ["time", "show"] => {klass: "Commands::Time::Show", json: true},
+      ["time", "sync"] => {klass: "Commands::Time::Sync", json: false},
+      ["update", "status"] => {klass: "Commands::Update::Status", json: true},
+      ["gps", "show"] => {klass: "Commands::Gps::Show", json: true},
+      ["gps", "set"] => {klass: "Commands::Gps::Set", json: false},
+      ["wifi", "show"] => {klass: "Commands::Wifi::Show", json: true},
+      ["wifi", "scan"] => {klass: "Commands::Wifi::Scan", json: true}
     }.freeze
 
     def self.run(argv, stdout: $stdout, stderr: $stderr, config: Config.new)
@@ -91,7 +96,6 @@ module Raygatherer
         return Commands::EXIT_CODE_ERROR
       end
 
-      require_relative route[:file]
       return Commands::EXIT_CODE_ERROR unless require_host!
 
       kwargs = {stdout: @stdout, stderr: @stderr, api_client: build_api_client}
@@ -189,6 +193,11 @@ module Raygatherer
       output.puts "    debug display-state STATE         Set device display state (recording, paused, warning)"
       output.puts "    time show                        Show device time (system, adjusted, offset)"
       output.puts "    time sync                        Sync device clock to this machine's time"
+      output.puts "    update status                    Show rayhunter daemon update status"
+      output.puts "    gps show                         Show last known GPS position"
+      output.puts "    gps set LAT LON                  Submit a GPS position (requires gps_mode=Api on device)"
+      output.puts "    wifi show                        Show wifi client connection status"
+      output.puts "    wifi scan                        Scan for available wifi networks"
       output.puts "    log                              Download the device log"
       output.puts "    stats                            Show device system stats"
       output.puts ""

data/lib/raygatherer/commands/alerts.rb

@@ -21,8 +21,7 @@ module Raygatherer
       EXIT_CODE_HIGH_SEVERITY = 12
 
       def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-        super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-        @json = json
+        super
         @latest = false
         @after = nil
         @recording = nil
@@ -41,11 +40,9 @@ module Raygatherer
           alerts = filter_after(alerts) if @after
           alerts = filter_latest(alerts, data[:rows]) if @latest
 
-          # Select formatter based on --json flag
           formatter = @json ? Formatters::AlertsJSON.new : Formatters::AlertsHuman.new
           @stdout.puts formatter.format(alerts)
 
-          # Return severity-based exit code
           severity_exit_code(alerts)
         end
       end
@@ -70,10 +67,7 @@ module Raygatherer
             @after = parse_timestamp(ts)
           end
 
-          opts.on("-h", "--help", "Show this help message") do
-            show_help
-            raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-          end
+          add_help_option(opts)
         end.parse!(@argv)
       end
 

data/lib/raygatherer/commands/analysis/report.rb

@@ -10,8 +10,7 @@ module Raygatherer
     module Analysis
       class Report < Base
         def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-          @json = json
+          super
           @live = false
         end
 
@@ -52,10 +51,7 @@ module Raygatherer
               @live = true
             end
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/analysis/run.rb

@@ -10,8 +10,7 @@ module Raygatherer
     module Analysis
       class Run < Base
         def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-          @json = json
+          super
           @all = false
         end
 
@@ -59,10 +58,7 @@ module Raygatherer
               @all = true
             end
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/analysis/status.rb

@@ -9,11 +9,6 @@ module Raygatherer
   module Commands
     module Analysis
       class Status < Base
-        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-          @json = json
-        end
-
         def run
           with_error_handling do
             parse_options
@@ -35,10 +30,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/base.rb

@@ -10,15 +10,23 @@ module Raygatherer
         new(argv, **kwargs).run
       end
 
-      def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, **_kwargs)
+      def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false, **_kwargs)
         @argv = argv
         @stdout = stdout
         @stderr = stderr
         @api_client = api_client
+        @json = json
       end
 
       private
 
+      def add_help_option(opts)
+        opts.on("-h", "--help", "Show this help message") do
+          show_help
+          raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+        end
+      end
+
       def print_global_options(output, json: false)
         output.puts "Global options (see 'raygatherer --help'):"
         if json
@@ -36,6 +44,17 @@ module Raygatherer
         @stderr.puts "Error: #{e.message}"
         EXIT_CODE_ERROR
       end
+
+      def warn_if_rayhunter_outdated(rayhunter_version)
+        actual = Gem::Version.new(rayhunter_version)
+        tested = Gem::Version.new(Raygatherer::TESTED_RAYHUNTER_VERSION)
+        return unless actual < tested
+
+        @stderr.puts "Warning: connected rayhunter is v#{rayhunter_version}; raygatherer was last " \
+          "tested against v#{Raygatherer::TESTED_RAYHUNTER_VERSION} — some fields or commands may not be supported."
+      rescue ArgumentError
+        nil
+      end
     end
   end
 end

data/lib/raygatherer/commands/config/set.rb

@@ -48,10 +48,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/config/show.rb

@@ -9,11 +9,6 @@ module Raygatherer
   module Commands
     module Config
       class Show < Base
-        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-          @json = json
-        end
-
         def run
           with_error_handling do
             parse_options
@@ -35,10 +30,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/config/test_notification.rb

@@ -26,10 +26,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/debug/display_state.rb

@@ -64,10 +64,7 @@ module Raygatherer
               @severity = s
             end
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/gps/set.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Raygatherer
+  module Commands
+    module Gps
+      class Set < Base
+        def run
+          with_error_handling do
+            parse_options
+
+            unless @argv.length == 2
+              @stderr.puts "Error: latitude and longitude are required (usage: gps set LAT LON)"
+              return EXIT_CODE_ERROR
+            end
+
+            lat_str, lon_str = @argv
+
+            latitude = parse_coordinate(lat_str, "latitude")
+            return EXIT_CODE_ERROR unless latitude
+
+            longitude = parse_coordinate(lon_str, "longitude")
+            return EXIT_CODE_ERROR unless longitude
+
+            @api_client.set_gps(latitude, longitude)
+            @stdout.puts "GPS position set: #{latitude}, #{longitude}"
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_coordinate(str, label)
+          Float(str)
+        rescue ArgumentError
+          @stderr.puts "Error: #{label} must be a number (got #{str.inspect})"
+          nil
+        end
+
+        # Deliberately not using OptionParser#parse! here: a negative longitude like "-0.1"
+        # looks like an unrecognized flag to it and raises OptionParser::InvalidOption. This
+        # command's only "option" is help, so just scan for it directly instead.
+        def parse_options
+          return unless @argv.include?("-h") || @argv.include?("--help")
+
+          show_help
+          raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] gps set [options] LAT LON"
+          output.puts ""
+          output.puts "Submit a GPS position to the device, to be embedded into the current recording."
+          output.puts "Requires the device's gps_mode config to be set to 'Api' (see 'config show'/'config set')."
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 gps set 51.5074 -0.1278"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/gps/show.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../base"
+require_relative "../../formatters/gps_json"
+require_relative "../../formatters/gps_human"
+
+module Raygatherer
+  module Commands
+    module Gps
+      class Show < Base
+        def run
+          with_error_handling do
+            parse_options
+
+            gps = @api_client.fetch_gps
+
+            formatter = @json ? Formatters::GpsJSON.new : Formatters::GpsHuman.new
+            @stdout.puts formatter.format(gps)
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer gps show [options]"
+            opts.separator ""
+            opts.separator "Options:"
+
+            add_help_option(opts)
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] gps show [options]"
+          output.puts ""
+          output.puts "Show the last GPS position submitted to the device (see 'gps set')."
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output, json: true)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 gps show"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 --json gps show"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/log.rb

@@ -18,10 +18,7 @@ module Raygatherer
 
       def parse_options
         OptionParser.new do |opts|
-          opts.on("-h", "--help", "Show this help message") do
-            show_help
-            raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-          end
+          add_help_option(opts)
         end.parse!(@argv)
       end
 

data/lib/raygatherer/commands/recording/delete.rb

@@ -20,7 +20,7 @@ module Raygatherer
 
             if @all && !@argv.empty?
               @stderr.puts "Error: cannot specify both a recording name and --all"
-              next EXIT_CODE_ERROR
+              return EXIT_CODE_ERROR
             end
 
             if @all
@@ -72,10 +72,7 @@ module Raygatherer
               @force = true
             end
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/recording/download.rb

@@ -87,10 +87,7 @@ module Raygatherer
               @save_as = path
             end
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/recording/list.rb

@@ -9,11 +9,6 @@ module Raygatherer
   module Commands
     module Recording
       class List < Base
-        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-          @json = json
-        end
-
         def run
           with_error_handling do
             parse_options
@@ -35,10 +30,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/recording/start.rb

@@ -30,10 +30,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/recording/stop.rb

@@ -30,10 +30,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/stats.rb

@@ -8,17 +8,15 @@ require_relative "../formatters/stats_human"
 module Raygatherer
   module Commands
     class Stats < Base
-      def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-        super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-        @json = json
-      end
-
       def run
         with_error_handling do
           parse_options
 
           stats = @api_client.fetch_system_stats
 
+          rayhunter_version = stats.dig("runtime_metadata", "rayhunter_version")
+          warn_if_rayhunter_outdated(rayhunter_version) if rayhunter_version
+
           formatter = @json ? Formatters::StatsJSON.new : Formatters::StatsHuman.new
           @stdout.puts formatter.format(stats)
 
@@ -34,10 +32,7 @@ module Raygatherer
           opts.separator ""
           opts.separator "Options:"
 
-          opts.on("-h", "--help", "Show this help message") do
-            show_help
-            raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-          end
+          add_help_option(opts)
         end.parse!(@argv)
       end
 

data/lib/raygatherer/commands/time/show.rb

@@ -9,11 +9,6 @@ module Raygatherer
   module Commands
     module Time
       class Show < Base
-        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
-          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
-          @json = json
-        end
-
         def run
           with_error_handling do
             parse_options
@@ -35,10 +30,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/time/sync.rb

@@ -30,10 +30,7 @@ module Raygatherer
             opts.separator ""
             opts.separator "Options:"
 
-            opts.on("-h", "--help", "Show this help message") do
-              show_help
-              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
-            end
+            add_help_option(opts)
           end.parse!(@argv)
         end
 

data/lib/raygatherer/commands/update/status.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../base"
+require_relative "../../formatters/update_status_json"
+require_relative "../../formatters/update_status_human"
+
+module Raygatherer
+  module Commands
+    module Update
+      class Status < Base
+        EXIT_CODE_UPDATE_AVAILABLE = 20
+
+        def run
+          with_error_handling do
+            parse_options
+
+            status = @api_client.fetch_update_status
+
+            warn_if_rayhunter_outdated(status["current_version"]) if status["current_version"]
+
+            formatter = @json ? Formatters::UpdateStatusJSON.new : Formatters::UpdateStatusHuman.new
+            @stdout.puts formatter.format(status)
+
+            status["update_available"] ? EXIT_CODE_UPDATE_AVAILABLE : EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer update status [options]"
+            opts.separator ""
+            opts.separator "Options:"
+
+            add_help_option(opts)
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] update status [options]"
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output, json: true)
+          output.puts ""
+          output.puts "Exit Codes:"
+          output.puts "    #{EXIT_CODE_SUCCESS}   Up to date (or auto_check_updates is disabled on the device)"
+          output.puts "    #{EXIT_CODE_ERROR}   Error (connection, parse, missing --host, etc.)"
+          output.puts "    #{EXIT_CODE_UPDATE_AVAILABLE}  Update available"
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 update status"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 --json update status"
+          output.puts "  raygatherer --host http://rayhunter update status; [ $? -eq #{EXIT_CODE_UPDATE_AVAILABLE} ] && telegram-send 'Rayhunter update available!'"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/wifi/scan.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../base"
+require_relative "../../formatters/wifi_scan_json"
+require_relative "../../formatters/wifi_scan_human"
+
+module Raygatherer
+  module Commands
+    module Wifi
+      class Scan < Base
+        def run
+          with_error_handling do
+            parse_options
+
+            networks = @api_client.scan_wifi
+
+            formatter = @json ? Formatters::WifiScanJSON.new : Formatters::WifiScanHuman.new
+            @stdout.puts formatter.format(networks)
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer wifi scan [options]"
+            opts.separator ""
+            opts.separator "Options:"
+
+            add_help_option(opts)
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] wifi scan [options]"
+          output.puts ""
+          output.puts "Scan for nearby wifi networks the device could connect to as a client."
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output, json: true)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 wifi scan"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 --json wifi scan"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/wifi/show.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../base"
+require_relative "../../formatters/wifi_status_json"
+require_relative "../../formatters/wifi_status_human"
+
+module Raygatherer
+  module Commands
+    module Wifi
+      class Show < Base
+        def run
+          with_error_handling do
+            parse_options
+
+            status = @api_client.fetch_wifi_status
+
+            formatter = @json ? Formatters::WifiStatusJSON.new : Formatters::WifiStatusHuman.new
+            @stdout.puts formatter.format(status)
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer wifi show [options]"
+            opts.separator ""
+            opts.separator "Options:"
+
+            add_help_option(opts)
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] wifi show [options]"
+          output.puts ""
+          output.puts "Show the device's wifi client connection status (the daemon's own outbound"
+          output.puts "connection to an upstream network, separate from the AP it hosts)."
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output, json: true)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 wifi show"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 --json wifi show"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/config_human.rb

@@ -7,12 +7,49 @@ module Raygatherer
         lines = []
 
         lines << "Port: #{config["port"]}"
-        lines << "Readonly port: #{config["readonly_port"]}"
         lines << "QMDL store path: #{config["qmdl_store_path"]}"
+        lines << "Device: #{config["device"]}" if config.key?("device")
+        lines << "Debug mode: #{config["debug_mode"]}" if config.key?("debug_mode")
+        lines << "UI level: #{config["ui_level"]}" if config.key?("ui_level")
+        lines << "Colorblind mode: #{config["colorblind_mode"]}" if config.key?("colorblind_mode")
+        lines << "Key input mode: #{config["key_input_mode"]}" if config.key?("key_input_mode")
 
-        notification_url = config["notification_url"]
+        notification_url = config["ntfy_url"] || config["notification_url"]
         lines << "Notification URL: #{notification_url || "(not set)"}"
 
+        if config.key?("enabled_notifications")
+          lines << "Notifications enabled: #{config["enabled_notifications"].join(", ")}"
+        end
+
+        if config.key?("min_space_to_start_recording_mb")
+          lines << "Min space to start recording: #{config["min_space_to_start_recording_mb"]} MB"
+        end
+        if config.key?("min_space_to_continue_recording_mb")
+          lines << "Min space to continue recording: #{config["min_space_to_continue_recording_mb"]} MB"
+        end
+
+        lines << "Auto check updates: #{config["auto_check_updates"]}" if config.key?("auto_check_updates")
+        lines << "Clock sync mode: #{config["clock_sync_mode"]}" if config.key?("clock_sync_mode")
+        lines << "GPS mode: #{config["gps_mode"]}" if config.key?("gps_mode")
+        lines << "GPS fixed latitude: #{config["gps_fixed_latitude"]}" if config["gps_fixed_latitude"]
+        lines << "GPS fixed longitude: #{config["gps_fixed_longitude"]}" if config["gps_fixed_longitude"]
+        lines << "WiFi enabled: #{config["wifi_enabled"]}" if config.key?("wifi_enabled")
+        lines << "WiFi SSID: #{config["wifi_ssid"]}" if config["wifi_ssid"]
+        lines << "WiFi security: #{config["wifi_security"]}" if config["wifi_security"]
+        lines << "DNS servers: #{config["dns_servers"].join(", ")}" if config["dns_servers"]&.any?
+
+        webdav = config["webdav"]
+        if webdav && !webdav["url"].to_s.empty?
+          lines << ""
+          lines << "WebDAV:"
+          lines << "  URL: #{webdav["url"]}"
+          lines << "  Username: #{webdav["username"]}" if webdav["username"]
+          lines << "  Upload timeout: #{webdav["upload_timeout_secs"]}s" if webdav.key?("upload_timeout_secs")
+          lines << "  Poll interval: #{webdav["poll_interval_secs"]}s" if webdav.key?("poll_interval_secs")
+          lines << "  Min age: #{webdav["min_age_secs"]}s" if webdav.key?("min_age_secs")
+          lines << "  Delete on upload: #{webdav["delete_on_upload"]}" if webdav.key?("delete_on_upload")
+        end
+
         analyzers = config["analyzers"]
         if analyzers
           lines << ""

data/lib/raygatherer/formatters/gps_human.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Raygatherer
+  module Formatters
+    class GpsHuman
+      def format(gps)
+        return "No GPS position recorded yet (nothing has been submitted to /api/gps this session)." if gps.nil?
+
+        "Latitude:  #{gps["latitude"]}\nLongitude: #{gps["longitude"]}"
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/gps_json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Raygatherer
+  module Formatters
+    class GpsJSON
+      def format(gps)
+        ::JSON.generate(gps)
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/update_status_human.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Raygatherer
+  module Formatters
+    class UpdateStatusHuman
+      def format(status)
+        lines = []
+
+        lines << "Current version: #{status["current_version"]}"
+        lines << "Update available: #{status["update_available"] ? "yes" : "no"}"
+        lines << "Latest version: #{status["latest_version"]}" if status["latest_version"]
+        lines << "Release notes: #{status["latest_release_url"]}" if status["latest_release_url"]
+        lines << "Last checked: #{status["last_checked"]}" if status["last_checked"]
+        lines << "Last error: #{status["last_error"]}" if status["last_error"]
+
+        if status["latest_version"].nil? && status["last_checked"].nil?
+          lines << ""
+          lines << "No update check has run yet — check that auto_check_updates is enabled in rayhunter's config."
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/update_status_json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Raygatherer
+  module Formatters
+    class UpdateStatusJSON
+      def format(status)
+        ::JSON.generate(status)
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/wifi_scan_human.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Raygatherer
+  module Formatters
+    class WifiScanHuman
+      def format(networks)
+        return "No networks found" if networks.empty?
+
+        lines = ["Networks: #{networks.length}", ""]
+        networks.each do |network|
+          lines << "#{network["ssid"]} (#{network["signal_dbm"]} dBm, #{network["security"]})"
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/wifi_scan_json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Raygatherer
+  module Formatters
+    class WifiScanJSON
+      def format(networks)
+        ::JSON.generate(networks)
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/wifi_status_human.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Raygatherer
+  module Formatters
+    class WifiStatusHuman
+      def format(status)
+        lines = []
+
+        lines << "State: #{status["state"]}"
+        lines << "SSID: #{status["ssid"]}" if status["ssid"]
+        lines << "IP: #{status["ip"]}" if status["ip"]
+        lines << "TX packets: #{status["txPackets"]}" if status["txPackets"]
+        lines << "Error: #{status["error"]}" if status["error"]
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/wifi_status_json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Raygatherer
+  module Formatters
+    class WifiStatusJSON
+      def format(status)
+        ::JSON.generate(status)
+      end
+    end
+  end
+end

data/lib/raygatherer/version.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
 module Raygatherer
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
+
+  # The rayhunter daemon version this release was last verified against. Used only to warn
+  # when talking to an older daemon that may lack fields/endpoints raygatherer expects;
+  # never enforced.
+  TESTED_RAYHUNTER_VERSION = "0.12.0"
 end

data/lib/raygatherer.rb

@@ -18,6 +18,14 @@ require_relative "raygatherer/formatters/config_json"
 require_relative "raygatherer/formatters/config_human"
 require_relative "raygatherer/formatters/time_json"
 require_relative "raygatherer/formatters/time_human"
+require_relative "raygatherer/formatters/update_status_json"
+require_relative "raygatherer/formatters/update_status_human"
+require_relative "raygatherer/formatters/gps_json"
+require_relative "raygatherer/formatters/gps_human"
+require_relative "raygatherer/formatters/wifi_status_json"
+require_relative "raygatherer/formatters/wifi_status_human"
+require_relative "raygatherer/formatters/wifi_scan_json"
+require_relative "raygatherer/formatters/wifi_scan_human"
 require_relative "raygatherer/spinner"
 require_relative "raygatherer/commands/base"
 require_relative "raygatherer/commands/alerts"
@@ -37,6 +45,11 @@ require_relative "raygatherer/commands/config/test_notification"
 require_relative "raygatherer/commands/debug/display_state"
 require_relative "raygatherer/commands/time/show"
 require_relative "raygatherer/commands/time/sync"
+require_relative "raygatherer/commands/update/status"
+require_relative "raygatherer/commands/gps/show"
+require_relative "raygatherer/commands/gps/set"
+require_relative "raygatherer/commands/wifi/show"
+require_relative "raygatherer/commands/wifi/scan"
 
 module Raygatherer
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raygatherer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Mike Stallard
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: 'Ruby CLI tool for interacting with Rayhunter, a cell tower analysis
   device for detecting IMSI catchers and other cellular network anomalies. '
 email:
@@ -65,6 +79,8 @@ files:
 - lib/raygatherer/commands/config/show.rb
 - lib/raygatherer/commands/config/test_notification.rb
 - lib/raygatherer/commands/debug/display_state.rb
+- lib/raygatherer/commands/gps/set.rb
+- lib/raygatherer/commands/gps/show.rb
 - lib/raygatherer/commands/log.rb
 - lib/raygatherer/commands/recording/delete.rb
 - lib/raygatherer/commands/recording/download.rb
@@ -74,6 +90,9 @@ files:
 - lib/raygatherer/commands/stats.rb
 - lib/raygatherer/commands/time/show.rb
 - lib/raygatherer/commands/time/sync.rb
+- lib/raygatherer/commands/update/status.rb
+- lib/raygatherer/commands/wifi/scan.rb
+- lib/raygatherer/commands/wifi/show.rb
 - lib/raygatherer/config.rb
 - lib/raygatherer/format_helpers.rb
 - lib/raygatherer/formatters/alerts_human.rb
@@ -84,12 +103,20 @@ files:
 - lib/raygatherer/formatters/analysis_status_json.rb
 - lib/raygatherer/formatters/config_human.rb
 - lib/raygatherer/formatters/config_json.rb
+- lib/raygatherer/formatters/gps_human.rb
+- lib/raygatherer/formatters/gps_json.rb
 - lib/raygatherer/formatters/recording_list_human.rb
 - lib/raygatherer/formatters/recording_list_json.rb
 - lib/raygatherer/formatters/stats_human.rb
 - lib/raygatherer/formatters/stats_json.rb
 - lib/raygatherer/formatters/time_human.rb
 - lib/raygatherer/formatters/time_json.rb
+- lib/raygatherer/formatters/update_status_human.rb
+- lib/raygatherer/formatters/update_status_json.rb
+- lib/raygatherer/formatters/wifi_scan_human.rb
+- lib/raygatherer/formatters/wifi_scan_json.rb
+- lib/raygatherer/formatters/wifi_status_human.rb
+- lib/raygatherer/formatters/wifi_status_json.rb
 - lib/raygatherer/spinner.rb
 - lib/raygatherer/version.rb
 homepage: https://github.com/mjstallard/raygatherer
@@ -113,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.9
 specification_version: 4
 summary: CLI for fetching and displaying alerts from Rayhunter
 test_files: []