feat(filter): add --jq global flag for jq-style output filtering

Cargo.toml

@@ -158,6 +158,9 @@ serde-wasm-bindgen = { version = "0.6", optional = true }
 # RNG support in browser WASM (getrandom 0.4 — wasm_js feature enables JS crypto API)
 getrandom = { version = "0.4", features = ["wasm_js"], optional = true }
 jsonschema = { version = "0.46.5", default-features = false }
+jaq-core = "3.1.0"
+jaq-std = "3.0.1"
+jaq-json = { version = "2.0.1", features = ["serde"] }
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 reqwest = { version = ">=0.13, <0.13.3", features = ["stream"] }

docs/COMMANDS.md

@@ -219,11 +219,52 @@ Available on all commands:
 --config string      Config file path (default: ~/.config/pup/config.yaml)
 --site string        Datadog site (default: datadoghq.com)
 --output string      Output format: json, yaml, table (default: json)
+--jq string          Filter/transform output with a jq expression (applied before formatting)
 --verbose            Enable verbose logging
 --yes                Skip confirmation prompts
 --read-only          Block all write operations (create, update, delete)
 ```
 
+### `--jq` filtering
+
+`--jq` applies a [jq](https://jqlang.github.io/jq/) expression to the raw JSON response
+**before** output formatting, so it works with every `-o` format:
+
+```bash
+# Extract a single field across all monitors
+pup monitors list --jq '.[].name'
+
+# Select matching records and then format as a table
+pup monitors list --jq '.[] | select(.name | endswith("prod"))' -o table
+
+# Compose with other jq features
+pup logs search --query="status:error" --jq '.data | length'
+```
+
+**Cardinality:** the jq expression may produce a stream of values.
+- 0 outputs → `null`
+- 1 output → the value (unwrapped)
+- 2+ outputs → an array
+
+**Agent mode — filter target:** `--jq` runs on the **raw response payload**, which
+is the value that appears under `.data` in agent mode. Write expressions against the
+payload (e.g. `.[]`), **not** against the envelope (`.data[]` will not work):
+
+```bash
+# correct — targets the payload array
+pup monitors list --agent --jq '.[0]'
+
+# wrong — .data does not exist in the payload --jq sees
+pup monitors list --agent --jq '.data[0]'
+```
+
+**Agent mode — metadata:** when `--jq` is active, `metadata.count` and
+`metadata.truncated` are omitted from the envelope because they describe the
+pre-filter data, not the filtered result.
+
+**Limitation:** commands that print output directly (e.g. `pup auth login`, some runbook
+steps) bypass `format_and_print` and do not honor `--jq`.
+
 ## Recent Enhancements
 
 ### v0.64.x — Error Tracking Issue Filters (SDK PRs #1568, #1480)

src/api.rs

@@ -135,6 +135,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -170,6 +171,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -209,6 +211,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -243,6 +246,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -277,6 +281,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -311,6 +316,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -344,6 +350,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -378,6 +385,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -410,6 +418,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let result = super::get(&cfg, "/api/v1/test", &[]).await;
@@ -438,6 +447,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server
@@ -472,6 +482,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         };
 
         let mock = server

src/client.rs

@@ -1117,6 +1117,7 @@ mod tests {
             auto_approve: false,
             agent_mode: false,
             read_only: false,
+            jq: None,
         }
     }
 

src/commands/alias.rs

@@ -45,7 +45,13 @@ pub fn list(cfg: &crate::config::Config) -> Result<()> {
                 .iter()
                 .map(|(name, command)| serde_json::json!({"name": name, "command": command}))
                 .collect();
-            crate::formatter::format_and_print(&items, &cfg.output_format, cfg.agent_mode, None)?;
+            crate::formatter::format_and_print(
+                &items,
+                &cfg.output_format,
+                cfg.agent_mode,
+                None,
+                cfg.jq.as_deref(),
+            )?;
         }
     }
     Ok(())