cfw-logging/packages/cli/README.md

@logger/cli

The log command-line tool for reading logs, driven by a project-local .logging/config.json profile.

Install

npm install @logger/cli --registry=http://192.168.0.15:4873

This installs the log binary (and npx log works too).

Commands

log tail [options]
log config init --system=<name> [--server=<url>] [--token-env=<name>] [--force]
log config doctor

log tail

Read recent records. Options:

Option	Meaning
-n, --limit=<n>	number of records (default: config.defaults.limit or 20)
--level=<level>	debug | info | warn | error
--app=<app>	filter by app
--service=<svc>	filter by service
--scope=<scope>	filter by scope
--since=<iso>	records at or after timestamp
--file=<path>	read this local JSONL file (overrides config / LOGGER_FILE)
--remote	query the configured server instead of a local file
--json	emit one JSON record per line
--max-lines=<n>	cap output lines (default: config.output.maxLines or 200)
--strict	fail on invalid JSONL lines instead of skipping

log tail --level=error --limit=20
log tail --app=shop --service=orders --scope=orders.refund --json
log tail --remote --json --since=2026-07-06T00:00:00Z

Source resolution (tail)

Predictable, and never silently hits a remote service:

1. --remote → query the configured server (requires server.baseUrl; auth resolved from auth).
2. --file=<path> or LOGGER_FILE → that local file.
3. config.local.file → the configured local file.
4. config.server configured with no local source → query the server.
5. fallback → .logging/logs.jsonl (with a hint to run log config init).

Command-line flags override config.defaults, which override built-in defaults. Output is capped to config.output.maxLines; output.redact (default true) masks known sensitive fields as a safety net.

log config init

Bootstraps .logging/config.json plus a .logging/.gitignore (ignores *.local.json, *.secret.json, tokens*, logs.jsonl; keeps config.json committable). Use --server / --token-env to scaffold remote access, --force to overwrite.

log config doctor

Validates the config shape, confirms systemName, checks any required token env var is set (without printing its value), probes remote reachability when a server is configured, and checks the local file. Exits non-zero on any hard failure.

Configuration

See the root README's "Configuration (.logging/config.json)" section and skills/logging-agent/references/config-contract.md for the full field reference. Minimal example:

{
  "version": 1,
  "systemName": "shop",
  "local": {"file": ".logging/logs.jsonl"},
  "defaults": {"app": "shop", "limit": 50},
  "output": {"format": "compact", "redact": true, "maxLines": 200}
}

Run from the source checkout

node packages/cli/dist/index.js tail --json --limit=20