evlog CLI

@evlog/cli is a separate package from evlog itself. It never runs in your app: it reads your source on disk, so there is nothing to configure and nothing to deploy.

Its main job is evlog map — a static observability score for your app, in the spirit of Lighthouse. It finds every entry point in your project, checks each one for wide-event coverage, and tells you which three to fix first.

pnpm dlx @evlog/cli map

bunx @evlog/cli map

npx @evlog/cli map

Add it as a dev dependency once you gate CI on the score, so every run uses the same version:

pnpm add -D @evlog/cli

bun add -d @evlog/cli

npm install --save-dev @evlog/cli

Commands

Global flags

Every command accepts these:

Human output goes to stderr

The report you read is written to stderr. Stdout is reserved for --json, so a run can be piped into jq without the report getting in the way:

evlog map --json | jq '.map.score'

Without --json, nothing is written to stdout at all. Colour is dropped when stdout is not a TTY or when NO_COLOR is set, and the report lays itself out for the width it is given — set COLUMNS to render at a fixed width.

Exit codes

When a check is wrong

Every verdict can be turned off from the code it is about, so a false positive never becomes a reason to stop running the tool:

// evlog-map-disable-next-line wide-event, context -- liveness probe, deliberately silent
export default defineEventHandler(() => ({ ok: true }))

The check becomes n/a with your reason attached — no score cost, no failed gate — and the report counts how many checks the project disabled, so the number stays honest. Full syntax.

Monorepos

Both map and doctor resolve the nearest package.json above the working directory, then treat that package as the project. In a pnpm or npm workspace, running from apps/web scans apps/web — not the repo root.

evlog map scans one app at a time. Running it from a bare workspace root, where there is no framework to detect, is an error rather than an empty report:

cd apps/web && evlog map
# or
evlog map --cwd apps/web

Debugging a run

--debug prints what the command did — the steps it went through, the directory it resolved, and any findings — and emits the same information as an evlog wide event:

evlog map --debug

── debug ────────────────────────────────
command  map
env      development
cwd      /Users/you/apps/web
steps    resolveProject → detectFramework → resolveEvlog → scan → writeMapFile → done
──────────────────────────────────────────
full event → --json --debug  (stderr)

Add --json to get the whole event instead of the summary. EVLOG_CLI_DEBUG=1 does the same as the flag, which is useful in a CI job you cannot easily edit.

Next

• evlog map — what it scans and how to read the report
• Rules — every check, what satisfies it, and how to fix it
• Scoring — how the number is calculated
• CI — gate a pull request on the score