From 6121656c641c3677f4d5255340dd0fe25a695c6a Mon Sep 17 00:00:00 2001
From: Anshul Garg <anshulgarg.garg509@gmail.com>
Date: Fri, 13 Mar 2026 02:32:40 +0530
Subject: [PATCH] fix: gws auth setup --help prints usage instead of running
 wizard

Previously, `gws auth setup --help` would start the setup wizard
(and fail if gcloud was not installed). Now it early-returns with
a usage message before any side effects.

Adds tests to verify --help, -h, and --help combined with other
flags all return Ok without starting the wizard.
---
 .changeset/fix-auth-setup-help.md |  5 +++++
 src/setup.rs                      | 35 +++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 .changeset/fix-auth-setup-help.md

diff --git a/.changeset/fix-auth-setup-help.md b/.changeset/fix-auth-setup-help.md
new file mode 100644
index 00000000..73dfa09a
--- /dev/null
+++ b/.changeset/fix-auth-setup-help.md
@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+fix: `gws auth setup --help` now prints usage instead of running the setup wizard
diff --git a/src/setup.rs b/src/setup.rs
index 10aebe1b..d6b70ffc 100644
--- a/src/setup.rs
+++ b/src/setup.rs
@@ -1598,6 +1598,21 @@ fn prompt_login_after_setup() -> Result<bool, GwsError> {
 
 /// Run the full setup flow. Orchestrates all steps and outputs JSON summary.
 pub async fn run_setup(args: &[String]) -> Result<(), GwsError> {
+    // Early-return for --help/-h so we never start the wizard or check for gcloud.
+    if args.iter().any(|a| a == "--help" || a == "-h") {
+        println!(
+            "Usage: gws auth setup [options]\n\n\
+             Configure a GCP project, enable Workspace APIs, and create OAuth\n\
+             credentials — all in one guided wizard.\n\n\
+             Options:\n\
+             \x20 --project <ID>  Use an existing GCP project instead of creating one\n\
+             \x20 --dry-run       Show what would be done without making changes\n\
+             \x20 --login         Run `gws auth login` after successful setup\n\
+             \x20 -h, --help      Show this help message"
+        );
+        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;
@@ -2312,4 +2327,24 @@ mod tests {
             assert_eq!(bin, "gcloud");
         }
     }
+
+    #[tokio::test]
+    async fn run_setup_help_flag_returns_ok_without_starting_wizard() {
+        // --help should print usage and return Ok without requiring gcloud.
+        let result = run_setup(&["--help".to_string()]).await;
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn run_setup_short_help_flag_returns_ok() {
+        let result = run_setup(&["-h".to_string()]).await;
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn run_setup_help_with_other_args_returns_ok() {
+        // --help should take priority even when combined with other flags.
+        let result = run_setup(&["--project".to_string(), "my-proj".to_string(), "--help".to_string()]).await;
+        assert!(result.is_ok());
+    }
 }