exa-ai-ruby 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d63e020a8a8be86a5f10fe3cef3be38eaec07537c1b4d20cfa52ebc6474c483
-  data.tar.gz: 5bf845c75eced722a8e3dc0e0bbc4ece8d14b6a74046e685c0f8daefea42ff78
+  metadata.gz: cbb55f4b95516f779fda2e4f26d34d38778ce94186683001768348b8378e06ac
+  data.tar.gz: dc31ed93afbc2a1f7d96db620fe975d70c2aaa7647a11eaa7592ae973e9fe5cb
 SHA512:
-  metadata.gz: a6423df0960415ee47438fbca1c72d015a53fb611f0721671a4d0cba2b7b1c8dff17a71a4e448324f2d42157ae05a4ccf385a351f332ccf91cd40b3a749bfce5
-  data.tar.gz: 353057eb46a716e65d1b984aea014f5d80d006bb613242bf41311c4a22d55a47b1483f090e9df711b58c15e38ca351e6cf85a192e9a92191a59010db42c4a645
+  metadata.gz: 8bcb3d9fa20d16ac14435ad04c327ab508afa1461fe0aa0f99528a5eb423fb32246bfdf5db732547c52bab9f89107dc5feae65f28879699948ef9d188570929f
+  data.tar.gz: 56019a774cb70ab4a1f73a9586c1e02735d3df867313c6c62d0012b19180f1067d6b0aa8774b5625a71d5b0b0f3ce924e490c86b8d99256444d66bf3da00b4c7

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.1.1] - 2025-10-26
+- Add CLI output formatters: `--format jsonl` emits one JSON object per line, and `--format markdown` prints share-ready bullet lists/tables.
+- Document copy-paste ready CLI and Ruby API examples in the README so users/LLMs can get started instantly.
+
 ## [1.1.0] - 2025-10-26
 - Add the `exa` CLI entrypoint (installed automatically with the gem) including multi-account credential management and JSON-friendly output helpers.
 - Introduce a secure YAML config store (`~/.config/exa/config.yml`) and CLI commands for `accounts:list`, `accounts:add`, `accounts:use`, and `accounts:remove`.

data/README.md

@@ -125,17 +125,67 @@ Starting with v1.1.0 the gem ships an `exa` executable that mirrors the API surf
 
    Every command accepts `--account`, `--api-key`, `--base-url`, `--config`, and `--format`. If omitted they fall back to the config file, environment variables (`EXA_ACCOUNT`, `EXA_API_KEY`, `EXA_BASE_URL`), or defaults.
 
-3. **Call the API from any shell**
+   3. **Call the API from any shell**
 
-   ```
-   # Run a typed search (pipe `--json` to jq or capture raw data)
-   $ exa search:run "latest reasoning LLM papers" --num-results 3 --json
+      ```
+      # Run a typed search (pipe `--json` to jq or capture raw data)
+      $ exa search:run "latest reasoning LLM papers" --num-results 3 --json
 
-   # Fetch contents for explicit URLs
-   $ exa search:contents --urls https://exa.ai,https://exa.com --json
-   ```
+      # Fetch contents for explicit URLs
+      $ exa search:contents --urls https://exa.ai,https://exa.com --json
+
+      # Stream results as JSON lines (great for logging/piping)
+      $ exa search:run "ai funding" --num-results 2 --format jsonl
+
+      # Share-ready Markdown lists
+      $ exa websets:list --format markdown
+      ```
+
+      Omit `--json` for friendly summaries; include it when scripting so you get the Sorbet structs serialized as plain JSON.
+
+   Prefer `--format jsonl` for streaming-friendly logs or `--format markdown` when you want ready-to-share bullet lists/tables.
+
+### Copy-paste CLI examples
+
+```bash
+# 1) Configure credentials once (stored at ~/.config/exa/config.yml)
+exa accounts:add prod --api-key $EXA_API_KEY --base-url https://api.exa.ai
+
+# 2) Run searches with different outputs
+exa search:run "latest reasoning LLM papers" --num-results 5
+exa search:run "biotech funding" --format jsonl | tee results.jsonl
+
+# 3) Inspect resources in Markdown form (perfect for PRs/notes)
+exa websets:list --format markdown
+exa webhooks:list --format markdown
+
+# 4) Use a one-off API key without mutating config
+exa search:contents --urls https://exa.ai --api-key $EXA_API_KEY --json
+```
+
+### Copy-paste API client example
 
