exa-ai 0.12.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (159) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +120 -83
  3. data/exe/exa-ai +45 -152
  4. data/exe/exa-ai-agent-run-create +55 -20
  5. data/exe/exa-ai-agent-run-delete +1 -8
  6. data/exe/exa-ai-agent-run-events +21 -1
  7. data/exe/exa-ai-agent-run-list +1 -1
  8. data/exe/{exa-ai-research-list → exa-ai-agent-run-stop} +31 -32
  9. data/exe/exa-ai-answer +25 -0
  10. data/exe/exa-ai-context +6 -2
  11. data/exe/exa-ai-find-similar +26 -68
  12. data/exe/exa-ai-get-contents +138 -42
  13. data/exe/exa-ai-search +27 -104
  14. data/exe/exa-ai-search-monitor-batch +93 -0
  15. data/exe/exa-ai-search-monitor-create +104 -0
  16. data/exe/exa-ai-search-monitor-delete +69 -0
  17. data/exe/exa-ai-search-monitor-get +69 -0
  18. data/exe/exa-ai-search-monitor-list +73 -0
  19. data/exe/exa-ai-search-monitor-runs-get +68 -0
  20. data/exe/exa-ai-search-monitor-runs-list +75 -0
  21. data/exe/exa-ai-search-monitor-trigger +69 -0
  22. data/exe/exa-ai-search-monitor-update +102 -0
  23. data/lib/exa/cli/base.rb +57 -0
  24. data/lib/exa/cli/contents_flags.rb +199 -0
  25. data/lib/exa/cli/formatters/agent_run_formatter.rb +79 -3
  26. data/lib/exa/cli/formatters/search_formatter.rb +18 -2
  27. data/lib/exa/cli/formatters/search_monitor_formatter.rb +98 -0
  28. data/lib/exa/cli/search_parser.rb +46 -87
  29. data/lib/exa/client.rb +183 -333
  30. data/lib/exa/middleware/raise_error.rb +14 -0
  31. data/lib/exa/resources/agent_run.rb +5 -3
  32. data/lib/exa/resources/agent_run_deletion.rb +17 -0
  33. data/lib/exa/resources/answer.rb +3 -3
  34. data/lib/exa/resources/contents_result.rb +5 -1
  35. data/lib/exa/resources/find_similar_result.rb +5 -1
  36. data/lib/exa/resources/search_monitor.rb +42 -0
  37. data/lib/exa/resources/search_monitor_batch_result.rb +11 -0
  38. data/lib/exa/resources/{research_list.rb → search_monitor_list.rb} +3 -2
  39. data/lib/exa/resources/search_monitor_run.rb +46 -0
  40. data/lib/exa/resources/search_monitor_trigger_result.rb +11 -0
  41. data/lib/exa/resources/search_result.rb +11 -1
  42. data/lib/exa/services/agent_run_cancel.rb +1 -12
  43. data/lib/exa/services/agent_run_create.rb +1 -12
  44. data/lib/exa/services/agent_run_delete.rb +6 -14
  45. data/lib/exa/services/agent_run_events.rb +33 -4
  46. data/lib/exa/services/agent_run_get.rb +1 -12
  47. data/lib/exa/services/agent_run_list.rb +1 -12
  48. data/lib/exa/services/agent_run_stop.rb +21 -0
  49. data/lib/exa/services/agent_run_stream.rb +56 -52
  50. data/lib/exa/services/answer.rb +5 -2
  51. data/lib/exa/services/answer_stream.rb +57 -46
  52. data/lib/exa/services/context.rb +3 -1
  53. data/lib/exa/services/find_similar.rb +9 -2
  54. data/lib/exa/services/get_contents.rb +14 -15
  55. data/lib/exa/services/parameter_converter.rb +128 -111
  56. data/lib/exa/services/search.rb +58 -19
  57. data/lib/exa/services/search_monitors/batch.rb +36 -0
  58. data/lib/exa/services/search_monitors/create.rb +37 -0
  59. data/lib/exa/services/search_monitors/delete.rb +22 -0
  60. data/lib/exa/services/search_monitors/get.rb +22 -0
  61. data/lib/exa/services/search_monitors/list.rb +29 -0
  62. data/lib/exa/services/search_monitors/runs_get.rb +23 -0
  63. data/lib/exa/services/search_monitors/runs_list.rb +29 -0
  64. data/lib/exa/services/search_monitors/trigger.rb +22 -0
  65. data/lib/exa/services/search_monitors/update.rb +42 -0
  66. data/lib/exa/services/search_stream.rb +38 -0
  67. data/lib/exa/version.rb +1 -1
  68. data/lib/exa.rb +18 -56
  69. metadata +31 -94
  70. data/exe/exa-ai-enrichment-cancel +0 -108
  71. data/exe/exa-ai-enrichment-create +0 -226
  72. data/exe/exa-ai-enrichment-delete +0 -122
  73. data/exe/exa-ai-enrichment-get +0 -104
  74. data/exe/exa-ai-enrichment-list +0 -99
  75. data/exe/exa-ai-enrichment-update +0 -171
  76. data/exe/exa-ai-import-create +0 -253
  77. data/exe/exa-ai-import-delete +0 -92
  78. data/exe/exa-ai-import-get +0 -92
  79. data/exe/exa-ai-import-list +0 -72
  80. data/exe/exa-ai-import-update +0 -164
  81. data/exe/exa-ai-monitor-create +0 -223
  82. data/exe/exa-ai-monitor-delete +0 -101
  83. data/exe/exa-ai-monitor-get +0 -92
  84. data/exe/exa-ai-monitor-list +0 -90
  85. data/exe/exa-ai-monitor-runs-get +0 -103
  86. data/exe/exa-ai-monitor-runs-list +0 -110
  87. data/exe/exa-ai-monitor-update +0 -207
  88. data/exe/exa-ai-research-get +0 -109
  89. data/exe/exa-ai-research-start +0 -174
  90. data/exe/exa-ai-webset-cancel +0 -97
  91. data/exe/exa-ai-webset-create +0 -254
  92. data/exe/exa-ai-webset-delete +0 -111
  93. data/exe/exa-ai-webset-get +0 -93
  94. data/exe/exa-ai-webset-item-delete +0 -111
  95. data/exe/exa-ai-webset-item-get +0 -105
  96. data/exe/exa-ai-webset-item-list +0 -108
  97. data/exe/exa-ai-webset-list +0 -91
  98. data/exe/exa-ai-webset-search-cancel +0 -104
  99. data/exe/exa-ai-webset-search-create +0 -247
  100. data/exe/exa-ai-webset-search-get +0 -105
  101. data/exe/exa-ai-webset-update +0 -143
  102. data/lib/exa/cli/formatters/enrichment_formatter.rb +0 -125
  103. data/lib/exa/cli/formatters/import_formatter.rb +0 -153
  104. data/lib/exa/cli/formatters/monitor_formatter.rb +0 -144
  105. data/lib/exa/cli/formatters/monitor_run_formatter.rb +0 -126
  106. data/lib/exa/cli/formatters/research_formatter.rb +0 -124
  107. data/lib/exa/cli/formatters/webset_formatter.rb +0 -134
  108. data/lib/exa/cli/formatters/webset_item_formatter.rb +0 -131
  109. data/lib/exa/cli/formatters/webset_search_formatter.rb +0 -57
  110. data/lib/exa/constants/websets.rb +0 -19
  111. data/lib/exa/resources/import.rb +0 -86
  112. data/lib/exa/resources/import_collection.rb +0 -33
  113. data/lib/exa/resources/monitor.rb +0 -48
  114. data/lib/exa/resources/monitor_collection.rb +0 -30
  115. data/lib/exa/resources/monitor_run.rb +0 -52
  116. data/lib/exa/resources/monitor_run_collection.rb +0 -30
  117. data/lib/exa/resources/research_task.rb +0 -39
  118. data/lib/exa/resources/webset.rb +0 -74
  119. data/lib/exa/resources/webset_collection.rb +0 -33
  120. data/lib/exa/resources/webset_enrichment.rb +0 -71
  121. data/lib/exa/resources/webset_enrichment_collection.rb +0 -28
  122. data/lib/exa/resources/webset_item_collection.rb +0 -33
  123. data/lib/exa/resources/webset_search.rb +0 -112
  124. data/lib/exa/services/research_get.rb +0 -30
  125. data/lib/exa/services/research_list.rb +0 -37
  126. data/lib/exa/services/research_start.rb +0 -26
  127. data/lib/exa/services/websets/cancel.rb +0 -36
  128. data/lib/exa/services/websets/cancel_enrichment.rb +0 -35
  129. data/lib/exa/services/websets/cancel_search.rb +0 -44
  130. data/lib/exa/services/websets/create.rb +0 -45
  131. data/lib/exa/services/websets/create_enrichment.rb +0 -35
  132. data/lib/exa/services/websets/create_search.rb +0 -48
  133. data/lib/exa/services/websets/create_search_validator.rb +0 -128
  134. data/lib/exa/services/websets/create_validator.rb +0 -213
  135. data/lib/exa/services/websets/delete.rb +0 -36
  136. data/lib/exa/services/websets/delete_enrichment.rb +0 -35
  137. data/lib/exa/services/websets/delete_item.rb +0 -20
  138. data/lib/exa/services/websets/get_item.rb +0 -20
  139. data/lib/exa/services/websets/get_search.rb +0 -43
  140. data/lib/exa/services/websets/import_create.rb +0 -40
  141. data/lib/exa/services/websets/import_delete.rb +0 -37
  142. data/lib/exa/services/websets/import_get.rb +0 -37
  143. data/lib/exa/services/websets/import_list.rb +0 -25
  144. data/lib/exa/services/websets/import_update.rb +0 -38
  145. data/lib/exa/services/websets/import_upload.rb +0 -58
  146. data/lib/exa/services/websets/list.rb +0 -25
  147. data/lib/exa/services/websets/list_items.rb +0 -26
  148. data/lib/exa/services/websets/monitors/create.rb +0 -42
  149. data/lib/exa/services/websets/monitors/delete.rb +0 -32
  150. data/lib/exa/services/websets/monitors/get.rb +0 -33
  151. data/lib/exa/services/websets/monitors/list.rb +0 -27
  152. data/lib/exa/services/websets/monitors/runs/get.rb +0 -37
  153. data/lib/exa/services/websets/monitors/runs/list.rb +0 -30
  154. data/lib/exa/services/websets/monitors/update.rb +0 -33
  155. data/lib/exa/services/websets/retrieve.rb +0 -47
  156. data/lib/exa/services/websets/retrieve_enrichment.rb +0 -35
  157. data/lib/exa/services/websets/update.rb +0 -37
  158. data/lib/exa/services/websets/update_enrichment.rb +0 -36
  159. data/lib/exa/services/websets_parameter_converter.rb +0 -45
