Skip to main content
LogBrew 命令行工具（CLI）可以在终端中读取日志、问题、链路和操作，也可以更新问题状态。使用 --json 可以为脚本和 AI 智能体输出结构化数据。 运行命令前，先替换所有尖括号占位符。使用 LogBrew 返回的项目、问题和链路 ID。

​
安装 CLI

选择一种安装方式。 macOS 或 Linux：
Windows（PowerShell）：
Homebrew：
npm：
Cargo：
在 Windows 上，也可以从最新版本安装 MSI 包。
使用 Cargo 安装需要 Rust 1.87 或更高版本。其他方式安装的是原生二进制文件，不需要 Rust。

​
更新 CLI

CLI 不会自动更新。用安装时的同一种方式更新。 Homebrew：
npm：
Cargo：
如果用的是 shell 或 PowerShell 安装脚本，重新运行一次安装脚本。 然后查看版本号。将它与最新版本对比：
JSON 输出包含 ok、name、version、binary、os 和 arch。

​
登录并验证会话

查看当前终端登录的账号：
如果 whoami 显示的是预期的账号，继续下一步。否则先登录。登录提供方的认证需要由人在浏览器中完成。编码智能体必须请人来完成这一步。
登录提供方可以是 github（默认）、gitlab 或 bitbucket。使用 --no-open 只打印登录 URL，不打开浏览器。--json 同样会打印登录交接信息，不打开浏览器。 登录后，再次运行 status 和 whoami。不要把账号凭据写进提示词、报告或源文件。

​
规划 SDK 接入

进入应用的包清单或构建清单所在的目录。在 monorepo 中，选择一个应用或服务。然后运行：
查看 detected、install_ready、install_plan 和 next。计划中包含运行时、框架、包管理器和安装命令。CLI 不会安装包，也不会修改文件。logbrew init、install、configure 和 sdk 给出的计划相同。
在 SDK 配置中填写项目的接入密钥。不要把账号凭据当作 SDK 密钥。不要把接入密钥提交到版本控制。
各运行时的具体步骤见 SDK 接入。运行 logbrew examples 可查看常用命令的简短列表。

​
读取、创建和配置项目

列出账号中的活动项目：
从结果中选择一个项目 ID。创建密钥和读取数据时都用它。 要为已有项目创建接入密钥，先选一个不在版本控制中的新文件。CLI 会把密钥写入这个仅所有者可访问的文件。它不会打印密钥或文件路径。
JSON 结果包含 status、project_id、ingest_key、checks 和 next。ingest_key 包含密钥的 id、label、kind、created_at 和 expires_at。要替换密钥，参见轮换接入密钥。 该命令会创建凭据。运行前，确认项目正确。如果结果不确定，再运行一次相同的命令。CLI 会复用尚未完成的那次尝试。只有要开始新的尝试时，才使用 --abandon-retry。 要创建新项目，按快速入门操作。它使用 logbrew projects create "<name>" --ingest-key-file "<private_key_file>"，以同样的方式保存第一个密钥。运行 logbrew setup --create-project 可以查看创建项目的帮助。该命令不会创建项目。 完成某个接入步骤后，可以为项目记录这一步。--source 的值为 api、cli 或 sdk：
然后查看项目的就绪状态：
退出码 0 并不表示所有检查都通过。查看报告的 status 和每一项检查。参见 doctor 报告参考。

​
查看账号用量

查看用量和限额。这不会改变账号或计费状态。
logbrew account usage --json 的结果相同。响应包含套餐、配额状态、重置日期、按项目和按遥测类型统计的用量总计，以及下一步建议。字段包括 plan、state、reset_at、by_project、by_stream 和 next。

​
常见排查场景

每次读取都按项目筛选。命令支持时，再加上版本、环境、时间或严重程度筛选条件。参见筛选条件。

某个版本的问题

单个失败请求

某个版本的日志

分配给你的问题

​
实时查看事件

测试改动时，用 watch 查看新产生的事件。按 Ctrl+C 停止。
watch 只输出 JSON 流。不加 --json 时，命令会报错退出。加上 logs、issues 或 actions 可以只查看一种类型，例如 logbrew watch logs --json。watch 不支持链路或 Span（一次计时操作）。 watch 没有项目、版本或环境筛选条件。只看一个项目时，使用上面的读取命令。支持的资源和筛选条件见实时查看。

​
修改代码前先查看解释

提出修复方案前，先读取上下文。
1

读取问题

2

读取链路

只有问题带有 Trace ID 时才做这一步。没有链路的问题同样有效。
3

读取解释

对于日志，使用 logbrew explain log "<log_id>" --json。对于操作，使用 logbrew explain action "<action_id>" --json。
4

验证后再解决

要批量更改问题的状态、优先级或负责人，参见更改问题状态和优先级和管理问题。

​
JSON 输出

  • --json 可以放在命令前面或后面，例如 logbrew --json status 或 logbrew status --json。
  • 使用输出之前，先检查退出码。
  • JSON 错误包含 ok、error、message 和 next。超时并不能证明写入失败。重复执行写操作之前，先阅读它的重试规则。
  • 不要基于没有 --json 的输出做自动化。这类输出可能会变化。
退出码和错误示例见读取结果和错误。