> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装和使用 LogBrew CLI

> 在 macOS、Linux 或 Windows 上安装 LogBrew CLI。登录、选择项目，并通过 JSON 输出排查问题。

LogBrew 命令行工具（CLI）可以在终端中读取日志、问题、链路和操作，也可以更新问题状态。使用 `--json` 可以为脚本和 AI 智能体输出结构化数据。

运行命令前，先替换所有尖括号占位符。使用 LogBrew 返回的项目、问题和链路 ID。

## 安装 CLI

选择一种安装方式。

macOS 或 Linux：

```bash theme={null}
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/LogBrewCo/cli/releases/latest/download/logbrew-cli-installer.sh | sh
```

Windows（PowerShell）：

```powershell theme={null}
powershell -ExecutionPolicy Bypass -c "irm https://github.com/LogBrewCo/cli/releases/latest/download/logbrew-cli-installer.ps1 | iex"
```

Homebrew：

```bash theme={null}
brew install LogBrewCo/tap/logbrew
```

npm：

```bash theme={null}
npm install -g logbrew-cli@latest
```

Cargo：

```bash theme={null}
cargo install logbrew-cli
```

在 Windows 上，也可以从[最新版本](https://github.com/LogBrewCo/cli/releases/latest)安装 MSI 包。

<Note>
  使用 Cargo 安装需要 Rust 1.87 或更高版本。其他方式安装的是原生二进制文件，不需要 Rust。
</Note>

## 更新 CLI

CLI 不会自动更新。用安装时的同一种方式更新。

Homebrew：

```bash theme={null}
brew update && brew upgrade LogBrewCo/tap/logbrew
```

npm：

```bash theme={null}
npm install -g logbrew-cli@latest
```

Cargo：

```bash theme={null}
cargo install --locked logbrew-cli
```

如果用的是 shell 或 PowerShell 安装脚本，重新运行一次安装脚本。

然后查看版本号。将它与[最新版本](https://github.com/LogBrewCo/cli/releases/latest)对比：

```bash theme={null}
logbrew version --json
```

JSON 输出包含 `ok`、`name`、`version`、`binary`、`os` 和 `arch`。

## 登录并验证会话

查看当前终端登录的账号：

```bash theme={null}
logbrew status --json
logbrew whoami --json
```

如果 `whoami` 显示的是预期的账号，继续下一步。否则先登录。登录提供方的认证需要由人在浏览器中完成。编码智能体必须请人来完成这一步。

```bash theme={null}
logbrew login --provider github
```

登录提供方可以是 `github`（默认）、`gitlab` 或 `bitbucket`。使用 `--no-open` 只打印登录 URL，不打开浏览器。`--json` 同样会打印登录交接信息，不打开浏览器。

登录后，再次运行 `status` 和 `whoami`。不要把账号凭据写进提示词、报告或源文件。

## 规划 SDK 接入

进入应用的包清单或构建清单所在的目录。在 monorepo 中，选择一个应用或服务。然后运行：

```bash theme={null}
logbrew setup --json
```

查看 `detected`、`install_ready`、`install_plan` 和 `next`。计划中包含运行时、框架、包管理器和安装命令。CLI 不会安装包，也不会修改文件。`logbrew init`、`install`、`configure` 和 `sdk` 给出的计划相同。

<Warning>
  在 SDK 配置中填写项目的接入密钥。不要把账号凭据当作 SDK 密钥。不要把接入密钥提交到版本控制。
</Warning>

各运行时的具体步骤见 [SDK 接入](/zh-Hans/guides/sdk-ingestion)。运行 `logbrew examples` 可查看常用命令的简短列表。

## 读取、创建和配置项目

列出账号中的活动项目：

```bash theme={null}
logbrew projects --json
```

从结果中选择一个项目 ID。创建密钥和读取数据时都用它。

要为已有项目创建接入密钥，先选一个不在版本控制中的新文件。CLI 会把密钥写入这个仅所有者可访问的文件。它不会打印密钥或文件路径。

```bash theme={null}
logbrew projects keys create "<project_id>" --ingest-key-file "<private_key_file>" --json
```

| 选项 | 值 |
| - | - |
| `--kind` | `sdk`（默认）、`browser`、`server`、`cli` 或 `artifact`。`artifact` 密钥用于上传 Source Map 和原生调试文件。它不能发送遥测数据。 |
| `--label` | 密钥名称，最多 120 个字符。默认值为 `CLI-created SDK key`。 |

JSON 结果包含 `status`、`project_id`、`ingest_key`、`checks` 和 `next`。`ingest_key` 包含密钥的 `id`、`label`、`kind`、`created_at` 和 `expires_at`。要替换密钥，参见[轮换接入密钥](/zh-Hans/guides/rotate-ingest-key)。

该命令会创建凭据。运行前，确认项目正确。如果结果不确定，再运行一次相同的命令。CLI 会复用尚未完成的那次尝试。只有要开始新的尝试时，才使用 `--abandon-retry`。

要创建新项目，按[快速入门](/zh-Hans/quickstart)操作。它使用 `logbrew projects create "<name>" --ingest-key-file "<private_key_file>"`，以同样的方式保存第一个密钥。运行 `logbrew setup --create-project` 可以查看创建项目的帮助。该命令不会创建项目。

完成某个接入步骤后，可以为项目记录这一步。`--source` 的值为 `api`、`cli` 或 `sdk`：

```bash theme={null}
logbrew projects setup "<project_id>" --source cli --environment production --json
```

然后查看项目的就绪状态：

```bash theme={null}
logbrew doctor --project "<project_id>" --json
```

退出码 `0` 并不表示所有检查都通过。查看报告的 `status` 和每一项检查。参见 [doctor 报告参考](/zh-Hans/reference/cli#read-a-project-doctor-report)。

## 查看账号用量

查看用量和限额。这不会改变账号或计费状态。

```bash theme={null}
logbrew usage --json
```

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

## 常见排查场景

每次读取都按项目筛选。命令支持时，再加上版本、环境、时间或严重程度筛选条件。参见[筛选条件](/zh-Hans/reference/cli#filters)。

<CardGroup cols={2}>
  <Card title="某个版本的问题" icon="tag">
    ```bash theme={null}
    logbrew read issues --project "<project_id>" --release api@1.2.3 --status unresolved --json
    ```
  </Card>

  <Card title="单个失败请求" icon="route">
    ```bash theme={null}
    logbrew read trace "<trace_id>" --project "<project_id>" --json
    ```
  </Card>

  <Card title="某个版本的日志" icon="file-text">
    ```bash theme={null}
    logbrew read logs --project "<project_id>" --release api@1.2.3 --since 24h --json
    ```
  </Card>

  <Card title="分配给你的问题" icon="user">
    ```bash theme={null}
    logbrew read issues --project "<project_id>" --assignee me --status unresolved --json
    ```
  </Card>
</CardGroup>

## 实时查看事件

测试改动时，用 watch 查看新产生的事件。按 Ctrl+C 停止。

```bash theme={null}
logbrew watch --severity error,critical --json
```

watch 只输出 JSON 流。不加 `--json` 时，命令会报错退出。加上 `logs`、`issues` 或 `actions` 可以只查看一种类型，例如 `logbrew watch logs --json`。watch 不支持链路或 Span（一次计时操作）。

watch 没有项目、版本或环境筛选条件。只看一个项目时，使用上面的读取命令。支持的资源和筛选条件见[实时查看](/zh-Hans/reference/cli#live-watch)。

## 修改代码前先查看解释

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

<Steps>
  <Step title="读取问题">
    ```bash theme={null}
    logbrew read issue "<issue_id>" --json
    ```
  </Step>

  <Step title="读取链路">
    只有问题带有 Trace ID 时才做这一步。没有链路的问题同样有效。

    ```bash theme={null}
    logbrew read trace "<trace_id>" --project "<project_id>" --json
    ```
  </Step>

  <Step title="读取解释">
    ```bash theme={null}
    logbrew explain issue "<issue_id>" --json
    ```

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

  <Step title="验证后再解决">
    ```bash theme={null}
    logbrew set issue "<issue_id>" resolved --json
    ```

    要批量更改问题的状态、优先级或负责人，参见[更改问题状态和优先级](/zh-Hans/reference/cli#change-issue-status-and-priority)和[管理问题](/zh-Hans/guides/issue-workflow)。
  </Step>
</Steps>

## JSON 输出

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

退出码和错误示例见[读取结果和错误](/zh-Hans/reference/cli#read-results-and-errors)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.