fix(cli): keep lite up on the client window and bound the proxy check to 3 seconds

This commit is contained in:
mateo-berri 2026-10-20 19:57:47 -07:00
parent cb97a89dbe
commit a757c076e2
5 changed files with 33 additions and 51 deletions

View file

@ -506,7 +506,7 @@ To pin the model, pass the agent's own model flag (for example `lite claude --mo
The token minted by `lite login` is a short-lived, per-session agent credential, not a managed virtual key. It is scoped to the user and team you authenticated as, inherits that user's and team's models and budgets, and is enforced on the proxy exactly like a virtual key on the same team (guardrails, routing, logging, spend). Spend is tracked against the shared team and user budgets, so running several agents (or logging in more than once) does not hand each session its own separate budget; they all draw down the same team/user allowance. There is no separate per-session cap, so sustained agent use is not capped at a small chat-session limit.
The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it until the proxy stops accepting it and then fails -- there is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. Past 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client, `print-token`, `lite whoami`, and `lite up` ask the proxy whether it still accepts the token instead of assuming it expired. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it until the proxy stops accepting it and then fails -- there is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. Past 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client, `print-token` and `lite whoami` ask the proxy whether it still accepts the token instead of assuming it expired. `lite up` still starts a new login at that point, since it copies the token into Claude Code's settings as a static key that it never renews. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
### Route Every Claude Code Session Through the Proxy

View file

@ -142,7 +142,7 @@ _TeamMapping: Final = TypeVar("_TeamMapping", bound=Mapping[str, object])
_JSON_OBJECT: Final = TypeAdapter(Mapping[str, object], config=ConfigDict(hide_input_in_errors=True))
_PROXY_KEY_CHECK_TIMEOUT_SECONDS: Final = 10
_PROXY_KEY_CHECK_TIMEOUT_SECONDS: Final = 3
_PROXY_REJECTED_KEY_STATUSES: Final = frozenset({401, 403, 404})
KEYRING_INSTALL_HINT: Final = "pip install 'litellm[cli]'"

View file