@@ -2,10 +2,30 @@
2
2
  # frozen_string_literal: true
3
3
 
4
4
  require "exa-ai"
5
+ require_relative "../lib/exa/cli/search_parser"
6
+
7
+ VALID_HIGHLIGHTS_VERBOSITY = %w[low medium high].freeze
8
+
9
+ # Raises ArgumentError unless value is one of the allowed values for flag.
10
+ def validate_choice(flag, value, allowed)
11
+ return if allowed.include?(value)
12
+
13
+ raise ArgumentError, "#{flag} must be one of: #{allowed.join(', ')}"
14
+ end
5
15
 
6
16
  # Parse command line arguments
7
17
  def parse_args(args)
18
+ urls = []
8
19
  ids = []
20
+ max_age_hours = nil
21
+ snapshot_as_of = nil
22
+ user_identifier = nil
23
+ compliance = nil
24
+ highlights = false
25
+ highlights_query = nil
26
+ highlights_max_characters = nil
27
+ highlights_verbosity = nil
28
+ text_verbosity = nil
9
29
  api_key = nil
10
30
  text = false
11
31
  text_max_characters = nil
@@ -28,14 +48,14 @@ def parse_args(args)
28
48
 
29
49
  case arg
30
50
  when "--api-key"
31
- i += 1
32
- api_key = args[i]
51
+ api_key = args[i + 1]
52
+ i += 2
33
53
  when "--text"
