Lumber

@infinitetoken/lumber-cli

在终端中读取你的 Lumber 日志，并让 AI Agent 通过 MCP 读取日志。日志会在你的电脑上使用你自己的账户密钥解密，因此 Lumber 的服务器仍然无法读取日志。

可在 macOS、Windows 和 Linux 上运行。它只读取数据；绝不会更改 Lumber 中的任何内容。

安装

npm install -g @infinitetoken/lumber-cli

此软件包使用了作用域名称：npm 上不带作用域的 lumber 和 lumber-cli 属于其他人。

也可以通过 Homebrew 安装，适用于 macOS 或 Linux。此仓库就是 tap：

brew tap infinitetoken/lumber https://github.com/infinitetoken/Lumber-CLI

brew install infinitetoken/lumber/lumber

首次使用完整名称，Homebrew 才会信任该 formula。使用 brew upgrade lumber 更新。

登录

lumber login

使用你的 Lumber 邮箱和密码登录，然后像关联新手机一样关联这台电脑：在已拥有你账户密钥的手机或 Mac 上打开 Lumber（手机会收到通知；切换到 Mac 应用时会弹出询问，或者打开“账户”>“关联另一台设备”），点按“显示代码”，然后在 Code 提示符处输入 7 位代码。该设备会验证代码并发送你的账户密钥。请求有效期为 10 分钟，输错代码会使请求失效。另一台设备需要安装最新版本的 Lumber 应用。

会话和账户密钥保存在系统自带的凭据存储中，绝不会存入文件：

• macOS：登录钥匙串中的“Lumber CLI”项目。
• Windows：凭据管理器中的通用凭据 session.Lumber CLI。
• Linux：由 GNOME Keyring 和 KWallet 提供的 Secret Service 中的“Lumber CLI”项目。桌面会话自带此服务；如果服务器或 SSH 会话中没有运行该服务，lumber 会说明情况并停止。

只要你每天使用，系统就会自动续期会话，因此只有连续 30 天未运行 lumber 后会话才会结束。届时以同一身份重新登录，无需再次关联设备。lumber logout 会移除两者。

命令

lumber status                          # who's signed in, which apps this computer can read
lumber apps                            # your apps
lumber logs                            # the newest 100 logs from every app, oldest at the bottom
lumber logs Lumber-Test -l error -s 2h # one app's errors and fatals from the last two hours
lumber logs -g "payment" -n 20         # the newest 20 logs mentioning "payment"
lumber tail Lumber-Test -l warn        # follow new warnings and worse as they arrive
lumber help                            # everything, and `lumber logs help` for one command

• 应用可以用名称（大小写均可）或 ID 指定。不指定则表示所有应用。
• -l, --level 可以指定一个级别，此时包含该级别及以上级别（warn 表示 warn、error 和 fatal）；也可以指定列表，此时仅包含指定级别（info,warn）。
• -s, --since 和 -u, --until 可使用时间长度（15m、2h、3d）、日期（2026-10-29、today、yesterday）或 ISO 时间。
• -g, --grep 会匹配消息、请求和跟踪 ID、上下文及元数据，且不区分大小写。服务器只存储密文，因此搜索会在本地执行，最多读取 20,000 条日志。
• -v, --verbose 会在每条日志下方显示其 ID、各类 ID、上下文和元数据。--json 会为每条日志输出一个 JSON 对象，供脚本和 Agent 使用。
• tail 会通过 Lumber 的实时连接跟踪 Dev 和 Pro 方案中的应用，并每 5 秒检查一次其他应用。在终端中，连接状态会显示在日志下方的一行中；-q 可隐藏该行。
• 在命令行的任意位置输入 help 都会显示帮助信息，因此 lumber logs -g help 会显示帮助，而不是执行搜索。若要搜索 Help，请改用 -g Help：匹配时不区分大小写。
• npm 上有新版本时，在终端运行的命令会在输出后提示新版本，并附上更新命令；每天最多提示一次。命令运行期间每天最多向 npm 查询一次，因此不会拖慢运行速度。tail、mcp、管道输出和 CI 均不会检查更新；设置 LUMBER_NO_UPDATE_CHECK=1 可关闭检查。

输出会采用各应用的颜色：微调指示器、帮助信息和提示会使用你的强调色（即你在 Lumber“账户”界面中选择的颜色），各级别使用对应颜色，每个应用名称前会显示一个与其颜色相同的方块。输出通过管道传递或使用 --json 时，则为纯文本。

AI Agent（MCP）

lumber mcp 会通过 stdio 提供与 MCP 工具相同的读取功能，并使用已保存的会话 lumber login。

Claude Code：

claude mcp add lumber -- lumber mcp

在 Windows 上，npm 会将 lumber 安装为 .cmd 文件，Agent 只能通过 cmd 启动该文件：

claude mcp add lumber -- cmd /c lumber mcp

Claude Desktop，在其 claude_desktop_config.json 中配置（在 macOS 和 Linux 上，使用 which lumber 输出的完整路径，因为该应用不会读取你的 shell PATH）：

{
  "mcpServers": {
    "lumber": { "command": "/opt/homebrew/bin/lumber", "args": ["mcp"] }
  }
}

在 Windows 上：

{
  "mcpServers": {
    "lumber": { "command": "cmd", "args": ["/c", "lumber", "mcp"] }
  }
}

工具：

• list_apps：列出你的应用，以及这台计算机能否读取每个应用。
• search_logs：搜索与指定应用、级别、时间范围和文本匹配的最新日志。
• wait_for_logs：等待新日志（除非另有说明，否则只等待错误和致命错误），并按消息分组返回，同时提供 next_after 以便传回，让 Agent 能在循环中监视而不漏掉或重复处理日志。
• list_notes：列出人们对某个应用日志写下的备注，以及备注作者。

让 Agent 监视错误

除非你启动监视，否则不会有任何监视任务运行。在 Claude Code 中，可以这样提出要求：

使用 wait_for_logs 监视 Lumber-Test 的错误。出现错误时，在此仓库中查找原因并修复，将更改留给我审核。

或者让它运行 lumber tail Lumber-Test -l error --json -q，该命令会为每条错误打印一行。

日志消息、上下文和元数据由你的应用及其使用者写入：表单字段、URL 或精心构造的请求都可能出现在日志中。每个工具都会告知 Agent 这一点，但能够编辑你代码的 Agent 读取的是任何人都可能写下的文本。请保留更改供审核，不要让它直接部署。

如何保护隐私

每个应用的日志在离开你的服务器前，都会使用该应用专属的密钥加密（AES-256-GCM）。服务器会保留每个应用密钥的副本，并使用每个人的账户密钥对其进行封装；服务器无法解封。关联时，批准设备会使用这台计算机为关联生成的密钥封装你的账户密钥，并将其交给这台计算机。你输入的代码会将该密钥绑定到此次关联；随后，账户密钥会带有只有该代码才能提供的秘密标记返回，因此服务器既无法选择你的账户密钥发往何处，也无法把自己的密钥交给这台计算机。之后，每条命令都会获取密文并在本机解密。

要求

• macOS、Windows，或使用 Secret Service（GNOME Keyring 或 KWallet）的 Linux。
• Node 20 或更高版本。
• 一个 Lumber 账户，以及一台已持有你账户密钥的手机或 Mac，用于显示关联这台计算机的代码。

发布

为发布版本打标签即可触发发布工作流：

npm run release:patch   # or release:minor / release:major: verifies, tags and pushes

许可证

MIT