> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Log Usage

> Inspect past curate and query operations for auditing and debugging.

ByteRover records a history of every curate and query operation so you can audit past activity, debug failures, and understand how your context tree has evolved over time.

## Curate History

Use `brv curate view` to inspect past curate operations.

**Arguments**

| Argument | Type   | Required | Description                                               |
| -------- | ------ | -------- | --------------------------------------------------------- |
| `id`     | string | No       | Log entry ID to view in detail (e.g. `cur-1739700001000`) |

**Flags**

| Flag                    | Description                                                                          | Default |
| ----------------------- | ------------------------------------------------------------------------------------ | ------- |
| `--since <time>`        | Show entries after this time (ISO date or relative: `30m`, `1h`, `24h`, `7d`, `2w`)  | —       |
| `--before <time>`       | Show entries before this time (ISO date or relative: `30m`, `1h`, `24h`, `7d`, `2w`) | —       |
| `--status <status>`     | Filter by status (repeatable): `cancelled`, `completed`, `error`, `processing`       | All     |
| `--detail`              | Show operations for each entry in list view                                          | `false` |
| `--limit <n>`           | Maximum number of entries to display                                                 | `10`    |
| `--format <text\|json>` | Output format                                                                        | `text`  |

**Examples**

```bash theme={null}
# List recent curate operations
brv curate view

# View a specific entry in detail
brv curate view cur-1739700001000

# Filter by status and time
brv curate view --status completed --since 1h
brv curate view --status completed --status error --limit 5

# Show per-operation detail for each entry
brv curate view --detail

# JSON output for scripting
brv curate view --format json
```

## Query History

Use `brv query-log view` to inspect past query operations and the knowledge files that were matched.

**Arguments**

| Argument | Type   | Required | Description                                               |
| -------- | ------ | -------- | --------------------------------------------------------- |
| `id`     | string | No       | Log entry ID to view in detail (e.g. `qry-1712345678901`) |

**Flags**

| Flag                    | Description                                                                          | Default |
| ----------------------- | ------------------------------------------------------------------------------------ | ------- |
| `--since <time>`        | Show entries after this time (ISO date or relative: `30m`, `1h`, `24h`, `7d`, `2w`)  | —       |
| `--before <time>`       | Show entries before this time (ISO date or relative: `30m`, `1h`, `24h`, `7d`, `2w`) | —       |
| `--status <status>`     | Filter by status (repeatable): `cancelled`, `completed`, `error`, `processing`       | All     |
| `--tier <n>`            | Filter by resolution tier (repeatable): `0`–`4`                                      | All     |
| `--detail`              | Show matched docs for each entry in list view                                        | `false` |
| `--limit <n>`           | Maximum number of entries to display                                                 | `10`    |
| `--format <text\|json>` | Output format                                                                        | `text`  |

Each query is resolved at one of five tiers, from fastest to most thorough:

| Tier | Label             | Description                                            |
| ---- | ----------------- | ------------------------------------------------------ |
| `0`  | exact cache hit   | Result served directly from an exact cache match       |
| `1`  | fuzzy cache match | Result served from a semantically similar cached query |
| `2`  | direct search     | Knowledge retrieved via direct vector search           |
| `3`  | optimized LLM     | LLM-guided search with optimized retrieval             |
| `4`  | full agentic      | Full agentic search across the context tree            |

**Examples**

```bash theme={null}
# List recent query operations
brv query-log view

# View a specific entry in detail
brv query-log view qry-1712345678901

# Filter by status and time
brv query-log view --status completed --since 1h

# Show only cache-hit queries (tiers 0 and 1)
brv query-log view --tier 0 --tier 1

# Show matched docs for each entry
brv query-log view --detail

# JSON output for scripting
brv query-log view --format json
```

## Query Recall Metrics

Use `brv query-log summary` to view aggregated metrics across recent queries — cache hit rate, coverage, response times, and knowledge gaps.

**Flags**

| Flag                               | Description                                                                           | Default |
| ---------------------------------- | ------------------------------------------------------------------------------------- | ------- |
| `--last <time>`                    | Relative time window (e.g. `1h`, `24h`, `7d`, `30d`). Takes precedence over `--since` | `24h`   |
| `--since <time>`                   | Entries after this time (ISO date or relative)                                        | —       |
| `--before <time>`                  | Entries before this time (ISO date or relative)                                       | —       |
| `--format <text\|json\|narrative>` | Output format                                                                         | `text`  |

**Examples**

```bash theme={null}
# Summary for the last 24 hours (default)
brv query-log summary

# Summary for the last 7 days
brv query-log summary --last 7d

# Narrative format (human-readable prose)
brv query-log summary --format narrative

# Custom date range
brv query-log summary --since 2026-04-01 --before 2026-04-03
```