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

# canonic report

> List and run curated, committed reports.

`canonic report` operates on `reports/*.yaml` — committed, git-reviewed definitions of a named, ordered sequence of `query()` calls. A report is composition over the semantic/knowledge/contracts layers, not a fourth kind of fact: it declares no SQL behavior, no meaning, and no authority of its own.

<Note>
  `canonic report` used to be an alias for the event-log diagnostics command now named [`canonic audit`](/cli-reference/status-report#canonic-audit). A bare `canonic report` (no subcommand) prints a pointer to `canonic audit` instead of silently doing something else.
</Note>

## `canonic report list`

```bash theme={null}
canonic report list
canonic report list --domain orders
```

| Flag       | Description                                      |
| ---------- | ------------------------------------------------ |
| `--domain` | Filter to reports declaring this `domain` field. |

A directory listing only: `id`, `title`, `description`, `owner`, `domain` per committed report — no execution, no per-section detail. `--json` output matches the MCP `list_reports` tool payload byte-for-byte.

## `canonic report run`

```bash theme={null}
canonic report run customer_report
canonic report run customer_report --as-of 2026-06-01 --user alice
```

| Argument / Flag | Description                                                                                                    |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `report_id`     | Committed report id to run (positional).                                                                       |
| `--as-of`       | ISO-8601 reference point for finality watermark evaluation, applied to every section that doesn't set its own. |
| `--user`        | Requesting user id, for narrative knowledge-page access control.                                               |

Runs every section of the report through `query()`, in declared order, and prints one table per section. A failing section — for example one blocked by a `min_trust` or `context` guardrail — does not abort the run: it's printed as a `code: message` error in place of a table, and the command still exits `0`. `--json` output matches the MCP `run_report` tool payload byte-for-byte, and every section's `result` is the same unmodified `QueryResult` shape a standalone `canonic query` call returns.

```bash theme={null}
$ canonic report run customer_report

Revenue and orders by customer type
┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ customer_type ┃ revenue ┃ order_count ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━┩
│ business      │ 43.00   │ 6           │
│ personal      │ 122.04  │ 19          │
└───────────────┴─────────┴─────────────┘
The `customer_type` field on the `customers` table has two values...

Average revenue per customer by segment
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ customer_type ┃ avg_revenue ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ personal      │ 8.136…      │
│ business      │ 8.6         │
└───────────────┴─────────────┘
Revenue is calculated as the `amount` column on the `orders` table...

Units sold by product type
...
```

This example report (`examples/jaffle-shop/reports/customer_report.yaml`) mixes several things a single report commonly needs: a multi-metric section (`revenue` + `order_count` together), a composite `ratio` metric (`avg_revenue`), a section joined through a different source (`units_sold` via `order_items` → `products`), a filtered section (store revenue for the first half of January), and sections with and without an attached narrative — proving none of it needs special-casing in `run_report` itself.

## `canonic validate` and reports

[`canonic validate`](/cli-reference/status-report#canonic-validate) also validates every committed `reports/*.yaml`: each section's query must compile against the current semantic layer (dry-run, no execution) and each `narrative_from` must resolve to an existing knowledge page. A metric rename that breaks a report is caught in the same `canonic validate` run — and the same PR — that already catches it for `semantics/`/`contracts/`.

See [Report schema](/reference/report-schema) for the `reports/*.yaml` file format.