Auditing pre-aggregates from the CLI

Availability: Pre-aggregates are a Beta feature available on Enterprise plans only.

lightdash pre-aggregate-audit reports, for one dashboard or every dashboard in a project, which tiles are served from a pre-aggregate, which ones miss (and why), and which ones are ineligible for pre-aggregates entirely. It calls the same audit data as the in-app Pre-aggregation audit menu (see Dashboard pre-aggregate view) but exposes it for scripting, automation, and CI.

When to use it

The CLI audit is the right tool when you want to:

Iterate on pre-aggregate YAML and verify that misses you’ve targeted are now hits, without clicking through dashboards in the UI
Run a project-wide sweep to find dashboards that aren’t benefitting from pre-aggregates yet
Get machine-readable JSON for custom reporting (for example, exporting coverage to a BI tool or Slack)
Block merges in CI when a critical dashboard regresses to warehouse queries

For a quick spot-check on one dashboard, the in-app audit menu is usually faster.

Pairs well with agentic coding tools. Cursor, Claude Code, Codex, and similar agents do really well with this command — every miss prints both the failing field and the reason, which is exactly the signal an agent needs to edit the right pre-aggregate in your dbt YAML. A typical loop is “run lightdash pre-aggregate-audit --dashboard <slug>, then update the model YAML to close the misses, then re-run until it’s clean.” The output is structured enough that the agent can fix coverage on its own without you having to translate misses into YAML edits manually.

Prerequisites

Lightdash Enterprise plan
Install the Lightdash CLI
Authenticate with lightdash login

Auditing a single dashboard

Pass the dashboard’s UUID or its URL slug:

lightdash pre-aggregate-audit --dashboard sales-overview

The output groups tiles by tab and tags each one with its status:

Dashboard: Sales Overview (sales-overview)  4 hit  2 miss  — 1 ineligible
  Tab: Q1
    HIT  Total revenue        (pre-aggregate: orders_daily_by_status)
    HIT  Average order value  (pre-aggregate: orders_daily_by_status)
    MISS New customers        (Metric not in pre-aggregate)
    MISS Revenue by hour      (Granularity too fine)
    1 ineligible tile(s) hidden (pass --verbose to show)

Each tile is one of:

Hit — the chart is served from the named pre-aggregate
Miss — the chart is eligible to use pre-aggregates but no pre-aggregate matches. The output prints the miss reason
Ineligible — the tile cannot use pre-aggregates at all (markdown tile, SQL chart, orphaned chart, broken explore). Hidden by default; pass --verbose to expand

Auditing every dashboard

lightdash pre-aggregate-audit --all

The CLI fetches every dashboard in the project and audits each one. This is the workflow for project-wide health checks or CI gates.

Selecting the project

The CLI resolves the project in this order:

--project <uuid> flag
LIGHTDASH_PROJECT_UUID environment variable
The project saved by your last lightdash login / lightdash config set-project

lightdash pre-aggregate-audit --all --project <project-uuid>

JSON output for scripting

lightdash pre-aggregate-audit --dashboard sales-overview --json

Returns the full audit object per dashboard ({ "dashboards": [...] } when combined with --all). Pipe into jq to extract what you care about — for example, every dashboard with at least one miss:

lightdash pre-aggregate-audit --all --json \
  | jq '.dashboards[] | select(.summary.missCount > 0) | .dashboardName'

Using audit results to improve your YAML

The miss labels printed by the CLI are the same ones documented in Why a query misses a pre-aggregate — that table maps each reason to the YAML or configuration change that fixes it. A typical iteration loop:

lightdash pre-aggregate-audit --dashboard <slug> to see the current misses
Edit your dbt model YAML to address each miss (use the miss-reason table to know which field to change)
lightdash deploy to push the change
Trigger a refresh from Project Settings > Pre-aggregates if the pre-aggregate definition changed
Re-run the audit to confirm the misses are now hits

CI integration with `--fail-on-miss`

--fail-on-miss makes the command exit with code 1 if any tile is a miss, so CI can block changes that regress pre-aggregate coverage:

- name: Audit pre-aggregate coverage
  run: lightdash pre-aggregate-audit --dashboard executive-summary --fail-on-miss
  env:
    LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
    LIGHTDASH_URL: ${{ vars.LIGHTDASH_URL }}
    LIGHTDASH_PROJECT_UUID: ${{ vars.LIGHTDASH_PROJECT_UUID }}

Ineligible tiles do not count as misses — only eligible tiles that failed to match contribute to the failure.

Gating an entire project with --all --fail-on-miss is usually too strict, since most projects have at least one dashboard with unsupported features. Pin the gate to the high-traffic dashboards you care about with --dashboard <slug> --fail-on-miss, or use --json and filter the dashboards you want to enforce.

Flag reference

Flag	Description
`--dashboard <uuid-or-slug>`	Audit a specific dashboard. Required unless `--all` is set.
`--all`	Audit every dashboard in the project.
`--project <uuid>`	Override the active project. Falls back to `LIGHTDASH_PROJECT_UUID`, then to the CLI config.
`--json`	Emit machine-readable JSON instead of the human-friendly text output.
`--fail-on-miss`	Exit 1 if any eligible tile misses. Ineligible tiles do not trigger a failure.
`--verbose`	Include ineligible tiles (and their reason) in the human output.

​When to use it

​Prerequisites

​Auditing a single dashboard

​Auditing every dashboard

​Selecting the project

​JSON output for scripting

​Using audit results to improve your YAML

​CI integration with --fail-on-miss

​Flag reference

When to use it

Prerequisites

Auditing a single dashboard

Auditing every dashboard

Selecting the project

JSON output for scripting

Using audit results to improve your YAML

CI integration with `--fail-on-miss`

Flag reference