LangSmith CLI

터미널에서 LangSmith 프로젝트, 트레이스, 실행, 데이터셋, 평가자, 실험, 스레드를 조회하고 관리하는 방법을 알려드릴게요.

LangSmith CLI는 LangSmith 데이터를 조회하고 관리하기 위한 커맨드라인 도구입니다. 개발자와 AI 코딩 에이전트 모두를 위해 설계되었으며 기본적으로 사람이 읽을 수 있는 테이블을 출력하고, 스크립팅용 --format json 옵션을 제공합니다. 대량 내보내기, 자동화, 또는 코딩 에이전트가 트레이스, 실행, 데이터셋에 직접 접근하게 하는 것 같은 스크립트 가능한 LangSmith 데이터 접근이 필요할 때 사용하세요.

출처: 문서

본문

설치

curl -fsSL https://cli.langsmith.com/install.sh | sh

irm https://cli.langsmith.com/install.ps1 | iex

brew install langchain-ai/tap/langsmith-cli

scoop install langsmith-cli

# Download the latest binary for your platform:
# https://github.com/langchain-ai/langsmith-cli/releases

go install github.com/langchain-ai/langsmith-cli/cmd/langsmith@latest

언제든 업그레이드하려면:

langsmith self-update

설치하지 않고 업데이트를 미리 보려면 --dry-run 플래그를 사용하세요.

참고: SmithDB 기반 배포를 조회하려면 LangSmith CLI v0.2.44 이상이 필요합니다.

인증

langsmith auth login은 LangSmith CLI v0.2.30 이상이 필요합니다. langsmith profile 명령은 LangSmith CLI v0.2.26 이상이 필요합니다.

권장되는 로컬 설정은 OAuth로 인증하는 것입니다:

참고: langsmith auth login은 LangSmith CLI v0.2.46 이상부터, OAuth 인증 서버가 활성화된(LangSmith 0.16 이상 배포, 서명 JWKS 구성 필요) 셀프 호스팅 인스턴스에서도 동작합니다. 셀프 호스팅 인스턴스를 참고하세요. 이전 배포나 서명 JWKS가 없으면 API 키로 인증하거나 API 키 프로필을 만드세요.

langsmith auth login

이것은 브라우저 기반 인증 흐름을 열고 선택한 프로필 아래 ~/.langsmith/config.json에 OAuth 토큰을 저장합니다. --profile 또는 LANGSMITH_PROFILE로 프로필을 선택하세요:

langsmith auth login --profile dev
langsmith --profile dev project list

헤드리스 환경에서는 --no-browser를 전달하고 출력된 URL을 수동으로 여세요:

langsmith auth login --no-browser --workspace-id <workspace-id>

저장된 프로필을 관리하려면:

langsmith profile list
langsmith profile create dev --workspace-id <workspace-id> --set-current
langsmith profile use dev
langsmith profile set-workspace <workspace-id>

전체 프로필 구성 레퍼런스는 프로필 구성을 참고하세요.

API 키로 직접 인증할 수도 있습니다.

API 키를 환경 변수로 설정합니다:

export LANGSMITH_API_KEY="lsv2_..."

선택적으로 조회용 기본 프로젝트를 설정합니다:

export LANGSMITH_PROJECT="my-default-project"

LangSmith 셀프 호스팅을 사용한다면 엔드포인트도 설정합니다:

export LANGSMITH_ENDPOINT="https://your-langsmith-instance.com"

또는 명령별 플래그로 전달하세요:

langsmith --api-key lsv2_... trace list --project my-app

셀프 호스팅 인스턴스

--api-url 또는 LANGSMITH_ENDPOINT로 CLI를 인스턴스에 지정합니다. 브라우저 기반 로그인과 API 키 모두 지원됩니다.

OAuth:

LangSmith CLI v0.2.46 이상과 LangSmith 0.16 이상 배포가 필요하며, OAuth 인증 서버가 활성화되어 있어야 합니다. 차트는 /api 아래에 OAuth 인증 서버를 노출하지만, 서명 JWKS를 구성하기 전까지 해당 엔드포인트는 비활성 상태입니다. 설정 단계는 Remote MCP 활성화를 참고하세요.

OAuth 인증 서버는 Helm 차트에서 config.hostname이 설정되고 그리고 서명 JWKS가 구성된 경우(config.signingJwks 또는 config.existingSecretName의 langsmith_signing_jwks 키) 자동으로 활성화됩니다. 서명 JWKS가 없으면 OAuth 엔드포인트는 비활성 상태이며 CLI는 404를 받습니다 — 대신 API 키 탭을 사용하세요.

langsmith auth login --api-url https://langsmith.example.com --profile self-hosted

인스턴스의 기본 URL을 전달합니다. CLI는 배포의 인증 서버 메타데이터를 읽어 OAuth 엔드포인트를 찾으므로 https://langsmith.example.com과 https://langsmith.example.com/api 모두 동작합니다.

토큰은 명명된 프로필 아래에 저장되므로 이후 명령은 --profile만 필요합니다:

langsmith --profile self-hosted project list

API key:

모든 LangSmith 버전에서 동작합니다.

export LANGSMITH_ENDPOINT="https://langsmith.example.com"
export LANGSMITH_API_KEY="lsv2_..."

langsmith project list

엔드포인트와 키를 재사용 가능한 프로필로 저장하려면:

LANGSMITH_API_KEY="lsv2_..." langsmith profile create self-hosted \
  --api-url https://langsmith.example.com --set-current

경고: LANGSMITH_ENDPOINT는 프로필의 api_url보다 우선합니다. 셸에 설정되어 있으면 선택한 모든 프로필이 해당 엔드포인트로 해석됩니다 — 셀프 호스팅 프로필이 활성 상태인데 명령이 뜻밖에 LangSmith Cloud에 도달하는 흔한 원인입니다. 프로필로 작업할 때는 이를 해제하거나 --api-url을 명시적으로 전달하세요.

퀵스타트

다음 명령이 핵심 리소스 유형을 다룹니다:

# List tracing projects
langsmith project list

# List recent traces in a project
langsmith trace list --project my-app --limit 5

# Get a specific trace with full detail
langsmith trace get <trace-id> --project my-app --full

# List LLM runs with token counts
langsmith run list --project my-app --run-type llm --include-metadata

# Datasets and experiments
langsmith dataset list
langsmith experiment list --dataset my-eval-set

# Conversation threads
langsmith thread list --project my-chatbot

# Sandboxes
langsmith sandbox list
langsmith sandbox tunnel my-vm --remote-port 5432

출력 형식

기본(Default)

사람이 읽을 수 있는 테이블:

langsmith trace list --project my-app

JSON

파이프, 스크립트, 에이전트 공급을 위한 --format json:

langsmith --format json trace list --project my-app

파일로 쓰기

-o <path>:

langsmith trace list --project my-app -o traces.json

명령

각 명령 그룹은 특정 LangSmith 리소스를 대상으로 합니다. 대부분 명령은 --limit, --offset, 공유 필터 플래그를 지원합니다.

프로젝트 목록

기본적으로 최근 활동순으로 최대 20개 프로젝트를 반환합니다. 트레이싱 프로젝트만 나열합니다. (평가 실험을 나열하려면 experiment list 사용)

langsmith project list
langsmith project list --limit 50 --name-contains chatbot
langsmith --format json project list

트레이스 조회

기본값은 최근 7일, 최신순입니다. --since 또는 --last-n-minutes를 사용해 시간 창을 변경하세요.

langsmith trace list --project my-app --limit 50 --last-n-minutes 60
langsmith trace list --project my-app --error                     # errors only
langsmith trace list --project my-app --min-latency 5             # slow traces (>5s)
langsmith trace list --project my-app --tags production           # filter by tag
langsmith trace list --project my-app --full                      # all fields
langsmith trace list --project my-app --show-hierarchy --limit 3  # include full run tree
langsmith trace get <trace-id> --project my-app --full
langsmith trace export ./traces --project my-app --limit 20 --full

실행 조회

기본값은 50개 결과입니다 (대부분 다른 명령은 20개 기본). 동일한 7일 시간 창이 적용됩니다. --since 또는 --last-n-minutes로 재정의하세요.

langsmith run list --project my-app --run-type llm
langsmith run list --project my-app --run-type tool --name search
langsmith run list --project my-app --min-tokens 1000 --include-metadata
langsmith run get <run-id> --full
langsmith run export llm_calls.jsonl --project my-app --run-type llm --full

스레드 조회

모든 스레드 명령에 --project가 필요합니다.

langsmith thread list --project my-chatbot --last-n-minutes 120
langsmith thread get <thread-id> --project my-chatbot --full

데이터셋 관리

dataset export는 데이터셋 자체의 메타데이터가 아니라 데이터셋 내의 예제(행)를 내보냅니다.

langsmith dataset list
langsmith dataset list --name-contains eval
langsmith dataset get my-dataset
langsmith dataset create --name my-eval-set --description "QA pairs for v2"
langsmith dataset delete my-old-dataset --yes
langsmith dataset export my-dataset ./data.json --limit 500
langsmith dataset upload data.json --name new-dataset

예제 관리

생성 또는 나열 시 --split을 사용해 예제를 명명된 분할(예: test 또는 train)에 배정합니다.

langsmith example list --dataset my-dataset --limit 50
langsmith example list --dataset my-dataset --split test
langsmith example create --dataset my-dataset \
  --inputs '{"question": "What is LangSmith?"}' \
  --outputs '{"answer": "A platform for LLM observability"}' \
  --split test
langsmith example delete <example-id> --yes

평가자 관리

평가자는 오프라인(실험 중 데이터셋에 대해 실행) 또는 온라인(라이브 프로젝트에 대해 실행)일 수 있습니다. --sampling-rate를 사용해 프로덕션 실행의 일부만 평가하고, --replace로 이름으로 기존 평가자를 덮어씁니다.