34
54
  text = true
35
55
  i += 1
36
56
  when "--text-max-characters"
37
- i += 1
38
- text_max_characters = args[i].to_i
57
+ text_max_characters = Exa::CLI::Base.parse_integer("--text-max-characters", args[i + 1])
58
+ i += 2
39
59
  when "--include-html-tags"
40
60
  include_html_tags = true
41
61
  i += 1
@@ -43,55 +63,90 @@ def parse_args(args)
43
63
  summary = true
44
64
  i += 1
45
65
  when "--summary-query"
46
- i += 1
47
- summary_query = args[i]
66
+ summary_query = args[i + 1]
67
+ i += 2
48
68
  when "--summary-schema"
49
- i += 1
50
- schema_arg = args[i]
51
- summary_schema = if schema_arg.start_with?("@")
52
- JSON.parse(File.read(schema_arg[1..]))
53
- else
54
- JSON.parse(schema_arg)
55
- end
69
+ summary_schema = Exa::CLI::Base.parse_json_or_file("--summary-schema", args[i + 1])
70
+ i += 2
56
71
  when "--subpages"
57
- i += 1
58
- subpages = args[i].to_i
72
+ subpages = Exa::CLI::Base.parse_integer("--subpages", args[i + 1])
73
+ i += 2
59
74
  when "--subpage-target"
60
- i += 1
61
- subpage_target << args[i]
75
+ subpage_target << args[i + 1]
76
+ i += 2
62
77
  when "--links"
63
- i += 1
64
- links = args[i].to_i
78
+ links = Exa::CLI::Base.parse_integer("--links", args[i + 1])
79
+ i += 2
65
80
  when "--image-links"
66
- i += 1
67
- image_links = args[i].to_i
81
+ image_links = Exa::CLI::Base.parse_integer("--image-links", args[i + 1])
82
+ i += 2
68
83
  when "--context"
69
84
  context = true
70
85
  i += 1
71
86
  when "--context-max-characters"
72
- i += 1
73
- context_max_characters = args[i].to_i
87
+ context_max_characters = Exa::CLI::Base.parse_integer("--context-max-characters", args[i + 1])
88
+ i += 2
74
89
  when "--livecrawl-timeout"
75
- i += 1
76
- livecrawl_timeout = args[i].to_i
90
+ livecrawl_timeout = Exa::CLI::Base.parse_integer("--livecrawl-timeout", args[i + 1])
91
+ i += 2
77
92
  when "--output-format"
