exa-ai 0.6.0 → 0.7.1

data/exe/exa-ai-webset-item-list

@@ -7,6 +7,8 @@ require "exa-ai"
 webset_id = nil
 api_key = nil
 output_format = "json"
+limit = nil
+cursor = nil
 
 args = ARGV.dup
 while args.any?
@@ -16,6 +18,10 @@ while args.any?
     api_key = args.shift
   when "--output-format"
     output_format = args.shift
+  when "--limit"
+    limit = args.shift&.to_i
+  when "--cursor"
+    cursor = args.shift
   when "--help", "-h"
     puts <<~HELP
       Usage: exa-ai webset-item-list <webset_id> [OPTIONS]
@@ -26,14 +32,17 @@ while args.any?
         webset_id              ID of the webset (required)
 
       Options:
+        --limit N              Maximum number of items to return (default: 20)
+        --cursor CURSOR        Cursor for pagination (use nextCursor from previous response)
         --api-key KEY          Exa API key (or set EXA_API_KEY env var)
-        --output-format FMT    Output format: json, pretty, or text (default: json)
+        --output-format FMT    Output format: json, pretty, text, or toon (default: json)
         --help, -h             Show this help message
 
       Examples:
         exa-ai webset-item-list ws_123
+        exa-ai webset-item-list ws_123 --limit 10
+        exa-ai webset-item-list ws_123 --limit 5 --cursor "abc123"
         exa-ai webset-item-list ws_123 --output-format pretty
-        exa-ai webset-item-list ws_123 --output-format text
     HELP
     exit 0
   else
@@ -63,11 +72,16 @@ begin
   # Build client
   client = Exa::CLI::Base.build_client(api_key)
 
+  # Build list params
+  list_params = {}
+  list_params[:limit] = limit if limit
+  list_params[:cursor] = cursor if cursor
+
   # List items
-  items = client.list_items(webset_id: webset_id)
+  collection = client.list_items(webset_id: webset_id, **list_params)
 
   # Format and output
-  output = Exa::CLI::Formatters::WebsetItemFormatter.format_collection(items, output_format)
+  output = Exa::CLI::Formatters::WebsetItemFormatter.format_collection(collection, output_format)
   puts output
   $stdout.flush
 

data/exe/exa-ai-webset-search-create

@@ -104,11 +104,20 @@ def parse_args(argv)
           --entity TYPE            Entity type: person, company, article, research_paper, custom
           --entity-description TXT Description for custom entity type (required with --entity custom)
           --criteria JSON          Search criteria array (supports @file.json)
+                                   Format: [{"description":"criterion 1"},{"description":"criterion 2"}]
           --exclude JSON           Items to exclude from results (supports @file.json)
+                                   Format: [{"source":"import|webset","id":"..."}]
           --scope JSON             Limit search to specific sources (supports @file.json)
+                                   Format: [{"source":"import|webset","id":"..."}]
+                                   Filters this search to only items from these sources
+                                   With relationship (hop search):
+                                   [{"source":"webset","id":"ws_123",
+                                     "relationship":{"definition":"investors of","limit":3}}]
           --recall                 Estimate total available results
-          --behavior TYPE          "override" or "append" (default: override)
+          --behavior TYPE          "override" (replace items) or "append" (add items)
+                                   Default: override when scope is present, append otherwise
           --metadata JSON          Custom metadata (supports @file.json)
+                                   Format: {"key":"value"}
           --api-key KEY            Exa API key (or set EXA_API_KEY env var)
           --output-format FMT      Output format: json, pretty, or text (default: json)
           --help, -h               Show this help message
@@ -121,11 +130,15 @@ def parse_args(argv)
           exa-ai webset-search-create ws_123 --query "tech CEOs" --entity person
           exa-ai webset-search-create ws_123 --query "Silicon Valley firms" --entity company
 
-          # Search with custom entity type
-          exa-ai webset-search-create ws_123 --query "Ford Mustang" \\
-            --entity custom --entity-description "vintage cars"
+          # Scoped search (filter to specific import)
+          exa-ai webset-search-create ws_123 --query "CTOs" \\
+            --scope '[{"source":"import","id":"import_abc"}]'
 
-          # Other options
+          # Hop search (find investors of companies in webset)
+          exa-ai webset-search-create ws_123 --query "investors" \\
+            --scope '[{"source":"webset","id":"ws_companies","relationship":{"definition":"investors of","limit":5}}]'
+
+          # Search with criteria and behavior
           exa-ai webset-search-create ws_123 --query "machine learning" --count 50
           exa-ai webset-search-create ws_123 --query "research" --behavior append --recall
       HELP
