# aalog — usage

Command surface for the `aalog` CLI. The tool reads AVEVA / Wonderware System Platform binary logs (`*.aaLGX`) under `C:\ProgramData\ArchestrA\LogFiles` (override with `--log-dir`).

## Common options

Inherited by `last`, `tail`, `range`, and `unread`:

| Option | Default | Notes |
| --- | --- | --- |
| `--log-dir <path>` | `C:\ProgramData\ArchestrA\LogFiles` | Read from a copied-out log directory. |
| `--component <pattern>` | (none) | Substring match against `Component`. With `--regex`, treated as a regex. |
| `--level <pattern>` | (none) | Substring/regex against `LogFlag` (`Info`, `Warning`, `Error`, `Trace`, …). |
| `--message <pattern>` | (none) | Substring/regex against the message body. |
| `--regex` | off | Switch all three pattern options to regex (case-insensitive). |
| `--llm-json` | off | Emit the stable JSON envelope instead of human-readable lines. |

## Commands

### `aalog last`

Most recent N records ending at `now` (or `--until`).

| Option | Default | Notes |
| --- | --- | --- |
| `-n`, `--count <int>` | `50` | How many records to return. |
| `--until <iso>` | now | ISO-8601 local time anchor for the end of the window. |

```powershell
aalog last                        # last 50, human readable
aalog last -n 200 --llm-json      # last 200, JSON envelope
aalog last --component aaEngine --level Error -n 100
```

### `aalog tail`

Records from the last N minutes.

| Option | Default | Notes |
| --- | --- | --- |
| `-m`, `--minutes <int>` | `10` | Window length in minutes. Must be positive. |
| `--max <int>` | `1000` | Hard cap on records returned (keeps LLM payloads bounded). |

```powershell
aalog tail                                     # last 10 minutes
aalog tail -m 60 --level Error --llm-json      # last hour, errors only, JSON
aalog tail -m 5 --message "checkpoint failed" --regex
```

### `aalog range`

Explicit start/end timestamps.

| Option | Default | Notes |
| --- | --- | --- |
| `--from <iso>` | (required) | Start timestamp, ISO-8601 local time. |
| `--to <iso>` | now | End timestamp, ISO-8601 local time. Must be later than `--from`. |
| `--max <int>` | `1000` | Hard cap on records returned. |

```powershell
aalog range --from 2026-05-03T08:00 --to 2026-05-03T09:00 --llm-json
aalog range --from 2026-05-03T14:30:00 --component "Galaxy" --level Warning
```

### `aalog unread`

Incremental polling. Uses the upstream library's cache file (under `%LOCALAPPDATA%\aaLogReader\` by default) to remember the last record ID seen, so successive invocations only return what's new.

| Option | Default | Notes |
| --- | --- | --- |
| `--max <ulong>` | `1000` | Maximum unread records to return. |
| `--ignore-cache` | off | Re-read regardless; the next call resumes from the new high-water mark. |
| `--client-id <name>` | (none) | Distinct cache files for parallel consumers. |

```powershell
aalog unread --llm-json                        # everything new since last call
aalog unread --client-id watchdog --max 200    # independent cache for this consumer
```

### `aalog fields`

Print the LogRecord JSON field reference and exit. Same content as [`fields.md`](fields.md).

```powershell
aalog fields
```

## LLM-JSON envelope

When `--llm-json` is set, every read command writes a single JSON document to stdout:

```json
{
  "query": {
    "command": "tail",
    "minutes": 5,
    "start": "2026-05-03T08:55:00",
    "end":   "2026-05-03T09:00:00",
    "max": 1000,
    "component": null,
    "level": "Error",
    "message": null,
    "regex": false,
    "log_dir": "C:\\ProgramData\\ArchestrA\\LogFiles"
  },
  "count": 3,
  "records": [
    {
      "MessageNumber": 18234021,
      "TimestampUtc":   "2026-05-03T13:59:42.117Z",
      "TimestampLocal": "2026-05-03T08:59:42.117",
      "Level":          "Error",
      "Component":      "aaEngine",
      "ProcessName":    "aaEngine",
      "ProcessId":      4128,
      "ThreadId":       6884,
      "SessionId":      "",
      "Host":           "PROD-AS-01.example.local",
      "Message":        "Galaxy connection timeout after 30000ms"
    }
  ]
}
```

### Envelope guarantees

- `query` echoes every parameter that affected the result, including the **resolved** `log_dir` after `--log-dir` is applied. Agents can confirm scope without re-running the command.
- `count == records.length`.
- `records` is sorted **newest first** for `last`, `tail`, `range`, and `unread`.
- Field names in `records[*]` match exactly what `aalog fields` prints. Adding new fields is non-breaking; renaming or removing them is.

## Tips for LLM use

- Cap aggressively. `--minutes 60 --max 200 --level Error` is more useful than dumping a thousand lines of `Trace`.
- Filter on `Component` first when chasing a specific subsystem (e.g. `aaEngine`, `Bootstrap`, `aaGR`). Levels alone are noisy.
- For follow-along debugging, prefer `unread --client-id <agent-name>` so each agent has its own cache.
- Pair with `graccesscli` mutations: run a `graccess` command, then `aalog tail -m 1 --llm-json` to read the resulting log activity.