feat(http): add --verbose / -v flag for request/response diagnostics

.changeset/verbose-flag.md

@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": minor
+---
+
+Add `--verbose` / `-v` flag to print HTTP request method, URL, response status, and timing to stderr for debugging

Cargo.toml

@@ -63,6 +63,7 @@ zeroize = { version = "1.8.2", features = ["derive"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
 tracing-appender = "0.2"
+url = "2"
 
 [target.'cfg(target_os = "macos")'.dependencies]
 keyring = { version = "3.6.3", features = ["apple-native"] }

src/commands.rs

@@ -46,6 +46,14 @@ pub fn build_cli(doc: &RestDescription) -> Command {
                 .help("Output format: json (default), table, yaml, csv")
                 .value_name("FORMAT")
                 .global(true),
+        )
+        .arg(
+            clap::Arg::new("verbose")
+                .long("verbose")
+                .short('v')
+                .help("Print request and response details to stderr (method, URL, status, timing)")
+                .action(clap::ArgAction::SetTrue)
+                .global(true),
         );
 
     // Inject helper commands
@@ -279,4 +287,19 @@ mod tests {
             "--sanitize arg should be present on root command"
         );
     }
+
+    #[test]
+    fn test_verbose_arg_present_and_global() {
+        let doc = make_doc();
+        let cmd = build_cli(&doc);
+
+        let args: Vec<_> = cmd.get_arguments().collect();
+        let verbose_arg = args.iter().find(|a| a.get_id() == "verbose");
+        assert!(
+            verbose_arg.is_some(),
+            "--verbose arg should be present on root command"
+        );
+        let verbose_arg = verbose_arg.unwrap();
+        assert!(verbose_arg.is_global_set(), "--verbose should be global");
+    }
 }

src/executor.rs

