feat(cli): Add TOON output format support

benjaminjackson · claude · benjaminjackson · commit e81b4d89e2f1 · 2025-11-28T14:01:37.000-05:00
Add support for TOON output format across all CLI formatters: - Add 'toon' as a valid output format - Implement TOON encoding for all resource types - Update base CLI to support TOON format validation - Add toon-ruby dependency to Gemspec - Create comprehensive test coverage for TOON output format This allows users to receive more compact, efficient serialization of CLI output. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -4,6 +4,7 @@ PATH
     exa-ai (0.5.0)
       faraday (~> 2.0)
       ld-eventsource (~> 2.0)
+      toon-ruby (~> 0.1)
 
 GEM
   remote: https://rubygems.org/
@@ -57,6 +58,7 @@ GEM
     rake (13.3.0)
     rexml (3.4.4)
     thor (1.4.0)
+    toon-ruby (0.1.1)
     uri (1.0.4)
     vcr (6.3.1)
       base64
diff --git a/exa.gemspec b/exa.gemspec
@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
   # Runtime dependencies
   spec.add_dependency "faraday", "~> 2.0"
   spec.add_dependency "ld-eventsource", "~> 2.0"
+  spec.add_dependency "toon-ruby", "~> 0.1"
 
   # Development dependencies
   spec.add_development_dependency "minitest", "~> 5.0"
diff --git a/lib/exa/cli/base.rb b/lib/exa/cli/base.rb
@@ -16,11 +16,11 @@ def self.resolve_api_key(flag_value)
       end
 
       # Resolve and validate output format
-      # Valid formats: json, pretty, text
+      # Valid formats: json, pretty, text, toon
       # Defaults to json
       def self.resolve_output_format(flag_value)
         format = (flag_value || "json").downcase
-        valid_formats = %w[json pretty text]
+        valid_formats = %w[json pretty text toon]
 
         return format if valid_formats.include?(format)
 
@@ -46,6 +46,12 @@ def self.format_output(data, format)
           data.to_s
         end
       end
+
+      # Encode data as TOON format
+      def self.encode_as_toon(data)
+        require "toon" unless defined?(Toon)
+        Toon.encode(data)
+      end
     end
   end
 end
diff --git a/lib/exa/cli/formatters/answer_formatter.rb b/lib/exa/cli/formatters/answer_formatter.rb
@@ -12,6 +12,8 @@ def self.format(result, format)
             format_pretty(result)
           when "text"
             format_text(result)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(result.to_h)
           else
             JSON.pretty_generate(result.to_h)
           end
diff --git a/lib/exa/cli/formatters/contents_formatter.rb b/lib/exa/cli/formatters/contents_formatter.rb
@@ -12,6 +12,8 @@ def self.format(result, format)
             format_pretty(result)
           when "text"
             format_text(result)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(result.to_h)
           else
             JSON.pretty_generate(result.to_h)
           end
diff --git a/lib/exa/cli/formatters/context_formatter.rb b/lib/exa/cli/formatters/context_formatter.rb
@@ -14,6 +14,8 @@ def self.format(result, format)
             format_pretty(result)
           when "text"
             format_text(result)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(result.to_h)
           else
             JSON.pretty_generate(result.to_h)
           end