langsmith evaluator list
langsmith evaluator upload evals.py --name accuracy \
  --function check_accuracy --dataset my-eval-set
langsmith evaluator upload evals.py --name latency-check \
  --function check_latency --project my-app --sampling-rate 0.5
langsmith evaluator upload evals.py --name accuracy \
  --function check_accuracy_v2 --dataset my-eval-set --replace --yes
langsmith evaluator delete accuracy --yes

실험 보기

experiment list는 트레이싱 프로젝트가 아닌 평가 실험을 보여줍니다. (트레이싱 프로젝트를 나열하려면 project list 사용)

langsmith experiment list
langsmith experiment list --dataset my-eval-set
langsmith experiment get my-experiment-2024-01-15

샌드박스 관리

샌드박스 명령으로 스냅샷 구축, 샌드박스 생성, 명령 실행, 인터랙티브 콘솔 열기, 샌드박스 내부에서 실행 중인 서비스로 TCP 포트 터널링을 할 수 있습니다.

전체 샌드박스 명령 레퍼런스는 Sandbox CLI를 참고하세요.

LangSmith API 직접 호출

api 명령은 원시 LangSmith REST API 주변의 인증된 스크립트 가능한 래퍼입니다 — 위의 타입 명령이 다루지 않는 엔드포인트나 셸 스크립트에서 JSON을 주고받을 때 유용합니다. gh api와 curl을 모델로 했습니다: 유일한 위치 인자로 경로를 전달하고, -X로 HTTP 메서드를 설정합니다(기본값 GET). 인증 헤더(x-api-key, x-tenant-id)는 자동으로 주입됩니다.

# GET (default method) — query string supported in the path
langsmith api sessions?limit=5

# Discover endpoints from the OpenAPI spec
langsmith api ls --tag datasets
langsmith api info GET sessions

# Typed JSON fields with -F (numbers, booleans, null, objects, arrays parsed as JSON)
# Method auto-promotes to POST when -F/-f/--input/--body is supplied
langsmith api runs/query -F session_id=abc -F limit=10

# String-typed fields with -f (always sent as a JSON string, even if numeric)
langsmith api datasets -f name=my-dataset -f description="QA pairs"

# Other HTTP methods via -X
langsmith api sessions/abc-123 -X DELETE

# Send a request body from a file or stdin
langsmith api datasets --input create-dataset.json
echo '{"name":"test"}' | langsmith api sessions --input -

# Force GET with fields — fields go to the query string instead of a body
langsmith api runs -X GET -F limit=5 -F session=abc

# Inspect response status + headers
langsmith api sessions --include

# Add custom headers
langsmith api sessions -H "Accept: text/csv"

주요 플래그:

Flag	Short	Default	Description
`--method`	`-X`	`GET`	HTTP method
`--field`	`-F`	—	Typed JSON field as `key=value`. Repeatable. Use `@<path>` or `@-` for file/stdin values.
`--raw-field`	`-f`	—	String JSON field as `key=value`. Repeatable.
`--input`	—	—	File to use as the request body (`-` for stdin)
`--body`	—	—	Raw request body (JSON string, `@file`, or `@-` for stdin)
`--header`	`-H`	—	Additional headers as `Key:Value`. Repeatable.
`--include`	`-i`	`false`	Print response status line and headers before body

--input과 --body는 상호 배타적입니다. 하위 명령 langsmith api ls와 langsmith api info는 캐시된 OpenAPI 스펙에서 엔드포인트를 탐색·설명합니다 — 다시 가져오려면 --refresh를 전달하세요.

필터 플래그

대부분의 trace 및 run 명령이 다음 필터를 공유합니다:

Flag	Description	Example
`--project`	Project name	`--project my-app`
`--limit, -n`	Max results	`-n 10`
`--offset`	Pagination offset	`--offset 20`
`--last-n-minutes`	Override the 7-day default	`--last-n-minutes 60`
`--since`	After ISO timestamp	`--since 2024-01-15T00:00:00Z`
`--error` / `--no-error`	Filter by error status	`--error`
`--name`	Name search (case-insensitive)	`--name ChatOpenAI`
`--run-type`	Run type (`llm` or `tool`)	`--run-type llm`
`--min-latency` / `--max-latency`	Latency range in seconds	`--min-latency 2.5`
`--min-tokens`	Minimum total tokens	`--min-tokens 1000`
`--tags`	Tags, comma-separated (OR logic)	`--tags prod,v2`
`--filter`	Raw LangSmith filter DSL	`--filter 'eq(status, "error")'`
`--trace-ids`	Specific trace IDs	`--trace-ids abc123,def456`

세부 플래그 — 응답에 포함되는 필드를 제어합니다:

Flag	Adds
`--include-metadata`	Status, duration, tokens, costs
`--include-io`	Inputs, outputs, error
`--include-feedback`	Feedback stats
`--full`	All of the above
`--show-hierarchy`	Full run tree (traces only)

더 알아보기

Sandbox CLI — 전체 샌드박스 명령 레퍼런스.
프로필 구성 — 프로필 설정 상세.