exa-ai 0.5.0 → 0.6.0

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,12 +75,14 @@ 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:
+        Required (choose one):
           --search JSON              Search configuration (supports @file.json)
+          --import ID                Import or webset ID to create webset from
+                                     (accepts import_* or webset_* IDs)
 
         Options:
           --enrichments JSON         Array of enrichment configs (supports @file.json)
@@ -90,9 +95,17 @@ def parse_args(argv)
           --help, -h                 Show this help message
 
         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 from import
+          exa-ai webset-create --import import_abc123
+          exa-ai webset-create --import import_def456 --enrichments @enrichments.json
+
+          # Create webset from existing webset
+          exa-ai webset-create --import webset_xyz789
       HELP
       exit 0
     else
@@ -109,8 +122,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 +144,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/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

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

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

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class ImportFormatter
+        def self.format(import, output_format)
+          case output_format
+          when "json"
+            JSON.generate(import.to_h)
+          when "pretty"
+            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
+        end
+
+        def self.format_collection(collection, output_format)
+          case output_format
+          when "json"
+            JSON.generate(collection.to_h)
+          when "pretty"
+            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
+        end
+
+        def self.format_as_text(import)
+          lines = []
+          lines << "Import: #{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 << "\nFailure Details:"
+            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 << "\nUpload:"
+            lines << "  URL: #{import.upload_url}"
+            lines << "  Valid Until: #{import.upload_valid_until}" if import.upload_valid_until
+          end
+
+          lines << "\nCreated: #{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_text
+
+        def self.format_collection_as_text(collection)
+          lines = ["Imports (#{collection.data.length} items):"]
+          collection.data.each do |imp|
+            lines << "\n  #{imp.id}"
+            lines << "  Status: #{imp.status}"
+            lines << "  Title: #{imp.title}" if imp.title
+            lines << "  Count: #{imp.count}" if imp.count
+          end
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end