deepeval 3.4.7__py3-none-any.whl → 3.4.9__py3-none-any.whl

deepeval/cli/main.py

@@ -1,6 +1,24 @@
+"""
+DeepEval CLI: Model Provider Configuration Commands
+
+General behavior for all `set-*` / `unset-*` commands:
+
+- Non-secret settings (model name, endpoint, deployment, toggles) are always
+  persisted in the hidden `.deepeval/.deepeval` JSON store.
+- Secrets (API keys) are **never** written to the JSON store.
+- If `--save=dotenv[:path]` is passed, both secrets and non-secrets are
+  written to the specified dotenv file (default: `.env.local`).
+  Dotenv files should be git-ignored.
+- If `--save` is not passed, only the JSON store is updated.
+- When unsetting a provider, only that provider’s keys are removed.
+  If another provider’s credentials remain (e.g. `OPENAI_API_KEY`), it
+  may still be selected as the default.
+"""
+
 import os
 from typing import Optional
 from rich import print
+from rich.markup import escape
 import webbrowser
 import threading
 import random
@@ -8,6 +26,7 @@ import string
 import socket
 import typer
 from enum import Enum
+from pydantic import SecretStr
 from deepeval.key_handler import (
     KEY_FILE_HANDLER,
     KeyValues,
@@ -17,6 +36,7 @@ from deepeval.key_handler import (
 from deepeval.telemetry import capture_login_event, capture_view_event
 from deepeval.cli.test import app as test_app
 from deepeval.cli.server import start_server
+from deepeval.config.settings import get_settings
 from deepeval.utils import delete_file_if_exists, open_browser
 from deepeval.test_run.test_run import (
     LATEST_TEST_RUN_FILE_PATH,
@@ -26,13 +46,16 @@ from deepeval.cli.utils import (
     render_login_message,
     upload_and_open_link,
     PROD,
-    clear_evaluation_model_keys,
-    clear_embedding_model_keys,
+    resolve_save_target,
+    save_environ_to_store,
+    unset_environ_in_store,
+    switch_model_provider,
 )
 from deepeval.confident.api import (
     get_confident_api_key,
     is_confident,
     set_confident_api_key,
+    CONFIDENT_API_KEY_ENV_VAR,
 )
 
 app = typer.Typer(name="deepeval")
@@ -55,16 +78,58 @@ def find_available_port():
         return s.getsockname()[1]
 
 
+def is_openai_configured() -> bool:
+    s = get_settings()
+    v = s.OPENAI_API_KEY
+    if isinstance(v, SecretStr):
+        try:
+            if v.get_secret_value().strip():
+                return True
+        except Exception:
+            pass
+    elif v and str(v).strip():
+        return True
+    env = os.getenv("OPENAI_API_KEY")
+    return bool(env and env.strip())
+
+
 @app.command(name="set-confident-region")
 def set_confident_region_command(
     region: Regions = typer.Argument(
         ..., help="The data region to use (US or EU)"
-    )
+    ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
     """Set the Confident AI data region."""
     # Add flag emojis based on region
     flag = "🇺🇸" if region == Regions.US else "🇪🇺"
-    KEY_FILE_HANDLER.write_key(KeyValues.CONFIDENT_REGION, region.value)
+
+    setting = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.CONFIDENT_REGION = region.value
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
         f":raising_hands: Congratulations! You're now using the {flag}  {region.value} data region for Confident AI."
     )
@@ -80,13 +145,20 @@ def login(
         None,
         "--confident-api-key",
         "-c",
-        help="Optional confident API key to bypass login.",
+        help="Confident API key (non-interactive). If omitted, you'll be prompted to enter one. In all cases the key is saved to a dotenv file (default: .env.local) unless overridden with --save.",
+    ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Where to persist settings. Format: dotenv[:path]. Defaults to .env.local. If omitted, login still writes to .env.local.",
     ),
 ):
     with capture_login_event() as span:
+        completed = False
         try:
+            # Resolve the key from CLI flag or interactive flow
             if confident_api_key:
-                api_key = confident_api_key
+                key = confident_api_key.strip()
             else:
                 render_login_message()
 
@@ -104,35 +176,93 @@ def login(
                 login_url = f"{PROD}/pair?code={pairing_code}&port={port}"
                 webbrowser.open(login_url)
                 print(
-                    f"(open this link if your browser did not opend: [link={PROD}]{PROD}[/link])"
+                    f"(open this link if your browser did not open: [link={PROD}]{PROD}[/link])"
                 )
+
+                # Manual fallback if still empty
                 if api_key == "":
                     while True:
-                        api_key = input(f"🔐 Enter your API Key: ").strip()
+                        api_key = input("🔐 Enter your API Key: ").strip()
                         if api_key:
                             break
                         else:
                             print(
                                 "❌ API Key cannot be empty. Please try again.\n"
                             )
-
-            set_confident_api_key(api_key)
-            span.set_attribute("completed", True)
-
+                key = api_key.strip()
+
+            settings = get_settings()
+            save = save or settings.DEEPEVAL_DEFAULT_SAVE or "dotenv:.env.local"
+            with settings.edit(save=save) as edit_ctx:
+                settings.API_KEY = key
+                settings.CONFIDENT_API_KEY = key
+
+            handled, path, updated = edit_ctx.result
+
+            if updated:
+                if not handled and save is not None:
+                    # invalid --save format (unsupported)
+                    print(
+                        "Unsupported --save option. Use --save=dotenv[:path]."
+                    )
+                elif path:
+                    # persisted to a file
+                    print(
+                        f"Saved environment variables to {path} (ensure it's git-ignored)."
+                    )
+
+            completed = True
             print(
-                "\n🎉🥳 Congratulations! You've successfully logged in! :raising_hands: "
+                "\n🎉🥳 Congratulations! You've successfully logged in! :raising_hands:"
             )
             print(
-                "You're now using DeepEval with [rgb(106,0,255)]Confident AI[/rgb(106,0,255)]. Follow our quickstart tutorial here: [bold][link=https://www.confident-ai.com/docs/llm-evaluation/quickstart]https://www.confident-ai.com/docs/llm-evaluation/quickstart[/link][/bold]"
+                "You're now using DeepEval with [rgb(106,0,255)]Confident AI[/rgb(106,0,255)]. "
+                "Follow our quickstart tutorial here: "
+                "[bold][link=https://www.confident-ai.com/docs/llm-evaluation/quickstart]"
+                "https://www.confident-ai.com/docs/llm-evaluation/quickstart[/link][/bold]"
             )
-        except:
-            span.set_attribute("completed", False)
+        except Exception as e:
+            completed = False
+            print(f"Login failed: {e}")
+        finally:
+            if getattr(span, "set_attribute", None):
+                span.set_attribute("completed", completed)
 
 
 @app.command()
-def logout():
-    set_confident_api_key(None)
+def logout(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Where to remove the saved key from. Use format dotenv[:path]. If omitted, uses DEEPEVAL_DEFAULT_SAVE or .env.local. The JSON keystore is always cleared.",
+    )
+):
+    """
+    Log out of Confident AI.
+
+    Behavior:
+    - Always clears the Confident API key from the JSON keystore and process env.
+    - Also removes credentials from a dotenv file; defaults to DEEPEVAL_DEFAULT_SAVE if set, otherwise.env.local.
+      Override the target with --save=dotenv[:path].
+    """
+    settings = get_settings()
+    save = save or settings.DEEPEVAL_DEFAULT_SAVE or "dotenv:.env.local"
+    with settings.edit(save=save) as edit_ctx:
+        settings.API_KEY = None
+        settings.CONFIDENT_API_KEY = None
+
+    handled, path, updated = edit_ctx.result
+
+    if updated:
+        if not handled and save is not None:
+            # invalid --save format (unsupported)
+            print("Unsupported --save option. Use --save=dotenv[:path].")
+        elif path:
+            # persisted to a file
+            print(f"Removed Confident AI key(s) from {path}.")
+
     delete_file_if_exists(LATEST_TEST_RUN_FILE_PATH)
+
     print("\n🎉🥳 You've successfully logged out! :raising_hands: ")
 
 
@@ -153,8 +283,22 @@ def view():
 
 
 @app.command(name="enable-grpc-logging")
-def enable_grpc_logging():
-    os.environ["DEEPEVAL_GRPC_LOGGING"] = "1"
+def enable_grpc_logging(save: Optional[str] = None):
+    """
+    Enable verbose gRPC logging for the current process.
+    Pass --save=dotenv[:path] to persist it (optional).
+    """
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.DEEPEVAL_GRPC_LOGGING = True
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    else:
+        print("gRPC logging enabled.")
 
 
 #############################################
@@ -181,37 +325,126 @@ def set_openai_env(
             "REQUIRED if you use a custom/unsupported model."
         ),
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    """Configure OpenAI as the active model.
-
-    Notes:
-    - If `model` is a known OpenAI model, costs can be omitted (built-in pricing will be used).
-    - If `model` is custom/unsupported, you must pass both --cost_per_input_token and --cost_per_output_token.
     """
+    Configure OpenAI as the active LLM provider.
+
+    What this does:
+    - Sets the active provider flag to `USE_OPENAI_MODEL`.
+    - Persists the selected model name and any cost overrides in the JSON store.
+    - secrets are never written to `.deepeval/.deepeval` (JSON).
+
+    Pricing rules:
+    - If `model` is a known OpenAI model, you may omit costs (built‑in pricing is used).
+    - If `model` is custom/unsupported, you must provide both
+      `--cost_per_input_token` and `--cost_per_output_token`.
+
+    Secrets & saving:
+    - Set your `OPENAI_API_KEY` via environment or a dotenv file.
+    - Pass `--save=dotenv[:path]` to write configuration to a dotenv file
+      (default: `.env.local`). This command does not set or persist OPENAI_API_KEY. Set it
+      via your environment or a dotenv file (e.g., add OPENAI_API_KEY=... to .env.local)
+      before running this command, or manage it with whatever command you use for secrets.
+
+    Args:
+        model: OpenAI model name, such as `gpt-4o-mini`.
+        cost_per_input_token: USD per input token (optional for known models).
+        cost_per_output_token: USD per output token (optional for known models).
+        save: Persist config (and supported secrets) to a dotenv file; format `dotenv[:path]`.
+
+    Example:
+        deepeval set-openai \\
+          --model gpt-4o-mini \\
+          --cost_per_input_token 0.0005 \\
+          --cost_per_output_token 0.0015 \\
+          --save dotenv:.env.local
+    """
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_OPENAI_MODEL)
+        settings.OPENAI_MODEL_NAME = model
+        if cost_per_input_token is not None:
+            settings.OPENAI_COST_PER_INPUT_TOKEN = cost_per_input_token
+        if cost_per_output_token is not None:
+            settings.OPENAI_COST_PER_OUTPUT_TOKEN = cost_per_output_token
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Tip: persist these settings to a dotenv file with --save=dotenv[:path] (default .env.local) "
+            "or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
 
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_OPENAI_MODEL, "YES")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.OPENAI_MODEL_NAME, model)
-    KEY_FILE_HANDLER.write_key(
-        ModelKeyValues.OPENAI_COST_PER_INPUT_TOKEN, str(cost_per_input_token)
-    )
-    KEY_FILE_HANDLER.write_key(
-        ModelKeyValues.OPENAI_COST_PER_OUTPUT_TOKEN, str(cost_per_output_token)
-    )
     print(
-        f":raising_hands: Congratulations! You're now using OpenAI's `{model}` for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using OpenAI's `{escape(model)}` for all evals that require an LLM."
     )
 
 
 @app.command(name="unset-openai")
-def unset_openai_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_OPENAI_MODEL)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.OPENAI_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.OPENAI_COST_PER_INPUT_TOKEN)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.OPENAI_COST_PER_OUTPUT_TOKEN)
-    print(
-        ":raising_hands: Congratulations! You're now using default OpenAI settings on DeepEval for all evals that require an LLM."
-    )
+def unset_openai_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the OpenAI related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    """
+    Unset OpenAI as the active provider.
+
+    Behavior:
+    - Removes OpenAI keys (model, costs, toggle) from the JSON store.
+    - If `--save` is provided, removes those keys from the specified dotenv file.
+    - After unsetting, if `OPENAI_API_KEY` is still set in the environment,
+      OpenAI may still be usable by default. Otherwise, no active provider is configured.
+
+    Args:
+        --save: Remove OpenAI keys from the given dotenv file as well.
+
+    Example:
+        deepeval unset-openai --save dotenv:.env.local
+    """
+
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.OPENAI_MODEL_NAME = None
+        settings.OPENAI_COST_PER_INPUT_TOKEN = None
+        settings.OPENAI_COST_PER_OUTPUT_TOKEN = None
+        settings.USE_OPENAI_MODEL = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed OpenAI environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "OpenAI has been unset. No active provider is configured. Set one with the CLI, or add credentials to .env[.local]."
+        )
 
 
 #############################################
@@ -222,7 +455,9 @@ def unset_openai_env():
 @app.command(name="set-azure-openai")
 def set_azure_openai_env(
     azure_openai_api_key: str = typer.Option(
-        ..., "--openai-api-key", help="Azure OpenAI API key"
+        ...,
+        "--openai-api-key",
+        help="Azure OpenAI API key",
     ),
     azure_openai_endpoint: str = typer.Option(
         ..., "--openai-endpoint", help="Azure OpenAI endpoint"
@@ -239,34 +474,43 @@ def set_azure_openai_env(
     azure_model_version: Optional[str] = typer.Option(
         None, "--model-version", help="Azure model version (optional)"
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(
-        ModelKeyValues.AZURE_OPENAI_API_KEY, azure_openai_api_key
-    )
-    KEY_FILE_HANDLER.write_key(
-        ModelKeyValues.AZURE_MODEL_NAME, openai_model_name
-    )
-    KEY_FILE_HANDLER.write_key(
-        ModelKeyValues.AZURE_OPENAI_ENDPOINT, azure_openai_endpoint
-    )
-    KEY_FILE_HANDLER.write_key(
-        ModelKeyValues.OPENAI_API_VERSION, openai_api_version
-    )
-    KEY_FILE_HANDLER.write_key(
-        ModelKeyValues.AZURE_DEPLOYMENT_NAME, azure_deployment_name
-    )
-
-    if azure_model_version is not None:
-        KEY_FILE_HANDLER.write_key(
-            ModelKeyValues.AZURE_MODEL_VERSION, azure_model_version
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_AZURE_OPENAI)
+        settings.AZURE_OPENAI_API_KEY = azure_openai_api_key
+        settings.AZURE_OPENAI_ENDPOINT = azure_openai_endpoint
+        settings.OPENAI_API_VERSION = openai_api_version
+        settings.AZURE_DEPLOYMENT_NAME = azure_deployment_name
+        settings.AZURE_MODEL_NAME = openai_model_name
+        if azure_model_version is not None:
+            settings.AZURE_MODEL_VERSION = azure_model_version
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
         )
-
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_AZURE_OPENAI, "YES")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_LOCAL_MODEL, "NO")
 
     print(
-        ":raising_hands: Congratulations! You're now using Azure OpenAI for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using Azure OpenAI's `{escape(openai_model_name)}` for all evals that require an LLM."
     )
 
 
@@ -277,46 +521,115 @@ def set_azure_openai_embedding_env(
         "--embedding-deployment-name",
         help="Azure embedding deployment name",
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_embedding_model_keys()
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.AZURE_EMBEDDING_DEPLOYMENT_NAME,
-        azure_embedding_deployment_name,
-    )
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.USE_AZURE_OPENAI_EMBEDDING, "YES"
-    )
-    KEY_FILE_HANDLER.write_key(EmbeddingKeyValues.USE_LOCAL_EMBEDDINGS, "NO")
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(
+            EmbeddingKeyValues.USE_AZURE_OPENAI_EMBEDDING
+        )
+        settings.AZURE_EMBEDDING_DEPLOYMENT_NAME = (
+            azure_embedding_deployment_name
+        )
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
         ":raising_hands: Congratulations! You're now using Azure OpenAI Embeddings within DeepEval."
     )
 
 
 @app.command(name="unset-azure-openai")
-def unset_azure_openai_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.AZURE_OPENAI_API_KEY)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.AZURE_OPENAI_ENDPOINT)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.OPENAI_API_VERSION)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.AZURE_DEPLOYMENT_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.AZURE_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.AZURE_MODEL_VERSION)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_AZURE_OPENAI)
-
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI for all evals that require an LLM."
+def unset_azure_openai_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the Azure OpenAI–related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
     )
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.AZURE_OPENAI_API_KEY = None
+        settings.AZURE_OPENAI_ENDPOINT = None
+        settings.OPENAI_API_VERSION = None
+        settings.AZURE_DEPLOYMENT_NAME = None
+        settings.AZURE_MODEL_NAME = None
+        settings.AZURE_MODEL_VERSION = None
+        settings.USE_AZURE_OPENAI = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed Azure OpenAI environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "Azure OpenAI has been unset. No active provider is configured. Set one with the CLI, or add credentials to .env[.local]."
+        )
 
 
 @app.command(name="unset-azure-openai-embedding")
-def unset_azure_openai_embedding_env():
-    KEY_FILE_HANDLER.remove_key(
-        EmbeddingKeyValues.AZURE_EMBEDDING_DEPLOYMENT_NAME
-    )
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.USE_AZURE_OPENAI_EMBEDDING)
+def unset_azure_openai_embedding_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the Azure OpenAI embedding related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.AZURE_EMBEDDING_DEPLOYMENT_NAME = None
+        settings.USE_AZURE_OPENAI_EMBEDDING = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Removed Azure OpenAI embedding environment variables from {path}."
+        )
 
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI embeddings for all evals that require text embeddings."
-    )
+    if is_openai_configured():
+        print(
+            ":raised_hands: Regular OpenAI embeddings will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The Azure OpenAI embedding model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 #############################################
@@ -333,27 +646,75 @@ def set_ollama_model_env(
         "--base-url",
         help="Base URL for the local model API",
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.LOCAL_MODEL_NAME, model_name)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.LOCAL_MODEL_BASE_URL, base_url)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_LOCAL_MODEL, "YES")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_AZURE_OPENAI, "NO")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.LOCAL_MODEL_API_KEY, "ollama")
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_LOCAL_MODEL)
+        settings.LOCAL_MODEL_API_KEY = "ollama"
+        settings.LOCAL_MODEL_NAME = model_name
+        settings.LOCAL_MODEL_BASE_URL = base_url
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
-        ":raising_hands: Congratulations! You're now using a local Ollama model for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using a local Ollama model `{escape(model_name)}` for all evals that require an LLM."
     )
 
 
 @app.command(name="unset-ollama")
-def unset_ollama_model_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LOCAL_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LOCAL_MODEL_BASE_URL)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_LOCAL_MODEL)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LOCAL_MODEL_API_KEY)
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI for all evals that require an LLM."
-    )
+def unset_ollama_model_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the Ollama related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.LOCAL_MODEL_API_KEY = None
+        settings.LOCAL_MODEL_NAME = None
+        settings.LOCAL_MODEL_BASE_URL = None
+        settings.USE_LOCAL_MODEL = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed local Ollama environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The local Ollama model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 @app.command(name="set-ollama-embeddings")
@@ -367,37 +728,78 @@ def set_ollama_embeddings_env(
         "--base-url",
         help="Base URL for the Ollama embedding model API",
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_embedding_model_keys()
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.LOCAL_EMBEDDING_MODEL_NAME, model_name
-    )
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.LOCAL_EMBEDDING_BASE_URL, base_url
-    )
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.LOCAL_EMBEDDING_API_KEY, "ollama"
-    )
-    KEY_FILE_HANDLER.write_key(EmbeddingKeyValues.USE_LOCAL_EMBEDDINGS, "YES")
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.USE_AZURE_OPENAI_EMBEDDING, "NO"
-    )
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(EmbeddingKeyValues.USE_LOCAL_EMBEDDINGS)
+        settings.LOCAL_EMBEDDING_API_KEY = "ollama"
+        settings.LOCAL_EMBEDDING_MODEL_NAME = model_name
+        settings.LOCAL_EMBEDDING_BASE_URL = base_url
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
 
     print(
-        ":raising_hands: Congratulations! You're now using Ollama embeddings for all evals that require text embeddings."
+        f":raising_hands: Congratulations! You're now using the Ollama embedding model `{escape(model_name)}` for all evals that require text embeddings."
     )
 
 
 @app.command(name="unset-ollama-embeddings")
-def unset_ollama_embeddings_env():
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.LOCAL_EMBEDDING_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.LOCAL_EMBEDDING_BASE_URL)
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.LOCAL_EMBEDDING_API_KEY)
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.USE_LOCAL_EMBEDDINGS)
+def unset_ollama_embeddings_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the Ollama embedding related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
 
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI embeddings for all evals that require text embeddings."
-    )
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.LOCAL_EMBEDDING_API_KEY = None
+        settings.LOCAL_EMBEDDING_MODEL_NAME = None
+        settings.LOCAL_EMBEDDING_BASE_URL = None
+        settings.USE_LOCAL_EMBEDDINGS = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Removed local Ollama embedding environment variables from {path}."
+        )
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: Regular OpenAI embeddings will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The local Ollama embedding model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 #############################################
@@ -414,39 +816,88 @@ def set_local_model_env(
         ..., "--base-url", help="Base URL for the local model API"
     ),
     api_key: Optional[str] = typer.Option(
-        None, "--api-key", help="API key for the local model (if required)"
+        None,
+        "--api-key",
+        help="API key for the local model. Persisted to dotenv if --save is used; never written to the legacy JSON keystore.",
     ),
-    format: Optional[str] = typer.Option(
+    model_format: Optional[str] = typer.Option(
         "json",
         "--format",
         help="Format of the response from the local model (default: json)",
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.LOCAL_MODEL_NAME, model_name)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.LOCAL_MODEL_BASE_URL, base_url)
-    if api_key:
-        KEY_FILE_HANDLER.write_key(ModelKeyValues.LOCAL_MODEL_API_KEY, api_key)
-    if format:
-        KEY_FILE_HANDLER.write_key(ModelKeyValues.LOCAL_MODEL_FORMAT, format)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_LOCAL_MODEL, "YES")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_AZURE_OPENAI, "NO")
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_LOCAL_MODEL)
+        settings.LOCAL_MODEL_NAME = model_name
+        settings.LOCAL_MODEL_BASE_URL = base_url
+        if model_format:
+            settings.LOCAL_MODEL_FORMAT = model_format
+        if api_key:
+            settings.LOCAL_MODEL_API_KEY = api_key
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
-        ":raising_hands: Congratulations! You're now using a local model for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using a local model `{escape(model_name)}` for all evals that require an LLM."
     )
 
 
 @app.command(name="unset-local-model")
-def unset_local_model_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LOCAL_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LOCAL_MODEL_BASE_URL)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LOCAL_MODEL_API_KEY)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LOCAL_MODEL_FORMAT)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_LOCAL_MODEL)
-
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI for all evals that require an LLM."
-    )
+def unset_local_model_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the local model related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.LOCAL_MODEL_API_KEY = None
+        settings.LOCAL_MODEL_NAME = None
+        settings.LOCAL_MODEL_BASE_URL = None
+        settings.LOCAL_MODEL_FORMAT = None
+        settings.USE_LOCAL_MODEL = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed local model environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The local model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 #############################################
@@ -460,31 +911,82 @@ def set_grok_model_env(
         ..., "--model-name", help="Name of the Grok model"
     ),
     api_key: str = typer.Option(
-        ..., "--api-key", help="API key for the Grok model"
+        ...,
+        "--api-key",
+        help="API key for the Grok model. Persisted to dotenv if --save is used; never written to the legacy JSON keystore.",
     ),
     temperature: float = typer.Option(
         0, "--temperature", help="Temperature for the Grok model"
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.GROK_MODEL_NAME, model_name)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.GROK_API_KEY, api_key)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.TEMPERATURE, str(temperature))
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_GROK_MODEL, "YES")
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_GROK_MODEL)
+        settings.GROK_API_KEY = api_key
+        settings.GROK_MODEL_NAME = model_name
+        settings.TEMPERATURE = temperature
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
-        ":raising_hands: Congratulations! You're now using a Grok model for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using a Grok's `{escape(model_name)}` for all evals that require an LLM."
     )
 
 
 @app.command(name="unset-grok")
-def unset_grok_model_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.GROK_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.GROK_API_KEY)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.TEMPERATURE)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_GROK_MODEL)
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI for all evals that require an LLM."
-    )
+def unset_grok_model_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the Grok model related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.GROK_API_KEY = None
+        settings.GROK_MODEL_NAME = None
+        settings.TEMPERATURE = None
+        settings.USE_GROK_MODEL = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed Grok model environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The Grok model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 #############################################
@@ -498,31 +1000,82 @@ def set_moonshot_model_env(
         ..., "--model-name", help="Name of the Moonshot model"
     ),
     api_key: str = typer.Option(
-        ..., "--api-key", help="API key for the Moonshot model"
+        ...,
+        "--api-key",
+        help="API key for the Moonshot model. Persisted to dotenv if --save is used; never written to the legacy JSON keystore.",
     ),
     temperature: float = typer.Option(
         0, "--temperature", help="Temperature for the Moonshot model"
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.MOONSHOT_MODEL_NAME, model_name)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.MOONSHOT_API_KEY, api_key)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.TEMPERATURE, str(temperature))
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_MOONSHOT_MODEL, "YES")
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_MOONSHOT_MODEL)
+        settings.MOONSHOT_API_KEY = api_key
+        settings.MOONSHOT_MODEL_NAME = model_name
+        settings.TEMPERATURE = temperature
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
-        ":raising_hands: Congratulations! You're now using a Moonshot model for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using Moonshot's `{escape(model_name)}` for all evals that require an LLM."
     )
 
 
 @app.command(name="unset-moonshot")
-def unset_moonshot_model_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.MOONSHOT_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.MOONSHOT_API_KEY)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.TEMPERATURE)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_MOONSHOT_MODEL)
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI for all evals that require an LLM."
-    )
+def unset_moonshot_model_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the Moonshot model related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.MOONSHOT_API_KEY = None
+        settings.MOONSHOT_MODEL_NAME = None
+        settings.TEMPERATURE = None
+        settings.USE_MOONSHOT_MODEL = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed Moonshot model environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The Moonshot model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 #############################################
@@ -536,31 +1089,82 @@ def set_deepseek_model_env(
         ..., "--model-name", help="Name of the DeepSeek model"
     ),
     api_key: str = typer.Option(
-        ..., "--api-key", help="API key for the DeepSeek model"
+        ...,
+        "--api-key",
+        help="API key for the DeepSeek model. Persisted to dotenv if --save is used; never written to the legacy JSON keystore.",
     ),
     temperature: float = typer.Option(
         0, "--temperature", help="Temperature for the DeepSeek model"
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.DEEPSEEK_MODEL_NAME, model_name)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.DEEPSEEK_API_KEY, api_key)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.TEMPERATURE, str(temperature))
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_DEEPSEEK_MODEL, "YES")
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_DEEPSEEK_MODEL)
+        settings.DEEPSEEK_API_KEY = api_key
+        settings.DEEPSEEK_MODEL_NAME = model_name
+        settings.TEMPERATURE = temperature
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
-        ":raising_hands: Congratulations! You're now using a DeepSeek model for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using DeepSeek's `{escape(model_name)}` for all evals that require an LLM."
     )
 
 
 @app.command(name="unset-deepseek")
-def unset_deepseek_model_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.DEEPSEEK_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.DEEPSEEK_API_KEY)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.TEMPERATURE)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_DEEPSEEK_MODEL)
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI for all evals that require an LLM."
-    )
+def unset_deepseek_model_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the DeepSeek model related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.DEEPSEEK_API_KEY = None
+        settings.DEEPSEEK_MODEL_NAME = None
+        settings.TEMPERATURE = None
+        settings.USE_DEEPSEEK_MODEL = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed DeepSeek model environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The DeepSeek model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 #############################################
@@ -577,45 +1181,84 @@ def set_local_embeddings_env(
         ..., "--base-url", help="Base URL for the local embeddings API"
     ),
     api_key: Optional[str] = typer.Option(
-        None, "--api-key", help="API key for the local embeddings (if required)"
+        None,
+        "--api-key",
+        help="API key for the local embeddings. Persisted to dotenv if --save is used; never written to the legacy JSON keystore.",
+    ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
     ),
 ):
-    clear_embedding_model_keys()
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.LOCAL_EMBEDDING_MODEL_NAME, model_name
-    )
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.LOCAL_EMBEDDING_BASE_URL, base_url
-    )
-    if api_key:
-        KEY_FILE_HANDLER.write_key(
-            EmbeddingKeyValues.LOCAL_EMBEDDING_API_KEY, api_key
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(EmbeddingKeyValues.USE_LOCAL_EMBEDDINGS)
+        settings.LOCAL_EMBEDDING_MODEL_NAME = model_name
+        settings.LOCAL_EMBEDDING_BASE_URL = base_url
+        if api_key:
+            settings.LOCAL_EMBEDDING_API_KEY = api_key
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
         )
-
-    KEY_FILE_HANDLER.write_key(EmbeddingKeyValues.USE_LOCAL_EMBEDDINGS, "YES")
-    KEY_FILE_HANDLER.write_key(
-        EmbeddingKeyValues.USE_AZURE_OPENAI_EMBEDDING, "NO"
-    )
 
     print(
-        ":raising_hands: Congratulations! You're now using local embeddings for all evals that require text embeddings."
+        f":raising_hands: Congratulations! You're now using the local embedding model `{escape(model_name)}` for all evals that require text embeddings."
     )
 
 
 @app.command(name="unset-local-embeddings")
-def unset_local_embeddings_env():
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.LOCAL_EMBEDDING_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.LOCAL_EMBEDDING_BASE_URL)
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.LOCAL_EMBEDDING_API_KEY)
-    KEY_FILE_HANDLER.remove_key(EmbeddingKeyValues.USE_LOCAL_EMBEDDINGS)
-
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI embeddings for all evals that require text embeddings."
-    )
+def unset_local_embeddings_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the local embedding related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.LOCAL_EMBEDDING_API_KEY = None
+        settings.LOCAL_EMBEDDING_MODEL_NAME = None
+        settings.LOCAL_EMBEDDING_BASE_URL = None
+        settings.USE_LOCAL_EMBEDDINGS = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed local embedding environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The local embeddings model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 #############################################
-# Ollama Integration ########################
+# Gemini Integration ########################
 #############################################
 
 
@@ -625,7 +1268,9 @@ def set_gemini_model_env(
         None, "--model-name", help="Gemini Model name"
     ),
     google_api_key: Optional[str] = typer.Option(
-        None, "--google-api-key", help="Google API Key for Gemini"
+        None,
+        "--google-api-key",
+        help="Google API Key for Gemini",
     ),
     google_cloud_project: Optional[str] = typer.Option(
         None, "--project-id", help="Google Cloud project ID"
@@ -633,8 +1278,13 @@ def set_gemini_model_env(
     google_cloud_location: Optional[str] = typer.Option(
         None, "--location", help="Google Cloud location"
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    clear_evaluation_model_keys()
     if not google_api_key and not (
         google_cloud_project and google_cloud_location
     ):
@@ -643,81 +1293,172 @@ def set_gemini_model_env(
             err=True,
         )
         raise typer.Exit(code=1)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_GEMINI_MODEL, "YES")
-    if model_name is not None:
-        KEY_FILE_HANDLER.write_key(ModelKeyValues.GEMINI_MODEL_NAME, model_name)
-    if google_api_key is not None:
-        KEY_FILE_HANDLER.write_key(
-            ModelKeyValues.GOOGLE_API_KEY, google_api_key
+
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_GEMINI_MODEL)
+
+        if google_api_key is not None:
+            settings.GOOGLE_API_KEY = google_api_key
+            settings.GOOGLE_GENAI_USE_VERTEXAI = False
+        else:
+            settings.GOOGLE_GENAI_USE_VERTEXAI = True
+        if google_cloud_project:
+            settings.GOOGLE_CLOUD_PROJECT = google_cloud_project
+        if google_cloud_location:
+            settings.GOOGLE_CLOUD_LOCATION = google_cloud_location
+        if model_name:
+            settings.GEMINI_MODEL_NAME = model_name
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
         )
     else:
-        KEY_FILE_HANDLER.write_key(
-            ModelKeyValues.GOOGLE_GENAI_USE_VERTEXAI, "YES"
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
         )
 
-    if google_cloud_project is not None:
-        KEY_FILE_HANDLER.write_key(
-            ModelKeyValues.GOOGLE_CLOUD_PROJECT, google_cloud_project
+    _model_name = (
+        model_name if model_name is not None else settings.GEMINI_MODEL_NAME
+    )
+    if _model_name is not None:
+        print(
+            f":raising_hands: Congratulations! You're now using Gemini's `{escape(_model_name)}` for all evals that require an LLM."
         )
-    if google_cloud_location is not None:
-        KEY_FILE_HANDLER.write_key(
-            ModelKeyValues.GOOGLE_CLOUD_LOCATION, google_cloud_location
+    else:
+        print(
+            f":raising_hands: Congratulations! You're now using Gemini's model for all evals that require an LLM."
         )
-    print(
-        ":raising_hands: Congratulations! You're now using a Gemini model for all evals that require an LLM."
-    )
 
 
 @app.command(name="unset-gemini")
-def unset_gemini_model_env():
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_GEMINI_MODEL)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.GEMINI_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.GOOGLE_API_KEY)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.GOOGLE_CLOUD_PROJECT)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.GOOGLE_CLOUD_LOCATION)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.GOOGLE_GENAI_USE_VERTEXAI)
-
-    print(
-        ":raised_hands: Gemini model has been unset. You're now using regular OpenAI for all evals that require an LLM."
-    )
+def unset_gemini_model_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the Gemini related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.GOOGLE_API_KEY = None
+        settings.GOOGLE_GENAI_USE_VERTEXAI = None
+        settings.GOOGLE_CLOUD_PROJECT = None
+        settings.GOOGLE_CLOUD_LOCATION = None
+        settings.GEMINI_MODEL_NAME = None
+        settings.USE_GEMINI_MODEL = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed Gemini model environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The Gemini model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 @app.command(name="set-litellm")
 def set_litellm_model_env(
     model_name: str = typer.Argument(..., help="Name of the LiteLLM model"),
     api_key: Optional[str] = typer.Option(
-        None, "--api-key", help="API key for the model (if required)"
+        None,
+        "--api-key",
+        help="API key for the model. Persisted to dotenv if --save is used; never written to the legacy JSON keystore.",
     ),
     api_base: Optional[str] = typer.Option(
         None, "--api-base", help="Base URL for the model API (if required)"
     ),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Persist CLI parameters as environment variables in a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
 ):
-    """Set up a LiteLLM model for evaluation."""
-    clear_evaluation_model_keys()
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.LITELLM_MODEL_NAME, model_name)
-    if api_key:
-        KEY_FILE_HANDLER.write_key(ModelKeyValues.LITELLM_API_KEY, api_key)
-    if api_base:
-        KEY_FILE_HANDLER.write_key(ModelKeyValues.LITELLM_API_BASE, api_base)
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_LITELLM, "YES")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_AZURE_OPENAI, "NO")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_LOCAL_MODEL, "NO")
-    KEY_FILE_HANDLER.write_key(ModelKeyValues.USE_GEMINI_MODEL, "NO")
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        edit_ctx.switch_model_provider(ModelKeyValues.USE_LITELLM)
+        settings.LITELLM_MODEL_NAME = model_name
+        if api_key is not None:
+            settings.LITELLM_API_KEY = api_key
+        if api_base is not None:
+            settings.LITELLM_API_BASE = api_base
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(
+            f"Saved environment variables to {path} (ensure it's git-ignored)."
+        )
+    else:
+        # updated in-memory & process env only
+        print(
+            "Settings updated for this session. To persist, use --save=dotenv[:path] "
+            "(default .env.local) or set DEEPEVAL_DEFAULT_SAVE=dotenv:.env.local"
+        )
+
     print(
-        ":raising_hands: Congratulations! You're now using a LiteLLM model for all evals that require an LLM."
+        f":raising_hands: Congratulations! You're now using LiteLLM's `{escape(model_name)}` for all evals that require an LLM."
     )
 
 
 @app.command(name="unset-litellm")
-def unset_litellm_model_env():
-    """Remove LiteLLM model configuration."""
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LITELLM_MODEL_NAME)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LITELLM_API_KEY)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.LITELLM_API_BASE)
-    KEY_FILE_HANDLER.remove_key(ModelKeyValues.USE_LITELLM)
-    print(
-        ":raising_hands: Congratulations! You're now using regular OpenAI for all evals that require an LLM."
-    )
+def unset_litellm_model_env(
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Remove only the LiteLLM related environment variables from a dotenv file. "
+        "Usage: --save=dotenv[:path] (default: .env.local)",
+    ),
+):
+    settings = get_settings()
+    with settings.edit(save=save) as edit_ctx:
+        settings.LITELLM_API_KEY = None
+        settings.LITELLM_MODEL_NAME = None
+        settings.LITELLM_API_BASE = None
+        settings.USE_LITELLM = None
+
+    handled, path, _ = edit_ctx.result
+
+    if not handled and save is not None:
+        # invalid --save format (unsupported)
+        print("Unsupported --save option. Use --save=dotenv[:path].")
+    elif path:
+        # persisted to a file
+        print(f"Removed LiteLLM model environment variables from {path}.")
+
+    if is_openai_configured():
+        print(
+            ":raised_hands: OpenAI will still be used by default because OPENAI_API_KEY is set."
+        )
+    else:
+        print(
+            "The LiteLLM model configuration has been removed. No model is currently configured, but you can set one with the CLI or add credentials to .env[.local]."
+        )
 
 
 if __name__ == "__main__":