diff --git a/.changeset/fix-auth-setup-help-flag.md b/.changeset/fix-auth-setup-help-flag.md
new file mode 100644
index 00000000..10a4935e
--- /dev/null
+++ b/.changeset/fix-auth-setup-help-flag.md
@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Handle -h/--help flag in `gws auth setup` to print usage and exit before running setup checks
diff --git a/.changeset/fix-gmail-triage-scope.md b/.changeset/fix-gmail-triage-scope.md
new file mode 100644
index 00000000..c14c6287
--- /dev/null
+++ b/.changeset/fix-gmail-triage-scope.md
@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Fix gmail +triage 403 error by using gmail.readonly scope instead of gmail.modify to avoid conflict with gmail.metadata scope that does not support the q parameter
diff --git a/src/helpers/gmail/mod.rs b/src/helpers/gmail/mod.rs
index b7019d53..da82d1e6 100644
--- a/src/helpers/gmail/mod.rs
+++ b/src/helpers/gmail/mod.rs
@@ -34,6 +34,7 @@ use std::pin::Pin;
 pub struct GmailHelper;
 
 pub(super) const GMAIL_SCOPE: &str = "https://www.googleapis.com/auth/gmail.modify";
+pub(super) const GMAIL_READONLY_SCOPE: &str = "https://www.googleapis.com/auth/gmail.readonly";
 pub(super) const PUBSUB_SCOPE: &str = "https://www.googleapis.com/auth/pubsub";
 
 impl Helper for GmailHelper {
diff --git a/src/helpers/gmail/triage.rs b/src/helpers/gmail/triage.rs
index 6899d4a8..d8adffba 100644
--- a/src/helpers/gmail/triage.rs
+++ b/src/helpers/gmail/triage.rs
@@ -32,8 +32,12 @@ pub async fn handle_triage(matches: &ArgMatches) -> Result<(), GwsError> {
         .map(|s| crate::formatter::OutputFormat::from_str(s))
         .unwrap_or(crate::formatter::OutputFormat::Table);
 
-    // Authenticate
-    let token = auth::get_token(&[GMAIL_SCOPE])
+    // Authenticate — use gmail.readonly instead of gmail.modify because triage
+    // is read-only and the `q` query parameter is not supported under the
+    // gmail.metadata scope.  When a token carries both metadata and modify
+    // scopes the API may resolve to the metadata path and reject `q` with 403.
+    // gmail.readonly always supports `q`.
+    let token = auth::get_token(&[GMAIL_READONLY_SCOPE])
         .await
         .map_err(|e| GwsError::Auth(format!("Gmail auth failed: {e}")))?;
 
diff --git a/src/setup.rs b/src/setup.rs
index a2730ec8..5cbf5dee 100644
--- a/src/setup.rs
+++ b/src/setup.rs
@@ -1431,8 +1431,25 @@ async fn stage_configure_oauth(ctx: &mut SetupContext) -> Result<SetupStage, Gws
     Ok(SetupStage::Finish)
 }
 
+const SETUP_USAGE: &str = concat!(
+    "Usage: gws auth setup [options]\n\n",
+    "Options:\n",
+    "  --project <PROJECT_ID>    Use a specific GCP project\n",
+    "  --dry-run                 Preview setup actions without making changes\n",
+    "  -h, --help                Show this help message\n",
+);
+
+fn is_help_requested(args: &[String]) -> bool {
+    args.iter().any(|arg| arg == "--help" || arg == "-h")
+}
+
 /// Run the full setup flow. Orchestrates all steps and outputs JSON summary.
 pub async fn run_setup(args: &[String]) -> Result<(), GwsError> {
+    if is_help_requested(args) {
+        println!("{SETUP_USAGE}");
+        return Ok(());
+    }
+
     let opts = parse_setup_args(args);
     let dry_run = opts.dry_run;
     let interactive = std::io::IsTerminal::is_terminal(&std::io::stdin()) && !dry_run;
@@ -1678,6 +1695,24 @@ mod tests {
         assert_eq!(opts.project.as_deref(), Some("p"));
     }
 
+    #[test]
+    fn test_is_help_requested_true_for_long_flag() {
+        let args: Vec<String> = vec!["--help".into()];
+        assert!(is_help_requested(&args));
+    }
+
+    #[test]
+    fn test_is_help_requested_true_for_short_flag() {
+        let args: Vec<String> = vec!["--project".into(), "my-project".into(), "-h".into()];
+        assert!(is_help_requested(&args));
+    }
+
+    #[test]
+    fn test_is_help_requested_false_without_help_flags() {
+        let args: Vec<String> = vec!["--project".into(), "my-project".into()];
+        assert!(!is_help_requested(&args));
+    }
+
     // ── Account selection → gcloud action ───────────────────────
 
     #[test]