setup-lw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set Up the LangWatch CLI

设置 LangWatch CLI

Get the CLI authenticated and talking to the right LangWatch project, then verify. The troubleshooting table at the end covers the common failure modes.

先让 CLI 完成认证并连接到正确的 LangWatch 项目，然后进行验证。文末的故障排查表涵盖常见故障模式。

Step 1: Credentials

第 1 步：凭据

IMPORTANT: You will need a LangWatch API key. Check whether LANGWATCH_API_KEY is already set: in the process environment, which is where CI injects it, and otherwise in the project's .env file. Use that key instead of asking for a new one. Read LANGWATCH_ENDPOINT from the same places, and nothing else out of .env: if the endpoint is set, the project is on a self-hosted instance, and the CLI works against that endpoint instead of app.langwatch.ai.

For CI and agents, configure non-interactively, and never block on a browser. Have the runner inject the key from your secret store into

LANGWATCH_API_KEY

, which is what the CLI reads:

yaml

undefined

**重要：**你需要一个 LangWatch API key。先检查

LANGWATCH_API_KEY

是否已设置：检查进程环境（CI 会将 key 注入此处）；如果其中没有，则检查项目的

.env

文件。直接使用该 key，不要重新索取。也从相同位置读取

LANGWATCH_ENDPOINT

，并且不要从

.env

中读取其他内容：如果设置了 endpoint，说明项目位于 self-hosted 实例上，CLI 将针对该 endpoint 工作，而不是

app.langwatch.ai

。

对于 CI 和 Agent，应进行非交互式配置，并且绝不能阻塞等待浏览器。让 runner 从 secret store 将 key 注入

LANGWATCH_API_KEY

，CLI 会读取该变量：

yaml

undefined

GitHub Actions; any secret store works the same way

env: LANGWATCH_API_KEY: ${{ secrets.LANGWATCH_API_KEY }} LANGWATCH_ENDPOINT: https://lw.acme.internal # self-hosted only; omit for cloud


That variable is the whole of the CI setup: every command resolves the key from the environment, so there is no `login` call to make. Keep the key off the command line: an argument is readable by every other process on the machine, and in a shell it lands in your history file.

Locally, run plain `langwatch login`. It asks where you are logging in (cloud or self-hosted) and how you will use LangWatch (AI tools, project SDK key, or both), then finishes in the browser. No credential is ever typed or pasted into the terminal: you pick the project on the approval page and its key comes back to the CLI over the same channel, so none of it reaches your shell history. A project SDK key lands as `LANGWATCH_API_KEY` in `.env` in the current directory, so keep `.env` out of version control; an AI-tools login lands in `~/.langwatch/config.json`. `langwatch login --device` skips the questions and goes straight to that RFC 8628 device flow via company SSO.

`langwatch login --api-key <key>` writes a key you already hold straight to `.env`, with no browser and no prompts. It is the only non-interactive way to hand `login` a key, and the key travels through the process argument list, so it is not how a runner should supply one: with `LANGWATCH_API_KEY` set the CLI already has the key, and the flag adds nothing but the file. Reach for it when something downstream genuinely needs the key on disk. It rewrites an existing `LANGWATCH_API_KEY` line rather than adding a second one, which is why it beats appending to `.env` from a shell: a second line makes the credential ambiguous, and one re-run of an append is all it takes to get one.

`langwatch login --project <slug>` writes a project's key to `.env` with no key on the command line either, but it authenticates through an existing device login, so it suits a developer machine or a long-lived agent box rather than a fresh CI runner.

`--endpoint https://lw.acme.internal` combines with any of these to pin a self-hosted instance. It pins the CLI; your instrumented app reads `LANGWATCH_ENDPOINT` from the environment, so a self-hosted setup needs both.

env: LANGWATCH_API_KEY: ${{ secrets.LANGWATCH_API_KEY }} LANGWATCH_ENDPOINT: https://lw.acme.internal # self-hosted only; omit for cloud


该变量就是 CI 配置的全部内容：每条命令都会从环境变量中解析 key，因此无需执行 `login`。不要把 key 放在命令行上：作为参数时，机器上的其他所有进程都能读取到它；在 shell 中，它还会进入历史文件。

在本地，直接运行 `langwatch login`。它会询问登录位置（cloud 或 self-hosted）以及使用 LangWatch 的方式（AI tools、项目 SDK key，或两者兼有），然后在浏览器中完成。整个过程中绝不会在终端中输入或粘贴任何凭据：你只需在授权页面上选择项目，其 key 就会通过同一通道返回 CLI，因此不会进入 shell history。项目 SDK key 会以 `LANGWATCH_API_KEY` 的形式写入当前目录的 `.env`，因此不要将 `.env` 纳入版本控制；AI-tools 登录结果则会写入 `~/.langwatch/config.json`。`langwatch login --device` 会跳过这些问答，直接通过公司 SSO 进入 RFC 8628 device flow。

