Add dual filtering with --fields (server-side) and --jq (client-side) flags

Author: ilyazub

Cargo.lock

@@ -22,6 +22,10 @@ serde_json = "1.0"
 serpapi = { version = "0.1.0", git = "https://github.com/serpapi/serpapi-rust.git", rev = "e65463152538433885fc1a4c66c8cd416a676715" }
 tokio = { version = "1.35", features = ["full"] }
 toml = "0.8"
+jaq-core = "1.2.1"
+jaq-interpret = "1.2.1"
+jaq-parse = "1.0.2"
+jaq-std = "1.2.1"
 
 [package.metadata.docs.rs]
 targets = []

Cargo.toml

@@ -41,8 +41,14 @@ Perform a search with any supported SerpApi engine.
 # Basic search
 serpapi --json search engine=google q=coffee
 
-# With server-side field filtering (reduces token usage for AI agents)
-serpapi --json --jq "organic_results[].{title,link}" search engine=google q=coffee
+# With server-side field filtering (reduces response size at API level)
+serpapi --json --fields "organic_results[].{title,link}" search engine=google q=coffee
+
+# With client-side jq filtering (like gh --jq)
+serpapi --json --jq ".organic_results[0:3] | [.[] | {title, link}]" search engine=google q=coffee
+
+# Both: server-side reduces payload, then client-side refines
+serpapi --json --fields "organic_results" --jq ".organic_results[0:3] | [.[] | {title, link}]" search engine=google q=coffee
 
 # Multiple parameters
 serpapi --json search engine=google q="coffee shops" location="Austin,TX"
@@ -84,7 +90,8 @@ serpapi login
 ## Global Flags
 
 - `--json` — Clean JSON output (no ANSI colors, for AI agents and pipelines)