-   Omit `--json` for friendly summaries; include it when scripting so you get the Sorbet structs serialized as plain JSON.
+```ruby
+require "exa"
+
+client = Exa::Client.new(api_key: ENV.fetch("EXA_API_KEY"))
+
+search = client.search.search(
+  query: "latest reasoning LLM papers",
+  num_results: 5,
+  text: true
+)
+
+search.results.each do |result|
+  puts "#{result.title} - #{result.url}"
+end
+
+# Websets + monitors
+websets = client.websets.list(limit: 5)
+websets.data.each_with_index do |webset, idx|
+  puts "#{idx + 1}. #{webset.title} (#{webset.id})"
+end
+```
 
 Command families currently available:
 

data/lib/exa/cli/formatters.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Exa
+  module CLI
+    module Formatters
+      def self.for(name)
+        case name&.to_s&.downcase
+        when "json"
+          JsonFormatter.new
+        when "jsonl"
+          JsonlFormatter.new
+        when "markdown"
+          MarkdownFormatter.new
+        else
+          TableFormatter.new
+        end
+      end
+
+      class BaseFormatter
+        def render(cli:, payload:, collection:)
+          raise NotImplementedError
+        end
+
+        private
+
+        def serialize(cli, object)
+          cli.send(:serializable, object)
+        end
+      end
+
+      class JsonFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          cli.say JSON.pretty_generate(serialize(cli, payload))
+        end
+      end
+
+      class JsonlFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          items = collection && !collection.empty? ? collection : [payload]
+          items.each do |item|
+            cli.say JSON.generate(serialize(cli, item))
+          end
+        end
+      end
+
+      class MarkdownFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          if collection && !collection.empty?
+            collection.each do |item|
+              cli.say "- #{markdown_line(cli, item)}"
+            end
+          else
+            cli.say "```json"
+            cli.say JSON.pretty_generate(serialize(cli, payload))
+            cli.say "```"
+          end
+        end
+
+        private
+
+        def markdown_line(cli, item)
+          title = cli.send(:value_from, item, :title) || cli.send(:value_from, item, :name)
+          url = cli.send(:value_from, item, :url)
+          id = cli.send(:value_from, item, :id)
+          primary = title || id || cli.send(:serializable, item)
+
+          line = primary.is_a?(String) ? primary : primary.to_s
+          line = "[#{line}](#{url})" if url
+          line += " (#{id})" if id && (title || url)
+          line
+        end
+      end
+
+      class TableFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          if collection && !collection.empty?
+            collection.each_with_index do |item, index|
+              cli.say cli.send(:format_collection_entry, item, index)
+            end
+          elsif collection
+            cli.say "No results."
+          else
+            cli.say cli.send(:format_single_entry, payload)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/cli/root.rb

@@ -5,6 +5,7 @@ require "json"
 require "exa"
 require_relative "config_store"
 require_relative "account_resolver"
+require_relative "formatters"
 
 module Exa
   module CLI
@@ -69,7 +70,7 @@ module Exa
       class_option :api_key, type: :string, desc: "Override the API key for this invocation"
       class_option :base_url, type: :string, desc: "Override the API base URL"
       class_option :config, type: :string, desc: "Path to the exa CLI config file"
-      class_option :format, type: :string, default: "table", desc: "Output format: table, json, or raw"
+      class_option :format, type: :string, default: "table", desc: "Output format: table, json, jsonl, or markdown"
 
       # Version -----------------------------------------------------------------
 
@@ -631,24 +632,10 @@ module Exa
 
         def render_response(response, json:, collection_accessor: nil)
           payload = serializable(response)
-          if json
-            say JSON.pretty_generate(payload)
-            return
-          end
-
           collection = extract_collection(response, payload, collection_accessor)
-          if collection
-            if collection.empty?
-              say "No results."
-            else
-              collection.each_with_index do |item, index|
-                say format_collection_entry(item, index)
-              end
-            end
-            return
-          end
-
-          say format_single_entry(payload)
+          formatter_name = determine_format(json)
+          formatter = Exa::CLI::Formatters.for(formatter_name)
+          formatter.render(cli: self, payload: payload, collection: collection)
         end
 
         def render_stream(stream, json:)
@@ -800,3 +787,8 @@ module Exa
     end
   end
 end
+        def determine_format(json_requested)
+          return "json" if json_requested
+          value = options[:format]
+          value.nil? ? "table" : value.to_s.downcase
+        end

data/lib/exa/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai-ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Vicente Reig Rincon de Arellano
@@ -193,6 +193,7 @@ files:
 - lib/exa/cli.rb
 - lib/exa/cli/account_resolver.rb
 - lib/exa/cli/config_store.rb
+- lib/exa/cli/formatters.rb
 - lib/exa/cli/root.rb
 - lib/exa/client.rb
 - lib/exa/errors.rb