`langwatch login --api-key <key>` 会将已经持有的 key 直接写入 `.env`，无需浏览器，也不会显示 prompt。这是向 `login` 提供 key 的唯一非交互方式；但 key 会经过进程参数列表，因此 runner 不应以此方式提供：设置 `LANGWATCH_API_KEY` 后，CLI 已经拥有该 key，而该 flag 除了写入文件之外没有任何额外作用。只有当下游确实需要磁盘上存在 key 时，才应使用它。它会重写已有的 `LANGWATCH_API_KEY` 行，而不是再添加一行；这也是它优于从 shell 向 `.env` 追加内容的原因：出现第二行会让凭据产生歧义，而只需重新运行一次追加操作，就会出现重复项。

`langwatch login --project <slug>` 同样无需在命令行中携带 key，即可将项目的 key 写入 `.env`，但它会通过现有的 device login 完成认证，因此适合开发机或长期运行的 Agent 主机，而不适合全新的 CI runner。

`--endpoint https://lw.acme.internal` 可与上述任何方式结合使用，以固定 self-hosted 实例。它固定的是 CLI；经过 instrumentation 的应用会从环境变量中读取 `LANGWATCH_ENDPOINT`，因此 self-hosted 配置需要同时设置两者。

Step 2: Endpoint and Project

第 2 步：Endpoint 与项目

Cloud (app.langwatch.ai) needs no endpoint configuration.
Self-hosted: the endpoint resolves flag > env > config > default. Persist it with
```
langwatch config set endpoint https://lw.acme.internal
```
, or export
```
LANGWATCH_ENDPOINT
```
per shell.
Project: the API key determines the project. Check you're in the right one:

bash

langwatch projects list -o json

A personal access token (PAT) instead of a project key also needs

LANGWATCH_PROJECT_ID

set.

Cloud（
```
app.langwatch.ai
```
）无需配置 endpoint。
Self-hosted：endpoint 的解析顺序为 flag > env > config > default。可使用
```
langwatch config set endpoint https://lw.acme.internal
```
持久保存，或针对每个 shell 进行导出。
项目：API key 决定项目。检查是否处于正确的项目：

bash

langwatch projects list -o json

如果使用个人访问令牌（PAT）而不是项目 key，还必须设置

LANGWATCH_PROJECT_ID

。

Step 3: Verify

第 3 步：验证

bash

langwatch whoami          # device-session identity (governance plane)
langwatch status          # resource counts: proves auth + endpoint + project in one shot

langwatch status

printing resource counts means the setup is done. Everything else (traces, evaluations, scenarios) builds on this.

bash

langwatch whoami          # device-session identity (governance plane)
langwatch status          # resource counts: proves auth + endpoint + project in one shot

langwatch status

输出资源数量即表示设置完成。后续所有功能（traces、evaluations、scenarios）都构建在此基础之上。

Step 4: Discover What You Can Do

第 4 步：发现可用功能

Use

langwatch docs <path>

to read documentation as Markdown. Some useful entry points:

bash

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

Discover commands with

langwatch --help

and

langwatch <subcommand> --help

. List and get commands accept

--format json

for machine-readable output. Every list command takes

--limit <n>

to cap the rows and

--jq <expr>

to read part of the answer. A paginated list answers with an envelope, so count its rows through the row array (

--jq '.traces | length'

), and read how many there are in all at

.pagination.total

. Bare

--jq length

counts the fields of the envelope, not the rows. Read the docs first instead of guessing SDK APIs or CLI flags.

If no shell is available, fetch the same Markdown over plain HTTP. Append

.md

