feat: rename --project to --gcp-project-id and add usage guidance

airbyte_cdk/cli/airbyte_cdk/_secrets.py

@@ -1,5 +1,16 @@
 # Copyright (c) 2025 Airbyte, Inc., all rights reserved.
-"""Secret management commands."""
+"""Secret management commands.
+
+This module provides commands for managing secrets for Airbyte connectors.
+
+Usage:
+    airbyte-cdk secrets fetch --connector-name source-github
+    airbyte-cdk secrets fetch --connector-directory /path/to/connector
+    airbyte-cdk secrets fetch  # Run from within a connector directory
+
+The 'fetch' command retrieves secrets from Google Secret Manager based on connector
+labels and writes them to the connector's secrets directory.
+"""
 
 import json
 import os
@@ -16,7 +27,18 @@
 
 @click.group(name="secrets")
 def secrets_cli_group() -> None:
-    """Secret management commands."""
+    """Secret management commands.
+
+    This module provides commands for managing secrets for Airbyte connectors.
+
+    Usage:
+        airbyte-cdk secrets fetch --connector-name source-github
+        airbyte-cdk secrets fetch --connector-directory /path/to/connector
+        airbyte-cdk secrets fetch  # Run from within a connector directory
+
+    The 'fetch' command retrieves secrets from Google Secret Manager based on connector
+    labels and writes them to the connector's secrets directory.
+    """
     pass
 
 
@@ -32,15 +54,15 @@ def secrets_cli_group() -> None:
     help="Path to the connector directory.",
 )
 @click.option(
-    "--project",
+    "--gcp-project-id",
     type=str,
     default=AIRBYTE_INTERNAL_GCP_PROJECT,
     help=f"GCP project ID. Defaults to '{AIRBYTE_INTERNAL_GCP_PROJECT}'.",
 )
 def fetch(
     connector_name: Optional[str] = None,
     connector_directory: Optional[Path] = None,
-    project: str = AIRBYTE_INTERNAL_GCP_PROJECT,
+    gcp_project_id: str = AIRBYTE_INTERNAL_GCP_PROJECT,
 ) -> None:
     """Fetch secrets for a connector from Google Secret Manager.
 
@@ -56,7 +78,7 @@ def fetch(
     except ImportError:
         raise ImportError(
             "google-cloud-secret-manager package is required for Secret Manager integration. "
-            "Install it with 'pip install google-cloud-secret-manager'."
+            "Install it with 'pip install airbyte-cdk[dev]' or 'pip install google-cloud-secret-manager'."
         )
 
     click.echo("Fetching secrets...")
@@ -78,7 +100,15 @@ def fetch(
         if not connector_name:
             connector_name = connector_directory.name
     elif connector_name:
-        connector_directory = find_connector_root_from_name(connector_name)
+        try:
+            connector_directory = find_connector_root_from_name(connector_name)
+        except FileNotFoundError as e:
+            raise FileNotFoundError(
+                f"Could not find connector directory for '{connector_name}'. "
+                "Please provide the --connector-directory option with the path to the connector. "
+                "Note: This command requires either running from within a connector directory, "
+                "being in the airbyte monorepo, or explicitly providing the connector directory path."
+            ) from e
     else:
         raise ValueError("Either connector_name or connector_directory must be provided.")
 
@@ -98,7 +128,7 @@ def fetch(
     )
 
     # List all secrets with the connector label
-    parent = f"projects/{project}"
+    parent = f"projects/{gcp_project_id}"
     filter_string = f"labels.{CONNECTOR_LABEL}={connector_name}"
     secrets = client.list_secrets(
         request=secretmanager.ListSecretsRequest(