fix(cli): warn when env gateway overrides selection

Closes #1206

Warn when gateway select saves a new active gateway while OPENSHELL_GATEWAY is set to a different value, and document the override precedence.

Signed-off-by: John Myers <9696606+johntmyers@users.noreply.github.com>

Author: johntmyers

crates/openshell-cli/src/run.rs

@@ -766,9 +766,23 @@ pub fn gateway_use(name: &str) -> Result<()> {
 
     save_active_gateway(name)?;
     eprintln!("{} Active gateway set to '{name}'", "✓".green().bold());
+    if let Some(warning) = gateway_env_override_warning(name) {
+        eprintln!("{} {warning}", "⚠".yellow().bold());
+    }
     Ok(())
 }
 
+fn gateway_env_override_warning(selected_name: &str) -> Option<String> {
+    let env_name = std::env::var("OPENSHELL_GATEWAY").ok()?;
+    if env_name.is_empty() || env_name == selected_name {
+        return None;
+    }
+
+    Some(format!(
+        "OPENSHELL_GATEWAY={env_name} is set and will override this selection.\n  Unset it or run: export OPENSHELL_GATEWAY={selected_name}"
+    ))
+}
+
 pub fn gateway_select(name: Option<&str>, gateway_flag: &Option<String>) -> Result<()> {
     let interactive = std::io::stdin().is_terminal() && std::io::stdout().is_terminal();
     gateway_select_with(name, gateway_flag, interactive, |gateways, default| {
@@ -5971,8 +5985,8 @@ mod tests {
     use super::{
         GatewayControlTarget, TlsOptions, dockerfile_sources_supported_for_gateway,
         format_gateway_select_header, format_gateway_select_items, gateway_add, gateway_auth_label,
-        gateway_select_with, gateway_type_label, git_sync_files, http_health_check,
-        image_requests_gpu, inferred_provider_type, parse_cli_setting_value,
+        gateway_env_override_warning, gateway_select_with, gateway_type_label, git_sync_files,
+        http_health_check, image_requests_gpu, inferred_provider_type, parse_cli_setting_value,
         parse_credential_pairs, plaintext_gateway_is_remote, provisioning_timeout_message,
         ready_false_condition_message, resolve_from, resolve_gateway_control_target_from,
         sandbox_should_persist, shell_escape, source_requests_gpu, validate_gateway_name,
@@ -6514,6 +6528,35 @@ mod tests {
         });
     }
 
+    #[test]
+    fn gateway_env_override_warning_mentions_masked_selection() {
+        let _guard = TEST_ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let _env = EnvVarGuard::set("OPENSHELL_GATEWAY", "openshell");
+
+        let warning = gateway_env_override_warning("docker-dev").expect("env override should warn");
+
+        assert!(
+            warning.contains("OPENSHELL_GATEWAY=openshell"),
+            "warning should name the overriding env var: {warning}"
+        );
+        assert!(
+            warning.contains("export OPENSHELL_GATEWAY=docker-dev"),
+            "warning should suggest updating the env var: {warning}"
+        );
+    }
+
+    #[test]
+    fn gateway_env_override_warning_skips_matching_gateway() {
+        let _guard = TEST_ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let _env = EnvVarGuard::set("OPENSHELL_GATEWAY", "docker-dev");
+
+        assert_eq!(gateway_env_override_warning("docker-dev"), None);
+    }
+
     #[test]
     fn gateway_select_prefers_active_gateway_as_default_choice() {
         let tmpdir = tempfile::tempdir().expect("create tmpdir");

docs/sandboxes/manage-gateways.mdx

@@ -158,6 +158,8 @@ For direct mTLS endpoints, place the CLI client certificate bundle in the gatewa
 
 One gateway is always the active gateway. All CLI commands target it by default. `gateway add` sets the new gateway as active.
 
+The active gateway is the persisted default. The `-g` flag and the `OPENSHELL_GATEWAY` environment variable override it when commands resolve a gateway. If `OPENSHELL_GATEWAY` is set to a different gateway, `openshell gateway select <name>` still saves the new default and warns that the current shell will keep using the environment value until you unset or update it.
+
 List all registered gateways:
 
 ```shell