LangSmith CLI

从终端查询和管理 LangSmith 项目、追踪、运行、数据集、评估器、实验和线程

LangSmith CLI 是一个用于查询和管理你 LangSmith 数据的命令行工具。它既为开发者也为 AI 编码 agent 设计，默认输出人类可读的表格，并带一个 --format json 选项用于脚本。当你需要对你 LangSmith 数据的可脚本化访问时使用它，例如批量导出、自动化，或给一个编码 agent 对你追踪、运行和数据集的直接访问。

安装

macOS / Linux (recommended)

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

Windows

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

Homebrew

brew install langchain-ai/tap/langsmith-cli

Scoop

scoop install langsmith-cli

GitHub Releases

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

Go install

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

随时升级：

langsmith self-update

使用 --dry-run 标志在不安装的情况下预览更新。

NOTE

查询由 SmithDB 支撑的部署需要 LangSmith CLI v0.2.44 或更高版本。

身份认证

langsmith auth login 需要 LangSmith CLI v0.2.30 或更高版本。langsmith profile 命令需要 LangSmith CLI v0.2.26 或更高版本。

推荐的本地设置是用 OAuth 进行身份验证：

NOTE

langsmith auth login 从 LangSmith CLI v0.2.46 起也能针对自托管实例工作，前提是部署在 LangSmith 0.16 或更高版本并已启用 OAuth 授权服务器（需要配置一个签名 JWKS）。参阅自托管实例。在更早的部署上，或没有签名 JWKS 时，用 API 密钥进行身份验证或创建一个 API-key 配置文件。

langsmith auth login

这会打开一个基于浏览器的授权流程，并把 OAuth 令牌存入 ~/.langsmith/config.json 下所选的配置文件。用 --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 密钥都受支持。

需要 LangSmith CLI v0.2.46 或更高版本，以及一个在 LangSmith 0.16 或更高版本、已启用 OAuth 授权服务器的部署。该 chart 在 /api 下暴露 OAuth 授权服务器，但那些端点在你配置签名 JWKS 之前保持无效。有关设置步骤，参阅启用远程 MCP。

当在你的 Helm chart 中设置了 config.hostname 并且配置了签名 JWKS（通过 config.signingJwks，或 config.existingSecretName 中的 langsmith_signing_jwks 键）时，OAuth 授权服务器会被自动启用。没有签名 JWKS 时，OAuth 端点是未激活的，CLI 会收到一个 404 —— 请改用 API key 标签。

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

WARNING

LANGSMITH_ENDPOINT 优先于配置文件的 api_url 值。如果你在 shell 中设置了它，你选择的每个配置文件都会解析到那个端点 —— 这是一个常见原因，导致命令在使用自托管配置文件时意外地访问到 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

输出格式

默认

人类可读的表格：

langsmith trace list --project my-app

JSON

--format json 用于通过管道、脚本，或把输出喂给一个 agent：

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 端口隧道。

完整的沙箱命令参考参阅沙箱 CLI。

管理自定义应用

langsmith apps 命令会脚手架、本地运行并发布自定义应用——运行在 LangSmith 内部并调用 LangSmith API 的 UI。

完整的命令列表参阅 CLI 参考。

直接调用 LangSmith API

api 命令是对原始 LangSmith REST API 的已认证、可脚本化 wrapper —— 对上面类型化命令未覆盖的端点，或把 JSON 通过管道进出 shell 脚本很有用。它仿照 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"

关键标志：

标志	简写	默认	描述
--method	-X	GET	HTTP 方法
--field	-F	—	以 key=value 形式的类型化 JSON 字段。可重复。对文件/stdin 值用 @<path> 或 @-。
--raw-field	-f	—	以 key=value 形式的字符串 JSON 字段。可重复。
--input	—	—	用作请求体的文件（- 表示 stdin）
--body	—	—	原始请求体（JSON 字符串、@file，或 @- 表示 stdin）
--header	-H	—	以 Key:Value 形式的额外标头。可重复。
--include	-i	false	在请求体之前打印响应状态行和标头

--input 和 --body 互斥。子命令 langsmith api ls 和 langsmith api info 从缓存的 OpenAPI spec 浏览并描述端点 —— 传入 --refresh 以重新拉取。

过滤标志

多数 trace 和 run 命令共享这些过滤器：

标志	描述	示例
--project	项目名	--project my-app
--limit, -n	最大结果数	-n 10
--offset	分页偏移	--offset 20
--last-n-minutes	覆盖 7 天默认值	--last-n-minutes 60
--since	在某 ISO 时间戳之后	--since 2024-01-15T00:00:00Z
--error / --no-error	按错误状态过滤	--error
--name	名称搜索（大小写不敏感）	--name ChatOpenAI
--run-type	运行类型（llm 或 tool）	--run-type llm
--min-latency / --max-latency	以秒计的延迟范围	--min-latency 2.5
--min-tokens	最小总 token 数	--min-tokens 1000
--tags	标签，逗号分隔（OR 逻辑）	--tags prod,v2
--filter	原始 LangSmith 过滤器 DSL	--filter 'eq(status, "error")'
--trace-ids	特定的追踪 ID	--trace-ids abc123,def456

详情标志 —— 控制响应中包含哪些字段：

标志	添加
--include-metadata	状态、时长、token、成本
--include-io	输入、输出、错误
--include-feedback	反馈统计
--full	以上全部
--show-hierarchy	完整的运行树（仅追踪）

---