@evlog/cli 独立于你的应用运行。你可以在本地或 CI 中使用它来检查源代码、配置 evlog 并处理遥测。
从 evlog map 开始，检查 evlog 日志模式支持的入口点，并获取带有建议修复项的静态可观测性评分。除非传入 --no-write，否则它会写入 evlog.map.json。该评分描述的是已识别的源代码模式，而不是你的处理程序在生产环境中生成的日志。
evlog init 会将 evlog 配置添加到应用中。evlog agents 会为在仓库中工作的 AI agents 写入日志约定。
evlog map 目前适配 Nuxt、Nitro、Next.js App Router、TanStack Start 和 Hono。每个适配器都会识别特定的入口点形态。在解读评分之前，请检查检测到的框架和入口点数量。规则可能会在不同版本之间发生变化，因此当你根据数量对 CI 进行门控时，请固定版本pnpm dlx @evlog/cli map
bunx @evlog/cli map
npx @evlog/cli map
当你根据分数对 CI 进行门控后，把它作为开发依赖添加，这样每次运行都使用相同的版本：
pnpm add -D @evlog/cli
bunx @evlog/cli map
npm install --save-dev @evlog/cli
evlog 二进制文件。命令
全局标志
每个命令都接受以下标志：
| 标志 | 作用 |
|---|---|
--json | 在标准输出上输出机器可读的 JSON，而不是报告 |
--debug | 打印本次运行的调试摘要，并将其作为宽事件发出 |
--noHeader | 跳过品牌化页眉 |
--cwd <dir> | 针对其他目录运行，而不是当前目录 |
--help | 命令的用法说明 |
--version | 打印 CLI 版本并退出 |
人类输出写入 stderr
你读到的报告会写入 stderr。stdout 保留给 --json，因此一次运行可以通过管道传给 jq，而不会让报告干扰输出：
evlog map --json | jq '.map.score'
不使用 --json 时，stdout 完全不会写入任何内容。当 stdout 不是 TTY 或设置了 NO_COLOR 时，颜色会被移除；报告会根据分配给它的宽度自行布局，因此可以设置 COLUMNS 以固定宽度进行渲染。
退出代码
| 代码 | 含义 |
|---|---|
0 | 命令已运行且没有任何失败 |
1 | 某项检查失败，或未达到 --min-score |
2 | 用法错误 — 未知标志或无效值 |
$? 替换为其中 最后一个 命令的退出代码，因此 evlog map --min-score 90 \| head 总是看起来成功。当你对受限运行进行管道处理时，请使用 set -o pipefail。当检查出错时
每个判定都可以针对其相关代码被关闭，因此假阳性永远不会成为停止运行工具的理由：
// evlog-map-disable-next-line wide-event, context -- 存活探针，故意保持静默
export default defineEventHandler(() => ({ ok: true }))
检查结果会变为 n/a，并附带你的理由，不会扣分，也不会导致门控失败；报告还会统计项目禁用的检查数量，因此这个数字保持真实。完整语法。
单一仓库
init、map 和 doctor 都会解析工作目录上方最近的 package.json，然后将该 package 视为项目。在 pnpm 或 npm 工作区中，从 apps/web 运行时会扫描 apps/web，而不是仓库根目录。
evlog map 一次只扫描一个应用。从没有可检测框架的裸工作区根目录运行它，会报错，而不是返回空报告：
cd apps/web && evlog map
# or
evlog map --cwd apps/web
调试一次运行
--debug 会打印命令执行的内容：经历的步骤、解析出的目录以及所有发现的问题，并将相同信息作为 evlog 宽事件发出：
evlog map --debug
── 调试 ────────────────────────────────
command map
env development
cwd /Users/you/apps/web
steps resolveProject → detectFramework → resolveEvlog → scan → writeMapFile → done
──────────────────────────────────────────
完整事件 → --json --debug （stderr）
添加 --json 可获取完整事件而不是摘要。EVLOG_CLI_DEBUG=1 的作用与该标志相同，这在你无法轻易修改的 CI 作业中很有用。
下一步
evlog init：将 evlog 接入尚未安装它的应用evlog map：它会扫描什么，以及如何阅读报告- 规则：每项检查、满足条件以及修复方法
- 评分：数字的计算方式
- CI：根据分数对 pull request 进行门控