Langfuse CLI
Langfuse CLI
Langfuse CLI는 전체 Langfuse API 를 감싸서 터미널에서 직접 Langfuse와 상호작용할 수 있게 해줍니다. 이 문서는 CLI 설치, 인증, 그리고 할 수 있는 일들을 설명해요. AI 코딩 에이전트와 커맨드라인을 선호하는 파워 유저를 위해 만들어졌습니다.
출처: 문서
본문
Langfuse CLI는 전체 Langfuse API 를 감싸므로 터미널에서 바로 Langfuse와 상호작용할 수 있습니다. 커맨드라인을 선호하는 AI 코딩 에이전트와 파워 유저를 위해 만들어졌습니다.
명령을 실행하거나 패키지를 설치할 수 없는 도구라면 Langfuse MCP server 를 연결하세요. 둘 다 프롬프트 관리 이상의 Langfuse 기능에 접근을 제공합니다.
전체 문서는 전용 CLI GitHub Repo 에서 확인할 수 있습니다.
시작하려면 다음을 실행하세요:
npx @langfuse/cli api <resource> <action>
또는 코딩 에이전트에게 그냥 요청하세요:
please install @langfuse/cli
참고: 이 패키지는 이전에 langfuse-cli라는 이름으로 게시되었습니다. 그 패키지는 이 패키지와 동일하며, 새 메이저 버전을 릴리스할 때까지 함께 업데이트됩니다. 지금부터는 @langfuse/cli를 사용할 것을 권장합니다.
langfuse-cli에서 새 @langfuse/cli 패키지로 이동
다음 메이저 버전까지 langfuse-cli를 유지 관리하지만, 지금부터는 @langfuse/cli를 사용할 것을 권장합니다.
langfuse-cli에서 마이그레이션하려면 명령어의 패키지 이름을 바꾸세요:
npx @langfuse/cli api <resource> <action>
# or
bunx @langfuse/cli api <resource> <action>
또는 전환:
# npm
npm uninstall --global langfuse-cli
npm install --global @langfuse/cli
# Bun
bun remove --global langfuse-cli
bun add --global @langfuse/cli
마이그레이션 후에도 같은 langfuse 명령으로 CLI를 계속 실행하면 됩니다.
인증
CLI는 Langfuse SDK와 public API에 사용하는 것과 같은 프로젝트 API 키 쌍으로 인증합니다. Langfuse UI에서 Project settings → API Keys 아래에 키 쌍을 만들고, CLI 명령을 실행하기 전에 환경 변수로 자격 증명을 노출하세요:
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
# Region-specific host. Defaults to https://cloud.langfuse.com (EU).
# US: https://us.cloud.langfuse.com
# Japan: https://jp.cloud.langfuse.com
# HIPAA: https://hipaa.cloud.langfuse.com
# Self-hosted: your own deployment URL.
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"
CLI는 이를 자동으로 감지합니다 — 별도의 login 절차는 없습니다. 키는 단일 프로젝트로 범위가 지정되므로, 상호작용하려는 프로젝트마다 다른 키 쌍을 사용하세요.
할 수 있는 일(What it can do)
CLI는 Langfuse API 가 할 수 있는 모든 것을 할 수 있습니다.
전체 OpenAPI 스펙에서 생성되므로 모든 엔드포인트(traces, observations, prompts, datasets, scores, sessions, metrics 등)가 CLI 명령으로 제공됩니다. 자세한 내용은 API Reference 를 참고하세요.
실패 시 머신이 읽을 수 있는 코드로 종료되므로 에이전트가 stderr를 파싱하지 않고도 무엇이 잘못됐는지 알 수 있습니다: usage(2), configuration(3), network(4), HTTP failure(5), local errors(6).
왜 사용하나요?
- 코딩 에이전트가 Langfuse를 대신 관리하게 하세요. Cursor, Claude Code, Windsurf 등이 CLI로 에디터를 떠나지 않고 데이터셋을 만들고, trace를 가져오고, 프롬프트를 업데이트할 수 있습니다.
- 워크플로우를 스크립트로 만들기. trace 내보내기, 배치 스코어링, 환경 간 프롬프트 동기화 같은 반복 작업을 CI/CD나 bash 스크립트에서 자동화하세요.
- 빠른 조회에 UI보다 빠름. 최근 5개 trace를 가져오고, 프롬프트 버전을 확인하고, 점수를 몇 초 만에 나열할 수 있습니다.
Agent Skills와 함께 사용
CLI는 Agent Skills 와 함께 동작하도록 설계되었습니다. 스킬은 에이전트가 CLI를 통해 엔드포인트를 발견하고, 일반적인 워크플로우를 따르고, 문서에 접근하는 방법을 가르칩니다. 스킬/CLI/MCP 서버가 어떻게 맞물리는지 전체 그림은 Langfuse for Agents 를 참고하거나 블로그 글 을 읽어보세요.
더 알아보기 (Learn more)
- 출처 문서: Langfuse CLI