exa-ai 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f55e9efe411da4b9eaf3018791aa7819fc8872c69e32369627014594eb23670
-  data.tar.gz: 0d074ce4bb6eaa2902b80fe5df239be717f182c3703ebfcd6c45944de7cd1245
+  metadata.gz: 1a5fb5324a2ae6dfb4380d91bce7d8d41a3f3b14e471e43bf254a5e763ef0113
+  data.tar.gz: 539a8486ec5e639c4f43fd3e81071ff0f1e5951b3e42c31bc1915d8e00d1df36
 SHA512:
-  metadata.gz: 732d915bf1eadcabff77ae2dcf7c573d426021bea3dac1fe0b2013958dde5a53129c62675ff66279b5204233c970b988ea72ad29ef94bb4b5219cba55910145b
-  data.tar.gz: f4f73347c282e2ebb2209afd42a02e1fb253e9d682a5959ce1cd2ea27519f132c156fb897bbd3177d24f4b88bd06874afd76b81bf70ccb225dcb3ad64ec6249b
+  metadata.gz: dd87558e4a7428b56d9e513478e9d02f88cc845bf7d14fa9c0822e4042dd73d100e686ce3c151bc755d680cc283017311ba2b5109eedfcffef03bd99d4457700
+  data.tar.gz: 49eac46680edc76e6bfa9a2032b9871841095e052cc6e21eac174675f4060149ddc3a690cdd5b6506f39dbaf621f124d7a288f227f99d1637979729e23d63042

data/README.md