@@ -203,7 +216,7 @@ begin
   search = client.create_webset_search(webset_id: args[:webset_id], **search_params)
 
   # Format and output result
-  output = Exa::CLI::Formatters::SearchFormatter.format(search, output_format)
+  output = Exa::CLI::Formatters::WebsetSearchFormatter.format(search, output_format)
   puts output
   $stdout.flush
 

data/exe/exa-ai-webset-search-get

@@ -78,7 +78,7 @@ begin
   search = client.get_webset_search(webset_id: webset_id, id: search_id)
 
   # Format and output
-  output = Exa::CLI::Formatters::SearchFormatter.format(search, output_format)
+  output = Exa::CLI::Formatters::WebsetSearchFormatter.format(search, output_format)
   puts output
   $stdout.flush
 

data/lib/exa/cli/formatters/answer_formatter.rb

@@ -4,24 +4,30 @@ module Exa
   module CLI
     module Formatters
       class AnswerFormatter
-        def self.format(result, format)
+        def self.format(result, format, skip_citations: false)
           case format
           when "json"
-            JSON.pretty_generate(result.to_h)
+            format_json(result, skip_citations: skip_citations)
           when "pretty"
-            format_pretty(result)
+            format_pretty(result, skip_citations: skip_citations)
           when "text"
             format_text(result)
           when "toon"
             Exa::CLI::Base.encode_as_toon(result.to_h)
           else
-            JSON.pretty_generate(result.to_h)
+            format_json(result, skip_citations: skip_citations)
           end
         end
 
         private
 
-        def self.format_pretty(result)
+        def self.format_json(result, skip_citations: false)
+          hash = result.to_h
+          hash.delete(:citations) if skip_citations
+          JSON.pretty_generate(hash)
+        end
+
+        def self.format_pretty(result, skip_citations: false)
           output = []
           output << "Answer:"
           output << "-" * 60
@@ -34,15 +40,17 @@ module Exa
           end
           output << ""
 
-          if result.citations && !result.citations.empty?
-            output << "Citations:"
-            output << "-" * 60
-            result.citations.each_with_index do |citation, idx|
-              output << "[#{idx + 1}] #{citation['title']}"
-              output << "    URL:      #{citation['url']}"
-              output << "    Author:   #{citation['author']}" if citation['author']
-              output << "    Date:     #{citation['publishedDate']}" if citation['publishedDate']
-              output << ""
+          unless skip_citations
+            if result.citations && !result.citations.empty?
+              output << "Citations:"
+              output << "-" * 60
+              result.citations.each_with_index do |citation, idx|
+                output << "[#{idx + 1}] #{citation['title']}"
+                output << "    URL:      #{citation['url']}"
+                output << "    Author:   #{citation['author']}" if citation['author']
+                output << "    Date:     #{citation['publishedDate']}" if citation['publishedDate']
+                output << ""
+              end
             end
           end
 

data/lib/exa/cli/formatters/enrichment_formatter.rb

@@ -9,7 +9,7 @@ module Exa
           when "json"
             JSON.generate(enrichment.to_h)
           when "pretty"
-            JSON.pretty_generate(enrichment.to_h)
+            format_as_pretty(enrichment)
           when "text"
             format_as_text(enrichment)
           when "toon"
@@ -24,7 +24,7 @@ module Exa
           when "json"
             JSON.generate(collection.to_h)
           when "pretty"
-            JSON.pretty_generate(collection.to_h)
+            format_collection_as_pretty(collection)
           when "text"
             format_collection_as_text(collection)
           when "toon"
@@ -34,6 +34,31 @@ module Exa
           end
         end
 
+        def self.format_as_pretty(enrichment)
+          lines = []
+          lines << "Enrichment ID: #{enrichment.id}"
+          lines << "Webset ID:     #{enrichment.webset_id}" if enrichment.webset_id
+          lines << "Status:        #{enrichment.status}"
+          lines << "Title:         #{enrichment.title}" if enrichment.title
+          lines << "Description:   #{enrichment.description}" if enrichment.description
+          lines << "Format:        #{enrichment.format}" if enrichment.format
+
+          if enrichment.options && !enrichment.options.empty?
+            lines << ""
+            lines << "Options (#{enrichment.options.length}):"
+            enrichment.options.each do |option|
+              lines << "  • #{option['label']}" if option['label']
+            end
+          end
+
+          lines << ""
+          lines << "Created:       #{enrichment.created_at}" if enrichment.created_at
+          lines << "Updated:       #{enrichment.updated_at}" if enrichment.updated_at
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_pretty
+
         def self.format_as_text(enrichment)
           lines = []
           lines << "Enrichment: #{enrichment.id}"