@@ -364,6 +364,14 @@ async fn handle_binary_response(
 /// 5. Handling various response types (JSON, binary).
 /// 6. Auto-pagination for list endpoints.
 /// 7. Model Armor prompt injection scanning.
+///
+/// # Stdout / stderr contract
+///
+/// * **stdout** — all structured output: JSON responses, dry-run previews,
+///   download summaries. Must remain machine-readable so that pipes like
+///   `gws ... | jq` work correctly.
+/// * **stderr** — all human-readable diagnostics: hints, warnings, verbose
+///   request/response details. Never emitted to stdout.
 #[allow(clippy::too_many_arguments)]
 pub async fn execute_method(
     doc: &RestDescription,
@@ -376,6 +384,7 @@ pub async fn execute_method(
     upload_path: Option<&str>,
     upload_content_type: Option<&str>,
     dry_run: bool,
+    verbose: bool,
     pagination: &PaginationConfig,
     sanitize_template: Option<&str>,
     sanitize_mode: &crate::helpers::modelarmor::SanitizeMode,
@@ -408,6 +417,10 @@ pub async fn execute_method(
     let mut captured_values = Vec::new();
 
     loop {
+        if verbose && pages_fetched > 0 {
+            eprintln!("[page {}]", pages_fetched + 1);
+        }
+
         let client = crate::client::build_client()?;
         let request = build_http_request(
             &client,
@@ -423,11 +436,31 @@ pub async fn execute_method(
         .await?;
 
         let method_id = method.id.as_deref().unwrap_or("unknown");
+        if verbose {
+            let display_url = {
+                let mut params = input.query_params.clone();
+                if let Some(pt) = page_token.as_deref() {
+                    params.push(("pageToken".to_string(), pt.to_string()));
+                }
+                if params.is_empty() {
+                    input.full_url.clone()
+                } else {
+                    let qs = url::form_urlencoded::Serializer::new(String::new())
+                        .extend_pairs(&params)
+                        .finish();
+                    format!("{}?{}", input.full_url, qs)
+                }
+            };
+            eprintln!("> {} {}", method.http_method, display_url);
+        }
         let start = std::time::Instant::now();
         let response = request.send().await.context("HTTP request failed")?;
         let latency_ms = start.elapsed().as_millis() as u64;
 
         let status = response.status();
+        if verbose {
+            eprintln!("< {} ({}ms)", status, latency_ms);
+        }
         let content_type = response
             .headers()
             .get("content-type")
@@ -2026,6 +2059,7 @@ async fn test_execute_method_dry_run() {
         None,
         None,
         true, // dry_run
+        false,
         &pagination,
         None,
         &sanitize_mode,
@@ -2070,6 +2104,7 @@ async fn test_execute_method_missing_path_param() {
         None,
         None,
         true,
+        false,
         &PaginationConfig::default(),
         None,
         &sanitize_mode,

src/helpers/calendar.rs

@@ -181,6 +181,7 @@ TIPS:
                     None,
                     None,
                     matches.get_flag("dry-run"),
+                    matches.get_flag("verbose"),
                     &executor::PaginationConfig::default(),
                     None,
                     &crate::helpers::modelarmor::SanitizeMode::Warn,

src/helpers/chat.rs

@@ -111,6 +111,7 @@ TIPS:
                     None,
                     None,
                     matches.get_flag("dry-run"),
+                    matches.get_flag("verbose"),
                     &pagination,
                     None,
                     &crate::helpers::modelarmor::SanitizeMode::Warn,

src/helpers/docs.rs

@@ -101,6 +101,7 @@ TIPS:
                     None,
                     None,
                     matches.get_flag("dry-run"),
+                    matches.get_flag("verbose"),
                     &pagination,
                     None,
                     &crate::helpers::modelarmor::SanitizeMode::Warn,

src/helpers/drive.rs

@@ -112,6 +112,7 @@ TIPS:
                     Some(file_path),
                     None,
                     matches.get_flag("dry-run"),
+                    matches.get_flag("verbose"),
                     &executor::PaginationConfig::default(),
                     None,
                     &crate::helpers::modelarmor::SanitizeMode::Warn,

src/helpers/gmail/mod.rs

@@ -674,6 +674,7 @@ pub(super) async fn send_raw_email(
         None,
         None,
         matches.get_flag("dry-run"),
+        matches.get_flag("verbose"),
         &pagination,
         None,
         &crate::helpers::modelarmor::SanitizeMode::Warn,

src/helpers/script.rs

@@ -124,6 +124,7 @@ TIPS:
                     None,
                     None,
                     matches.get_flag("dry-run"),
+                    matches.get_flag("verbose"),
                     &executor::PaginationConfig::default(),
                     None,
                     &crate::helpers::modelarmor::SanitizeMode::Warn,

src/helpers/sheets.rs

@@ -138,6 +138,7 @@ TIPS:
                     None,
                     None,
                     matches.get_flag("dry-run"),
+                    matches.get_flag("verbose"),
                     &pagination,
                     None,
                     &crate::helpers::modelarmor::SanitizeMode::Warn,
@@ -181,6 +182,7 @@ TIPS:
                     None,
                     None,
                     matches.get_flag("dry-run"),
+                    matches.get_flag("verbose"),
                     &executor::PaginationConfig::default(),
                     None,
                     &crate::helpers::modelarmor::SanitizeMode::Warn,

src/main.rs

@@ -228,6 +228,7 @@ async fn run() -> Result<(), GwsError> {
         .map(|s| s.as_str());
 
     let dry_run = matched_args.get_flag("dry-run");
+    let verbose = matched_args.get_flag("verbose");
 
     // Build pagination config from flags
     let pagination = parse_pagination_config(matched_args);
@@ -266,6 +267,7 @@ async fn run() -> Result<(), GwsError> {
         upload_path,
         upload_content_type,
         dry_run,
+        verbose,
         &pagination,
         sanitize_config.template.as_deref(),
         &sanitize_config.mode,
@@ -435,6 +437,7 @@ fn print_usage() {
     println!("    --upload-content-type <MIME>  MIME type of the uploaded file (auto-detected from extension if omitted)");
     println!("    --output <PATH>       Output file path for binary responses");
     println!("    --format <FMT>        Output format: json (default), table, yaml, csv");
+    println!("    --verbose / -v        Print request/response details to stderr");
     println!("    --api-version <VER>   Override the API version (e.g., v2, v3)");
     println!("    --page-all            Auto-paginate, one JSON line per page (NDJSON)");
     println!("    --page-limit <N>      Max pages to fetch with --page-all (default: 10)");