93
+ output_format = args[i + 1]
94
+ i += 2
95
+ when "--ids"
96
+ ids = Exa::CLI::Base.option_value("--ids", args[i + 1]).split(",").map(&:strip)
97
+ i += 2
98
+ when "--max-age-hours"
99
+ max_age_hours = Exa::CLI::Base.parse_integer("--max-age-hours", args[i + 1])
100
+ i += 2
101
+ when "--snapshot-as-of"
102
+ snapshot_as_of = args[i + 1]
103
+ i += 2
104
+ when "--user-identifier"
105
+ user_identifier = args[i + 1]
106
+ i += 2
107
+ when "--compliance"
108
+ compliance = args[i + 1]
109
+ validate_choice("--compliance", compliance, Exa::CLI::SearchParser::VALID_COMPLIANCE)
110
+ i += 2
111
+ when "--highlights"
112
+ highlights = true
78
113
  i += 1
79
- output_format = args[i]
114
+ when "--highlights-query"
115
+ highlights_query = args[i + 1]
116
+ i += 2
117
+ when "--highlights-max-characters"
118
+ highlights_max_characters = Exa::CLI::Base.parse_integer("--highlights-max-characters", args[i + 1])
119
+ i += 2
120
+ when "--highlights-verbosity"
121
+ highlights_verbosity = args[i + 1]
122
+ validate_choice("--highlights-verbosity", highlights_verbosity, VALID_HIGHLIGHTS_VERBOSITY)
123
+ i += 2
124
+ when "--text-verbosity"
125
+ text_verbosity = args[i + 1]
126
+ validate_choice("--text-verbosity", text_verbosity, Exa::CLI::SearchParser::VALID_TEXT_VERBOSITY)
127
+ i += 2
80
128
  when "--help", "-h"
81
129
  print_help
82
130
  exit 0
83
131
  else
84
- # First non-flag argument is the IDs (comma-separated or single)
85
- if ids.empty?
86
- ids_arg = arg
87
- ids = ids_arg.include?(",") ? ids_arg.split(",").map(&:strip) : [ids_arg]
88
- end
132
+ # First non-flag argument is the URLs (comma-separated or single)
133
+ urls = arg.split(",").map(&:strip) if urls.empty?
89
134
  i += 1
90
135
  end
91
136
  end
92
137
 
