imapcli 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee39530d31868e3c8f3c90a1ad9957552ee91f51e7ed05c57fb9a3724a297ef7
-  data.tar.gz: 3d6484ebcce956fc9425447786daaf6d7bce486e0b787d5be9e817cba4517dab
+  metadata.gz: 5a1983fc995c34ea7b3a8d03cdbc45d644090aa0cc60527fe824cd7ae5227300
+  data.tar.gz: f688ac2337ae9c3f0cb5d6d62df60a345bb5fabc0dab771d518be5d1ce1b18a1
 SHA512:
-  metadata.gz: 0e6fab7ebd5c9e58b432323e7ee974c8880785ccf969139966ac2bc9bc7f1034db51678e95c35d7fb53a7df434790340c03aedd40bf2d1bfb6308b2d6b6d4614
-  data.tar.gz: 44801f7d7aa3311683b7e2370b39b9738d4de629e080f32f034b6ae6ac65bda0882dfc15d3731af3929421757a350217f8e4a74ec2127f35d543215cf8aef84e
+  metadata.gz: 23e6aaf015e5ffb731e4f5a6e6d926ff0b8988ba3ea92503df7615aff9217e1b1b55a4c5236a9aabade45dffe53f7bf2912e6084886c25ec0f0d83202fc220f9
+  data.tar.gz: 5cae5a577598c723f2c9621ad5ad173aa246bf93ffaff740f57e5ab6ce4f3c21b0d124daddf55b801f22b60e677a37a93ae1d20a913da82eff3d644818899833

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Version 3.0.0 (2025-04-21)][v3.0.0]
+
+### Changed
+
+ - **BREAKING:** Removed the `-v`/`--verbose` switch which was not functional
+   anyway and added a new option `-O`/`--log-output` flag to write IMAP responses
+   to a file in JSON format.
+
+## [Version 2.1.0 (2025-03-16)][v2.1.0]
+
+### Added
+
+- New command-line flag `-l`/`--limit` to limit the statistics output to
+  a given number of mailboxes (folders).
+
 ## [Version 2.0.1 (2025-03-11)][v2.0.1]
 
 ### Fixed
@@ -72,6 +87,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix: Docker image.
 - Fix: Options error message.
 
+[v3.0.0]: https://github.com/bovender/imapcli/releases/tag/v3.0.0
+[v2.1.0]: https://github.com/bovender/imapcli/releases/tag/v2.1.0
 [v2.0.1]: https://github.com/bovender/imapcli/releases/tag/v2.0.1
 [v2.0.0]: https://github.com/bovender/imapcli/releases/tag/v2.0.0
 [v1.0.7]: https://github.com/bovender/imapcli/releases/tag/v1.0.7

data/Gemfile.lock

@@ -1,13 +1,15 @@
 PATH
   remote: .
   specs:
-    imapcli (2.0.0)
+    imapcli (2.1.0)
       activesupport (~> 8.0)
       csv
       descriptive_statistics (~> 2.5)
       dotenv (~> 3.1)
       gli (~> 2.22)
+      multi_json (~> 1.15)
       net-imap
+      oj (~> 3.16)
       tty-progressbar (~> 0.18)
       tty-prompt (~> 0.23)
       tty-table (~> 0.12)
@@ -16,7 +18,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.1)
+    activesupport (8.0.2)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -83,7 +85,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.10.1)
+    json (2.10.2)
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
     listen (3.9.0)
@@ -92,7 +94,8 @@ GEM
     logger (1.6.6)
     lumberjack (1.2.10)
     method_source (1.1.0)
-    minitest (5.25.4)
+    minitest (5.25.5)
+    multi_json (1.15.0)
     nenv (0.3.0)
     net-imap (0.5.6)
       date
@@ -102,6 +105,9 @@ GEM
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
+    oj (3.16.10)
+      bigdecimal (>= 3.0)
+      ostruct (>= 0.2)
     ostruct (0.6.1)
     parallel (1.26.3)
     parser (3.3.7.1)
