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

安装

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

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

# 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 标志可预览更新而不安装。

身份验证

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

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

langsmith auth login

这将打开基于浏览器的授权流程，并将 OAuth 令牌存储在所选 ~/.langsmith/config.json 配置文件下的 中。使用选择一个配置文件 --profile or 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 密钥 设置为环境变量：

（可选）设置默认项目用于查询：

如果您使用的是自托管 LangSmith self-hosted，还需设置端点：

或者，按命令传递它们作为标志：

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

快速入门

以下命令涵盖核心资源类型：

# 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

输出格式

默认

JSON 输出到标准输出 — 易于管道传输、脚本化或提供给代理：

  langsmith trace list --project my-app
  

格式化表格

--format pretty 用于人类可读的输出：

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

写入文件

-o <path>:

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

命令

每个命令组针对特定的 LangSmith 资源。大多数命令支持 --limit, --offset和一组共享的 过滤标志.

列出项目

默认返回最多 20 个项目，按最近活动排序。仅列出 tracing 项目。(使用 experiment list 可列出评估实验。)

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

查询 traces

默认最近 7 天，最新的在前。使用 --since or --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

查询 runs

默认 50 条结果（大多数其他命令默认为 20）。同样适用 7 天时间范围。使用 --since or --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

查询 threads

--project 是所有 thread 命令的必需项。

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 or 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 显示评估实验，而非 tracing 项目。(使用 project list 可列出 tracing 项目。)

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

管理沙箱

沙箱命令允许您构建快照、创建沙箱、执行命令、打开交互式控制台，以及将 TCP 端口隧道传输到沙箱内运行的服务。

参见 沙箱 CLI 获取完整的沙箱命令参考。

直接调用 LangSmith API

该 api 命令是对原始 LangSmith REST API 的认证式可脚本化包装器——适用于类型化命令未覆盖的端点，或用于将 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"

关键标志：

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

筛选标志

大多数 trace 和 run 命令共享这些筛选器：

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