diff --git a/lib/exa/cli/formatters/enrichment_formatter.rb b/lib/exa/cli/formatters/enrichment_formatter.rb
@@ -12,6 +12,8 @@ def self.format(enrichment, output_format)
             JSON.pretty_generate(enrichment.to_h)
           when "text"
             format_as_text(enrichment)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(enrichment.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ def self.format_collection(collection, output_format)
             JSON.pretty_generate(collection.to_h)
           when "text"
             format_collection_as_text(collection)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
diff --git a/lib/exa/cli/formatters/import_formatter.rb b/lib/exa/cli/formatters/import_formatter.rb
@@ -12,6 +12,8 @@ def self.format(import, output_format)
             JSON.pretty_generate(import.to_h)
           when "text"
             format_as_text(import)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(import.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ def self.format_collection(collection, output_format)
             JSON.pretty_generate(collection.to_h)
           when "text"
             format_collection_as_text(collection)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
diff --git a/lib/exa/cli/formatters/monitor_formatter.rb b/lib/exa/cli/formatters/monitor_formatter.rb
@@ -12,6 +12,8 @@ def self.format(monitor, output_format)
             JSON.pretty_generate(monitor.to_h)
           when "text"
             format_as_text(monitor)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(monitor.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ def self.format_collection(collection, output_format)
             JSON.pretty_generate(collection.to_h)
           when "text"
             format_collection_as_text(collection)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
diff --git a/lib/exa/cli/formatters/monitor_run_formatter.rb b/lib/exa/cli/formatters/monitor_run_formatter.rb
@@ -12,6 +12,8 @@ def self.format(monitor_run, output_format)
             JSON.pretty_generate(monitor_run.to_h)
           when "text"
             format_as_text(monitor_run)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(monitor_run.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ def self.format_collection(collection, output_format)
             JSON.pretty_generate(collection.to_h)
           when "text"
             format_collection_as_text(collection)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
diff --git a/lib/exa/cli/formatters/research_formatter.rb b/lib/exa/cli/formatters/research_formatter.rb
@@ -10,6 +10,8 @@ def self.format_task(task, format, show_events: false)
             format_task_pretty(task, show_events: show_events)
           when "text"
             format_task_text(task, show_events: show_events)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(task.to_h)
           else
             JSON.pretty_generate(task.to_h)
           end
@@ -23,6 +25,8 @@ def self.format_list(list, format)
             format_list_pretty(list)
           when "text"
             format_list_text(list)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(list.to_h)
           else
             JSON.pretty_generate(list.to_h)
           end
diff --git a/lib/exa/cli/formatters/search_formatter.rb b/lib/exa/cli/formatters/search_formatter.rb
@@ -12,6 +12,8 @@ def self.format(result, format)
             format_pretty(result)
           when "text"
             format_text(result)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(result.to_h)
           else
             JSON.pretty_generate(result.to_h)
           end
diff --git a/lib/exa/cli/formatters/webset_formatter.rb b/lib/exa/cli/formatters/webset_formatter.rb
@@ -12,6 +12,8 @@ def self.format(webset, output_format)
             JSON.pretty_generate(webset.to_h)
           when "text"
             format_as_text(webset)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(webset.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ def self.format_collection(collection, output_format)
             JSON.pretty_generate(collection.to_h)
           when "text"
             format_collection_as_text(collection)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
diff --git a/lib/exa/cli/formatters/webset_item_formatter.rb b/lib/exa/cli/formatters/webset_item_formatter.rb
@@ -12,6 +12,8 @@ def self.format(item, output_format)
             JSON.pretty_generate(item)
           when "text"
             format_as_text(item)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(item)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -25,6 +27,8 @@ def self.format_collection(items, output_format)
             JSON.pretty_generate(items)
           when "text"
             format_collection_as_text(items)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(items)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
diff --git a/test/cli/base_test.rb b/test/cli/base_test.rb
@@ -44,6 +44,11 @@ def test_accepts_text_output_format
     assert_equal "text", format
   end
 
+  def test_accepts_toon_output_format
+    format = Exa::CLI::Base.resolve_output_format("toon")
+    assert_equal "toon", format
+  end
+
   def test_raises_error_on_invalid_output_format
     error = assert_raises(Exa::ConfigurationError) do
       Exa::CLI::Base.resolve_output_format("invalid_format")
@@ -75,4 +80,13 @@ def test_formats_output_as_text_uses_to_s
     output = Exa::CLI::Base.format_output(data, "text")
     assert_equal "test string", output
   end
+
+  def test_encode_as_toon
+    data = { key: "value", nested: { inner: 123 } }
+    output = Exa::CLI::Base.encode_as_toon(data)
+
+    assert_instance_of String, output
+    assert_includes output, "key"
+    assert_includes output, "value"
+  end
 end
diff --git a/test/cli/formatters/answer_formatter_test.rb b/test/cli/formatters/answer_formatter_test.rb
@@ -105,4 +105,16 @@ def test_text_format_with_structured_answer
     assert_includes output, "Albany"
     assert_includes output, "New York"
   end
+
+  def test_toon_format_returns_toon_string
+    output = Exa::CLI::Formatters::AnswerFormatter.format(@result, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "SpaceX"
+    assert_includes output, "180 billion"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::AnswerFormatter.format(@result, "json")
+    assert output.length < json_output.length
+  end
 end
diff --git a/test/cli/formatters/contents_formatter_test.rb b/test/cli/formatters/contents_formatter_test.rb
@@ -71,6 +71,19 @@ def test_text_format_shows_url_and_text
     assert_includes output, "This is the text content for the second example."
   end
 
+  def test_toon_format_returns_toon_string
+    result = create_contents_result
+    output = Exa::CLI::Formatters::ContentsFormatter.format(result, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "Example Title 1"
+    assert_includes output, "https://example.com/1"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::ContentsFormatter.format(result, "json")
+    assert output.length < json_output.length
+  end
+
   private
 
   def create_contents_result
diff --git a/test/cli/formatters/context_formatter_test.rb b/test/cli/formatters/context_formatter_test.rb
@@ -55,4 +55,15 @@ def test_text_format_shows_code_snippets
     assert_includes output, "Sample code"
     assert_includes output, "def authenticate"
   end
+
+  def test_toon_format_returns_toon_string
+    output = Exa::CLI::Formatters::ContextFormatter.format(@result, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "ruby authentication"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::ContextFormatter.format(@result, "json")
+    assert output.length < json_output.length
+  end
 end
diff --git a/test/cli/formatters/enrichment_formatter_test.rb b/test/cli/formatters/enrichment_formatter_test.rb
@@ -74,4 +74,33 @@ def test_formats_collection_as_text
     assert_includes output, "completed"
     assert_includes output, "running"
   end
+
+  def test_toon_format_returns_toon_string
+    output = Exa::CLI::Formatters::EnrichmentFormatter.format(@enrichment, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "enr_123"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::EnrichmentFormatter.format(@enrichment, "json")
+    assert output.length < json_output.length
+  end
+
+  def test_format_collection_toon_format_returns_toon_string
+    collection = Exa::Resources::WebsetEnrichmentCollection.new(
+      data: [
+        {"id" => "enr_1", "status" => "completed", "title" => "Size"},
+        {"id" => "enr_2", "status" => "running", "title" => "Industry"}
+      ]
+    )
+
+    output = Exa::CLI::Formatters::EnrichmentFormatter.format_collection(collection, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "enr_1"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::EnrichmentFormatter.format_collection(collection, "json")
+    assert output.length < json_output.length
+  end
 end
diff --git a/test/cli/formatters/monitor_formatter_test.rb b/test/cli/formatters/monitor_formatter_test.rb
@@ -91,4 +91,34 @@ def test_formats_collection_as_text
     assert_includes output, "active"
     assert_includes output, "paused"
   end
+
+  def test_toon_format_returns_toon_string
+    output = Exa::CLI::Formatters::MonitorFormatter.format(@monitor, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "mon_123"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::MonitorFormatter.format(@monitor, "json")
+    assert output.length < json_output.length
+  end
+
+  def test_format_collection_toon_format_returns_toon_string
+    collection = Exa::Resources::MonitorCollection.new(
+      data: [
+        {"id" => "mon_1", "status" => "active", "websetId" => "ws_1"},
+        {"id" => "mon_2", "status" => "paused", "websetId" => "ws_2"}
+      ],
+      has_more: false
+    )
+
+    output = Exa::CLI::Formatters::MonitorFormatter.format_collection(collection, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "mon_1"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::MonitorFormatter.format_collection(collection, "json")
+    assert output.length < json_output.length
+  end
 end
diff --git a/test/cli/formatters/monitor_run_formatter_test.rb b/test/cli/formatters/monitor_run_formatter_test.rb
@@ -92,4 +92,34 @@ def test_formats_collection_as_text
     assert_includes output, "completed"
     assert_includes output, "failed"
   end
+
+  def test_toon_format_returns_toon_string
+    output = Exa::CLI::Formatters::MonitorRunFormatter.format(@monitor_run, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "run_123"
+
+    # TOON should be more compact than JSON
+    json_output = Exa::CLI::Formatters::MonitorRunFormatter.format(@monitor_run, "json")
+    assert output.length < json_output.length
+  end
+
+  def test_format_collection_toon_format_returns_toon_string
+    collection = Exa::Resources::MonitorRunCollection.new(
+      data: [
+        {"id" => "run_1", "status" => "completed", "completedAt" => "2025-01-01T01:00:00Z"},
+        {"id" => "run_2", "status" => "failed", "failedReason" => "timeout"}
+      ],
+      has_more: false
+    )
+
+    output = Exa::CLI::Formatters::MonitorRunFormatter.format_collection(collection, "toon")
+
+    assert_instance_of String, output
+    assert_includes output, "run_1"
+
+    # TOON should be more compact than or equal to JSON
+    json_output = Exa::CLI::Formatters::MonitorRunFormatter.format_collection(collection, "json")
+    assert output.length <= json_output.length
+  end
 end
diff --git a/test/cli/formatters/research_formatter_test.rb b/test/cli/formatters/research_formatter_test.rb
diff --git a/test/cli/formatters/search_formatter_test.rb b/test/cli/formatters/search_formatter_test.rb
diff --git a/test/cli/formatters/webset_formatter_test.rb b/test/cli/formatters/webset_formatter_test.rb
diff --git a/test/test_helper.rb b/test/test_helper.rb
diff --git a/test/vcr_cassettes/search_ruby_programming.yml b/test/vcr_cassettes/search_ruby_programming.yml