@@ -142,7 +148,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.2)
-    rubocop (1.73.2)
+    rubocop (1.74.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -153,7 +159,7 @@ GEM
       rubocop-ast (>= 1.38.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.38.1)
+    rubocop-ast (1.39.0)
       parser (>= 3.3.1.0)
     rubocop-performance (1.24.0)
       lint_roller (~> 1.1)

data/README.md

@@ -263,12 +263,34 @@ keyword, as shown below.
 
 Example:
 
-    bundle exec -it bin/imapcli -s yourserver.example.com -u myusername -P stats -r -o max_size Archive
+    docker run -it bin/imapcli -s yourserver.example.com -u myusername -P stats -r -o max_size Archive
+
+#### Limiting the number of mailboxes
+
+You can limit the number of mailboxes (folders) in the output table with the
+`-l`/`--limit` flag. This flag takes an argument that indicates the maximum
+number of mailboxes. THe default value for this argument is 10.
+
+Use case: Say you have a very large IMAP account, and you would like to know the
+5 folders that contain the largest messages. The command should be:
+
+    imapcli -s yourserver.example.com -u myusername -P stats -o max_size --limit 5 
 
 #### Obtaining comma-separated values (CSV)
 
 Use the `--csv` flag.
 
+### Writing IMAP responses to file
+
+Using the `-O`/`--log-output` flag, you can have `imapcli` write the IMAP responses
+to a file in JSON format:
+
+```bash
+imapcli -s yourserver.example.com -u username -P -O output_file.json stats Inbox 
+```
+
+**WARNING:** The output file will be overwritten without notice!
+
 ## Alternative resources
 
 While researching command-line tools for IMAP servers, I came across the

data/imapcli.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |s|
   s.add_dependency('dotenv', '~> 3.1')
   s.add_dependency('gli', '~> 2.22')
   s.add_dependency('net-imap')
+  s.add_dependency('oj', '~> 3.16')
   s.add_dependency('tty-progressbar', '~> 0.18')
   s.add_dependency('tty-prompt', '~> 0.23')
   s.add_dependency('tty-table', '~> 0.12')

data/lib/imapcli/cli.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'multi_json'
+require 'oj'
+
 module Imapcli
   class Cli # rubocop:disable Metrics/ClassLength,Style/Documentation
     extend GLI::App
@@ -31,8 +34,8 @@ module Imapcli
     desc 'Prompt for password'
     switch %i[P prompt], negatable: false
 
-    desc 'Verbose output (e.g., response values from Rubys Net::IMAP)'
-    switch %i[v verbose], negatable: false
+    desc 'Output responses from Rubys Net::IMAP to file in JSON format. File will be overwritten if it exists!'
+    flag %i[O log-output]
 
     desc 'Tests if the server is available and log-in succeeds with the credentials'
     command :check do |c|
@@ -74,6 +77,10 @@ module Imapcli
         default: 'total_size'
       c.switch %i[reverse], desc: 'Reverse sort order (largest first)', negatable: false
       c.switch [:csv], desc: 'Output comma-separated values (CSV)'
+      c.flag %i[l limit],
+        desc: 'Limit the results to n folders (IMAP mailboxes)',
+        arg_name: 'max_lines',
+        default: 10
 
       c.action do |_global_options, options, args| # rubocop:disable Metrics/BlockLength
         raise unless @validator.stats_options_valid?(options, args)
@@ -85,7 +92,7 @@ module Imapcli
           if progress_bar
             progress_bar.advance
           else
-            @prompt.say "info: collecting stats for #{n} folders" if n > 1
+            @prompt.warn "info: collecting stats for #{n} folders" if n > 1
             progress_bar = TTY::ProgressBar.new(
               'collecting stats... :current/:total (:percent, :eta remaining)',
               total: n, clear: true
@@ -107,9 +114,9 @@ module Imapcli
           formatted_body = formatted_body.insert(0, :separator).insert(-2, :separator)
 
           if options[:human]
-            @prompt.say "notice: -H/--human flag present, message sizes are given with SI prefixes"
+            @prompt.warn "notice: -H/--human flag present, message sizes are given with SI prefixes"
           else
-            @prompt.say "notice: message sizes are given in bytes"
+            @prompt.warn "notice: message sizes are given in bytes"
           end
 
           table = TTY::Table.new(head, formatted_body)
@@ -139,27 +146,25 @@ module Imapcli
       global[:p] = @prompt.mask 'Enter password:' if global[:P]
       global[:p] ||= ENV.fetch('IMAP_PASS', nil)
 
-      client = Imapcli::Client.new(global[:s], global[:u], global[:p])
+      @client = Imapcli::Client.new(global[:s], global[:u], global[:p])
       @prompt.say "server: #{global[:s]}"
       @prompt.say "user: #{global[:u]}"
-      raise 'invalid server name' unless client.server_valid?
-      raise 'invalid user name' unless client.user_valid?
+      raise 'invalid server name' unless @client.server_valid?
+      raise 'invalid user name' unless @client.user_valid?
 
       @prompt.warn 'warning: no password was provided (missing -p/-P option)' unless global[:p]
-      raise 'unable to connect to server' unless client.connection
+      raise 'unable to connect to server' unless @client.connection
 
-      @command = Imapcli::Command.new(client)
+      @command = Imapcli::Command.new(@client)
 
       true
     end
 
     post do |global, _command, _options, _args|
       @client&.logout
-      if global[:v]
-        @prompt.say "\n>>> --verbose switch on, listing server responses <<<"
-        @client.responses.each do |response|
-          @prompt.say response
-        end
+      if file_name = global[:o]
+        @prompt.warn "notice: writing IMAP responses to #{file_name.dump}"
+        File.write(file_name, Oj.dump(@client.responses, mode: :object, indent: 2, escape: :unicode_xss, symbolize_names: false))
       end
     end
 

data/lib/imapcli/client.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Imapcli
   # Wrapper for Net::IMAP
   class Client # rubocop:disable Metrics/ClassLength
     attr_accessor :port, :user, :pass
-    attr_reader :responses
 
     ## Initializs the Client class.
     ##
@@ -17,7 +18,7 @@ module Imapcli
       self.server = server_with_optional_port
       @user = user
       @pass = pass
-      clear_log
+      clear_responses
     end
 
     # Attribute reader for the server domain name
@@ -57,10 +58,15 @@ module Imapcli
     end
 
     # Clears the server response log
-    def clear_log
+    def clear_responses
       @log = []
     end
 
+    # Returns the IMAP server response log
+    def responses
+      @log
+    end
+
     # Returns the last response from the server
     def last_response
       @log.last
@@ -96,17 +102,17 @@ module Imapcli
     # Returns the server's greeting (which may reveal the server software name
     # such as 'Dovecot').
     def greeting
-      query_server { connection.greeting.data.text.strip }
+      query_server('greeting') { connection.greeting.data.text.strip }
     end
 
     # Returns the server's capabilities.
     def capability
-      @capability ||= query_server { connection.capability }
+      @capability ||= query_server('capability') { connection.capability }
     end
 
     # Returns the character that is used to separate nested mailbox names.
     def separator
-      @separator ||= query_server { connection.list('', '')[0].delim }
+      @separator ||= query_server("list('')") { connection.list('', '')[0].delim }
     end
 
     # Returns true if the server supports the IMAP QUOTA extension.
@@ -120,7 +126,7 @@ module Imapcli
       return unless supports_quota
 
       @quota ||= begin
-        info = query_server { @connection.getquotaroot('INBOX')[1] }
+        info = query_server("getquotaroot('INBOX')") { @connection.getquotaroot('INBOX')[1] }
         percent = info.quota.to_i.positive? ? info.usage.to_i.fdiv(info.quota.to_i) * 100 : nil
         [info.usage, info.quota, percent]
       end
@@ -130,8 +136,8 @@ module Imapcli
     #
     # The value is currently NOT cached.
     def messages(mailbox)
-      query_server { connection.examine(mailbox) }
-      query_server { connection.search('ALL') }
+      query_server("examine('#{mailbox}')") { connection.examine(mailbox) }
+      query_server("search('ALL')") { connection.search('ALL') }
     end
 
     # Examines a mailbox and returns statistics about the messages in it.
@@ -149,7 +155,7 @@ module Imapcli
       if messages.empty?
         []
       else
-        query_server do
+        query_server('fetch(...)') do
           messages.each_slice(1000).map do |some_messages|
             connection.fetch(some_messages, 'RFC822.SIZE').map do |f|
               f.attr['RFC822.SIZE']
@@ -168,7 +174,7 @@ module Imapcli
     #
     # The value is cached.
     def mailboxes
-      @mailboxes ||= query_server { @connection.list('', '*') }
+      @mailboxes ||= query_server('list') { @connection.list('', '*') }
     end
 
     # Returns a tree of +Imapcli::Mailbox+ objects.
@@ -188,12 +194,10 @@ module Imapcli
     private
 
     def response_ok?(response)
-      @log << response
       response.name == 'OK'
     end
 
     def log_error(error)
-      @log << error
       false
     end
 
@@ -203,13 +207,31 @@ module Imapcli
     # error if not. The code that queries the server must be contained in the
     # +block+, and the +block+'s return value is returned by this function.
     # The +connection+'s responses are logged.
-    def query_server
+    def query_server(imap_command)
       raise('no connection to a server') unless connection
 
       result = yield
-      @log << connection.responses
+      @log << {
+                'imap_command': imap_command,
+                'imap_response': connection.responses.to_h
+              }
       result
     end
 
+    # Recursively convert structs in an array of hashes to hashes
+    # Inspired by  https://stackoverflow.com/a/62804063/270712
+    # and rephrased to improve readability a bit
+    def to_h_recursively(hash)
+      hash.map do |value|
+        if value.is_a?(Arry)
+          to_h_recursively(value)
+        elsif value.is_a?(Struct)
+          value.to_h
+        else
+          value
+        end
+     end
+    end
+
   end
 end

data/lib/imapcli/command.rb

@@ -68,7 +68,12 @@ module Imapcli
             yield current_count if block_given?
           end
         end
-        output = sorted_list(list, options).map do |mailbox|
+
+        output = if options[:limit]
+          sorted_list(list, options).last(options[:limit].to_i)
+        else
+          sorted_list(list, options)
+        end.map do |mailbox|
           stats_to_table(mailbox.full_name, mailbox.stats)
         end
         output << stats_to_table('Total', total_stats) if list.length > 1

data/lib/imapcli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imapcli
-  VERSION = '2.0.1'
+  VERSION = '3.0.0'
 end

data/logoutput.json

@@ -0,0 +1,527 @@
+[
+  {
+    ":imap_command":"list",
+    ":imap_response":{
+      "FLAGS":[
+        [
+          ":Answered",
+          ":Flagged",
+          ":Deleted",
+          ":Seen",
+          ":Draft",
+          "NonJunk",
+          "Junk",
+          "$label2",
+          "$forwarded",
+          "$label5",
+          "Old",
+          "$label4",
+          "$label3",
+          "$SIGNED",
+          "$JUNK",
+          "$ATTACHMENT",
+          "$NOTJUNK",
+          "$INVITATION",
+          "$label1",
+          "$TODO"
+        ]
+      ],
+      "OK":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "PERMANENTFLAGS",
+                []]},
+            "Read-only mailbox."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UNSEEN",
+                6]},
+            "First unseen."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDVALIDITY",
+                1435851445]},
+            "UIDs valid"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDNEXT",
+                104489]},
+            "Predicted next UID"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "HIGHESTMODSEQ",
+                309489]},
+            "Highest"]}
+      ],
+      "PERMANENTFLAGS":[
+        []
+      ],
+      "EXISTS":[
+        6
+      ],
+      "RECENT":[
+        0
+      ],
+      "UNSEEN":[
+        6
+      ],
+      "UIDVALIDITY":[
+        1435851445
+      ],
+      "UIDNEXT":[
+        104489
+      ],
+      "HIGHESTMODSEQ":[
+        309489
+      ],
+      "ESEARCH":[],
+      "BYE":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            null,
+            "Logging out"]}
+      ]
+    }
+  },
+  {
+    ":imap_command":"list('')",
+    ":imap_response":{
+      "FLAGS":[
+        [
+          ":Answered",
+          ":Flagged",
+          ":Deleted",
+          ":Seen",
+          ":Draft",
+          "NonJunk",
+          "Junk",
+          "$label2",
+          "$forwarded",
+          "$label5",
+          "Old",
+          "$label4",
+          "$label3",
+          "$SIGNED",
+          "$JUNK",
+          "$ATTACHMENT",
+          "$NOTJUNK",
+          "$INVITATION",
+          "$label1",
+          "$TODO"
+        ]
+      ],
+      "OK":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "PERMANENTFLAGS",
+                []]},
+            "Read-only mailbox."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UNSEEN",
+                6]},
+            "First unseen."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDVALIDITY",
+                1435851445]},
+            "UIDs valid"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDNEXT",
+                104489]},
+            "Predicted next UID"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "HIGHESTMODSEQ",
+                309489]},
+            "Highest"]}
+      ],
+      "PERMANENTFLAGS":[
+        []
+      ],
+      "EXISTS":[
+        6
+      ],
+      "RECENT":[
+        0
+      ],
+      "UNSEEN":[
+        6
+      ],
+      "UIDVALIDITY":[
+        1435851445
+      ],
+      "UIDNEXT":[
+        104489
+      ],
+      "HIGHESTMODSEQ":[
+        309489
+      ],
+      "ESEARCH":[],
+      "BYE":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            null,
+            "Logging out"]}
+      ]
+    }
+  },
+  {
+    ":imap_command":"examine('INBOX')",
+    ":imap_response":{
+      "FLAGS":[
+        [
+          ":Answered",
+          ":Flagged",
+          ":Deleted",
+          ":Seen",
+          ":Draft",
+          "NonJunk",
+          "Junk",
+          "$label2",
+          "$forwarded",
+          "$label5",
+          "Old",
+          "$label4",
+          "$label3",
+          "$SIGNED",
+          "$JUNK",
+          "$ATTACHMENT",
+          "$NOTJUNK",
+          "$INVITATION",
+          "$label1",
+          "$TODO"
+        ]
+      ],
+      "OK":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "PERMANENTFLAGS",
+                []]},
+            "Read-only mailbox."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UNSEEN",
+                6]},
+            "First unseen."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDVALIDITY",
+                1435851445]},
+            "UIDs valid"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDNEXT",
+                104489]},
+            "Predicted next UID"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "HIGHESTMODSEQ",
+                309489]},
+            "Highest"]}
+      ],
+      "PERMANENTFLAGS":[
+        []
+      ],
+      "EXISTS":[
+        6
+      ],
+      "RECENT":[
+        0
+      ],
+      "UNSEEN":[
+        6
+      ],
+      "UIDVALIDITY":[
+        1435851445
+      ],
+      "UIDNEXT":[
+        104489
+      ],
+      "HIGHESTMODSEQ":[
+        309489
+      ],
+      "ESEARCH":[],
+      "BYE":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            null,
+            "Logging out"]}
+      ]
+    }
+  },
+  {
+    ":imap_command":"search('ALL')",
+    ":imap_response":{
+      "FLAGS":[
+        [
+          ":Answered",
+          ":Flagged",
+          ":Deleted",
+          ":Seen",
+          ":Draft",
+          "NonJunk",
+          "Junk",
+          "$label2",
+          "$forwarded",
+          "$label5",
+          "Old",
+          "$label4",
+          "$label3",
+          "$SIGNED",
+          "$JUNK",
+          "$ATTACHMENT",
+          "$NOTJUNK",
+          "$INVITATION",
+          "$label1",
+          "$TODO"
+        ]
+      ],
+      "OK":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "PERMANENTFLAGS",
+                []]},
+            "Read-only mailbox."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UNSEEN",
+                6]},
+            "First unseen."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDVALIDITY",
+                1435851445]},
+            "UIDs valid"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDNEXT",
+                104489]},
+            "Predicted next UID"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "HIGHESTMODSEQ",
+                309489]},
+            "Highest"]}
+      ],
+      "PERMANENTFLAGS":[
+        []
+      ],
+      "EXISTS":[
+        6
+      ],
+      "RECENT":[
+        0
+      ],
+      "UNSEEN":[
+        6
+      ],
+      "UIDVALIDITY":[
+        1435851445
+      ],
+      "UIDNEXT":[
+        104489
+      ],
+      "HIGHESTMODSEQ":[
+        309489
+      ],
+      "ESEARCH":[],
+      "BYE":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            null,
+            "Logging out"]}
+      ]
+    }
+  },
+  {
+    ":imap_command":"fetch(...)",
+    ":imap_response":{
+      "FLAGS":[
+        [
+          ":Answered",
+          ":Flagged",
+          ":Deleted",
+          ":Seen",
+          ":Draft",
+          "NonJunk",
+          "Junk",
+          "$label2",
+          "$forwarded",
+          "$label5",
+          "Old",
+          "$label4",
+          "$label3",
+          "$SIGNED",
+          "$JUNK",
+          "$ATTACHMENT",
+          "$NOTJUNK",
+          "$INVITATION",
+          "$label1",
+          "$TODO"
+        ]
+      ],
+      "OK":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "PERMANENTFLAGS",
+                []]},
+            "Read-only mailbox."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UNSEEN",
+                6]},
+            "First unseen."]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDVALIDITY",
+                1435851445]},
+            "UIDs valid"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "UIDNEXT",
+                104489]},
+            "Predicted next UID"]},
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            {
+              "^u":[
+                "Net::IMAP::ResponseCode",
+                "HIGHESTMODSEQ",
+                309489]},
+            "Highest"]}
+      ],
+      "PERMANENTFLAGS":[
+        []
+      ],
+      "EXISTS":[
+        6
+      ],
+      "RECENT":[
+        0
+      ],
+      "UNSEEN":[
+        6
+      ],
+      "UIDVALIDITY":[
+        1435851445
+      ],
+      "UIDNEXT":[
+        104489
+      ],
+      "HIGHESTMODSEQ":[
+        309489
+      ],
+      "ESEARCH":[],
+      "BYE":[
+        {
+          "^u":[
+            "Net::IMAP::ResponseText",
+            null,
+            "Logging out"]}
+      ]
+    }
+  }
+]

