exa-ai 0.5.0 → 0.6.1

data/exe/exa-ai-monitor-runs-get

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+monitor_id = nil
+run_id = nil
+api_key = nil
+output_format = "json"
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai monitor-runs-get <monitor_id> <run_id> [OPTIONS]
+
+      Retrieve details for a specific monitor run
+
+      Arguments:
+        monitor_id             ID of the monitor (required)
+        run_id                 ID of the run to retrieve (required)
+
+      Options:
+        --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
+
+      Examples:
+        exa-ai monitor-runs-get mon_abc123 run_xyz789
+        exa-ai monitor-runs-get mon_abc123 run_xyz789 --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is monitor_id, second is run_id
+    if monitor_id.nil?
+      monitor_id = arg
+    elsif run_id.nil?
+      run_id = arg
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate
+if monitor_id.nil?
+  $stderr.puts "Error: monitor_id argument is required"
+  $stderr.puts "Usage: exa-ai monitor-runs-get <monitor_id> <run_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai monitor-runs-get --help' for more information"
+  exit 1
+end
+
+if run_id.nil?
+  $stderr.puts "Error: run_id argument is required"
+  $stderr.puts "Usage: exa-ai monitor-runs-get <monitor_id> <run_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai monitor-runs-get --help' for more information"
+  exit 1
+end
+
+begin
+  # Resolve API key and format
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+  output_format = Exa::CLI::Base.resolve_output_format(output_format)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Get monitor run
+  monitor_run = client.get_monitor_run(monitor_id: monitor_id, id: run_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::MonitorRunFormatter.format(monitor_run, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Monitor run not found: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  $stderr.puts "Authentication error: #{e.message}"
+  $stderr.puts "Check your API key (set EXA_API_KEY or use --api-key)"
+  exit 1
+rescue Exa::ClientError => e
+  $stderr.puts "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  $stderr.puts "Server error: #{e.message}"
+  exit 1
+rescue Exa::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  $stderr.puts "Unexpected error: #{e.message}"
+  $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
+  exit 1
+end

data/exe/exa-ai-monitor-runs-list

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+monitor_id = nil
+limit = nil
+cursor = nil
+api_key = nil
+output_format = "json"
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--limit"
+    limit = args.shift&.to_i
+  when "--cursor"
+    cursor = args.shift
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai monitor-runs-list <monitor_id> [OPTIONS]
+
+      List execution runs for a monitor
+
+      Arguments:
+        monitor_id             ID of the monitor (required)
+
+      Options:
+        --limit N              Maximum number of runs to return (default: 25, max: 100)
+        --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)
+        --help, -h             Show this help message
+
+      Examples:
+        exa-ai monitor-runs-list mon_abc123
+        exa-ai monitor-runs-list mon_abc123 --limit 10
+        exa-ai monitor-runs-list mon_abc123 --limit 5 --cursor "abc123"
+        exa-ai monitor-runs-list mon_abc123 --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is monitor_id
+    if monitor_id.nil?
+      monitor_id = arg
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate
+if monitor_id.nil?
+  $stderr.puts "Error: monitor_id argument is required"
+  $stderr.puts "Usage: exa-ai monitor-runs-list <monitor_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai monitor-runs-list --help' for more information"
+  exit 1
+end
+
+begin
+  # Resolve API key and format
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+  output_format = Exa::CLI::Base.resolve_output_format(output_format)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # List monitor runs with optional pagination
+  list_params = {monitor_id: monitor_id}
+  list_params[:limit] = limit if limit
+  list_params[:cursor] = cursor if cursor
+
+  collection = client.list_monitor_runs(**list_params)
+
+  # Format and output
+  output = Exa::CLI::Formatters::MonitorRunFormatter.format_collection(collection, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Monitor not found: #{e.message}"
+  exit 1
+rescue Exa::ConfigurationError => e
+  $stderr.puts "Configuration error: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  $stderr.puts "Authentication error: #{e.message}"
+  $stderr.puts "Check your API key (set EXA_API_KEY or use --api-key)"
+  exit 1
+rescue Exa::ClientError => e
+  $stderr.puts "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  $stderr.puts "Server error: #{e.message}"
+  $stderr.puts "The Exa API may be experiencing issues. Please try again later."
+  exit 1
+rescue Exa::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  $stderr.puts "Unexpected error: #{e.message}"
+  $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
+  exit 1
+end

data/exe/exa-ai-monitor-update

@@ -0,0 +1,207 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+VALID_BEHAVIOR_TYPES = %w[search refresh].freeze
+
+# Recursively convert hash keys from strings to symbols
+def deep_symbolize_keys(obj)
+  case obj
+  when Hash
+    obj.each_with_object({}) do |(key, value), result|
+      result[key.to_sym] = deep_symbolize_keys(value)
+    end
+  when Array
+    obj.map { |item| deep_symbolize_keys(item) }
+  else
+    obj
+  end
+end
+
+# Parse JSON string or load from file (supports @file.json syntax)
+def parse_json_or_file(value)
+  json_data = if value.start_with?("@")
+                file_path = value[1..]
+                JSON.parse(File.read(file_path))
+              else
+                JSON.parse(value)
+              end
+  deep_symbolize_keys(json_data)
+rescue JSON::ParserError => e
+  $stderr.puts "Error: Invalid JSON: #{e.message}"
+  exit 1
+rescue Errno::ENOENT => e
+  $stderr.puts "Error: File not found: #{e.message}"
+  exit 1
+end
+
+# Parse command-line arguments
+def parse_args(argv)
+  # Check for help first
+  if argv.include?("--help") || argv.include?("-h")
+    puts <<~HELP
+      Usage: exa-ai monitor-update <monitor_id> [OPTIONS]
+
+      Update a monitor's schedule or behavior
+
+      Required:
+        <monitor_id>               Monitor ID
+
+      Cadence options:
+        --cron EXPR                Cron expression (e.g., "0 0 * * *")
+        --timezone TZ              Timezone (e.g., "America/New_York")
+
+      Behavior options:
+        --behavior-type TYPE       One of: #{VALID_BEHAVIOR_TYPES.join(', ')}
+        --query TEXT               Search query (for search behavior)
+        --count N                  Number of results (for search behavior)
+        --behavior-mode MODE       Mode: override or append (for search behavior)
+
+      Other options:
+        --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
+
+      Examples:
+        # Update cron schedule
+        exa-ai monitor-update mon_123 --cron "0 */12 * * *"
+
+        # Update search query
+        exa-ai monitor-update mon_123 --query "AI startups in Europe"
+
+        # Update multiple fields
+        exa-ai monitor-update mon_123 --cron "0 0 * * *" --timezone "UTC" \\
+          --query "New companies" --count 100
+    HELP
+    exit 0
+  end
+
+  args = {
+    output_format: "json",
+    api_key: nil
+  }
+
+  # First, check for positional argument (monitor_id)
+  if argv.empty? || argv[0].start_with?("--")
+    return args
+  end
+
+  args[:monitor_id] = argv[0]
+  i = 1
+
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--cron"
+      args[:cron] = argv[i + 1]
+      i += 2
+    when "--timezone"
+      args[:timezone] = argv[i + 1]
+      i += 2
+    when "--behavior-type"
+      args[:behavior_type] = argv[i + 1]
+      i += 2
+    when "--query"
+      args[:query] = argv[i + 1]
+      i += 2
+    when "--count"
+      args[:count] = argv[i + 1]&.to_i
+      i += 2
+    when "--behavior-mode"
+      args[:behavior_mode] = argv[i + 1]
+      i += 2
+    when "--api-key"
+      args[:api_key] = argv[i + 1]
+      i += 2
+    when "--output-format"
+      args[:output_format] = argv[i + 1]
+      i += 2
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+
+  args
+end
+
+# Validate required arguments
+def validate_args(args)
+  unless args[:monitor_id]
+    $stderr.puts "Error: monitor_id argument is required"
+    $stderr.puts "Usage: exa-ai monitor-update <monitor_id> [OPTIONS]"
+    $stderr.puts "Try 'exa-ai monitor-update --help' for more information"
+    exit 1
+  end
+
+  # Validate behavior type if provided
+  if args[:behavior_type] && !VALID_BEHAVIOR_TYPES.include?(args[:behavior_type])
+    $stderr.puts "Error: --behavior-type must be one of: #{VALID_BEHAVIOR_TYPES.join(', ')}"
+    exit 1
+  end
+end
+
+# Main execution
+args = parse_args(ARGV)
+validate_args(args)
+
+begin
+  # Resolve API key and format
+  api_key = Exa::CLI::Base.resolve_api_key(args[:api_key])
+  output_format = Exa::CLI::Base.resolve_output_format(args[:output_format])
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Build update params
+  update_params = {}
+
+  # Build cadence object if any cadence params provided
+  if args[:cron] || args[:timezone]
+    update_params[:cadence] = {}
+    update_params[:cadence][:cron] = args[:cron] if args[:cron]
+    update_params[:cadence][:timezone] = args[:timezone] if args[:timezone]
+  end
+
+  # Build behavior object if any behavior params provided
+  if args[:behavior_type] || args[:query] || args[:count] || args[:behavior_mode]
+    update_params[:behavior] = {}
+    update_params[:behavior][:type] = args[:behavior_type] if args[:behavior_type]
+    update_params[:behavior][:query] = args[:query] if args[:query]
+    update_params[:behavior][:count] = args[:count] if args[:count]
+    update_params[:behavior][:mode] = args[:behavior_mode] if args[:behavior_mode]
+  end
+
+  # Update monitor
+  monitor = client.update_monitor(args[:monitor_id], **update_params)
+
+  # Format and output
+  output = Exa::CLI::Formatters::MonitorFormatter.format(monitor, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Monitor not found: #{e.message}"
+  exit 1
+rescue Exa::ConfigurationError => e
+  $stderr.puts "Configuration error: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  $stderr.puts "Authentication error: #{e.message}"
+  $stderr.puts "Check your API key (set EXA_API_KEY or use --api-key)"
+  exit 1
+rescue Exa::ClientError => e
+  $stderr.puts "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  $stderr.puts "Server error: #{e.message}"
+  $stderr.puts "The Exa API may be experiencing issues. Please try again later."
+  exit 1
+rescue Exa::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  $stderr.puts "Unexpected error: #{e.message}"
+  $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
+  exit 1
+end

data/exe/exa-ai-webset-create

@@ -46,6 +46,9 @@ def parse_args(argv)
   while i < argv.length
     arg = argv[i]
     case arg
+    when "--import"
+      args[:import] = argv[i + 1]
+      i += 2
     when "--search"
       args[:search] = parse_json_or_file(argv[i + 1])
       i += 2
@@ -72,27 +75,56 @@ def parse_args(argv)
       i += 2
     when "--help", "-h"
       puts <<~HELP
-        Usage: exa-ai webset-create --search JSON [OPTIONS]
+        Usage: exa-ai webset-create (--search JSON | --import ID) [OPTIONS]
 
-        Create a new webset with search criteria
+        Create a new webset from search criteria or an import
 
-        Required:
-          --search JSON              Search configuration (supports @file.json)
+        Required (choose one):
+          --search JSON              Search configuration as JSON (supports @file.json)
+                                     Format: {"query":"...","count":10,"scope":[...]}
+                                     The 'scope' field limits search to specific sources
+          --import ID                Import/webset ID to attach data to this webset
+                                     (loads data but does NOT filter searches)
+                                     Format: import_abc123 or webset_xyz789
 
         Options:
           --enrichments JSON         Array of enrichment configs (supports @file.json)
-          --exclude JSON             Array of exclude configs (supports @file.json)
+                                     Format: [{"description":"...","format":"text"}]
+          --exclude JSON             Sources to exclude from searches (supports @file.json)
+                                     Format: [{"source":"import|webset","id":"..."}]
           --external-id ID           External identifier for the webset
           --metadata JSON            Custom metadata (supports @file.json)
+                                     Format: {"key":"value"}
           --wait                     Wait for webset to reach idle status
           --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
 
+        JSON Format Details:
+          search.scope               Array of source references to limit search
+                                     Format: [{"source":"import|webset","id":"..."}]
+                                     With relationship (hop search):
+                                     [{"source":"webset","id":"ws_123",
+                                       "relationship":{"definition":"investors of","limit":3}}]
+
+          IMPORTANT: Cannot use the same import ID in both --import and search.scope
+                    (this will return a 400 error from the API)
+
         Examples:
+          # Create webset from search
           exa-ai webset-create --search '{"query":"AI startups","count":10}'
           exa-ai webset-create --search @search.json --enrichments @enrichments.json
           exa-ai webset-create --search @search.json --wait
+
+          # Create webset with scoped search (filter to specific import)
+          exa-ai webset-create --search '{"query":"CEOs","count":10,"scope":[{"source":"import","id":"import_abc"}]}'
+
+          # Create webset from import
+          exa-ai webset-create --import import_abc123
+          exa-ai webset-create --import import_def456 --enrichments @enrichments.json
+
+          # Load import AND run search (search not scoped to import)
+          exa-ai webset-create --import import_abc123 --search '{"query":"investors","count":20}'
       HELP
       exit 0
     else
@@ -109,8 +141,14 @@ begin
   args = parse_args(ARGV)
 
   # Validate required parameters
-  unless args[:search]
-    $stderr.puts "Error: --search is required"
+  if args[:search] && args[:import]
+    $stderr.puts "Error: Cannot specify both --search and --import"
+    $stderr.puts "Run 'exa-ai webset-create --help' for usage information"
+    exit 1
+  end
+
+  unless args[:search] || args[:import]
+    $stderr.puts "Error: Either --search or --import is required"
     $stderr.puts "Run 'exa-ai webset-create --help' for usage information"
     exit 1
   end
@@ -125,7 +163,25 @@ begin
   client = Exa::CLI::Base.build_client(api_key)
 
   # Prepare webset parameters
-  webset_params = { search: args[:search] }
+  webset_params = {}
+
+  if args[:search]
+    webset_params[:search] = args[:search]
+  elsif args[:import]
+    # Detect source type from ID prefix and convert to API format
+    import_id = args[:import]
+    source = if import_id.start_with?("import_")
+               "import"
+             elsif import_id.start_with?("webset_")
+               "webset"
+             else
+               $stderr.puts "Error: Import ID must start with 'import_' or 'webset_'"
+               exit 1
+             end
+
+    webset_params[:import] = [{ source: source, id: import_id }]
+  end
+
   webset_params[:enrichments] = args[:enrichments] if args[:enrichments]
   webset_params[:exclude] = args[:exclude] if args[:exclude]
   webset_params[:externalId] = args[:external_id] if args[:external_id]

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/base.rb

@@ -16,11 +16,11 @@ module Exa
       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 @@ module Exa
           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

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

@@ -12,6 +12,8 @@ module Exa
             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

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

@@ -12,6 +12,8 @@ module Exa
             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

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

@@ -14,6 +14,8 @@ module Exa
             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