@@ -57,6 +82,33 @@ module Exa
         end
         private_class_method :format_as_text
 
+        def self.format_collection_as_pretty(collection)
+          lines = []
+          lines << "Enrichments (#{collection.data.length} items)"
+          lines << ""
+
+          collection.data.each_with_index do |enr, idx|
+            lines << "" if idx > 0  # Blank line between enrichments
+
+            lines << "Enrichment ID: #{enr['id']}"
+            lines << "Webset ID:     #{enr['websetId']}" if enr['websetId']
+            lines << "Status:        #{enr['status']}"
+            lines << "Title:         #{enr['title']}" if enr['title']
+            lines << "Description:   #{enr['description']}" if enr['description']
+            lines << "Format:        #{enr['format']}" if enr['format']
+            lines << "Created:       #{enr['createdAt']}" if enr['createdAt']
+            lines << "Updated:       #{enr['updatedAt']}" if enr['updatedAt']
+          end
+
+          if collection.has_more
+            lines << ""
+            lines << "Next Cursor:   #{collection.next_cursor}"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_pretty
+
         def self.format_collection_as_text(collection)
           lines = ["Enrichments (#{collection.data.length} items):"]
           collection.data.each do |enr|

data/lib/exa/cli/formatters/import_formatter.rb

@@ -9,7 +9,7 @@ module Exa
           when "json"
             JSON.generate(import.to_h)
           when "pretty"
-            JSON.pretty_generate(import.to_h)
+            format_as_pretty(import)
           when "text"
             format_as_text(import)
           when "toon"
@@ -24,7 +24,7 @@ module Exa
           when "json"
             JSON.generate(collection.to_h)
           when "pretty"
-            JSON.pretty_generate(collection.to_h)
+            format_collection_as_pretty(collection)
           when "text"
             format_collection_as_text(collection)
           when "toon"
@@ -34,6 +34,43 @@ module Exa
           end
         end
 
+        def self.format_as_pretty(import)
+          lines = []
+          lines << "Import ID:     #{import.id}"
+          lines << "Status:        #{import.status}"
+          lines << "Title:         #{import.title}" if import.title
+          lines << "Format:        #{import.format}" if import.format
+
+          if import.entity
+            entity_type = import.entity['type'] || import.entity[:type]
+            lines << "Entity Type:   #{entity_type}" if entity_type
+          end
+
+          lines << "Count:         #{import.count}" if import.count
+
+          if import.failed?
+            lines << ""
+            lines << "Failure:"
+            lines << "  Reason:      #{import.failed_reason}" if import.failed_reason
+            lines << "  Message:     #{import.failed_message}" if import.failed_message
+            lines << "  Failed At:   #{import.failed_at}" if import.failed_at
+          end
+
+          if import.upload_url
+            lines << ""
+            lines << "Upload:"
+            lines << "  URL:         #{import.upload_url}"
+            lines << "  Valid Until: #{import.upload_valid_until}" if import.upload_valid_until
+          end
+
+          lines << ""
+          lines << "Created:       #{import.created_at}" if import.created_at
+          lines << "Updated:       #{import.updated_at}" if import.updated_at
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_pretty
+
         def self.format_as_text(import)
           lines = []
           lines << "Import: #{import.id}"
@@ -68,6 +105,37 @@ module Exa
         end
         private_class_method :format_as_text
 
+        def self.format_collection_as_pretty(collection)
+          lines = []
+          lines << "Imports (#{collection.data.length} items)"
+          lines << ""
+
+          collection.data.each_with_index do |imp, idx|
+            lines << "" if idx > 0  # Blank line between imports
+
+            lines << "Import ID:     #{imp.id}"
+            lines << "Status:        #{imp.status}"
+            lines << "Title:         #{imp.title}" if imp.title
+            lines << "Format:        #{imp.format}" if imp.format
+            lines << "Entity Type:   #{imp.entity['type']}" if imp.entity && imp.entity['type']
+            lines << "Count:         #{imp.count}" if imp.count
+            lines << "Created:       #{imp.created_at}" if imp.created_at
+            lines << "Updated:       #{imp.updated_at}" if imp.updated_at
+
+            if imp.status == 'failed'
+              lines << "Failed Reason: #{imp.failed_reason}" if imp.failed_reason
+            end
+          end
+
+          if collection.has_more
+            lines << ""
+            lines << "Next Cursor:   #{collection.next_cursor}"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_pretty
+
         def self.format_collection_as_text(collection)
           lines = ["Imports (#{collection.data.length} items):"]
           collection.data.each do |imp|