93
138
  {
139
+ urls: urls,
94
140
  ids: ids,
141
+ max_age_hours: max_age_hours,
142
+ snapshot_as_of: snapshot_as_of,
143
+ user_identifier: user_identifier,
144
+ compliance: compliance,
145
+ highlights: highlights,
146
+ highlights_query: highlights_query,
147
+ highlights_max_characters: highlights_max_characters,
148
+ highlights_verbosity: highlights_verbosity,
149
+ text_verbosity: text_verbosity,
95
150
  api_key: api_key,
96
151
  text: text,
97
152
  text_max_characters: text_max_characters,
@@ -116,10 +171,11 @@ def build_contents_params(args)
116
171
 
117
172
  # Text options
118
173
  if args[:text]
119
- if args[:text_max_characters] || args[:include_html_tags]
174
+ if args[:text_max_characters] || args[:include_html_tags] || args[:text_verbosity]
120
175
  params[:text] = {}
121
176
  params[:text][:max_characters] = args[:text_max_characters] if args[:text_max_characters]
122
177
  params[:text][:include_html_tags] = args[:include_html_tags] if args[:include_html_tags]
178
+ params[:text][:verbosity] = args[:text_verbosity] if args[:text_verbosity]
123
179
  else
124
180
  params[:text] = true
125
181
  end
@@ -156,8 +212,27 @@ def build_contents_params(args)
156
212
  params[:extras][:image_links] = args[:image_links] if args[:image_links]
157
213
  end
158
214
 
159
- # Livecrawl options
215
+ # Highlights options
216
+ if args[:highlights]
217
+ if args[:highlights_query] || args[:highlights_max_characters] || args[:highlights_verbosity]
218
+ params[:highlights] = {}
219
+ params[:highlights][:query] = args[:highlights_query] if args[:highlights_query]
220
+ params[:highlights][:max_characters] = args[:highlights_max_characters] if args[:highlights_max_characters]
221
+ params[:highlights][:verbosity] = args[:highlights_verbosity] if args[:highlights_verbosity]
222
+ else
223
+ params[:highlights] = true
224
+ end
225
+ end
226
+
227
+ # Livecrawl and freshness options
160
228
  params[:livecrawl_timeout] = args[:livecrawl_timeout] if args[:livecrawl_timeout]
229
+ params[:max_age_hours] = args[:max_age_hours] if args[:max_age_hours]
230
+ params[:snapshot_as_of] = args[:snapshot_as_of] if args[:snapshot_as_of]
231
+
232
+ # Request options
233
+ params[:ids] = args[:ids] if args[:ids].any?
234
+ params[:user_identifier] = args[:user_identifier] if args[:user_identifier]
235
+ params[:compliance] = args[:compliance] if args[:compliance]
161
236
 
162
237
  params.empty? ? nil : params
163
238
  end
@@ -165,17 +240,19 @@ end
165
240
  def print_help
166
241
  puts <<~HELP
167
242
  Usage: exa-ai get-contents <urls> [options]
243
+ exa-ai get-contents --ids ID1,ID2 [options]
168
244
 
169
- Retrieve full page contents from URLs
245
+ Retrieve full page contents from URLs or document IDs
170
246
 
171
247
  Arguments:
172
- urls Comma-separated list of URLs (required)
248
+ urls Comma-separated list of URLs (required unless --ids is given)
173
249
 
174
250
  Options:
175
251
  Text Extraction:
176
252
  --text Include page text in response
177
253
  --text-max-characters N Max characters for page text
178
254
  --include-html-tags Include HTML tags in text extraction
255
+ --text-verbosity LEVEL Text verbosity: compact, standard, or full
179
256
 
180
257
  Summary:
181
258
  --summary Include AI-generated summary
@@ -183,8 +260,9 @@ def print_help
183
260
  --summary-schema FILE JSON schema for summary structure (@file syntax)
184
261
 
185
262
  Context:
186
- --context Format results as context for LLM RAG
187
- --context-max-characters N Max characters for context string
263
+ --context Deprecated: use --highlights or --text instead
264
+ (format results as one context string)
265
+ --context-max-characters N Deprecated: max characters for context string
188
266
 
189
267
  Subpages:
190
268
  --subpages N Number of subpages to crawl
@@ -194,8 +272,22 @@ def print_help
194
272
  --links N Number of links to extract per result
195
273
  --image-links N Number of image links to extract
196
274
 
197
- Livecrawl:
275
+ Highlights:
276
+ --highlights Include text highlights in results
277
+ --highlights-query QUERY Custom query for highlight extraction
278
+ --highlights-max-characters N Max characters per highlight
279
+ --highlights-verbosity LEVEL Highlights verbosity: low, medium, or high
280
+ (sends the Exa-Beta dynamic highlights header)
281
+
282
+ Livecrawl and Freshness:
198
283
  --livecrawl-timeout N Timeout for livecrawling in milliseconds
284
+ --max-age-hours N Maximum age of cached content in hours
285
+ --snapshot-as-of DATE Return page contents as of this time (ISO 8601)
286
+
287
+ Request:
288
+ --ids ID1,ID2 Comma-separated document IDs from earlier searches
289
+ --user-identifier ID Your identifier for the end user
290
+ --compliance MODE Compliance mode: hipaa (enterprise only)
199
291
 
200
292
  General:
201
293
  --api-key KEY Exa API key (or set EXA_API_KEY env var)
@@ -216,9 +308,9 @@ begin
216
308
  # Parse arguments
217
309
  options = parse_args(ARGV)
218
310
 
219
- # Validate IDs
220
- if options[:ids].empty?
221
- $stderr.puts "Error: URLs argument required"
311
+ # Validate that there is something to fetch
312
+ if options[:urls].empty? && options[:ids].empty?
313
+ $stderr.puts "Error: URLs argument or --ids required"
222
314
  $stderr.puts ""
223
315
  $stderr.puts "Run 'exa-ai get-contents --help' for usage information."
224
316
  exit 1
@@ -238,12 +330,16 @@ begin
238
330
  params ||= {}
239
331
 
240
332
  # Call API
241
- result = client.get_contents(options[:ids], **params)
333
+ urls = options[:urls].empty? ? nil : options[:urls]
334
+ result = client.get_contents(urls, **params)
242
335
 
243
336
  # Format and output
244
337
  output = Exa::CLI::Formatters::ContentsFormatter.format(result, output_format)
245
338
  puts output
246
339
  $stdout.flush
340
+ rescue ArgumentError => e
341
+ $stderr.puts "Error: #{e.message}"
342
+ exit 1
247
343
  rescue Exa::ConfigurationError => e
248
344
  $stderr.puts "Configuration error: #{e.message}"
249
345
  exit 1
data/exe/exa-ai-search CHANGED
@@ -15,50 +15,41 @@ def print_help
15
15
 
16
16
  Options:
17
17
  --num-results N Number of results to return (default: 10)
18
- --type TYPE Search type: auto, neural, fast, deep, deep-reasoning,
19
- or instant (default: auto)
20
- deep/deep-reasoning synthesize an 'output' field
18
+ --type TYPE Search type: auto, lite, deep-lite, deep, neural, fast,
19
+ deep-reasoning, or instant (default: auto)
20
+ fast and instant are legacy: use lite instead
21
+ deep-reasoning is legacy: use deep instead
22
+ neural is legacy: still accepted, not in the spec
23
+ lite accepts a limited set of parameters
24
+ deep/deep-lite/deep-reasoning synthesize an 'output' field
21
25
  only when --output-schema is provided
22
26
  --category CAT Focus on specific data category
23
- Options: "company", "publication", "news", "github",
27
+ Options: "company", "publication", "news",
24
28
  "personal site", "people", "financial report"
25
29
  --include-domains D Comma-separated list of domains to include
26
30
  --exclude-domains D Comma-separated list of domains to exclude
27
31
  --start-published-date DATE Filter by published date (ISO 8601 format)
28
32
  --end-published-date DATE Filter by published date (ISO 8601 format)
29
- --start-crawl-date DATE Filter by crawl date (ISO 8601 format)
30
- --end-crawl-date DATE Filter by crawl date (ISO 8601 format)
31
- --include-text PHRASE Include results with exact phrase (repeatable)
32
- --exclude-text PHRASE Exclude results with exact phrase (repeatable)
33
+ --start-crawl-date DATE Deprecated: the API ignores it and returns a warning
34
+ --end-crawl-date DATE Deprecated: the API ignores it and returns a warning
35
+ --include-text PHRASE Deprecated: include results that contain the phrase
36
+ (approximate match, repeatable)
37
+ --exclude-text PHRASE Deprecated: exclude results that contain the phrase
38
+ (approximate match, repeatable)
33
39
 
34
40
  Content Extraction:
35
- --text Include full webpage text
36
- --text-max-characters N Max characters for webpage text
37
- --text-verbosity LEVEL Text verbosity: compact, standard, or full
38
- --include-html-tags Include HTML tags in text extraction
39
- --summary Include AI-generated summary
40
- --summary-query PROMPT Custom prompt for summary generation
41
- --summary-schema FILE JSON schema for summary structure (@file syntax)
42
- --context Format results as context for LLM RAG
43
- --context-max-characters N Max characters for context string
44
- --subpages N Number of subpages to crawl
45
- --subpage-target PHRASE Subpage target phrases (repeatable)
46
- --links N Number of links to extract per result
47
- --image-links N Number of image links to extract
48
- --highlights Include text highlights in results
49
- --highlights-max-characters N Max characters per highlight
50
- --highlights-num-sentences N Number of sentences per highlight
51
- --highlights-per-url N Number of highlights per URL
52
- --highlights-query QUERY Custom query for highlight extraction
53
- --livecrawl Enable livecrawl (sets maxAgeHours=0, livecrawlTimeout=5000)
54
- --livecrawl-timeout N Livecrawl timeout in milliseconds (overrides --livecrawl default)
55
- --max-age-hours N Maximum age of results in hours
41
+ #{Exa::CLI::ContentsFlags::HELP}
56
42
 
57
43
  Search Options:
58
44
  --additional-queries QUERY Additional search queries (repeatable)
59
45
  --output-schema JSON JSON schema for output structure (@file syntax)
60
46
  Required to get synthesized 'output' from deep/deep-reasoning
61
- --user-location CODE User location (ISO country code)
47
+ --user-location LOC User location: ISO country code (US), or a JSON
48
+ object with country, latitude, longitude
49
+ (@file syntax)
50
+ --objective TEXT The broader goal this search serves
51
+ --user-identifier ID Your identifier for the end user
52
+ --compliance MODE Compliance mode: hipaa (enterprise only)
62
53
  --system-prompt PROMPT System prompt for AI-powered search
63
54
  --moderation Enable content moderation
64
55
 
@@ -78,79 +69,6 @@ def print_help
78
69
  HELP
79
70
  end
80
71
 
81
- # Build contents parameter from extracted flags
82
- def build_contents(args)
83
- contents = {}
84
-
85
- # Text options
86
- if args[:text]
87
- if args[:text_max_characters] || args[:include_html_tags] || args[:text_verbosity]
88
- contents[:text] = {}
89
- contents[:text][:max_characters] = args[:text_max_characters] if args[:text_max_characters]
90
- contents[:text][:include_html_tags] = args[:include_html_tags] if args[:include_html_tags]
91
- contents[:text][:verbosity] = args[:text_verbosity] if args[:text_verbosity]
92
- else
93
- contents[:text] = true
94
- end
95
- end
96
-
97
- # Summary options
98
- if args[:summary]
99
- if args[:summary_query] || args[:summary_schema]
100
- contents[:summary] = {}
101
- contents[:summary][:query] = args[:summary_query] if args[:summary_query]
102
- contents[:summary][:schema] = args[:summary_schema] if args[:summary_schema]
103
- else
104
- contents[:summary] = true
105
- end
106
- end
107
-
108
- # Context options
109
- if args[:context]
110
- if args[:context_max_characters]
111
- contents[:context] = { max_characters: args[:context_max_characters] }
112
- else
113
- contents[:context] = true
114
- end
115
- end
116
-
117
- # Subpages options
118
- contents[:subpages] = args[:subpages] if args[:subpages]
119
- contents[:subpage_target] = args[:subpage_target] if args[:subpage_target]
120
-
121
- # Extras options
122
- if args[:links] || args[:image_links]
123
- contents[:extras] = {}
124
- contents[:extras][:links] = args[:links] if args[:links]
125
- contents[:extras][:image_links] = args[:image_links] if args[:image_links]
126
- end
127
-
128
- # Highlights options
129
- if args[:highlights]
130
- highlight_opts = %i[highlights_max_characters highlights_num_sentences highlights_per_url highlights_query]
131
- if highlight_opts.any? { |k| args[k] }
132
- contents[:highlights] = {}
133
- contents[:highlights][:max_characters] = args[:highlights_max_characters] if args[:highlights_max_characters]
134
- contents[:highlights][:num_sentences] = args[:highlights_num_sentences] if args[:highlights_num_sentences]
135
- contents[:highlights][:highlights_per_url] = args[:highlights_per_url] if args[:highlights_per_url]
136
- contents[:highlights][:query] = args[:highlights_query] if args[:highlights_query]
137
- else
138
- contents[:highlights] = true
139
- end
140
- end
141
-
142
- # Livecrawl options
143
- if args[:livecrawl]
144
- contents[:max_age_hours] = args[:max_age_hours].nil? ? 0 : args[:max_age_hours]
145
- contents[:livecrawl_timeout] = args[:livecrawl_timeout].nil? ? 5000 : args[:livecrawl_timeout]
146
- else
147
- contents[:livecrawl_timeout] = args[:livecrawl_timeout] if args[:livecrawl_timeout]
148
- contents[:max_age_hours] = args[:max_age_hours] if args[:max_age_hours]
149
- end
150
-
151
- contents.empty? ? nil : contents
152
- end
153
-
154
72
  # Main execution
155
73
  begin
156
74
  # Handle help flag
@@ -189,7 +107,11 @@ begin
189
107
  search_params[:user_location] = args[:user_location] if args[:user_location]
190
108
  search_params[:system_prompt] = args[:system_prompt] if args[:system_prompt]
191
109
  search_params[:moderation] = args[:moderation] if args[:moderation]
192
- contents = build_contents(args)
110
+ search_params[:objective] = args[:objective] if args[:objective]
111
+ search_params[:user_identifier] = args[:user_identifier] if args[:user_identifier]
112
+ search_params[:compliance] = args[:compliance] if args[:compliance]
113
+ search_params[:snapshot_as_of] = args[:snapshot_as_of] if args[:snapshot_as_of]
114
+ contents = Exa::CLI::ContentsFlags.build(args)
193
115
  search_params.merge!(contents) if contents
194
116
 
195
117
  # Execute search
@@ -199,6 +121,7 @@ begin
199
121
  output = Exa::CLI::Formatters::SearchFormatter.format(result, output_format)
200
122
  puts output
201
123
  $stdout.flush
124
+ Exa::CLI::Formatters::SearchFormatter.print_warnings(result)
202
125
 
203
126
  rescue Exa::ConfigurationError => e
204
127
  $stderr.puts "Configuration error: #{e.message}"
@@ -0,0 +1,93 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "exa-ai"
5
+
6
+ api_key = nil
7
+ output_format = "json"
8
+ action = nil
9
+ filter = {}
10
+ limit = nil
11
+ dry_run = true
12
+
13
+ args = ARGV.dup
14
+ while args.any?
15
+ arg = args.shift
16
+ case arg
17
+ when "--api-key"
18
+ api_key = args.shift
19
+ when "--action"
20
+ action = args.shift
21
+ when "--status"
22
+ filter[:status] = args.shift
23
+ when "--name"
24
+ filter[:name] = args.shift
25
+ when "--metadata"
26
+ filter[:metadata] = Exa::CLI::Base.parse_json_or_file("--metadata", args.shift)
27
+ when "--limit"
28
+ limit = Exa::CLI::Base.parse_integer("--limit", args.shift)
29
+ when "--execute"
30
+ dry_run = false
31
+ when "--output-format"
32
+ output_format = args.shift
33
+ when "--help", "-h"
34
+ puts <<~HELP
35
+ Usage: exa-ai search-monitor-batch --action ACTION [filter options] [options]
36
+
37
+ Delete, pause, or unpause every search monitor that matches a filter.
38
+ This is a DRY RUN by default: it only reports what would change.
39
+ Pass --execute to apply the change. Repeat until has_more is false.
40
+
41
+ Required:
42
+ --action ACTION delete, pause, or unpause
43
+
44
+ Filter options:
45
+ --status STATUS Match monitors with this status
46
+ --name TEXT Match monitors whose name contains TEXT
47
+ --metadata JSON Match metadata key-value pairs (JSON or @file.json)
48
+
49
+ Options:
50
+ --limit N Maximum monitors to change in one call
51
+ --execute Apply the change (default: dry run)
52
+ --api-key KEY Exa API key (or use EXA_API_KEY env var)
53
+ --output-format FORMAT Output format: json, pretty, text, or toon (default: json)
54
+ --help, -h Show this help message
55
+
56
+ Examples:
57
+ exa-ai search-monitor-batch --action pause --status active
58
+ exa-ai search-monitor-batch --action delete --name "old test" --execute
59
+ HELP
60
+ exit 0
61
+ else
62
+ warn "Unknown option: #{arg}"
63
+ exit 1
64
+ end
65
+ end
66
+
67
+ unless %w[delete pause unpause].include?(action)
68
+ warn "Error: --action must be delete, pause, or unpause. Run with --help for usage."
69
+ exit 1
70
+ end
71
+
72
+ begin
73
+ output_format = Exa::CLI::Base.resolve_output_format(output_format)
74
+ client = Exa::CLI::Base.build_client(Exa::CLI::Base.resolve_api_key(api_key))
75
+ result = client.search_monitor_batch(action: action, filter: filter, dry_run: dry_run, limit: limit)
76
+ puts Exa::CLI::Formatters::SearchMonitorFormatter.format(result, output_format)
77
+ rescue Exa::Unauthorized => e
78
+ warn "Authentication failed: #{e.message}"
79
+ warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
80
+ exit 1
81
+ rescue Exa::ClientError => e
82
+ warn "Client error: #{e.message}"
83
+ exit 1
84
+ rescue Exa::ServerError => e
85
+ warn "Server error: #{e.message}"
86
+ exit 1
87
+ rescue Exa::Error => e
88
+ warn "Error: #{e.message}"
89
+ exit 1
90
+ rescue StandardError => e
91
+ warn "Unexpected error: #{e.message}"
92
+ exit 1
93
+ end
@@ -0,0 +1,104 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "exa-ai"
5
+
6
+ api_key = nil
7
+ output_format = "json"
8
+ search = {}
9
+ webhook = {}
10
+ params = {}
11
+
12
+ args = ARGV.dup
13
+ while args.any?
14
+ arg = args.shift
15
+ case arg
16
+ when "--api-key"
17
+ api_key = args.shift
18
+ when "--query"
19
+ search[:query] = args.shift
20
+ when "--num-results"
21
+ search[:num_results] = Exa::CLI::Base.parse_integer("--num-results", args.shift)
22
+ when "--include-domains"
23
+ search[:include_domains] = Exa::CLI::Base.option_value("--include-domains", args.shift).split(",").map(&:strip)
24
+ when "--exclude-domains"
25
+ search[:exclude_domains] = Exa::CLI::Base.option_value("--exclude-domains", args.shift).split(",").map(&:strip)
26
+ when "--webhook-url"
27
+ webhook[:url] = args.shift
28
+ when "--webhook-events"
29
+ webhook[:events] = Exa::CLI::Base.option_value("--webhook-events", args.shift).split(",").map(&:strip)
30
+ when "--period"
31
+ params[:trigger] = { type: "interval", period: args.shift }
32
+ when "--name"
33
+ params[:name] = args.shift
34
+ when "--output-schema"
35
+ params[:output_schema] = Exa::CLI::Base.parse_json_or_file("--output-schema", args.shift)
36
+ when "--metadata"
37
+ params[:metadata] = Exa::CLI::Base.parse_json_or_file("--metadata", args.shift)
38
+ when "--output-format"
39
+ output_format = args.shift
40
+ when "--help", "-h"
41
+ puts <<~HELP
42
+ Usage: exa-ai search-monitor-create --query TEXT --webhook-url URL [options]
43
+
44
+ Create a search monitor: a scheduled Exa search that posts new results to a webhook.
45
+ Search monitors are the /monitors API.
46
+
47
+ Required:
48
+ --query TEXT Search query
49
+ --webhook-url URL Webhook that receives results
50
+
51
+ Options:
52
+ --period PERIOD Run on a schedule, e.g. 1h, 6h, 1d, 7d (minimum 1h).
53
+ Without it the monitor runs only with search-monitor-trigger.
54
+ --name NAME Monitor name
55
+ --num-results N Results per run
56
+ --include-domains LIST Comma-separated domains to include
57
+ --exclude-domains LIST Comma-separated domains to exclude
58
+ --webhook-events LIST Comma-separated webhook events
59
+ --output-schema JSON JSON schema for structured output (JSON or @file.json)
60
+ --metadata JSON Custom metadata (JSON or @file.json)
61
+ --api-key KEY Exa API key (or use EXA_API_KEY env var)
62
+ --output-format FORMAT Output format: json, pretty, text, or toon (default: json)
63
+ --help, -h Show this help message
64
+
65
+ The response holds the webhook secret. The API returns it only once.
66
+
67
+ Example:
68
+ exa-ai search-monitor-create --query "AI/ML infrastructure startups with Series A funding" \\
69
+ --webhook-url https://example.com/webhooks/exa --period 1d --name "AI funding"
70
+ HELP
71
+ exit 0
72
+ else
73
+ warn "Unknown option: #{arg}"
74
+ exit 1
75
+ end
76
+ end
77
+
78
+ unless search[:query] && webhook[:url]
79
+ warn "Error: --query and --webhook-url are required. Run with --help for usage."
80
+ exit 1
81
+ end
82
+
83
+ begin
84
+ output_format = Exa::CLI::Base.resolve_output_format(output_format)
85
+ client = Exa::CLI::Base.build_client(Exa::CLI::Base.resolve_api_key(api_key))
86
+ result = client.search_monitor_create(search: search, webhook: webhook, **params)
87
+ puts Exa::CLI::Formatters::SearchMonitorFormatter.format(result, output_format)
88
+ rescue Exa::Unauthorized => e
89
+ warn "Authentication failed: #{e.message}"
90
+ warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
91
+ exit 1
92
+ rescue Exa::ClientError => e
93
+ warn "Client error: #{e.message}"
94
+ exit 1
95
+ rescue Exa::ServerError => e
96
+ warn "Server error: #{e.message}"
97
+ exit 1
98
+ rescue Exa::Error => e
99
+ warn "Error: #{e.message}"
100
+ exit 1
101
+ rescue StandardError => e
102
+ warn "Unexpected error: #{e.message}"
103
+ exit 1
104
+ end