LangSmith CLI

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

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

身份验证

langsmith auth login 需要 LangSmith CLI v0.2.30 或更高版本。langsmith profile 命令需要 LangSmith CLI v0.2.26 或更高版本。推荐的本地设置方式是使用 OAuth 进行身份验证：

langsmith auth login 目前仅支持 LangSmith Cloud（SaaS）。对于自托管或其他非 SaaS 的 LangSmith 端点，请使用 API 密钥进行身份验证，或创建 API 密钥配置文件。

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

快速入门

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

# 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 输出到 stdout，便于通过管道传递、编写脚本或提供给代理：

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 个项目，并按最近活动时间排序。仅列出跟踪项目。（使用 experiment list 列出评估实验。）

langsmith project list
langsmith project list --limit 50 --name-contains chatbot
langsmith --format pretty 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 的、经过身份验证且支持脚本调用的封装器，适用于上述类型化命令未涵盖的端点，或用于在 shell 脚本中通过管道传入和传出 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"

主要标志：

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

--input 和 --body 不能同时使用。子命令 langsmith api ls 和 langsmith api info 可从缓存的 OpenAPI 规范中浏览和描述端点；传入 --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`	Status、持续时间、token、成本
`--include-io`	输入、输出、错误
`--include-feedback`	反馈统计信息
`--full`	以上所有内容
`--show-hierarchy`	完整的运行记录树（仅跟踪记录）

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Organization

Users & access control

Tools

Auditing

Data & compliance

Additional resources

安装

身份验证

快速入门

输出格式

命令

列出项目

查询跟踪记录

查询运行记录

查询线程

管理数据集

管理示例

管理评估器

查看实验

管理沙箱

直接调用 LangSmith API

筛选标志

​安装

​身份验证

​快速入门

​输出格式

​命令

​列出项目

​查询跟踪记录

​查询运行记录

​查询线程

​管理数据集

​管理示例

​管理评估器

​查看实验

​管理沙箱

​直接调用 LangSmith API

​筛选标志

安装

身份验证

快速入门

输出格式

命令

列出项目

查询跟踪记录

查询运行记录

查询线程

管理数据集

管理示例

管理评估器

查看实验

管理沙箱

直接调用 LangSmith API

筛选标志