From bd322ed8a7eb6968b2af8bebce28eb9f19251fd3 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Wed, 19 Aug 2026 19:11:01 -0700
Subject: [PATCH] refactor(cli): state the credential-store precedence rules as
 contracts

Drop the inline notes on keychain erasure and disk-vs-vault precedence in favour
of docstrings on the two functions that own those rules, and remove a stale
section header and a field note that the code already says plainly.
---
 litellm/litellm_core_utils/cli_keyring.py     | 6 +++++-
 litellm/litellm_core_utils/cli_token_utils.py | 6 +++++-
 litellm/proxy/client/cli/commands/auth.py     | 3 ---
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/litellm/litellm_core_utils/cli_keyring.py b/litellm/litellm_core_utils/cli_keyring.py
index 873db64a728..fcbf5ada55a 100644
--- a/litellm/litellm_core_utils/cli_keyring.py
+++ b/litellm/litellm_core_utils/cli_keyring.py
@@ -98,10 +98,14 @@ class KeyringVault:
         return True
 
     def erase(self) -> bool:
+        """Whether the keychain is guaranteed to hold no credential afterwards.
+
+        An uninstalled `keyring` package can never have stored one. A kill switch set after
+        a credential was stored leaves that entry out of reach, so erasure cannot be promised.
+        """
         if _import_keyring() is None:
             return True
         if _keyring_disabled():
-            # a credential stored before the kill switch was set may still be in the keychain
             return False
         match self.read():
             case SecretUnavailable():
diff --git a/litellm/litellm_core_utils/cli_token_utils.py b/litellm/litellm_core_utils/cli_token_utils.py
index 9960192180c..dd263ccd412 100644
--- a/litellm/litellm_core_utils/cli_token_utils.py
+++ b/litellm/litellm_core_utils/cli_token_utils.py
@@ -168,8 +168,12 @@ def _resolve_secret(record: CliTokenRecord, vault: SecretVault) -> CliTokenRecor
 
 
 def _apply_vault_secret(record: CliTokenRecord, blob: str, vault: SecretVault) -> CliTokenRecord | None:
+    """Resolve the credential when both stores hold one.
+
+    A secret still on disk is the fresher of the two, because it is only left there when the
+    keychain write that should have removed it failed, so it outranks the vault entry.
+    """
     if record.key is not None:
-        # a secret still on disk means the last keychain write failed: the file outranks the vault
         return _migrate_file_secret(record, vault)
     try:
         secret: Final = CliTokenSecret.model_validate_json(blob)
diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index 8b9ef5633da..c2b5b6a620f 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -76,7 +76,6 @@ KEYCHAIN_UNREACHABLE_MESSAGE: Final = (
 )
 
 
-# Token storage utilities
 def context_secret_vault(ctx: click.Context) -> SecretVault:
     """Where this invocation reads and writes secret material; injectable through ctx.obj for tests"""
     ctx_obj: Final[CliContextObj | None] = ctx.obj
@@ -666,8 +665,6 @@ def login(ctx: click.Context, config_claude: bool):
             api_key: Final = auth_result["api_key"]
             user_id: Final = auth_result["user_id"]
 
-            # base_url is stored so we can verify origin before reusing the
-            # key on a subsequent CLI invocation.
             record: Final = CliTokenRecord(
                 base_url=base_url.rstrip("/"),
                 key=api_key,