@@ -2,6 +2,57 @@
 
 Ruby client for the Exa.ai API. Search and analyze web content using neural search, question answering, code discovery, and research automation.
 
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Error Handling](#error-handling)
+- [Documentation](#documentation)
+- [Development](#development)
+- [Testing](#testing)
+- [Support](#support)
+- [License](#license)
+
+## Requirements
+
+- **Ruby 3.0.0 or higher**
+
+### Installing Ruby on macOS
+
+If you're setting up on a fresh macOS laptop, the easiest way to get Ruby 3.x is through Homebrew:
+
+**1. Install Homebrew** (if not already installed):
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+**2. Install Ruby:**
+
+```bash
+brew install ruby
+```
+
+**3. Add Homebrew's Ruby to your PATH** (follow the instructions Homebrew prints, usually adding to `~/.zshrc`):
+
+```bash
+echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**4. Verify installation:**
+
+```bash
+ruby -v  # Should show Ruby 3.x
+```
+
+**Alternative: Using a version manager**
+
+For managing multiple Ruby versions, consider [rbenv](https://github.com/rbenv/rbenv) or [asdf](https://asdf-vm.com/).
+
 ## Installation
 
 Add to your Gemfile:
@@ -32,6 +83,20 @@ Get your API key from [dashboard.exa.ai](https://dashboard.exa.ai).
 export EXA_API_KEY="your-api-key-here"
 ```
 
+**Using .env file (local development)**
+
+Create a `.env` file in your project root:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit .env and add your API key
+EXA_API_KEY=your-api-key-here
+```
+
+The gem automatically loads `.env` files in development when the `dotenv` gem is installed.
+
 **Ruby Code**
 
 ```ruby
@@ -193,6 +258,46 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
 - Code conventions
 - Building and releasing
 
+## Testing
+
+### Running Tests
+
+```bash
+# Run unit tests (integration tests skip by default)
+bundle exec rake test
+
+# Run integration tests (VCR-based, no real API calls)
+RUN_INTEGRATION_TESTS=true bundle exec rake test
+
+# Run CLI integration tests (real API calls, requires explicit opt-in)
+RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
+```
+
+### Integration Tests
+
+**Integration tests are skipped by default** to prevent accidental API calls.
+
+**VCR-based integration tests (`RUN_INTEGRATION_TESTS`):**
+- Use recorded HTTP interactions (VCR cassettes)
+- No real API calls when replaying cassettes
+- Set `RUN_INTEGRATION_TESTS=true` to run them
+- Safe to run during development
+
+**CLI integration tests (`RUN_CLI_INTEGRATION_TESTS`):**
+- Make real API calls through shell commands
+- Consume Exa's concurrent search quota
+- Set `RUN_CLI_INTEGRATION_TESTS=true` AND `EXA_API_KEY` to run them
+- **Warning:** Can exhaust API quota and trigger rate limits lasting 1-2 days
+
+**When to run integration tests:**
+- VCR tests: Anytime (safe, no real API calls)
+- CLI tests: Only before releases or when testing CLI-specific functionality
+
+**Test Coverage:**
+- **Unit tests** - Fast, no API calls, always run
+- **VCR integration tests** - Replay cassettes, skipped by default
+- **CLI integration tests** - Real API calls via shell, skipped by default
+
 ## Support
 
 - **Documentation**: https://docs.exa.ai

data/exe/exa-ai-answer

@@ -9,7 +9,8 @@ def parse_args(argv)
     output_format: "json",
     api_key: nil,
     text: false,
-    stream: false
+    stream: false,
+    skip_citations: false
   }
 
   # Extract query (first non-flag argument)
@@ -24,6 +25,9 @@ def parse_args(argv)
     when "--stream"
       args[:stream] = true
       i += 1
+    when "--skip-citations", "--no-citations"
+      args[:skip_citations] = true
+      i += 1
     when "--output-schema"
       args[:output_schema] = argv[i + 1]
       i += 2
@@ -48,6 +52,8 @@ def parse_args(argv)
         Options:
           --stream              Stream answer chunks in real-time
           --text                Include full text content from sources
+          --skip-citations      Remove citations from output (saves tokens)
+          --no-citations        Alias for --skip-citations
           --output-schema JSON  JSON schema for structured output
           --system-prompt TEXT  System prompt to guide answer generation
           --api-key KEY         Exa API key (or set EXA_API_KEY env var)
@@ -123,7 +129,7 @@ begin
   else
     # Non-streaming mode - collect full response and format
     result = client.answer(args[:query], **answer_params)
-    output = Exa::CLI::Formatters::AnswerFormatter.format(result, output_format)
+    output = Exa::CLI::Formatters::AnswerFormatter.format(result, output_format, skip_citations: args[:skip_citations])
     puts output
     $stdout.flush
   end

data/exe/exa-ai-enrichment-create

@@ -3,7 +3,7 @@
 
 require "exa-ai"
 
-VALID_FORMATS = %w[text url options].freeze
+VALID_FORMATS = Exa::Constants::Websets::ENRICHMENT_FORMATS
 
 # Recursively convert hash keys from strings to symbols
 def deep_symbolize_keys(obj)

data/exe/exa-ai-search

@@ -2,189 +2,61 @@
 # frozen_string_literal: true
 
 require "exa-ai"
-
-# Parse command-line arguments
-def parse_args(argv)
-  args = {
-    output_format: "json",
-    api_key: nil
-  }
-
-  # Extract query (first non-flag argument)
-  query_parts = []
-  i = 0
-  while i < argv.length
-    arg = argv[i]
-    case arg
-    when "--num-results"
-      args[:num_results] = argv[i + 1].to_i
-      i += 2
-    when "--type"
-      search_type = argv[i + 1]
-      valid_types = ["fast", "deep", "keyword", "auto"]
-      unless valid_types.include?(search_type)
-        $stderr.puts "Error: Search type must be one of: #{valid_types.join(', ')}"
-        exit 1
-      end
-      args[:type] = search_type
-      i += 2
-    when "--category"
-      category = argv[i + 1]
-      valid_categories = ["company", "research paper", "news", "pdf", "github", "tweet", "personal site", "linkedin profile", "financial report"]
-      unless valid_categories.include?(category)
-        $stderr.puts "Error: Category must be one of: #{valid_categories.map { |c| "\"#{c}\"" }.join(', ')}"
-        exit 1
-      end
-      args[:category] = category
-      i += 2
-    when "--include-domains"
-      args[:include_domains] = argv[i + 1].split(",").map(&:strip)
-      i += 2
-    when "--exclude-domains"
-      args[:exclude_domains] = argv[i + 1].split(",").map(&:strip)
-      i += 2
-    when "--api-key"
-      args[:api_key] = argv[i + 1]
-      i += 2
-    when "--output-format"
-      args[:output_format] = argv[i + 1]
-      i += 2
-    when "--linkedin"
-      linkedin_type = argv[i + 1]
-      valid_types = ["company", "person", "all"]
-      unless valid_types.include?(linkedin_type)
-        $stderr.puts "Error: LinkedIn type must be one of: #{valid_types.join(', ')}"
-        exit 1
-      end
-      args[:linkedin] = linkedin_type
-      i += 2
-    when "--start-published-date"
-      args[:start_published_date] = argv[i + 1]
-      i += 2
-    when "--end-published-date"
-      args[:end_published_date] = argv[i + 1]
-      i += 2
-    when "--start-crawl-date"
-      args[:start_crawl_date] = argv[i + 1]
-      i += 2
-    when "--end-crawl-date"
-      args[:end_crawl_date] = argv[i + 1]
-      i += 2
-    when "--include-text"
-      args[:include_text] ||= []
-      args[:include_text] << argv[i + 1]
-      i += 2
-    when "--exclude-text"
-      args[:exclude_text] ||= []
-      args[:exclude_text] << argv[i + 1]
-      i += 2
-    when "--text"
-      args[:text] = true
-      i += 1
-    when "--text-max-characters"
-      args[:text_max_characters] = argv[i + 1].to_i
-      i += 2
-    when "--include-html-tags"
-      args[:include_html_tags] = true
-      i += 1
-    when "--summary"
-      args[:summary] = true
-      i += 1
-    when "--summary-query"
-      args[:summary_query] = argv[i + 1]
-      i += 2
-    when "--summary-schema"
-      schema_arg = argv[i + 1]
-      args[:summary_schema] = if schema_arg.start_with?("@")
-                               JSON.parse(File.read(schema_arg[1..]))
-                             else
-                               JSON.parse(schema_arg)
-                             end
-      i += 2
-    when "--context"
-      args[:context] = true
-      i += 1
-    when "--context-max-characters"
-      args[:context_max_characters] = argv[i + 1].to_i
-      i += 2
-    when "--subpages"
-      args[:subpages] = argv[i + 1].to_i
-      i += 2
-    when "--subpage-target"
-      args[:subpage_target] ||= []
-      args[:subpage_target] << argv[i + 1]
-      i += 2
-    when "--links"
-      args[:links] = argv[i + 1].to_i
-      i += 2
-    when "--image-links"
-      args[:image_links] = argv[i + 1].to_i
-      i += 2
-    when "--help", "-h"
-      puts <<~HELP
-        Usage: exa-ai search QUERY [OPTIONS]
-
-        Search the web using Exa AI
-
-        Arguments:
-          QUERY                 Search query (required)
-
-        Options:
-          --num-results N              Number of results to return (default: 10)
-          --type TYPE                  Search type: fast, deep, keyword, or auto (default: fast)
-          --category CAT               Focus on specific data category
-                                       Options: "company", "research paper", "news", "pdf",
-                                       "github", "tweet", "personal site", "linkedin profile",
-                                       "financial report"
-          --include-domains D          Comma-separated list of domains to include
-          --exclude-domains D          Comma-separated list of domains to exclude
-          --start-published-date DATE  Filter by published date (ISO 8601 format)
-          --end-published-date DATE    Filter by published date (ISO 8601 format)
-          --start-crawl-date DATE      Filter by crawl date (ISO 8601 format)
-          --end-crawl-date DATE        Filter by crawl date (ISO 8601 format)
-          --include-text PHRASE        Include results with exact phrase (repeatable)
-          --exclude-text PHRASE        Exclude results with exact phrase (repeatable)
-
-        Content Extraction:
-          --text                       Include full webpage text
-          --text-max-characters N      Max characters for webpage text
-          --include-html-tags          Include HTML tags in text extraction
-          --summary                    Include AI-generated summary
-          --summary-query PROMPT       Custom prompt for summary generation
-          --summary-schema FILE        JSON schema for summary structure (@file syntax)
-          --context                    Format results as context for LLM RAG
-          --context-max-characters N   Max characters for context string
-          --subpages N                 Number of subpages to crawl
-          --subpage-target PHRASE      Subpage target phrases (repeatable)
-          --links N                    Number of links to extract per result
-          --image-links N              Number of image links to extract
-
-        General Options:
-          --linkedin TYPE              Search LinkedIn: company, person, or all
-          --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 search "ruby programming"
-          exa-ai search "machine learning" --num-results 5 --type deep
-          exa-ai search "Latest LLM research" --category "research paper"
-          exa-ai search "AI startups" --category company
-          exa-ai search "Anthropic" --linkedin company
-          exa-ai search "Dario Amodei" --linkedin person
-          exa-ai search "AI" --linkedin all
-          exa-ai search "AI research" --include-domains arxiv.org,scholar.google.com
-          exa-ai search "tutorials" --output-format pretty
-      HELP
-      exit 0
-    else
-      query_parts << arg
-      i += 1
-    end
-  end
-
-  args[:query] = query_parts.join(" ")
-  args
+require_relative "../lib/exa/cli/search_parser"
+
+def print_help
+  puts <<~HELP
+    Usage: exa-ai search QUERY [OPTIONS]
+
+    Search the web using Exa AI
+
+    Arguments:
+      QUERY                 Search query (required)
+
+    Options:
+      --num-results N              Number of results to return (default: 10)
+      --type TYPE                  Search type: fast, deep, keyword, or auto (default: fast)
+      --category CAT               Focus on specific data category
+                                   Options: "company", "research paper", "news", "pdf",
+                                   "github", "tweet", "personal site", "financial report",
+                                   "people"
+      --include-domains D          Comma-separated list of domains to include
+      --exclude-domains D          Comma-separated list of domains to exclude
+      --start-published-date DATE  Filter by published date (ISO 8601 format)
+      --end-published-date DATE    Filter by published date (ISO 8601 format)
+      --start-crawl-date DATE      Filter by crawl date (ISO 8601 format)
+      --end-crawl-date DATE        Filter by crawl date (ISO 8601 format)
+      --include-text PHRASE        Include results with exact phrase (repeatable)
+      --exclude-text PHRASE        Exclude results with exact phrase (repeatable)
+
+    Content Extraction:
+      --text                       Include full webpage text
+      --text-max-characters N      Max characters for webpage text
+      --include-html-tags          Include HTML tags in text extraction
+      --summary                    Include AI-generated summary
+      --summary-query PROMPT       Custom prompt for summary generation
+      --summary-schema FILE        JSON schema for summary structure (@file syntax)
+      --context                    Format results as context for LLM RAG
+      --context-max-characters N   Max characters for context string
+      --subpages N                 Number of subpages to crawl
+      --subpage-target PHRASE      Subpage target phrases (repeatable)
+      --links N                    Number of links to extract per result
+      --image-links N              Number of image links to extract
+
+    General 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 search "ruby programming"
+      exa-ai search "machine learning" --num-results 5 --type deep
+      exa-ai search "Latest LLM research" --category "research paper"
+      exa-ai search "AI startups" --category company
+      exa-ai search "Dario Amodei" --category people
+      exa-ai search "AI research" --include-domains arxiv.org,scholar.google.com
+      exa-ai search "tutorials" --output-format pretty
+  HELP
 end
 
 # Build contents parameter from extracted flags
@@ -238,15 +110,15 @@ end
 
 # Main execution
 begin
-  args = parse_args(ARGV)
-
-  # Validate query
-  if args[:query].nil? || args[:query].empty?
-    $stderr.puts "Error: Query is required"
-    $stderr.puts "Run 'exa-ai search --help' for usage information"
-    exit 1
+  # Handle help flag
+  if ARGV.include?("--help") || ARGV.include?("-h")
+    print_help
+    exit 0
   end
 
+  # Parse command-line arguments
+  args = Exa::CLI::SearchParser.parse(ARGV)
+
   # Resolve API key
   api_key = Exa::CLI::Base.resolve_api_key(args[:api_key])
 
@@ -272,17 +144,8 @@ begin
   contents = build_contents(args)
   search_params.merge!(contents) if contents
 
-  # Execute search based on LinkedIn type
-  result = case args[:linkedin]
-           when "company"
-             client.linkedin_company(args[:query], **search_params)
-           when "person"
-             client.linkedin_person(args[:query], **search_params)
-           when "all"
-             client.search(args[:query], includeDomains: ["linkedin.com"], **search_params)
-           else
-             client.search(args[:query], **search_params)
-           end
+  # Execute search
+  result = client.search(args[:query], **search_params)
 
   # Format and output result
   output = Exa::CLI::Formatters::SearchFormatter.format(result, output_format)

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

@@ -19,16 +19,16 @@ module Exa
           end
         end
 
-        def self.format_collection(items, output_format)
+        def self.format_collection(collection, output_format)
           case output_format
           when "json"
-            JSON.generate(items)
+            JSON.generate(collection.to_h)
           when "pretty"
-            format_collection_as_pretty(items)
+            format_collection_as_pretty(collection)
           when "text"
-            format_collection_as_text(items)
+            format_collection_as_text(collection)
           when "toon"
-            Exa::CLI::Base.encode_as_toon(items)
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
@@ -74,12 +74,17 @@ module Exa
         end
         private_class_method :format_as_text
 
-        def self.format_collection_as_pretty(items)
+        def self.format_collection_as_pretty(collection)
           lines = []
-          lines << "Items (#{items.length})"
+          lines << "Webset Items (#{collection.data.length} items)"
+
+          if collection.has_more
+            lines << "Next Cursor:   #{collection.next_cursor}"
+          end
+
           lines << ""
 
-          items.each_with_index do |item, idx|
+          collection.data.each_with_index do |item, idx|
             lines << "" if idx > 0  # Blank line between items
 
             lines << "Item ID:       #{item['id']}"
@@ -101,9 +106,9 @@ module Exa
         end
         private_class_method :format_collection_as_pretty
 
-        def self.format_collection_as_text(items)
-          lines = ["Items (#{items.length} total):"]
-          items.each_with_index do |item, idx|
+        def self.format_collection_as_text(collection)
+          lines = ["Webset Items (#{collection.data.length} items):"]
+          collection.data.each_with_index do |item, idx|
             lines << "\n#{idx + 1}. #{item['id']}"
             lines << "   URL: #{item['url']}" if item['url']
             lines << "   Title: #{item['title']}" if item['title']
@@ -112,6 +117,11 @@ module Exa
               lines << "   Entity: #{item['entity']['name']}"
             end
           end
+
+          if collection.has_more
+            lines << "\nMore available (cursor: #{collection.next_cursor})"
+          end
+
           lines.join("\n")
         end
         private_class_method :format_collection_as_text

data/lib/exa/cli/search_parser.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    class SearchParser
+      VALID_SEARCH_TYPES = ["fast", "deep", "keyword", "auto"].freeze
+      VALID_CATEGORIES = [
+        "company", "research paper", "news", "pdf", "github",
+        "tweet", "personal site", "financial report", "people"
+      ].freeze
+
+      def self.parse(argv)
+        new(argv).parse
+      end
+
+      def initialize(argv)
+        @argv = argv
+        @args = {
+          output_format: "json",
+          api_key: nil
+        }
+      end
+
+      def parse
+        parse_arguments
+        validate_query
+        @args
+      end
+
+      private
+
+      def parse_arguments
+        query_parts = []
+        i = 0
+
+        while i < @argv.length
+          arg = @argv[i]
+          case arg
+          when "--num-results"
+            @args[:num_results] = @argv[i + 1].to_i
+            i += 2
+          when "--type"
+            search_type = @argv[i + 1]
+            validate_search_type(search_type)
+            @args[:type] = search_type
+            i += 2
+          when "--category"
+            category = @argv[i + 1]
+            validate_category(category)
+            @args[:category] = category
+            i += 2
+          when "--include-domains"
+            @args[:include_domains] = @argv[i + 1].split(",").map(&:strip)
+            i += 2
+          when "--exclude-domains"
+            @args[:exclude_domains] = @argv[i + 1].split(",").map(&:strip)
+            i += 2
+          when "--api-key"
+            @args[:api_key] = @argv[i + 1]
+            i += 2
+          when "--output-format"
+            @args[:output_format] = @argv[i + 1]
+            i += 2
+          when "--start-published-date"
+            @args[:start_published_date] = @argv[i + 1]
+            i += 2
+          when "--end-published-date"
+            @args[:end_published_date] = @argv[i + 1]
+            i += 2
+          when "--start-crawl-date"
+            @args[:start_crawl_date] = @argv[i + 1]
+            i += 2
+          when "--end-crawl-date"
+            @args[:end_crawl_date] = @argv[i + 1]
+            i += 2
+          when "--include-text"
+            @args[:include_text] ||= []
+            @args[:include_text] << @argv[i + 1]
+            i += 2
+          when "--exclude-text"
+            @args[:exclude_text] ||= []
+            @args[:exclude_text] << @argv[i + 1]
+            i += 2
+          when "--text"
+            @args[:text] = true
+            i += 1
+          when "--text-max-characters"
+            @args[:text_max_characters] = @argv[i + 1].to_i
+            i += 2
+          when "--include-html-tags"
+            @args[:include_html_tags] = true
+            i += 1
+          when "--summary"
+            @args[:summary] = true
+            i += 1
+          when "--summary-query"
+            @args[:summary_query] = @argv[i + 1]
+            i += 2
+          when "--summary-schema"
+            schema_arg = @argv[i + 1]
+            @args[:summary_schema] = if schema_arg.start_with?("@")
+                                      JSON.parse(File.read(schema_arg[1..]))
+                                    else
+                                      JSON.parse(schema_arg)
+                                    end
+            i += 2
+          when "--context"
+            @args[:context] = true
+            i += 1
+          when "--context-max-characters"
+            @args[:context_max_characters] = @argv[i + 1].to_i
+            i += 2
+          when "--subpages"
+            @args[:subpages] = @argv[i + 1].to_i
+            i += 2
+          when "--subpage-target"
+            @args[:subpage_target] ||= []
+            @args[:subpage_target] << @argv[i + 1]
+            i += 2
+          when "--links"
+            @args[:links] = @argv[i + 1].to_i
+            i += 2
+          when "--image-links"
+            @args[:image_links] = @argv[i + 1].to_i
+            i += 2
+          else
+            query_parts << arg
+            i += 1
+          end
+        end
+
+        @args[:query] = query_parts.join(" ")
+      end
+
+      def validate_query
+        raise ArgumentError, "Query is required" if @args[:query].nil? || @args[:query].empty?
+      end
+
+      def validate_search_type(search_type)
+        return if VALID_SEARCH_TYPES.include?(search_type)
+
+        raise ArgumentError, "Search type must be one of: #{VALID_SEARCH_TYPES.join(', ')}"
+      end
+
+      def validate_category(category)
+        return if VALID_CATEGORIES.include?(category)
+
+        raise ArgumentError, "Category must be one of: #{VALID_CATEGORIES.map { |c| "\"#{c}\"" }.join(', ')}"
+      end
+    end
+  end
+end

data/lib/exa/client.rb

@@ -122,32 +122,6 @@ module Exa
       Services::Context.new(connection, query: query, **params).call
     end
 
-    # Search for LinkedIn company pages
-    #
-    # Convenience method that restricts search to LinkedIn company profiles
-    # using keyword search for precise name matching.
-    #
-    # @param query [String] Company name to search
-    # @param params [Hash] Additional search parameters
-    # @option params [Integer] :numResults Number of results to return
-    # @return [Resources::SearchResult] LinkedIn company results
-    def linkedin_company(query, **params)
-      search(query, type: "keyword", includeDomains: ["linkedin.com/company"], **params)
-    end
-
-    # Search for LinkedIn profiles
-    #
-    # Convenience method that restricts search to LinkedIn individual profiles
-    # using keyword search for precise name matching.
-    #
-    # @param query [String] Person name to search
-    # @param params [Hash] Additional search parameters
-    # @option params [Integer] :numResults Number of results to return
-    # @return [Resources::SearchResult] LinkedIn profile results
-    def linkedin_person(query, **params)
-      search(query, type: "keyword", includeDomains: ["linkedin.com/in"], **params)
-    end
-
     # List all websets
     #
     # @param params [Hash] Pagination parameters
@@ -314,9 +288,12 @@ module Exa
     # List all items in a webset
     #
     # @param webset_id [String] Webset ID
-    # @return [Array<Hash>] Array of items
-    def list_items(webset_id:)
-      Services::Websets::ListItems.new(connection, webset_id: webset_id).call
+    # @param params [Hash] Pagination parameters
+    # @option params [String] :cursor Cursor for pagination
+    # @option params [Integer] :limit Maximum number of items to return (default: 20)
+    # @return [Resources::WebsetItemCollection] Paginated list of items
+    def list_items(webset_id:, **params)
+      Services::Websets::ListItems.new(connection, webset_id: webset_id, **params).call
     end
 
     # List all imports

data/lib/exa/constants/websets.rb

@@ -7,7 +7,7 @@ module Exa
       ENTITY_TYPES = %w[company person article research_paper custom].freeze
 
       # Valid enrichment formats
-      ENRICHMENT_FORMATS = %w[text date number options url].freeze
+      ENRICHMENT_FORMATS = %w[text date number options email phone url].freeze
 
       # Valid source types for imports and exclusions
       SOURCE_TYPES = %w[import webset].freeze

data/lib/exa/resources/webset_item_collection.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a paginated list of webset items from the Exa API
+    #
+    # This class wraps the JSON response from the GET /websets/v0/websets/{id}/items endpoint
+    # and provides pagination support.
+    class WebsetItemCollection < Struct.new(
+      :data,
+      :has_more,
+      :next_cursor,
+      keyword_init: true
+    )
+      def initialize(data:, has_more: false, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def to_h
+        {
+          data: data,
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

data/lib/exa/services/websets/list_items.rb

@@ -4,15 +4,21 @@ module Exa
   module Services
     module Websets
       class ListItems
-        def initialize(connection, webset_id:)
+        def initialize(connection, webset_id:, **params)
           @connection = connection
           @webset_id = webset_id
+          @params = params
         end
 
         def call
-          response = @connection.get("/websets/v0/websets/#{@webset_id}/items")
+          response = @connection.get("/websets/v0/websets/#{@webset_id}/items", @params)
           body = response.body
-          body["data"] || []
+
+          Resources::WebsetItemCollection.new(
+            data: body["data"] || [],
+            has_more: body["hasMore"] || false,
+            next_cursor: body["nextCursor"]
+          )
         end
       end
     end

data/lib/exa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exa
-  VERSION = "0.6.1"
+  VERSION = "0.7.1"
 end

data/lib/exa.rb

@@ -17,6 +17,7 @@ require_relative "exa/resources/webset"
 require_relative "exa/resources/webset_search"
 require_relative "exa/resources/webset_enrichment"
 require_relative "exa/resources/webset_enrichment_collection"
+require_relative "exa/resources/webset_item_collection"
 require_relative "exa/resources/import"
 require_relative "exa/resources/import_collection"
 require_relative "exa/resources/monitor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.1
 platform: ruby
 authors:
 - Benjamin Jackson
@@ -135,6 +135,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: A Ruby gem for interacting with the Exa.ai search and discovery API
 email:
 - ben@hearmeout.co
@@ -208,6 +222,7 @@ files:
 - lib/exa/cli/formatters/webset_item_formatter.rb
 - lib/exa/cli/formatters/webset_search_formatter.rb
 - lib/exa/cli/polling.rb
+- lib/exa/cli/search_parser.rb
 - lib/exa/client.rb
 - lib/exa/connection.rb
 - lib/exa/constants/websets.rb
@@ -230,6 +245,7 @@ files:
 - lib/exa/resources/webset_collection.rb
 - lib/exa/resources/webset_enrichment.rb
 - lib/exa/resources/webset_enrichment_collection.rb
+- lib/exa/resources/webset_item_collection.rb
 - lib/exa/resources/webset_search.rb
 - lib/exa/services/answer.rb
 - lib/exa/services/answer_stream.rb