LiteLLM Proxy CLI

lite CLI는 LiteLLM 프록시 서버를 관리하고, 그걸 통해 코딩 에이전트를 실행하기 위한 커맨드라인 도구예요. 모델, 자격증명, API 키, 팀, 사용자를 관리하고 프록시에 대해 채팅·HTTP 요청을 실행하며, 저장된 자격증명 암호화를 마이그레이션하고 코딩 에이전트(Claude Code, Codex, OpenCode)의 LLM 트래픽을 프록시를 통해 라우팅해요.

출처: 문서

본문

기능	할 수 있는 것
코딩 에이전트	프록시를 통해 Claude Code, Codex, OpenCode 실행
모델 관리	모델 나열·추가·업데이트·삭제
자격증명 관리	프로바이더 자격증명 관리
키 관리	API 키 생성·나열·삭제·가져오기
팀 관리	팀 나열, 가입 가능한 팀 나열, 자신의 키를 팀에 지정
사용자 관리	사용자 생성·나열·삭제
채팅 완성	채팅 완성 실행
HTTP 요청	프록시 서버에 커스텀 HTTP 요청
암호화 마이그레이션	저장된 자격증명을 AES-256-GCM으로 다시 암호화

빠른 시작 (Quick Start)

CLI로 인증하기 (Authentication using CLI)

CLI로 LiteLLM 게이트웨이에 인증할 수 있어요. 많은 개발자에게 LiteLLM 게이트웨이에 대한 셀프서비스 접근을 주려고 할 때 유용해요. 심층 가이드는 CLI 인증을 참고하세요.

사전 요구사항 (Prerequisites)

CLI SSO 인증은 현재 베타예요. LiteLLM 프록시를 시작할 때 다음 환경 변수를 설정해야 해요.

export EXPERIMENTAL_UI_LOGIN="True"
litellm --config config.yaml

또는 프록시 시작 명령에 추가하세요: EXPERIMENTAL_UI_LOGIN="True" litellm --config config.yaml

단계 (Steps)

프록시를 통해 코딩 에이전트 실행하기

LLM 트래픽 전부가 LiteLLM 프록시를 통해 라우팅되는 코딩 에이전트를 실행해요. 각 지원 에이전트는 별도 명령이므로 에이전트 이름 외에 기억할 것이 없어요.

lite claude
lite codex
lite opencode

에이전트 이름 뒤의 모든 것은 에이전트에 그대로 전달되므로 자체 플래그가 계속 동작해요.

lite claude --resume
lite codex exec "summarize the repo"

각 명령은 LiteLLM 키를 해석하고(저장된 키가 없고 터미널에 있으면 SSO로 로그인, 그렇지 않으면 LITELLM_PROXY_API_KEY 또는 --api-key를 읽음), 키를 프록시에 검증해 잘못된 자격증명이 에이전트 내부 깊숙이서가 아니라 즉시 실패하게 한 뒤, 에이전트가 읽는 환경 변수를 내보내고 에이전트 프로세스로 대체돼요.

변수는 에이전트별로 선택돼요. Claude Code는 ANTHROPIC_BASE_URL(프록시 루트, 그래서 /v1/messages를 붙임)과 ANTHROPIC_AUTH_TOKEN을 받고, 흩어진 ANTHROPIC_API_KEY는 지워져 프록시 토큰이 이겨요. Codex와 OpenCode는 OPENAI_BASE_URL(프록시 + /v1)과 OPENAI_API_KEY를 받아요. Codex는 OPENAI_BASE_URL을 무시하므로 -c config 오버라이드를 통해 전달되는 커스텀 프로바이더로 추가로 프록시를 가리켜요(HTTP/SSE Responses 전송. 프록시가 Responses WebSocket 프로토콜을 말하지 않기 때문).

--skip-verify는 사전 실행 키 검사를 건너뛰며 오프라인이나 비표준 인증에 도움이 돼요. 래퍼에 속하므로 에이전트의 자체 플래그 앞에 둬요.

lite claude --skip-verify --resume

모델을 고정하려면 에이전트의 자체 모델 플래그(lite claude --model my-proxy-model 또는 lite codex -m my-proxy-model)를 전달하거나 에이전트가 읽는 변수를 내보내요(Claude Code의 ANTHROPIC_MODEL/ANTHROPIC_SMALL_FAST_MODEL). 래퍼는 이미 설정한 것을 보존해요. 에이전트가 요청하는 모델은 프록시에 존재해야 해요. 요청이 프록시의 /v1/messages(Anthropic) 또는 /v1/chat/completions·/v1/responses(OpenAI) 엔드포인트에 착륙하기 때문이에요.

