# @logger/cli

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

## Install

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

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

## Commands

```bash
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 |

```bash
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:

```json
{
  "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

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