data/spec/lib/imapcli/command_spec.rb

@@ -133,6 +133,11 @@ RSpec.describe Imapcli::Command do
         expect(output).to be_a Array
         expect(output[0][0]).to eq 'Inbox/Smallest/Messages'
       end
+
+      it 'returns only the first n mailboxes' do
+        output = command.stats('Inbox', depth: -1, limit: 2)
+        expect(output.length).to eq 3 # including summary line
+      end
     end
 
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: imapcli
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Daniel Kraus (bovender)
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 2025-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -94,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
 - !ruby/object:Gem::Dependency
   name: tty-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -150,7 +163,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.7.0
-description:
 email: bovender@bovender.de
 executables:
 - imapcli
@@ -186,6 +198,7 @@ files:
 - lib/imapcli/option_validator.rb
 - lib/imapcli/stats.rb
 - lib/imapcli/version.rb
+- logoutput.json
 - spec/lib/imapcli/client_spec.rb
 - spec/lib/imapcli/command_spec.rb
 - spec/lib/imapcli/mailbox_spec.rb
@@ -195,7 +208,6 @@ homepage: https://github.com/bovender/imapcli
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
 rdoc_options:
 - "--title"
 - imapcli
@@ -215,8 +227,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Command-line tool to query IMAP servers
 test_files: []