fix(websets): validate import/scope conflicts and improve CLI help

Add validation to prevent using the same import/webset ID in both
top-level :import and search[:scope] parameters, which causes a 400
error from the API.

Improve CLI help text with:
- JSON format examples for all parameters
- Clear distinction between :import (data loading) and scope (search filtering)
- Warning about the duplicate ID constraint
- Additional examples showing scoped searches and hop searches

Changes:
- Add validate_no_duplicate_ids_in_import_and_scope! to CreateValidator
- Add comprehensive tests for duplicate ID detection
- Update webset-create help with JSON formats and important warnings
- Update webset-search-create help with JSON formats and examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: benjaminjackson

exe/exa-ai-webset-create

@@ -80,32 +80,51 @@ def parse_args(argv)
         Create a new webset from search criteria or an import
 
         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)
+          --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
 
-          # Create webset from existing webset
-          exa-ai webset-create --import webset_xyz789
+          # 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

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

lib/exa/services/websets/create_validator.rb

@@ -20,6 +20,7 @@ def validate!(params)
             validate_exclude!(params[:exclude]) if params[:exclude]
             validate_external_id!(params[:externalId]) if params[:externalId]
             validate_metadata!(params[:metadata]) if params[:metadata]
+            validate_no_duplicate_ids_in_import_and_scope!(params)
           end
 
           private
@@ -184,6 +185,20 @@ def validate_string_length!(value, name, min: nil, max: nil)
             raise ArgumentError, "#{name} must be at least #{min} characters" if min && value.length < min
             raise ArgumentError, "#{name} cannot exceed #{max} characters" if max && value.length > max
           end
+
+          def validate_no_duplicate_ids_in_import_and_scope!(params)
+            return unless params[:import] && params[:search] && params[:search][:scope]
+
+            import_ids = params[:import].map { |item| item[:id] }
+            scope_ids = params[:search][:scope].map { |item| item[:id] }
+
+            duplicates = import_ids & scope_ids
+
+            return if duplicates.empty?
+
+            raise ArgumentError,
+                  "Cannot use the same import/webset ID in both :import and search[:scope]: #{duplicates.join(', ')}"
+          end
         end
       end
     end

test/services/websets/create_validator_test.rb

@@ -465,4 +465,96 @@ def test_raises_when_metadata_value_exceeds_max_length
 
     assert_match(/1000 characters/i, error.message)
   end
+
+  def test_raises_when_same_import_id_in_both_import_and_search_scope
+    params = {
+      import: [
+        { source: "import", id: "import_abc123" }
+      ],
+      search: {
+        query: "test",
+        count: 10,
+        scope: [
+          { source: "import", id: "import_abc123" }
+        ]
+      }
+    }
+
+    error = assert_raises(ArgumentError) do
+      Exa::Services::Websets::CreateValidator.validate!(params)
+    end
+
+    assert_match(/cannot use the same.*import.*in both/i, error.message)
+    assert_match(/import_abc123/i, error.message)
+  end
+
+  def test_raises_when_same_webset_id_in_both_import_and_search_scope
+    params = {
+      import: [
+        { source: "webset", id: "ws_xyz789" }
+      ],
+      search: {
+        query: "test",
+        count: 10,
+        scope: [
+          { source: "webset", id: "ws_xyz789" }
+        ]
+      }
+    }
+
+    error = assert_raises(ArgumentError) do
+      Exa::Services::Websets::CreateValidator.validate!(params)
+    end
+
+    assert_match(/cannot use the same.*in both/i, error.message)
+    assert_match(/ws_xyz789/i, error.message)
+  end
+
+  def test_allows_different_ids_in_import_and_search_scope
+    params = {
+      import: [
+        { source: "import", id: "import_abc123" }
+      ],
+      search: {
+        query: "test",
+        count: 10,
+        scope: [
+          { source: "import", id: "import_xyz789" }
+        ]
+      }
+    }
+
+    # Should not raise
+    Exa::Services::Websets::CreateValidator.validate!(params)
+  end
+
+  def test_allows_import_without_search_scope
+    params = {
+      import: [
+        { source: "import", id: "import_abc123" }
+      ],
+      search: {
+        query: "test",
+        count: 10
+      }
+    }
+
+    # Should not raise
+    Exa::Services::Websets::CreateValidator.validate!(params)
+  end
+
+  def test_allows_search_scope_without_import
+    params = {
+      search: {
+        query: "test",
+        count: 10,
+        scope: [
+          { source: "import", id: "import_abc123" }
+        ]
+      }
+    }
+
+    # Should not raise
+    Exa::Services::Websets::CreateValidator.validate!(params)
+  end
 end