-- `--jq <expr>` — Server-side field filtering (maps to SerpApi's `json_restrictor` parameter)
+- `--fields <expr>` — Server-side field filtering (maps to SerpApi's `json_restrictor` parameter)
+- `--jq <expr>` — Client-side jq filter applied to JSON output (same as `gh --jq`)
 - `--api-key <key>` — Override API key (takes priority over environment and config file)
 
 **⚠️ Important: Flag Position**
@@ -94,7 +101,7 @@ Global flags must come **BEFORE** the subcommand, not after:
 ```bash
 # ✅ Correct
 serpapi --json account
-serpapi --json --jq "organic_results[0:3]" search engine=google q=coffee
+serpapi --json --jq ".organic_results[0:3]" search engine=google q=coffee
 
 # ❌ Incorrect (will fail with "unexpected argument")
 serpapi account --json
@@ -124,10 +131,17 @@ api_key = "your_serpapi_key_here"
 This CLI is optimized for consumption by AI agents (OpenClaw, Claude Code, Codex, etc.):
 
 - **Use `--json` flag** for clean, parseable JSON output (no ANSI colors or formatting)
-- **Use `--jq` for server-side filtering** to reduce token usage:
-  - Example: `--jq "organic_results[0:3]"` returns only first 3 results
+- **Use `--fields` for server-side filtering** to reduce token usage:
+  - Example: `--fields "organic_results[0:3]"` returns only first 3 results
   - Filtering happens at the API level, saving bandwidth and context window tokens
-  - Syntax follows JSONPath expressions
+  - Syntax follows SerpApi's `json_restrictor` parameter
+- **Use `--jq` for client-side filtering** (same as `gh --jq`):
+  - Example: `--jq ".organic_results | length"` counts results locally
+  - Full jq expression support: pipes, array slicing, object construction, `select`, `map`, etc.
+  - Runs after API response is received
+- **Combine both** for maximum efficiency:
+  - `--fields` reduces the API response size (less bandwidth)
+  - `--jq` refines the result further (less context window tokens)
 - **Exit codes**:
   - `0` = success
   - `1` = API error (invalid key, rate limit, etc.)

README.md

@@ -1,22 +1,16 @@
 use crate::error::CliError;
-use crate::output;
 use serde_json::Value;
 use serpapi::Client;
 use std::collections::HashMap;
 
-pub async fn run(api_key: &str, json_mode: bool) -> Result<(), CliError> {
-    // Create client with API key
+pub async fn run(api_key: &str) -> Result<Value, CliError> {
     let mut client_params = HashMap::new();
     client_params.insert("api_key".to_string(), api_key.to_string());
     let client = Client::new(client_params);
-    
-    // Call account API
     let result = client.account(&()).await
         .map_err(|e| CliError::NetworkError {
             message: format!("Network error: {}", e),
         })?;
-    
-    // Check for error in response
     if let Value::Object(ref map) = result {
         if let Some(error_val) = map.get("error") {
             let error_msg = error_val.as_str()
@@ -27,11 +21,5 @@ pub async fn run(api_key: &str, json_mode: bool) -> Result<(), CliError> {
             });
         }
     }
-    
-    // Output result
-    output::print_json(&result, json_mode)
-        .map_err(|e| CliError::ApiError {
-            message: format!("Output error: {}", e),
-        })?;
-    Ok(())
+    Ok(result)
 }

src/commands/account.rs

@@ -1,22 +1,16 @@
 use crate::error::CliError;
-use crate::output;
 use serde_json::Value;
 use serpapi::Client;
 use std::collections::HashMap;
 
-pub async fn run(id: &str, api_key: &str, json_mode: bool) -> Result<(), CliError> {
-    // Create client with API key
+pub async fn run(id: &str, api_key: &str) -> Result<Value, CliError> {
     let mut client_params = HashMap::new();
     client_params.insert("api_key".to_string(), api_key.to_string());
     let client = Client::new(client_params);
-    
-    // Call search_archive API
     let result = client.search_archive(id).await
         .map_err(|e| CliError::NetworkError {
             message: format!("Network error: {}", e),
         })?;
-    
-    // Check for error in response
     if let Value::Object(ref map) = result {
         if let Some(error_val) = map.get("error") {
             let error_msg = error_val.as_str()
@@ -27,10 +21,5 @@ pub async fn run(id: &str, api_key: &str, json_mode: bool) -> Result<(), CliErro
             });
         }
     }
-    
-    // Output result
-    output::print_json(&result, json_mode).map_err(|e| CliError::ApiError {
-        message: format!("Output error: {}", e),
-    })?;
-    Ok(())
+    Ok(result)
 }

src/commands/archive.rs

@@ -1,24 +1,16 @@
 use crate::error::CliError;
-use crate::output;
 use crate::params::{self, Param};
 use serde_json::Value;
 use serpapi::Client;
 use std::collections::HashMap;
 
-pub async fn run(params: Vec<Param>, json_mode: bool) -> Result<(), CliError> {
-    // Build params HashMap
+pub async fn run(params: Vec<Param>) -> Result<Value, CliError> {
     let params_map = params::params_to_hashmap(&params);
-    
-    // Create client (no API key needed for locations)
     let client = Client::new(HashMap::<String, String>::new());
-    
-    // Call locations API
     let result = client.location(params_map).await
         .map_err(|e| CliError::NetworkError {
             message: format!("Network error: {}", e),
         })?;
-    
-    // Check for error in response
     if let Value::Object(ref map) = result {
         if let Some(error_val) = map.get("error") {
             let error_msg = error_val.as_str()
@@ -29,11 +21,5 @@ pub async fn run(params: Vec<Param>, json_mode: bool) -> Result<(), CliError> {
             });
         }
     }
-    
-    // Output result
-    output::print_json(&result, json_mode)
-        .map_err(|e| CliError::ApiError {
-            message: format!("Output error: {}", e),
-        })?;
-    Ok(())
+    Ok(result)
 }

src/commands/locations.rs

@@ -1,5 +1,4 @@
 use crate::error::CliError;
-use crate::output;
 use crate::params::{self, Param};
 use serde_json::Value;
 use serpapi::Client;
@@ -8,29 +7,19 @@ use std::collections::HashMap;
 pub async fn run(
     params: Vec<Param>,
     api_key: &str,
-    json_mode: bool,
-    jq: Option<&str>,
-) -> Result<(), CliError> {
-    // 1. Build params HashMap using params::params_to_hashmap
+    fields: Option<&str>,
+) -> Result<Value, CliError> {
     let mut params_map = params::params_to_hashmap(&params);
-    
-    // 2. Apply --jq if provided (inserts json_restrictor parameter)
-    if let Some(jq_expr) = jq {
-        params::apply_jq(&mut params_map, Some(jq_expr));
+    if let Some(expr) = fields {
+        params::apply_fields(&mut params_map, Some(expr));
     }
-    
-    // 3. Create serpapi Client with API key
     let mut client_params = HashMap::new();
     client_params.insert("api_key".to_string(), api_key.to_string());
     let client = Client::new(client_params);
-    
-    // 4. Call client.search(params).await
     let result = client.search(params_map).await
         .map_err(|e| CliError::NetworkError {
             message: format!("Network error: {}", e),
         })?;
-    
-    // 5. Check for "error" key in response JSON
     if let Value::Object(ref map) = result {
         if let Some(error_val) = map.get("error") {
             let error_msg = error_val.as_str()
@@ -41,10 +30,5 @@ pub async fn run(
             });
         }
     }
-    
-    // 6. Output result via output module
-    output::print_json(&result, json_mode).map_err(|e| CliError::ApiError {
-        message: format!("Output error: {}", e),
-    })?;
-    Ok(())
+    Ok(result)
 }

src/commands/search.rs

@@ -0,0 +1,35 @@
+use jaq_interpret::{Ctx, FilterT, ParseCtx, RcIter, Val};
+use serde_json::Value;
+
+pub fn apply(expression: &str, input: &Value) -> Result<Value, Box<dyn std::error::Error>> {
+    let mut defs = ParseCtx::new(Vec::new());
+    defs.insert_natives(jaq_core::core());
+    defs.insert_defs(jaq_std::std());
+
+    let (filter, errs) = jaq_parse::parse(expression, jaq_parse::main());
+    if !errs.is_empty() {
+        return Err(format!("jq parse error: {:?}", errs).into());
+    }
+
+    let filter = match filter {
+        Some(f) => f,
+        None => return Err("jq parse error: empty filter".into()),
+    };
+
+    let filter = defs.compile(filter);
+    if !defs.errs.is_empty() {
+        return Err(format!("jq compile error: {} error(s)", defs.errs.len()).into());
+    }
+
+    let inputs = RcIter::new(core::iter::empty());
+    let out: Vec<Value> = filter
+        .run((Ctx::new(Vec::new(), &inputs), Val::from(input.clone())))
+        .map(|v| v.map(Value::from).map_err(|e| format!("jq error: {:?}", e)))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    match out.len() {
+        0 => Ok(Value::Null),
+        1 => Ok(out.into_iter().next().unwrap()),
+        _ => Ok(Value::Array(out)),
+    }
+}

src/jq.rs

@@ -2,3 +2,4 @@ pub mod config;
 pub mod error;
 pub mod output;
 pub mod params;
+pub mod jq;

src/lib.rs

@@ -6,6 +6,7 @@ mod output;
 mod error;
 mod config;
 mod params;
+mod jq;
 
 #[derive(Parser, Debug)]
 #[command(
@@ -21,6 +22,11 @@ struct Cli {
     #[arg(long)]
     json: bool,
 
+    /// Server-side field filtering (SerpApi json_restrictor parameter)
+    #[arg(long)]
+    fields: Option<String>,
+
+    /// Client-side jq filter applied to JSON output (like gh --jq)
     #[arg(long)]
     jq: Option<String>,
 
@@ -48,7 +54,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let cli = Cli::parse();
     let json_mode = cli.json;
 
-    match cli.command {
+    let result = match cli.command {
         Command::Search { params } => {
             let api_key = config::resolve_api_key(
                 cli.api_key.as_deref(),
@@ -57,47 +63,55 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             let parsed_params = params.iter()
                 .map(|s| params::Param::from_str(s))
                 .collect::<Result<Vec<_>, _>>()?;
-            if let Err(e) = commands::search::run(parsed_params, &api_key, json_mode, cli.jq.as_deref()).await {
-                error::print_error(&e);
-                std::process::exit(error::exit_code(&e));
-            }
+            commands::search::run(parsed_params, &api_key, cli.fields.as_deref()).await
         },
         Command::Account => {
             let api_key = config::resolve_api_key(
                 cli.api_key.as_deref(),
                 std::env::var("SERPAPI_KEY").ok().as_deref()
             )?;
-            if let Err(e) = commands::account::run(&api_key, json_mode).await {
-                error::print_error(&e);
-                std::process::exit(error::exit_code(&e));
-            }
+            commands::account::run(&api_key).await
         },
         Command::Locations { params } => {
             let parsed_params = params.iter()
                 .map(|s| params::Param::from_str(s))
                 .collect::<Result<Vec<_>, _>>()?;
-            if let Err(e) = commands::locations::run(parsed_params, json_mode).await {
-                error::print_error(&e);
-                std::process::exit(error::exit_code(&e));
-            }
+            commands::locations::run(parsed_params).await
         },
         Command::Archive { id } => {
             let api_key = config::resolve_api_key(
                 cli.api_key.as_deref(),
                 std::env::var("SERPAPI_KEY").ok().as_deref()
             )?;
-            if let Err(e) = commands::archive::run(&id, &api_key, json_mode).await {
-                error::print_error(&e);
-                std::process::exit(error::exit_code(&e));
-            }
+            commands::archive::run(&id, &api_key).await
         },
         Command::Login => {
             if let Err(e) = commands::login::run().await {
                 error::print_error(&e);
                 std::process::exit(error::exit_code(&e));
             }
+            return Ok(());
         },
-    }
+    };
 
+    match result {
+        Ok(value) => {
+            let filtered = match cli.jq.as_deref() {
+                Some(expr) => jq::apply(expr, &value)?,
+                None => value,
+            };
+            output::print_json(&filtered, json_mode).map_err(|e| {
+                let err = error::CliError::ApiError {
+                    message: format!("Output error: {}", e),
+                };
+                error::print_error(&err);
+                std::process::exit(error::exit_code(&err));
+            }).ok();
+        }
+        Err(e) => {
+            error::print_error(&e);
+            std::process::exit(error::exit_code(&e));
+        }
+    }
     Ok(())
 }