Skip to main content
Availability: Pre-aggregates are an Early Access 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

​
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:
  1. --project <uuid> flag
  2. LIGHTDASH_PROJECT_UUID environment variable
  3. 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:
  1. lightdash pre-aggregate-audit --dashboard <slug> to see the current misses
  2. Edit your dbt model YAML to address each miss (use the miss-reason table to know which field to change)
  3. lightdash deploy to push the change
  4. Trigger a refresh from Project Settings > Pre-aggregates if the pre-aggregate definition changed
  5. 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

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