feat(credential_store): add GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND env var

.changeset/fix-keyring-fallback.md

@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": minor
+---
+
+Add `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` env var for explicit keyring backend selection (`keyring` or `file`). Fixes credential key loss in Docker/keyring-less environments by never deleting `.encryption_key` and always persisting it as a fallback.

AGENTS.md

@@ -171,7 +171,8 @@ Use these labels to categorize pull requests and issues:
 | Variable | Description |
 |---|---|
 | `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth2 access token (highest priority; bypasses all credential file loading) |
-| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to OAuth credentials JSON (no default; if unset, falls back to credentials secured by the OS Keyring and encrypted in `~/.config/gws/`) |
+| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to OAuth credentials JSON (no default; if unset, falls back to encrypted credentials in `~/.config/gws/`) |
+| `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` | Keyring backend: `keyring` (default, uses OS keyring with file fallback) or `file` (file only, for Docker/CI/headless) |
 
 | `GOOGLE_APPLICATION_CREDENTIALS` | Standard Google ADC path; used as fallback when no gws-specific credentials are configured |
 

Cargo.toml

@@ -56,6 +56,7 @@ keyring = "3.6.3"
 async-trait = "0.1.89"
 serde_yaml = "0.9.34"
 percent-encoding = "2.3.2"
+zeroize = { version = "1.8.2", features = ["derive"] }
 
 
 # The profile that 'cargo dist' will build with

README.md

@@ -115,7 +115,7 @@ The CLI supports multiple auth workflows so it works on your laptop, in CI, and
 
 ### Interactive (local desktop)
 
-Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring.
+Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring (or `~/.config/gws/.encryption_key` when `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file`).
 
 ```bash
 gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in

skills/gws-gmail-forward/SKILL.md

@@ -44,6 +44,7 @@ gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com --cc eve@examp
 ## Tips
 
 - Includes the original message with sender, date, subject, and recipients.
+- Sends the forward as a new message rather than forcing it into the original thread.
 
 ## See Also
 

src/auth_commands.rs

@@ -359,7 +359,7 @@ async fn handle_login(args: &[String]) -> Result<(), GwsError> {
             "message": "Authentication successful. Encrypted credentials saved.",
             "account": actual_email.as_deref().unwrap_or("(unknown)"),
             "credentials_file": enc_path.display().to_string(),
-            "encryption": "AES-256-GCM (key secured by OS Keyring or local `.encryption_key`)",
+            "encryption": "AES-256-GCM (key in OS keyring or local `.encryption_key`; set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file for headless)",
             "scopes": scopes,
         });
         println!(
@@ -944,6 +944,7 @@ async fn handle_status() -> Result<(), GwsError> {
     let mut output = json!({
         "auth_method": auth_method,
         "storage": storage,
+        "keyring_backend": credential_store::active_backend_name(),
         "encrypted_credentials": enc_path.display().to_string(),
         "encrypted_credentials_exists": has_encrypted,
         "plain_credentials": plain_path.display().to_string(),