data/lib/exa/cli/formatters/monitor_formatter.rb

@@ -9,7 +9,7 @@ module Exa
           when "json"
             JSON.generate(monitor.to_h)
           when "pretty"
-            JSON.pretty_generate(monitor.to_h)
+            format_as_pretty(monitor)
           when "text"
             format_as_text(monitor)
           when "toon"
@@ -24,7 +24,7 @@ module Exa
           when "json"
             JSON.generate(collection.to_h)
           when "pretty"
-            JSON.pretty_generate(collection.to_h)
+            format_collection_as_pretty(collection)
           when "text"
             format_collection_as_text(collection)
           when "toon"
@@ -34,6 +34,35 @@ module Exa
           end
         end
 
+        def self.format_as_pretty(monitor)
+          lines = []
+          lines << "Monitor ID:    #{monitor.id}"
+          lines << "Webset ID:     #{monitor.webset_id}" if monitor.webset_id
+          lines << "Status:        #{monitor.status}"
+
+          if monitor.cadence
+            lines << ""
+            lines << "Cadence:"
+            lines << "  Cron:        #{monitor.cadence['cron']}" if monitor.cadence['cron']
+            lines << "  Timezone:    #{monitor.cadence['timezone']}" if monitor.cadence['timezone']
+          end
+
+          if monitor.behavior
+            lines << ""
+            lines << "Behavior:"
+            lines << "  Type:        #{monitor.behavior['type']}" if monitor.behavior['type']
+            lines << "  Query:       #{monitor.behavior['query']}" if monitor.behavior['query']
+            lines << "  Count:       #{monitor.behavior['count']}" if monitor.behavior['count']
+          end
+
+          lines << ""
+          lines << "Created:       #{monitor.created_at}" if monitor.created_at
+          lines << "Updated:       #{monitor.updated_at}" if monitor.updated_at
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_pretty
+
         def self.format_as_text(monitor)
           lines = []
           lines << "Monitor: #{monitor.id}"
@@ -60,6 +89,40 @@ module Exa
         end
         private_class_method :format_as_text
 
+        def self.format_collection_as_pretty(collection)
+          lines = []
+          lines << "Monitors (#{collection.data.length} items)"
+          lines << ""
+
+          collection.data.each_with_index do |mon, idx|
+            lines << "" if idx > 0  # Blank line between monitors
+
+            lines << "Monitor ID:    #{mon['id']}"
+            lines << "Webset ID:     #{mon['websetId']}" if mon['websetId']
+            lines << "Status:        #{mon['status']}"
+
+            if mon['cadence']
+              lines << "Cron:          #{mon['cadence']['cron']}" if mon['cadence']['cron']
+              lines << "Timezone:      #{mon['cadence']['timezone']}" if mon['cadence']['timezone']
+            end
+
+            if mon['behavior']
+              lines << "Query:         #{mon['behavior']['query']}" if mon['behavior']['query']
+            end
+
+            lines << "Created:       #{mon['createdAt']}" if mon['createdAt']
+            lines << "Updated:       #{mon['updatedAt']}" if mon['updatedAt']
+          end
+
+          if collection.has_more
+            lines << ""
+            lines << "Next Cursor:   #{collection.next_cursor}"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_pretty
+
         def self.format_collection_as_text(collection)
           lines = ["Monitors (#{collection.data.length} items):"]
           collection.data.each do |mon|

data/lib/exa/cli/formatters/monitor_run_formatter.rb

@@ -9,7 +9,7 @@ module Exa
           when "json"
             JSON.generate(monitor_run.to_h)
           when "pretty"
-            JSON.pretty_generate(monitor_run.to_h)
+            format_as_pretty(monitor_run)
           when "text"
             format_as_text(monitor_run)
           when "toon"
@@ -24,7 +24,7 @@ module Exa
           when "json"
             JSON.generate(collection.to_h)
           when "pretty"
-            JSON.pretty_generate(collection.to_h)
+            format_collection_as_pretty(collection)
           when "text"
             format_collection_as_text(collection)
           when "toon"
@@ -34,6 +34,27 @@ module Exa
           end
         end
 
