rshelly 0.1.0

data/lib/rshelly/cli.rb

@@ -0,0 +1,1067 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../rshelly"
+
+module Shelly
+  class CLI
+    COMMAND_ALIASES = {
+      "temperature" => "temp",
+      "get" => "gen1"
+    }.freeze
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @options = { timeout: 5, json: false }
+    end
+
+    def run
+      parse_global_options!
+      command = @argv.shift
+      return command_help(command) if command && consume_help_flag!
+
+      case command
+      when "discover" then discover
+      when "scan" then scan
+      when "info" then with_client { |client| output(client.normalized_info, :info) }
+      when "status" then with_client { |client| output(client.status, :status, host: client.host) }
+      when "config" then with_client { |client| output(client.config, :config, host: client.host) }
+      when "switch" then switch
+      when "meter" then meter
+      when "temp", "temperature" then temperature
+      when "rgbw" then rgbw
+      when "light" then light
+      when "update" then update
+      when "reboot" then reboot
+      when "wifi" then wifi
+      when "rpc" then rpc
+      when "gen1", "get" then gen1_get
+      when "mqtt" then mqtt
+      when "input" then input
+      when "webhook" then webhook
+      when "help" then command_help(@argv.shift)
+      when nil then help
+      when "version", "--version", "-v"
+        @stdout.puts VERSION
+        0
+      else
+        raise Error, "unknown command: #{command}"
+      end
+    rescue Error, OptionParser::ParseError, ArgumentError, JSON::ParserError => e
+      @stderr.puts "shelly: #{e.message}"
+      @stderr.puts "Run `shelly help` for usage."
+      1
+    end
+
+    private
+
+    def parse_global_options!
+      parser = OptionParser.new do |opts|
+        opts.on("--json", "Print JSON") { @options[:json] = true }
+        opts.on("--timeout SECONDS", Float, "HTTP/discovery timeout") { |value| @options[:timeout] = value }
+        opts.on("-h", "--help", "Print help") { @options[:help] = true }
+        opts.on("-v", "--version", "Print version") { @options[:version] = true }
+      end
+      parser.order!(@argv)
+      @argv.unshift("version") if @options[:version]
+      @argv.unshift("help") if @options[:help]
+    end
+
+    def discover
+      verify = consume_flag!("--verify")
+      concurrency = consume_option!("--concurrency", Integer) || Discovery::DEFAULT_CONCURRENCY
+      raise Error, "unexpected arguments: #{@argv.join(" ")}" unless @argv.empty?
+
+      output(
+        Discovery.discover(
+          timeout: @options[:timeout],
+          verify: verify,
+          concurrency: concurrency,
+          client_options: client_options
+        ),
+        verify ? :devices : :discovery
+      )
+    end
+
+    def scan
+      concurrency = consume_option!("--concurrency", Integer) || Discovery::DEFAULT_CONCURRENCY
+      max_hosts = consume_option!("--max-hosts", Integer) || 4096
+      network = @argv.shift
+      raise Error, "unexpected arguments: #{@argv.join(" ")}" unless @argv.empty?
+
+      output(Discovery.scan(
+        network: network,
+        timeout: @options[:timeout],
+        concurrency: concurrency,
+        max_hosts: max_hosts,
+        client_options: client_options
+      ), :devices)
+    end
+
+    def switch
+      host = require_arg!("HOST")
+      action = require_arg!("ACTION")
+      id = consume_option!("--id", Integer) || 0
+      client = Client.new(host, **client_options)
+
+      result = case action
+      when "get", "status" then client.switch_status(id)
+      when "on" then client.switch_set(id: id, on: true)
+      when "off" then client.switch_set(id: id, on: false)
+      when "toggle" then client.switch_toggle(id)
+      else raise Error, "switch action must be get, on, off, or toggle"
+      end
+      output(result, :switch, host: host, action: action, id: id)
+    end
+
+    def meter
+      host = require_arg!("HOST")
+      id = consume_option!("--id", Integer) || 0
+      output(Client.new(host, **client_options).meter_status(id), :meter, host: host, id: id)
+    end
+
+    def temperature
+      host = require_arg!("HOST")
+      id = consume_option!("--id", Integer) || 100
+      output(Client.new(host, **client_options).temperature_status(id: id), :temperature, host: host, id: id)
+    end
+
+    def rgbw
+      host = require_arg!("HOST")
+      action = require_arg!("ACTION")
+      client = Client.new(host, **client_options)
+
+      case action
+      when "get", "status"
+        id = consume_option!("--id", Integer) || 0
+        output(client.rgbw_status(id), :rgbw, host: host, action: action, id: id)
+      when "set"
+        opts = parse_rgbw_set_options
+        output(client.rgbw_set(**opts), :write, action: "RGBW set", host: host)
+      else
+        raise Error, "rgbw action must be get or set"
+      end
+    end
+
+    def light
+      host = require_arg!("HOST")
+      action = require_arg!("ACTION")
+      id = consume_option!("--id", Integer) || 0
+      client = Client.new(host, **client_options)
+
+      case action
+      when "get", "status"
+        output(client.light_status(id), :light, host: host, action: action, id: id)
+      when "set"
+        on = consume_flag!("--on") ? true : nil
+        on = false if consume_flag!("--off")
+        brightness = consume_option!("--brightness", Integer)
+        transition_duration = consume_option!("--transition", Float)
+        output(client.light_set(id: id, on: on, brightness: brightness, transition_duration: transition_duration), :write, action: "Light set", host: host)
+      else
+        raise Error, "light action must be get or set"
+      end
+    end
+
+    def update
+      action = require_arg!("ACTION")
+      host = require_arg!("HOST")
+      client = Client.new(host, **client_options)
+
+      case action
+      when "check" then output(client.update_info, :update_check, host: host)
+      when "start" then output(client.update_start(stage: consume_option!("--stage") || "stable"), :write, action: "Update started", host: host)
+      else raise Error, "update action must be check or start"
+      end
+    end
+
+    def reboot
+      host = require_arg!("HOST")
+      output(Client.new(host, **client_options).reboot, :write, action: "Reboot requested", host: host)
+    end
+
+    def wifi
+      options = parse_wifi_options
+      host = require_arg!("HOST")
+      slot = require_arg!("primary|secondary")
+      ssid = require_arg!("SSID")
+      password = @argv.shift
+      raise Error, "missing PASSWORD" unless password
+      raise Error, "unexpected arguments: #{@argv.join(" ")}" unless @argv.empty?
+
+      output(Client.new(host, **client_options).set_wifi(
+        slot: slot,
+        ssid: ssid,
+        password: password,
+        ip: options[:ip],
+        netmask: options[:netmask],
+        gw: options[:gw],
+        dns: options[:dns]
+      ), :write, action: "Wi-Fi #{slot} configured", host: host)
+    end
+
+    def rpc
+      host = require_arg!("HOST")
+      method = require_arg!("METHOD")
+      params = @argv.empty? ? nil : parse_json_or_file(@argv.shift)
+      output(Client.new(host, **client_options).rpc(method, params), :raw, title: "#{host} #{method}")
+    end
+
+    def gen1_get
+      host = require_arg!("HOST")
+      path = require_arg!("PATH")
+      params = parse_key_values(@argv)
+      output(Client.new(host, **client_options).get_json(path, params), :raw, title: "#{host} #{path}")
+    end
+
+    def mqtt
+      host = require_arg!("HOST")
+      server = require_arg!("SERVER")
+      enable = !consume_flag!("--disable")
+      output(Client.new(host, **client_options).enable_mqtt(server: server, enable: enable), :write, action: enable ? "MQTT configured" : "MQTT disabled", host: host)
+    end
+
+    def input
+      action = require_arg!("ACTION")
+      raise Error, "input action must be setup" unless action == "setup"
+
+      host = require_arg!("HOST")
+      device_id = consume_option!("--device-id") || consume_option!("--prefix") || require_arg!("DEVICE_ID")
+      base_url = consume_option!("--base-url") || "http://home.home/inputs"
+      count = consume_option!("--count", Integer) || 4
+      client = Client.new(host, **client_options)
+
+      client.set_device_name("input_device_#{device_id}")
+      client.webhook_delete_all
+      created = []
+
+      (0...count).each do |cid|
+        input_name = "input_#{cid + 1}"
+        input_id = "#{device_id}-#{cid + 1}"
+        client.input_set_config(id: cid, type: "button", name: input_name)
+
+        %w[push longpush doublepush].each do |event|
+          url = "#{base_url}/#{input_id}/#{event}"
+          client.webhook_create(
+            cid: cid,
+            name: event,
+            event: "input.button_#{event}",
+            urls: [url]
+          )
+          created << { input: input_id, cid: cid, event: event, url: url }
+        end
+      end
+
+      output(created, :input_setup, host: host, device_id: device_id)
+    end
+
+    def webhook
+      action = require_arg!("ACTION")
+      host = require_arg!("HOST")
+      client = Client.new(host, **client_options)
+
+      case action
+      when "delete-all" then output(client.webhook_delete_all, :write, action: "Webhooks deleted", host: host)
+      else raise Error, "webhook action must be delete-all"
+      end
+    end
+
+    def with_client
+      host = require_arg!("HOST")
+      yield Client.new(host, **client_options)
+    end
+
+    def parse_rgbw_set_options
+      result = { id: 0 }
+      parser = OptionParser.new do |opts|
+        opts.on("--id ID", Integer) { |value| result[:id] = value }
+        opts.on("--on") { result[:on] = true }
+        opts.on("--off") { result[:on] = false }
+        opts.on("--brightness N", Integer) { |value| result[:brightness] = value }
+        opts.on("--white N", Integer) { |value| result[:white] = value }
+        opts.on("--red N", Integer) { |value| result[:red] = value }
+        opts.on("--green N", Integer) { |value| result[:green] = value }
+        opts.on("--blue N", Integer) { |value| result[:blue] = value }
+        opts.on("--transition SECONDS", Float) { |value| result[:transition_duration] = value }
+      end
+      parser.parse!(@argv)
+      result
+    end
+
+    def parse_wifi_options
+      result = {}
+      parser = OptionParser.new do |opts|
+        opts.on("--ip IP") { |value| result[:ip] = value }
+        opts.on("--netmask MASK") { |value| result[:netmask] = value }
+        opts.on("--mask MASK") { |value| result[:netmask] = value }
+        opts.on("--gw IP") { |value| result[:gw] = value }
+        opts.on("--gateway IP") { |value| result[:gw] = value }
+        opts.on("--dns IP") { |value| result[:dns] = value }
+        opts.on("--nameserver IP") { |value| result[:dns] = value }
+      end
+      parser.parse!(@argv)
+      result
+    end
+
+    def output(value, format = :raw, context = {})
+      if @options[:json]
+        @stdout.puts JSON.pretty_generate(value)
+      else
+        @stdout.puts human_output(value, format, context)
+      end
+      0
+    end
+
+    def human_output(value, format, context)
+      case format
+      when :devices then devices_table(value)
+      when :discovery then discovery_table(value)
+      when :info then info_block(value)
+      when :status then status_block(value, context)
+      when :config then config_block(value, context)
+      when :switch then switch_line(value, context)
+      when :meter then meter_block(value, context)
+      when :temperature then temperature_block(value, context)
+      when :light, :rgbw then component_block(value, context)
+      when :update_check then update_check_block(value, context)
+      when :write then write_line(value, context)
+      when :input_setup then input_setup_block(value, context)
+      else raw_block(value, context[:title])
+      end
+    end
+
+    def devices_table(devices)
+      rows = Array(devices).map do |device|
+        raw = device["raw"] || {}
+        wifi = raw["wifi"] || {}
+        update = device["update"] || {}
+        [
+          device["ip"],
+          device["gen"],
+          device["model"] || device["model_id"],
+          device["name"],
+          device["hostname"],
+          update_label(update),
+          wifi["ssid"] || raw.dig("wifi_sta", "ssid"),
+          wifi["rssi"] || raw.dig("wifi_sta", "rssi"),
+          short_version(device["firmware"] || update["current_version"])
+        ]
+      end
+      table(%w[IP Gen Model Name Hostname Update Wi-Fi RSSI Firmware], rows)
+    end
+
+    def discovery_table(records)
+      rows = Array(records).map do |record|
+        [
+          record[:ip] || record["ip"],
+          record[:name] || record["name"],
+          record[:hostname] || record["hostname"],
+          record[:source] || record["source"],
+          record[:gen] || record["gen"],
+          record[:mac] || record["mac"]
+        ]
+      end
+      table(%w[IP Name Hostname Source Gen MAC], rows)
+    end
+
+    def info_block(device)
+      raw = device["raw"] || {}
+      wifi = raw["wifi"] || {}
+      update = device["update"] || {}
+      lines = []
+      lines << (device["name"] || "Unnamed device").to_s
+      lines << ""
+      lines.concat(key_values([
+        ["IP", device["ip"]],
+        ["Model", model_label(device)],
+        ["Model ID", device["model_id"]],
+        ["Generation", device["gen"]],
+        ["MAC", device["mac"]],
+        ["Hostname", device["hostname"] || raw["id"] || raw.dig("device", "hostname")],
+        ["Firmware", device["firmware"]],
+        ["Update", update_label(update)],
+        ["New Version", update["new_version"]],
+        ["Wi-Fi", wifi_summary(wifi, raw)],
+        ["Cloud", connection_label(raw["cloud"])],
+        ["MQTT", connection_label(raw["mqtt"])],
+        ["Uptime", duration(raw.dig("sys", "uptime"))],
+        ["Restart Required", raw.dig("sys", "restart_required")],
+        ["Config Rev", raw.dig("sys", "cfg_rev")]
+      ]))
+      component_summary(raw).tap { |summary| lines.concat(["", summary]) unless summary.empty? }
+      lines.join("\n")
+    end
+
+    def status_block(status, context)
+      lines = ["Status #{context[:host]}".strip, ""]
+      lines.concat(key_values([
+        ["Wi-Fi", wifi_summary(status["wifi"] || {}, status)],
+        ["Cloud", connection_label(status["cloud"])],
+        ["MQTT", connection_label(status["mqtt"])],
+        ["Uptime", duration(status.dig("sys", "uptime"))],
+        ["Time", status.dig("sys", "time")],
+        ["Restart Required", status.dig("sys", "restart_required")]
+      ]))
+      component_summary(status).tap { |summary| lines.concat(["", summary]) unless summary.empty? }
+      lines.join("\n")
+    end
+
+    def config_block(config, context)
+      device = config["device"] || config.dig("sys", "device") || {}
+      sys = config["sys"] || {}
+      lines = ["Config #{context[:host]}".strip, ""]
+      lines.concat(key_values([
+        ["Name", device["name"] || config["name"]],
+        ["MAC", device["mac"] || config["mac"]],
+        ["Discoverable", device.key?("discoverable") ? device["discoverable"] : config["discoverable"]],
+        ["Firmware", device["fw_id"] || config["fw"]],
+        ["Cloud", enabled_label(config["cloud"])],
+        ["MQTT", mqtt_config_label(config["mqtt"])],
+        ["Config Rev", sys["cfg_rev"] || config["cfg_rev"]]
+      ]))
+      wifi_config_summary(config["wifi"] || config).tap { |summary| lines.concat(["", summary]) unless summary.empty? }
+      component_config_summary(config).tap { |summary| lines.concat(["", summary]) unless summary.empty? }
+      lines.join("\n")
+    end
+
+    def switch_line(value, context)
+      state = if value.key?("output") then value["output"] else value["ison"] end
+      power = value["apower"] || value["power"]
+      temp = temperature_value(value)
+      details = []
+      details << "power #{format_number(power)} W" if power
+      details << "temp #{format_number(temp)} C" if temp
+      "switch:#{context[:id]} #{on_off(state)}#{details.empty? ? "" : " (#{details.join(", ")})"}"
+    end
+
+    def meter_block(value, context)
+      lines = ["Meter #{context[:host]} id #{context[:id]}"]
+      lines.concat(key_values([
+        ["Power", value["power"] && "#{format_number(value["power"])} W"],
+        ["Voltage", value["voltage"] && "#{format_number(value["voltage"])} V"],
+        ["Current", value["current"] && "#{format_number(value["current"])} A"],
+        ["Total", value["total"] || value["aenergy"]]
+      ]))
+      lines.join("\n")
+    end
+
+    def temperature_block(value, context)
+      lines = ["Temperature #{context[:host]} id #{context[:id]}"]
+      if value.values.all? { |entry| entry.is_a?(Hash) } && !value.key?("tC")
+        value.each do |id, entry|
+          lines << "#{id}: #{format_number(entry["tC"] || entry["temperature"])} C"
+        end
+      else
+        lines.concat(key_values([
+          ["Temperature", (value["tC"] || value["temperature"]) && "#{format_number(value["tC"] || value["temperature"])} C"],
+          ["Valid", value["is_valid"]]
+        ]))
+      end
+      lines.join("\n")
+    end
+
+    def component_block(value, context)
+      lines = ["#{context[:action].to_s.capitalize} #{context[:host]} id #{context[:id]}"]
+      lines.concat(key_values(value.map { |key, val| [key, scalar?(val) ? val : nil] }))
+      nested = value.reject { |_, val| scalar?(val) }
+      lines.concat(["", render_tree(nested)]) unless nested.empty?
+      lines.join("\n")
+    end
+
+    def update_check_block(value, context)
+      state = value["has_update"] ? "update available" : "up to date"
+      line = "#{context[:host]}: #{state}"
+      current = value["current_version"]
+      new_version = value["new_version"]
+      [line, current && "Current: #{current}", new_version && "New: #{new_version}"].compact.join("\n")
+    end
+
+    def write_line(value, context)
+      suffix = value.is_a?(Hash) && !value.empty? ? " #{compact_inline(value)}" : ""
+      "#{context[:action]}: #{context[:host]}#{suffix}"
+    end
+
+    def input_setup_block(value, context)
+      "Input setup complete: #{context[:host]} device #{context[:device_id]} (#{Array(value).size} webhooks)"
+    end
+
+    def raw_block(value, title = nil)
+      lines = []
+      lines << title if title
+      lines << render_tree(value)
+      lines.join("\n")
+    end
+
+    def table(headers, rows)
+      rows = rows.map { |row| row.map { |value| display(value) } }
+      widths = headers.each_with_index.map do |header, index|
+        ([header.length] + rows.map { |row| row[index].to_s.length }).max
+      end
+      lines = []
+      lines << headers.each_with_index.map { |header, index| header.ljust(widths[index]) }.join("  ")
+      lines << widths.map { |width| "-" * width }.join("  ")
+      rows.each do |row|
+        lines << row.each_with_index.map { |value, index| value.ljust(widths[index]) }.join("  ")
+      end
+      lines.join("\n")
+    end
+
+    def key_values(pairs)
+      pairs = pairs.reject { |_, value| blank?(value) }
+      width = pairs.map { |key, _| key.length }.max || 0
+      pairs.map { |key, value| "#{key.ljust(width)}: #{display(value)}" }
+    end
+
+    def render_tree(value, indent = 0)
+      case value
+      when Hash
+        return "#{"  " * indent}{}" if value.empty?
+
+        value.map do |key, child|
+          prefix = "#{"  " * indent}#{key}:"
+          if scalar?(child) || child.nil?
+            "#{prefix} #{display(child)}"
+          else
+            "#{prefix}\n#{render_tree(child, indent + 1)}"
+          end
+        end.join("\n")
+      when Array
+        return "#{"  " * indent}[]" if value.empty?
+
+        value.map do |child|
+          prefix = "#{"  " * indent}-"
+          if scalar?(child) || child.nil?
+            "#{prefix} #{display(child)}"
+          else
+            "#{prefix}\n#{render_tree(child, indent + 1)}"
+          end
+        end.join("\n")
+      else
+        "#{"  " * indent}#{display(value)}"
+      end
+    end
+
+    def component_summary(hash)
+      lines = []
+      component_keys(hash).each do |key|
+        entry = hash[key] || {}
+        label = key.tr(":", " ")
+        values = []
+        values << on_off(entry["output"]) if entry.key?("output")
+        values << "input #{on_off(entry["state"])}" if entry.key?("state")
+        values << "#{format_number(entry["apower"] || entry["power"])} W" if entry["apower"] || entry["power"]
+        temp = temperature_value(entry)
+        values << "#{format_number(temp)} C" if temp
+        values << "source #{entry["source"]}" if entry["source"]
+        lines << "#{label}: #{values.empty? ? compact_inline(entry) : values.join(", ")}"
+      end
+      lines.join("\n")
+    end
+
+    def component_config_summary(hash)
+      lines = []
+      component_keys(hash).each do |key|
+        entry = hash[key] || {}
+        bits = []
+        bits << "name #{entry["name"]}" if entry["name"]
+        bits << "type #{entry["type"]}" if entry["type"]
+        bits << "enabled #{display(entry["enable"])}" if entry.key?("enable")
+        bits << "mode #{entry["in_mode"]}" if entry["in_mode"]
+        bits << "initial #{entry["initial_state"]}" if entry["initial_state"]
+        bits << "auto_off #{entry["auto_off_delay"]}s" if entry["auto_off"]
+        lines << "#{key.tr(":", " ")}: #{bits.empty? ? compact_inline(entry) : bits.join(", ")}"
+      end
+      lines.join("\n")
+    end
+
+    def component_keys(hash)
+      hash.keys.grep(/\A(?:switch|input|light|rgbw|temperature|humidity):\d+\z/).sort
+    end
+
+    def temperature_value(hash)
+      value = hash["temperature"]
+      value.is_a?(Hash) ? value["tC"] : value
+    end
+
+    def wifi_summary(wifi, raw = {})
+      ssid = wifi["ssid"] || raw.dig("wifi_sta", "ssid")
+      ip = wifi["sta_ip"] || wifi.dig("sta", "ip") || raw.dig("wifi_sta", "ip")
+      bssid = wifi["bssid"]
+      rssi = wifi["rssi"] || raw.dig("wifi_sta", "rssi")
+      status = wifi["status"] || (raw.dig("wifi_sta", "connected") == true ? "connected" : nil)
+      [ssid, ip, bssid, rssi && "#{rssi} dBm", status].compact.join(", ")
+    end
+
+    def wifi_config_summary(wifi)
+      rows = []
+      if wifi["sta"] || wifi["sta1"]
+        %w[sta sta1].each do |slot|
+          sta = wifi[slot] || {}
+          rows << [slot, sta["enable"], sta["ssid"], sta["ipv4mode"], sta["ip"], sta["gw"], sta["nameserver"]]
+        end
+      elsif wifi["wifi_sta"] || wifi["wifi_sta1"]
+        %w[wifi_sta wifi_sta1].each do |slot|
+          sta = wifi[slot] || {}
+          rows << [slot, sta["enabled"], sta["ssid"], sta["ipv4_method"], sta["ip"], sta["gw"], sta["dns"]]
+        end
+      end
+      return "" if rows.empty?
+
+      "Wi-Fi\n" + table(%w[Slot Enabled SSID Mode IP GW DNS], rows).lines.map { |line| "  #{line}" }.join
+    end
+
+    def model_label(device)
+      model = device["model"]
+      model_id = device["model_id"]
+      model && model_id && model != model_id ? "#{model} (#{model_id})" : (model || model_id)
+    end
+
+    def update_label(update)
+      return nil unless update
+      return "available #{short_version(update["current_version"])} -> #{short_version(update["new_version"])}" if update["has_update"]
+
+      current = update["current_version"]
+      current ? "ok #{short_version(current)}" : "ok"
+    end
+
+    def connection_label(hash)
+      return nil unless hash
+      connected = hash["connected"]
+      enabled = hash["enable"] || hash["enabled"]
+      if connected.nil?
+        enabled.nil? ? nil : enabled_label(hash)
+      else
+        connected ? "connected" : "disconnected"
+      end
+    end
+
+    def enabled_label(hash)
+      return nil unless hash
+      value = hash["enable"]
+      value = hash["enabled"] if value.nil?
+      value.nil? ? nil : (value ? "enabled" : "disabled")
+    end
+
+    def mqtt_config_label(hash)
+      return nil unless hash
+      label = enabled_label(hash)
+      server = hash["server"]
+      [label, server].compact.join(" ")
+    end
+
+    def compact_inline(hash)
+      return display(hash) unless hash.is_a?(Hash)
+
+      hash.select { |_, value| scalar?(value) || value.nil? }
+          .map { |key, value| "#{key}=#{display(value)}" }
+          .join(", ")
+    end
+
+    def on_off(value)
+      case value
+      when true then "on"
+      when false then "off"
+      when nil then "unknown"
+      else value.to_s
+      end
+    end
+
+    def duration(seconds)
+      return nil unless seconds
+
+      seconds = seconds.to_i
+      days, rem = seconds.divmod(86_400)
+      hours, rem = rem.divmod(3600)
+      minutes, = rem.divmod(60)
+      parts = []
+      parts << "#{days}d" if days.positive?
+      parts << "#{hours}h" if hours.positive? || parts.any?
+      parts << "#{minutes}m"
+      parts.join(" ")
+    end
+
+    def short_version(value)
+      value.to_s.split("/").last unless blank?(value)
+    end
+
+    def format_number(value)
+      return nil if value.nil?
+      number = Float(value)
+      number == number.to_i ? number.to_i.to_s : format("%.2f", number).sub(/0+\z/, "").sub(/\.\z/, "")
+    rescue ArgumentError, TypeError
+      value.to_s
+    end
+
+    def display(value)
+      case value
+      when nil then "-"
+      when true then "true"
+      when false then "false"
+      when Array then value.join(", ")
+      else value.to_s.empty? ? "-" : value.to_s
+      end
+    end
+
+    def scalar?(value)
+      value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+    end
+
+    def blank?(value)
+      value.nil? || value == "" || value == []
+    end
+
+    def client_options
+      { timeout: @options[:timeout] }
+    end
+
+    def consume_flag!(name)
+      index = @argv.index(name)
+      return false unless index
+
+      @argv.delete_at(index)
+      true
+    end
+
+    def consume_help_flag!
+      consume_flag!("--help") || consume_flag!("-h")
+    end
+
+    def consume_option!(name, type = nil)
+      index = @argv.index(name)
+      return nil unless index
+
+      @argv.delete_at(index)
+      value = @argv.delete_at(index)
+      raise Error, "#{name} requires a value" unless value
+
+      type ? convert_option_value(type, value) : value
+    end
+
+    def convert_option_value(type, value)
+      case type.name
+      when "Integer" then Integer(value)
+      when "Float" then Float(value)
+      when "String" then value
+      else type.call(value)
+      end
+    end
+
+    def require_arg!(name)
+      value = @argv.shift
+      raise Error, "missing #{name}" unless value
+
+      value
+    end
+
+    def parse_json_or_file(value)
+      json = File.exist?(value) ? File.read(value) : value
+      JSON.parse(json)
+    end
+
+    def parse_key_values(values)
+      values.each_with_object({}) do |pair, params|
+        key, value = pair.split("=", 2)
+        raise Error, "expected key=value, got #{pair.inspect}" unless key && value
+
+        params[key] = value
+      end
+    end
+
+    def help
+      @stdout.puts <<~USAGE
+        Usage:
+          shelly [--json] [--timeout SECONDS] COMMAND ...
+          shelly help [COMMAND]
+          shelly COMMAND --help
+
+        Discovery and inspection:
+          shelly discover [--verify] [--concurrency N]
+          shelly scan [CIDR] [--concurrency N] [--max-hosts N]
+          shelly info HOST
+          shelly status HOST
+          shelly config HOST
+
+        Device control:
+          shelly switch HOST get|on|off|toggle [--id ID]
+          shelly meter HOST [--id ID]
+          shelly temp HOST [--id ID]
+          shelly light HOST get [--id ID]
+          shelly light HOST set [--id ID] [--on|--off] [--brightness N] [--transition SECONDS]
+          shelly rgbw HOST get [--id ID]
+          shelly rgbw HOST set [--id ID] [--on|--off] [--white N] [--brightness N] [--red N] [--green N] [--blue N] [--transition SECONDS]
+
+        Management:
+          shelly reboot HOST
+          shelly wifi HOST primary|secondary SSID PASSWORD [--ip IP] [--netmask MASK] [--gw IP] [--dns IP]
+          shelly update check HOST
+          shelly update start HOST [--stage stable]
+          shelly mqtt HOST SERVER [--disable]
+          shelly input setup HOST DEVICE_ID [--base-url URL] [--count N]
+          shelly webhook delete-all HOST
+
+        Escape hatches:
+          shelly rpc HOST METHOD [JSON_OR_FILE]
+          shelly gen1 HOST PATH [key=value ...]
+      USAGE
+      0
+    end
+
+    def command_help(command)
+      return help unless command
+
+      key = COMMAND_ALIASES.fetch(command, command)
+      text = command_help_text(key)
+      raise Error, "unknown help topic: #{command}" unless text
+
+      @stdout.puts text
+      0
+    end
+
+    def command_help_text(command)
+      case command
+      when "discover"
+        <<~HELP
+          Usage:
+            shelly discover [--verify] [--concurrency N]
+
+          Find Shelly devices via mDNS.
+
+          Options:
+            --verify          Connect to each discovered IPv4 device and print normalized device info.
+            --concurrency N   Number of parallel HTTP verification requests with --verify. Default: 32.
+
+          Notes:
+            Uses avahi-browse on Linux and dns-sd on macOS. This depends on working mDNS.
+        HELP
+      when "scan"
+        <<~HELP
+          Usage:
+            shelly scan [CIDR] [--concurrency N] [--max-hosts N]
+
+          Probe IPv4 addresses for Shelly devices without using mDNS.
+
+          Arguments:
+            CIDR         Optional network, for example 192.168.0.0/24. If omitted, the current IPv4 network is used.
+
+          Options:
+            --concurrency N   Number of parallel HTTP probes. Default: 32.
+            --max-hosts N     Safety cap for addresses to scan. Default: 4096.
+
+          Examples:
+            shelly scan
+            shelly --timeout 2 scan 192.168.0.0/24 --concurrency 64
+        HELP
+      when "info"
+        <<~HELP
+          Usage:
+            shelly info HOST
+
+          Print normalized device information: generation, model, MAC, name, firmware, update state, and raw merged data.
+
+          Example:
+            shelly --json info 192.168.0.55
+        HELP
+      when "status"
+        <<~HELP
+          Usage:
+            shelly status HOST
+
+          Print current device status. Uses /status on Gen1 and Shelly.GetStatus on Gen2+.
+        HELP
+      when "config"
+        <<~HELP
+          Usage:
+            shelly config HOST
+
+          Print current device configuration. Uses /settings on Gen1 and Shelly.GetConfig on Gen2+.
+        HELP
+      when "switch"
+        <<~HELP
+          Usage:
+            shelly switch HOST get|on|off|toggle [--id ID]
+
+          Read or control a switch/relay output.
+
+          Options:
+            --id ID      Output id. Default: 0.
+
+          Examples:
+            shelly switch 192.168.0.71 get
+            shelly switch 192.168.0.71 off --id 0
+        HELP
+      when "meter"
+        <<~HELP
+          Usage:
+            shelly meter HOST [--id ID]
+
+          Print power meter data. On Gen2+ this reads Switch.GetStatus for the given id.
+
+          Options:
+            --id ID      Meter or switch id. Default: 0.
+        HELP
+      when "temp"
+        <<~HELP
+          Usage:
+            shelly temp HOST [--id ID]
+            shelly temperature HOST [--id ID]
+
+          Print temperature sensor data.
+
+          Options:
+            --id ID      Gen2+ temperature component id. Default: 100.
+        HELP
+      when "light"
+        <<~HELP
+          Usage:
+            shelly light HOST get [--id ID]
+            shelly light HOST set [--id ID] [--on|--off] [--brightness N] [--transition SECONDS]
+
+          Read or control a Gen2+ Light component.
+
+          Options:
+            --id ID                 Light id. Default: 0.
+            --on, --off             Desired output state.
+            --brightness N          Brightness value accepted by the device.
+            --transition SECONDS    Transition duration.
+        HELP
+      when "rgbw"
+        <<~HELP
+          Usage:
+            shelly rgbw HOST get [--id ID]
+            shelly rgbw HOST set [--id ID] [--on|--off] [--white N] [--brightness N] [--red N] [--green N] [--blue N] [--transition SECONDS]
+
+          Read or control a Gen2+ RGBW component.
+
+          Options:
+            --id ID                 RGBW id. Default: 0.
+            --on, --off             Desired output state.
+            --white N               White channel value.
+            --brightness N          Brightness value accepted by the device.
+            --red N --green N --blue N
+            --transition SECONDS    Transition duration.
+        HELP
+      when "reboot"
+        <<~HELP
+          Usage:
+            shelly reboot HOST
+
+          Reboot a device. Uses /reboot on Gen1 and Shelly.Reboot on Gen2+.
+        HELP
+      when "wifi"
+        <<~HELP
+          Usage:
+            shelly wifi HOST primary|secondary SSID PASSWORD [--ip IP] [--netmask MASK] [--gw IP] [--dns IP]
+
+          Configure a Wi-Fi station slot.
+
+          Slot mapping:
+            primary      Gen2+ WiFi sta, Gen1 /settings/sta.
+            secondary    Gen2+ WiFi sta1, Gen1 /settings/sta1.
+
+          By default the station uses DHCP. If --ip is provided, static IPv4 is configured.
+
+          Static defaults:
+            --netmask    Defaults to 255.255.255.0.
+            --gw         Defaults to .1 in the same /24 as --ip.
+            --dns        Defaults to the gateway.
+
+          Examples:
+            shelly wifi 192.168.0.55 secondary NewSSID 'new password'
+            shelly wifi 192.168.0.55 primary NewSSID 'new password' --ip 192.168.10.55
+        HELP
+      when "update"
+        <<~HELP
+          Usage:
+            shelly update check HOST
+            shelly update start HOST [--stage stable|beta]
+
+          Check for firmware updates or start an update.
+
+          Options:
+            --stage NAME    Gen2+ update stage for start. Default: stable.
+        HELP
+      when "mqtt"
+        <<~HELP
+          Usage:
+            shelly mqtt HOST SERVER [--disable]
+
+          Enable or disable MQTT and set the MQTT server.
+
+          Examples:
+            shelly mqtt 192.168.0.55 192.168.0.10:1883
+            shelly mqtt 192.168.0.55 192.168.0.10:1883 --disable
+        HELP
+      when "input"
+        <<~HELP
+          Usage:
+            shelly input setup HOST DEVICE_ID [--base-url URL] [--count N]
+
+          Configure a Gen2+ input device for the home.home input webhook workflow.
+
+          Actions:
+            setup       Set device/input names, delete existing webhooks, and create push, longpush, and doublepush webhooks.
+
+          Options:
+            --base-url URL    Base webhook URL. Default: http://home.home/inputs.
+            --count N         Number of inputs to configure. Default: 4.
+            --device-id ID    Alternative way to provide DEVICE_ID.
+        HELP
+      when "webhook"
+        <<~HELP
+          Usage:
+            shelly webhook delete-all HOST
+
+          Delete all Gen2+ webhooks from a device.
+        HELP
+      when "rpc"
+        <<~HELP
+          Usage:
+            shelly rpc HOST METHOD [JSON_OR_FILE]
+
+          Call a raw Gen2+ RPC method. The optional params argument can be an inline JSON object or a path to a JSON file.
+
+          Examples:
+            shelly rpc 192.168.0.55 Shelly.GetStatus
+            shelly rpc 192.168.0.55 Switch.Set '{"id":0,"on":false}'
+        HELP
+      when "gen1"
+        <<~HELP
+          Usage:
+            shelly gen1 HOST PATH [key=value ...]
+            shelly get HOST PATH [key=value ...]
+
+          Call a raw Gen1 HTTP JSON endpoint.
+
+          Examples:
+            shelly gen1 192.168.0.51 /settings
+            shelly gen1 192.168.0.51 /relay/0 turn=off
+        HELP
+      when "help"
+        <<~HELP
+          Usage:
+            shelly help [COMMAND]
+            shelly COMMAND --help
+
+          Print the global command summary or detailed help for a specific command.
+
+          Examples:
+            shelly help
+            shelly help wifi
+            shelly scan --help
+        HELP
+      when "version"
+        <<~HELP
+          Usage:
+            shelly version
+            shelly --version
+            shelly -v
+
+          Print the rshelly gem version.
+        HELP
+      end
+    end
+  end
+end