lite login이 발급하는 토큰은 수명이 짧은 세션별 에이전트 자격증명이지 관리형 가상 키가 아니에요. 인증한 사용자와 팀으로 범위가 한정되며, 그 사용자·팀의 모델과 예산을 상속하고, 같은 팀의 가상 키와 똑같이 프록시에서 강제돼요(가드레일, 라우팅, 로깅, 지출). 지출은 공유 팀·사용자 예산에 집계되므로 여러 에이전트를 실행하거나 여러 번 로그인해도 각 세션에 자체 예산이 생기지 않아요. 모두 같은 팀·사용자 허용량을 소진하며 별도 세션별 상한은 없어요.

자격증명은 의도적으로 수명이 짧아요(기본 24시간, LITELLM_CLI_JWT_EXPIRATION_HOURS로 구성). lite login을 다시 실행해 새로 고치는데, 이는 최신 팀·사용자 설정도 다시 읽어요. Keys UI에는 나타나지 않고 세션 중 회전·폐기도 불가능하며, lite claude, lite codex, lite opencode는 기본 배포에서 이와 동작해요. 수명이 길고 회전 가능한 키가 필요하면 대시보드에서 전용 가상 키를 만들고 --api-key 또는 LITELLM_PROXY_API_KEY로 전달하세요.

lite login은 자격증명을 OS 키체인(macOS Keychain, Windows Credential Manager, Linux Secret Service)의 litellm-cli 서비스 아래에 둬요. 비밀 아닌 절반만 ~/.litellm/token.json에 착륙해요. 게이트웨이 URL, 사용자 id·이메일·역할, 인증 헤더 이름, 로그인 시각. 그 파일은 0700 디렉터리 안에 0600으로 만들어져요. 키체인에 도달하려면 keyring 패키지가 필요하며 이는 cli extra와 함께 옵니다. 키체인 저장을 원한다면 맨 pip install litellm이나 pip install 'litellm[proxy]' 대신 pip install 'litellm[cli]'로 설치하세요. litellm.get_litellm_gateway_api_key()를 통해 자격증명을 다시 읽는 코드도 같은 이유로 keyring이 필요해요. 없으면 호출이 키체인 항목을 볼 수 없어 None을 반환하는데, lite login이 저장했는데도 그렇죠.

키체인이 없는 머신(예: 헤드리스 Linux)은 자격증명을 같은 소유자 전용 파일에 보관하며, keyring이 없는 설치와 LITELLM_CLI_DISABLE_KEYRING을 1, true, yes, on으로 설정해 키체인 저장을 완전히 끈 셸도 그렇습니다. lite login은 어느 쪽이든 자격증명이 어디 갔는지 출력해요. 이전 lite가 token.json에 평문으로 쓴 자격증명도 여전히 인증돼요. 다음 명령이 읽으면 키체인으로 옮기고 파일에서 빼요.

lite login --pkce의 자격증명에는 refresh 토큰도 함께 와요. CLI는 다음 사용 시 키를 갱신하고, lite auth print-token은 현재 키를 다른 도구에 건네며, lite logout은 프록시에서 refresh 토큰을 폐기해요. 갱신된 각 키는 이전 것처럼 키체인으로 가고, 그것을 산 refresh 토큰도 그렇습니다. PKCE 브라우저 로그인 참조.

로그인 중 팀으로 인증하거나 나중에 저장된 키를 다른 팀으로 옮기려면 lite teams assign-key를 사용해요(팀 관리 참조). 저장된 자격증명을 검사·지우려면:

lite whoami             # show the authenticated user and the token age
lite auth print-token   # print the current key, renewing a --pkce credential first when needed
lite logout             # clear the keychain entry and the token file, and revoke a --pkce refresh token

lite logout은 두 저장소를 모두 지워요. 키체인이 항목을 놓아주기를 거부하거나 확인을 위해 도달할 수 없으면 깨끗한 로그아웃을 보고하는 대신 경고하고 무엇을 할지 알려줘요.

주요 명령 (Main Commands)

모델 관리 (Models Management)

자격증명 관리 (Credentials Management)

키 관리 (Keys Management)

사용자 관리 (User Management)

팀 관리 (Teams Management)

채팅 완성 (Chat Completions)

일반 HTTP 요청 (General HTTP Requests)

암호화 마이그레이션 (Encryption Migration)

환경 변수 (Environment Variables)

예시 (Examples)

오류 처리 (Error Handling)

CLI는 다음에 대해 오류 메시지를 표시해요. 상세 디버깅 출력에는 --debug 플래그를 사용하세요. 전체 명령 참조와 고급 사용법은 CLI README를 참고하세요.

더 알아보기 (Learn more)

CLI 인증

LiteLLM Proxy CLI