+        def self.format_as_pretty(monitor_run)
+          lines = []
+          lines << "Monitor Run ID: #{monitor_run.id}"
+          lines << "Monitor ID:     #{monitor_run.monitor_id}" if monitor_run.monitor_id
+          lines << "Status:         #{monitor_run.status}"
+
+          lines << ""
+          lines << "Created:        #{monitor_run.created_at}" if monitor_run.created_at
+          lines << "Updated:        #{monitor_run.updated_at}" if monitor_run.updated_at
+          lines << "Completed:      #{monitor_run.completed_at}" if monitor_run.completed_at
+
+          if monitor_run.failed?
+            lines << ""
+            lines << "Failed:         #{monitor_run.failed_at}" if monitor_run.failed_at
+            lines << "Reason:         #{monitor_run.failed_reason}" if monitor_run.failed_reason
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_pretty
+
         def self.format_as_text(monitor_run)
           lines = []
           lines << "Monitor Run: #{monitor_run.id}"
@@ -53,6 +74,36 @@ module Exa
         end
         private_class_method :format_as_text
 
+        def self.format_collection_as_pretty(collection)
+          lines = []
+          lines << "Monitor Runs (#{collection.data.length} items)"
+          lines << ""
+
+          collection.data.each_with_index do |run, idx|
+            lines << "" if idx > 0  # Blank line between runs
+
+            lines << "Monitor Run ID: #{run['id']}"
+            lines << "Monitor ID:     #{run['monitorId']}" if run['monitorId']
+            lines << "Status:         #{run['status']}"
+            lines << "Created:        #{run['createdAt']}" if run['createdAt']
+            lines << "Updated:        #{run['updatedAt']}" if run['updatedAt']
+            lines << "Completed:      #{run['completedAt']}" if run['completedAt']
+
+            if run['status'] == 'failed'
+              lines << "Failed:         #{run['failedAt']}" if run['failedAt']
+              lines << "Reason:         #{run['failedReason']}" if run['failedReason']
+            end
+          end
+
+          if collection.has_more
+            lines << ""
+            lines << "Next Cursor:    #{collection.next_cursor}"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_pretty
+
         def self.format_collection_as_text(collection)
           lines = ["Monitor Runs (#{collection.data.length} items):"]
           collection.data.each do |run|

data/lib/exa/cli/formatters/webset_formatter.rb

@@ -24,7 +24,7 @@ module Exa
           when "json"
             JSON.generate(collection.to_h)
           when "pretty"
-            JSON.pretty_generate(collection.to_h)
+            format_collection_as_pretty(collection)
           when "text"
             format_collection_as_text(collection)
           when "toon"
@@ -66,6 +66,66 @@ module Exa
           lines.join("\n")
         end
         private_class_method :format_collection_as_text
+
+        def self.format_collection_as_pretty(collection)
+          lines = []
+
+          # Header with count and pagination info
+          header = "Websets (#{collection.data.length} items)"
+          header += " - Page #{collection.has_more ? '1 of many' : '1 of 1'}" if collection.data.any?
+          lines << header
+
+          if collection.has_more
+            lines << "Next Cursor:   #{collection.next_cursor}"
+          end
+
+          lines << ""
+
+          # Format each webset
+          collection.data.each_with_index do |ws, idx|
+            lines << "" if idx > 0  # Blank line between websets
+
+            lines << "Webset ID:     #{ws['id']}"
+            lines << "Status:        #{ws['status']}"
+            lines << "Title:         #{ws['title']}" if ws['title']
+            lines << "External ID:   #{ws['externalId']}" if ws['externalId']
+            lines << "Created:       #{ws['createdAt']}" if ws['createdAt']
+            lines << "Updated:       #{ws['updatedAt']}" if ws['updatedAt']
+
+            # Searches
+            if ws['searches'] && !ws['searches'].empty?
+              lines << ""
+              lines << "Searches (#{ws['searches'].length}):"
+              ws['searches'].each do |search|
+                status_indicator = case search['status']
+                                   when 'completed' then '✓'
+                                   when 'running' then '→'
+                                   when 'failed' then '✗'
+                                   else '•'
+                                   end
+                lines << "  #{status_indicator} #{search['query']} (#{search['status']})" if search['query']
+              end
+            end
+
+            # Enrichments
+            if ws['enrichments'] && !ws['enrichments'].empty?
+              lines << "Enrichments:   #{ws['enrichments'].length}"
+            end
+
+            # Monitors
+            if ws['monitors'] && !ws['monitors'].empty?
+              lines << "Monitors:      #{ws['monitors'].length}"
+            end
+
+            # Imports
+            if ws['imports'] && !ws['imports'].empty?
+              lines << "Imports:       #{ws['imports'].length}"
+            end
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_pretty
       end
     end
   end