to any docs path (e.g. https://langwatch.ai/docs/integration/python/guide.md). Index: https://langwatch.ai/docs/llms.txt. Scenario index: https://langwatch.ai/scenario/llms.txt

If anything fails or confuses you while following this skill (broken commands, docs that do not match reality, errors you had to work around), ask the user for permission and run

npx --yes langwatch report --user-approved

with a

--title

and

--summary

(or

--session <transcript.jsonl>

) to send it to the LangWatch team, and it directly shapes what gets fixed. No login or API key needed. Nothing is sent without

--user-approved

, and

--dry-run

prints the exact payload without sending anything. The title, summary and transcript are scrubbed locally first, by pattern: secrets and API keys, plus email addresses, phone numbers, card numbers and public IPv4 addresses. Anything no pattern matches is sent as written, including a contact address passed with

--email

. With

--session

, always run

--dry-run

first and let the user read the payload, because a transcript carries content they never reviewed.

npx --yes langwatch report --help

explains the options.

使用

langwatch docs <path>

以 Markdown 格式阅读文档。以下是一些实用入口：

bash

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

使用

langwatch --help

和

langwatch <subcommand> --help

发现命令。list 和 get 命令接受

--format json

以获得机器可读输出。每个 list 命令都接受

--limit <n>

来限制行数，并接受

--jq <expr>

读取结果的一部分。分页 list 会返回一个 envelope，因此应通过 row array 统计行数（

--jq '.traces | length'

），并通过

.pagination.total

查看总数。单独使用

--jq length

统计的是 envelope 的字段数，而不是行数。请先阅读文档，不要猜测 SDK API 或 CLI flag。

如果环境中没有 shell，可通过普通 HTTP 获取相同的 Markdown。给任意 docs path 追加

.md

（例如 https://langwatch.ai/docs/integration/python/guide.md）。索引：https://langwatch.ai/docs/llms.txt。Scenario 索引：https://langwatch.ai/scenario/llms.txt

如果在执行此 skill 时遇到任何失败或令人困惑的情况（命令失效、文档与实际情况不符，或者你不得不绕过错误），请征得用户许可，然后运行

npx --yes langwatch report --user-approved

，并提供

--title

和

--summary

（或

--session <transcript.jsonl>

），将其发送给 LangWatch 团队；这些反馈会直接影响后续修复。无需 login 或 API key。如果没有

--user-approved

，不会发送任何内容；

--dry-run

会打印将要发送的确切 payload，但不会发送。title、summary 和 transcript 会先在本地按模式进行脱敏：包括 secrets、API keys，以及电子邮件地址、电话号码、银行卡号和 public IPv4 地址。任何未被模式匹配的内容都会按原样发送，包括通过

--email

传入的联系地址。使用

--session

时，务必先运行

--dry-run

并让用户阅读 payload，因为 transcript 可能包含他们从未审阅过的内容。

npx --yes langwatch report --help

会说明各个选项。

Troubleshooting

故障排查

Symptom	Likely cause	Fix
`401` / `unauthorized` on every command	Wrong, revoked, or missing API key	Re-run `langwatch login` ; check `LANGWATCH_API_KEY` in `.env` and the shell (shell wins)
`401` with a PAT	Missing project id	`export LANGWATCH_PROJECT_ID=<your-project-id>`
Connection refused / DNS errors	Self-hosted endpoint wrong or unreachable	Check `langwatch config get endpoint` and `LANGWATCH_ENDPOINT` ; verify the instance URL loads in a browser from this machine
Right credentials, wrong data	Talking to the wrong project or instance	`langwatch projects list` ; re-login with a key from the intended project
Old shell ignores new `.env`	Env vars already exported	Start a new shell, or `unset LANGWATCH_API_KEY LANGWATCH_ENDPOINT` so `.env` is re-read
A command hangs waiting for input	Interactive prompt in a non-interactive context	No flag answers prompts globally. Set `LANGWATCH_API_KEY` so nothing needs `login` , then pass the flag that command takes: `--force` for `prompt tag delete` , `--force-local` or `--force-remote` for `prompt push` , `-y` for `logout` , `skills install` , `skills uninstall` and `skills update` . `-o json` only selects an output format; on `skills` it turns the confirmation into an error rather than a prompt, elsewhere it changes nothing

症状	可能原因	修复方式
每个命令都出现 `401` / `unauthorized`	API key 错误、已吊销或缺失	重新运行 `langwatch login` ；检查 `.env` 和 shell 中的 `LANGWATCH_API_KEY` （shell 中的值优先）
使用 PAT 时出现 `401`	缺少 project id	`export LANGWATCH_PROJECT_ID=<your-project-id>`
Connection refused / DNS errors	self-hosted endpoint 错误或无法访问	检查 `langwatch config get endpoint` 和 `LANGWATCH_ENDPOINT` ；验证从本机浏览器能否打开该实例 URL
凭据正确，但数据错误	正在连接错误的项目或实例	`langwatch projects list` ；使用目标项目的 key 重新登录
旧 shell 忽略新的 `.env`	环境变量已经被导出	启动新 shell，或执行 `unset LANGWATCH_API_KEY LANGWATCH_ENDPOINT` ，让 `.env` 重新加载
命令挂起并等待输入	在非交互上下文中出现交互式 prompt	没有任何 flag 能在全局范围内自动回答 prompt。先设置 `LANGWATCH_API_KEY` ，使任何操作都不再需要 `login` ，然后传入相应命令支持的 flag： `prompt tag delete` 使用 `--force` ， `prompt push` 使用 `--force-local` 或 `--force-remote` ， `logout` 、 `skills install` 、 `skills uninstall` 和 `skills update` 使用 `-y` 。 `-o json` 只选择输出格式；对于 `skills` ，它会将确认操作变成 error 而不是 prompt，在其他命令中则不会改变任何行为