@ -15,18 +15,11 @@ import click
from pydantic import JsonValue, TypeAdapter, ValidationError
from litellm.litellm_core_utils.cli_keyring import SecretVault
from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
from litellm.litellm_core_utils.private_json import ensure_private_dir
from .agents import AgentRunError, resolve_api_key, verify_proxy_key
from .auth import (
CliContextObj,
cli_context_obj,
context_secret_vault,
get_stored_api_key,
load_token,
login,
token_expired,
)
from .auth import CliContextObj, cli_context_obj, context_secret_vault, get_stored_api_key, load_token, login
from .claude_settings import (
BACKUP_PATH,
CLAUDE_SETTINGS_PATH,
@ -118,7 +111,7 @@ def _usable_login(api_key: str | None, vault: SecretVault) -> bool:
if api_key is None:
return False
token_data: Final = load_token(vault=vault)
return token_data is not None and not token_expired(token_data)
return token_data is not None and is_cli_token_fresh(token_data)
def _key_resolved_on_the_way_in(ctx_obj: CliContextObj, base_url: str, vault: SecretVault) -> str | None:

View file

@ -1105,6 +1105,25 @@ class TestPrintTokenCommand:
assert result.stderr == expected_stderr
assert len(responses.calls) == 1
@responses.activate
def test_proxy_check_waits_only_a_few_seconds_for_a_silent_proxy(self):
_register_models_answer("sk-stale-key", 200)
with patch(
"litellm.proxy.client.cli.commands.auth.load_cli_token",
return_value=CliTokenRecord(
base_url=STALE_TOKEN_BASE_URL,
key="sk-stale-key",
timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600,
),
):
result: Final = self.runner.invoke(print_token, obj={})
timeout: Final = responses.calls[0].request.req_kwargs["timeout"]
assert result.exit_code == 0
assert isinstance(timeout, int | float)
assert 0 < timeout <= 5
class TestPrintTokenWithConfigFile:
"""A config-file base_url is a drop-in replacement for exporting

View file

@ -3,15 +3,12 @@ import shutil
import stat
import sys
import time
from typing import Final
from unittest.mock import patch
import click
import pytest
import responses
from click.testing import CliRunner
from litellm.constants import CLI_JWT_EXPIRATION_HOURS
from litellm.proxy.client.cli.commands import up as up_module
from litellm.proxy.client.cli.commands.agents import AgentRunError
from litellm.proxy.client.cli.commands.claude_settings import ClaudeSettingsError, StaticToken
@ -305,7 +302,7 @@ class TestEnsureFreshLogin:
_FakeTokenStore(
monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {"http://proxy-a:4000": "sk-a"}
)
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
login_calls = _capture_login(monkeypatch)
ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
@ -315,7 +312,7 @@ class TestEnsureFreshLogin:
def test_forces_a_fresh_login_when_the_cached_token_is_for_a_different_proxy(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
store = _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
login_calls = _capture_login(
monkeypatch, on_login=lambda: store.log_in({"key": "sk-b", "base_url": "http://proxy-b:4000"}, "sk-b")
)
@ -328,7 +325,7 @@ class TestEnsureFreshLogin:
def test_forces_a_fresh_login_when_the_cached_token_has_no_readable_key(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
store = _FakeTokenStore(monkeypatch, {"base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
login_calls = _capture_login(
monkeypatch,
on_login=lambda: store.log_in({"key": "sk-a", "base_url": "http://proxy-a:4000"}, "sk-a"),
@ -341,38 +338,11 @@ class TestEnsureFreshLogin:
def test_fails_cleanly_non_interactively_when_only_a_different_proxys_token_is_cached(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
_FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
with pytest.raises(UpError, match="Run `lite login` first"):
ensure_fresh_login(_make_ctx("http://proxy-b:4000"))
@pytest.mark.parametrize(("proxy_status", "expected_login_calls"), [(200, []), (401, [("http://proxy-a:4000", False)])])
@responses.activate
def test_lets_the_proxy_judge_a_classic_token_older_than_the_client_window(
self, monkeypatch, proxy_status: int, expected_login_calls: list[tuple[str, bool]]
):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
responses.get("http://proxy-a:4000/v1/models", json={"data": []}, status=proxy_status)
store: Final = _FakeTokenStore(
monkeypatch,
{
"key": "sk-a",
"base_url": "http://proxy-a:4000",
"timestamp": time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600,
},
{"http://proxy-a:4000": "sk-a"},
)
login_calls: Final = _capture_login(
monkeypatch,
on_login=lambda: store.log_in(
{"key": "sk-new", "base_url": "http://proxy-a:4000", "timestamp": time.time()}, "sk-new"
),
)
ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
assert login_calls == expected_login_calls
def test_trusts_a_pkce_credential_that_was_renewed_on_the_way_in(self, monkeypatch):
"""A --pkce key inside its freshness buffer is renewed by `get_stored_api_key`, so `lite up`
must judge the rotated record rather than refuse the one it started with."""
@ -406,7 +376,7 @@ class TestEnsureFreshLogin:
"""`lite config set pkce true` is honoured by the login `lite up` starts, not only by `lite login`."""
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
store = _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "pkce_default", lambda: True)
login_calls = _capture_login(
monkeypatch,
@ -420,7 +390,7 @@ class TestEnsureFreshLogin:
def test_names_the_pkce_login_in_the_non_interactive_error_when_the_saved_pkce_default_is_on(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
_FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "pkce_default", lambda: True)
with pytest.raises(UpError, match="Run `lite login --pkce` first"):
@ -485,7 +455,7 @@ class TestUpCommand:
with (
patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.token_expired", return_value=False),
patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.verify_proxy_key"),
):
@ -516,7 +486,7 @@ class TestUpCommand:
with (
patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.token_expired", return_value=False),
patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
patch(
f"{UP_MODULE}.verify_proxy_key",
@ -545,7 +515,7 @@ class TestUpCommand:
with (
patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.token_expired", return_value=False),
patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.verify_proxy_key"),
patch(f"{UP_MODULE}.signal.signal"),