feat: add @evlog/cli observability package

.changeset/cli-package-v1.md

@@ -0,0 +1,19 @@
+---
+"@evlog/cli": minor
+---
+
+# Add `@evlog/cli`
+
+Add `@evlog/cli` — CLI observability for evlog.
+
+- `setupEvlog()` + `invoke()` + `createCommandLogger()` + `useLogger()`
+- `@evlog/cli/citty` — `runMain()` adapter with auto-injected `--log` (peer: citty)
+- `@evlog/cli/http` — `createOutboundHooks()` for ofetch (peer: ofetch)
+- `errorCatalog` / `auditCatalog` config (symmetric with HTTP integrations)
+- `cliRedactPreset`, `parseCliError`, `exitWithError`, flush-on-exit
+- Default: drain-only (silent evlog console); `--log` / `logToConsole` for debug output
+- Drain routing: wire `evlog/fs`, `evlog/axiom`, etc. in `src/drain.ts`; operator selects destination via env (see docs)
+- Demo CLI: `pnpm example:cli` — citty + Clack, `useLogger()` for telemetry (see `examples/cli/`)
+- Docs: `/integrate/frameworks/cli`
+
+Peer dependency: `evlog`. Optional peers: `citty`, `ofetch`.

.github/pull_request_template.md

@@ -28,6 +28,7 @@ scope.
 - bench (benchmarks)
 - better-auth (Better Auth integration)
 - better-stack (Better Stack drain adapter)
+- cli (@evlog/cli — citty observability)
 - core (logger, pipeline, error, redact, catalog internals)
 - datadog (Datadog drain adapter)
 - deps (the dependencies)

.github/workflows/ci.yml

@@ -108,5 +108,11 @@ jobs:
         run: pnpm run dev:prepare
       - name: Build package
         run: pnpm run build:package
+      - name: Verify publish tarballs
+        run: |
+          for dir in packages/evlog packages/nuxthub packages/cli; do
+            echo "==> $dir"
+            (cd "$dir" && npm publish --dry-run --access public)
+          done
       - name: Publish
-        run: pnpx pkg-pr-new publish --compact --no-template --pnpm './packages/evlog' './packages/nuxthub'
+        run: pnpx pkg-pr-new publish --compact --no-template --pnpm './packages/evlog' './packages/nuxthub' './packages/cli'

.github/workflows/semantic-pull-request.yml

@@ -27,6 +27,7 @@ jobs:
             bench
             better-auth
             better-stack
+            cli
             core
             datadog
             deps

AGENTS.md

@@ -33,6 +33,8 @@ packages/evlog/            Main package
   src/enrichers/           Built-in enrichers (UserAgent, Geo, RequestSize, TraceContext)
   src/runtime/             Runtime code (client/, server/, utils/)
   test/                    Tests
+packages/cli/              @evlog/cli — CLI observability (setupEvlog, citty, http)
+examples/cli/              Demo citty + Clack CLI
 .agents/skills/            Internal skills for creating adapters, enrichers, and framework integrations
 ```
 

apps/docs/content/1.start/3.installation.md

@@ -26,7 +26,7 @@ actions:
 
 Install evlog in my TypeScript project.
 
-- Detect the framework I'm using (Nuxt, Next.js, SvelteKit, Nitro, NestJS, Express, Hono, Fastify, Elysia, TanStack Start, React Router, Cloudflare Workers, or standalone)
+- Detect the framework I'm using (Nuxt, Next.js, SvelteKit, Nitro, NestJS, Express, Hono, Fastify, Elysia, TanStack Start, React Router, Cloudflare Workers, CLI with @evlog/cli, or standalone)
 - Install evlog with my package manager: pnpm add evlog (or npm/yarn/bun)
 - Wire up the framework-specific integration (module, plugin, or middleware)
 - Set evlog.env.service to my app name
@@ -179,6 +179,15 @@ After installing the package, follow the setup guide for your framework:
   :::
   :::card
   ---
+  icon: i-lucide-terminal
+  title: CLI
+  to: /integrate/frameworks/cli
+  color: neutral
+  ---
+  `@evlog/cli` — wide events per command, citty adapter, drain routing (fs / Axiom / …), catalogs.
+  :::
+  :::card
+  ---
   icon: i-simple-icons-cloudflare
   title: Cloudflare Workers
   to: /integrate/frameworks/cloudflare-workers

apps/docs/content/3.integrate/frameworks/00.overview.md

@@ -32,6 +32,7 @@ No HTTP framework? Use [Standalone TypeScript](/integrate/frameworks/standalone)
 | [Cloudflare Workers](/integrate/frameworks/cloudflare-workers) | `evlog/workers` | Factory | `createWorkersLogger()` | Stable |
 | [AWS Lambda](/integrate/frameworks/aws-lambda) | `evlog` | Manual | `createLogger()` / `createRequestLogger()` | Guide |
 | [Standalone](/integrate/frameworks/standalone) | `evlog` | Manual | `createLogger()` / `createRequestLogger()` | Stable |
+| [CLI](/integrate/frameworks/cli) | `@evlog/cli` | Bootstrap + invoke | `useLogger()` / `log.audit()` | Stable |
 | [Astro](/integrate/frameworks/astro) | `evlog` | Manual | `createRequestLogger()` | Guide |
 | [Custom](/extend/custom-framework) | `evlog/toolkit` | Build your own | `createMiddlewareLogger()` | Beta |
 
@@ -48,6 +49,7 @@ Two things differ per framework: how you **bootstrap** evlog, and how you **acce
 | `EvlogModule.forRoot()` | NestJS |
 | Module default export | Nuxt, Nitro v2/v3 |
 | Manual factory | Cloudflare Workers (`createWorkersLogger`), Standalone, AWS Lambda, Astro |
+| `setupEvlog()` + `src/drain.ts` | CLI (`@evlog/cli`) — you wire the drain; env selects fs vs Axiom/etc. |
 
 ### Logger access
 
@@ -211,6 +213,15 @@ Hono intentionally has no `useLogger()` — use `c.get('log')` inside handlers.
   :::
   :::card
   ---
+  icon: i-lucide-terminal
+  title: CLI
+  to: /integrate/frameworks/cli
+  color: neutral
+  ---
+  `@evlog/cli` + citty — `setupEvlog({ drain })`, `useLogger()` per command. Wire Axiom/Datadog via `src/drain.ts` + env.
+  :::
+  :::card
+  ---
   icon: i-lucide-puzzle
   title: Custom Integration
   to: /extend/custom-framework