pbiplint

Best-practice linter for Power BI projects. Browser and CLI. Nothing leaves your machine.

Paste TMDL, or drop a PBIP folder, a .SemanticModel folder, or a .Report folder, and get ranked best-practice findings with guidance on how to fix each one, and, when the input has a report, a "Report at a glance" block that says what the report will do when someone opens it. The analysis runs entirely in your browser or on your own machine from the command line. Nothing is uploaded, ever: the pbiplint Privacy Promise says what that covers and how to check it.

Status

Version 0.3.0. It covers the semantic model layer (TMDL): every rule from the Microsoft best-practice ruleset, ported and verified against Tabular Editor, plus pbiplint's own rules for a year or a date fixed in DAX, for DAX user-defined functions, for translations, and for decimal columns' format strings; the report layer (PBIR): the 11 base rules of PBI Inspector, ported and verified against it, plus pbiplint's own rules for what is broken, unfinished, or expensive in a report, for a filter held to a fixed year, and for what the model holds that the report never reaches; and Power Query, the M behind the model's tables and shared expressions, read with Microsoft's Power Query parser: 16 rules, 15 of them pbiplint's own. 122 rules in all, 40 of them built into pbiplint. The site at https://pbiplint.com runs the code on main; the command line runs the version npm gives you, and the releases page lists each version with the date it was published.

Use it

npx pbiplint path/to/Project                     # a PBIP folder, a .pbip file, a .SemanticModel or .Report folder, or one .tmdl file
npx pbiplint --sample                            # try it on the bundled sample project
npx pbiplint path/to/model --format sarif --output pbiplint.sarif
npx pbiplint rules                               # every rule with status and severity
npx pbiplint explain HIDE_FOREIGN_KEYS           # one rule's guidance, offline (--format json too)
npx pbiplint path/to/model --quiet               # the counts, one line per rule
npx pbiplint path/to/model --rule HIDE_FOREIGN_KEYS  # one rule's findings (repeatable)
npx pbiplint skill --install claude              # the skill for AI assistants (--install copilot, codex, gemini; --show)
npx pbiplint mcp                                 # a local MCP server with read-only tools, for an AI assistant to start

Or use it in the browser at https://pbiplint.com: paste TMDL, or drop a PBIP folder, a .SemanticModel folder, or a .Report folder. The page never uploads anything; the Privacy Promise explains how to check that.

Exit codes: 0 no findings at or above --fail-on (default error), 1 findings, 2 a usage error, an input it cannot read, or nothing to lint. That makes it a CI gate. What a script can rely on, from stdout to the JSON fields: https://pbiplint.com/cli/#contract The pbiplint CLI page has the rest: where to get it, what it reads and writes, and how to check that it sends nothing.

With an AI assistant

An assistant that edits a Power BI project can lint its own work without reading pages of output: --quiet gives the counts, one line per rule; --rule <RULE_ID> gives that rule's findings with their files and lines; and pbiplint explain <RULE_ID> gives the rule's guidance from the version installed, with no network. pbiplint skill prints a skill, in the Agent Skills format, that tells the assistant when to lint, how to read the results, and what to leave to you; --install claude, copilot, codex, or gemini writes it where that assistant reads a project's skills. For a chat app with no terminal, pbiplint mcp is a local MCP server with three read-only tools (lint, explain_rule, list_rules); the CLI page has each app's setup. With Claude, the pbiplint plugin for Claude installs the skill and the MCP server in one step: in Claude Code and Cowork, /plugin marketplace add pbiplint/claude-plugin, then /plugin install pbiplint@pbiplint; for Claude Desktop's chat, the .mcpb file from its latest release, which carries pbiplint itself. On the site, the results page's "Copy for an AI assistant" button copies the report with each rule's guidance, to paste into a chat.

In your pipelines

GitHub Actions and Azure Pipelines each have a pbiplint step. In GitHub Actions, one step lints the project, its semantic model and its report, on every pull request: the check fails on findings, each finding is annotated on its line in the Files changed tab, the full report is in the job summary, and the findings reach code scanning. See https://github.com/pbiplint/action for the inputs and outputs.

permissions:
  contents: read
  security-events: write # for code scanning; drop it and set upload-sarif: false otherwise
steps:
  - uses: actions/checkout@v7
  - uses: pbiplint/action@v1
    with:
      path: Sales.pbip

In Azure Pipelines, the pbiplint task does the same with build issues, a report on the run, and a SARIF artifact; see https://github.com/pbiplint/azure-pipelines, which also has a plain YAML route for organizations that cannot install an extension.

steps:
  - task: pbiplint@1
    inputs:
      path: Sales.pbip

Pipelines on the site lists what each sends where, and how to check it.

Configure it

pbiplint.config.json next to your project (or anywhere above it):

{
  "$schema": "https://pbiplint.com/schema/pbiplint.config.schema.json",
  "rules": {
    "REMOVE_ROLES_WITH_NO_MEMBERS": "off",
    "DAX_COLUMNS_FULLY_QUALIFIED": "warning"
  },
  "failOn": "warning"
}

The $schema line is optional; with it, editors validate the file as you type.

A rule that takes options is set with an object. The ported report rules' thresholds and the three policy rules are examples of it; each rule's page lists its options:

{
  "rules": {
    "REDUCE_VISUALS_ON_PAGE": { "severity": "error", "max": 15 },
    "FILTERS_PANE_STATE": { "expect": "closed" },
    "SLICER_SELECTION_SAVED": { "expect": "none" },
    "TAB_ORDER_FOLLOWS_LAYOUT": { "expect": "layout" }
  }
}

The search walks up from the project to the filesystem root and uses the first file it finds, so a pbiplint.config.json in a parent folder or in your home directory applies to every project below it. Pass --config <file> to pick one explicitly. Rule ids match regardless of case, and an id that names no rule prints a warning, so a typo never switches a rule off silently.

To ignore a rule on one object, add an annotation in TMDL. Power BI Desktop keeps it:

	column 'Product ID'
		dataType: int64
		annotation pbiplint.ignore = HIDE_FOREIGN_KEYS, MARK_PRIMARY_KEYS

annotation pbiplint.ignore = * ignores every rule on that object. Ids match regardless of case here too.

To ignore a report rule on one page or visual, add an annotation to the annotations array of its page.json or visual.json. Desktop keeps it, and its value is a list of ids or *, as in TMDL:

"annotations": [{ "name": "pbiplint.ignore", "value": "ENSURE_ALTTEXT" }]

What it checks

Every rule from Microsoft's Best Practice Analyzer ruleset, ported so the results match Tabular Editor on the same model, with twelve documented deviations where the source is noisier, or quieter, than it means to be; and pbiplint's own rules for a year or a date fixed in DAX, such as a measure filtered to 2025 or a date table that ends in 2026, for a DAX user-defined function that nothing calls, has a one-word name, or has no description, for a visible name that a translated culture gives no caption, and for a visible decimal column with no format string. Four of pbiplint's own model rules take their test from Tabular Editor's rules, from Tabular Editor 3's built-in set or the community's published rule files, and are checked against Tabular Editor on the same model. Five of the Microsoft rules need VertiPaq statistics and are listed but not run. A column whose TMDL names no type, as Power BI Desktop saves most calculated columns, is left out of the thirteen ported rules that test a column's type, where Tabular Editor reads the type from the column's DAX. A TMDL line the parser cannot place gets a PARSE_ISSUE error on that line rather than being dropped silently; that includes a declaration its object does not hold, such as a misspelt columm under a table or a hierarchy's level that lost its tab. Each rule has a page at https://pbiplint.com/rules (source under rules/) with what it checks, an example that fires it and the same example fixed, why it matters, how to fix it, when ignoring it is legitimate, known quirks, and related rules.

The report layer: the 11 base rules of PBI Inspector by Nat Van Gulck, ported so the results match its command line on the same report, with six documented deviations where the source is noisier, or quieter, than it means to be; and pbiplint's own rules for a report's correctness and readiness: fields the model does not have, model objects the report never reaches, a landing page not set, the opening page, the Filters pane, hidden visuals left with fields bound, default page names, empty visuals, visuals past the page edge, report-level measures, actions that point at a missing page or bookmark, bookmarks that refer to a missing page or visual, actions with no destination, tab order against layout, saved slicer selections and search terms, and Filters pane filters held to a fixed year, such as a page filtered to 2025. "Report at a glance" states what the report will do whether or not anything fired.

The Power Query layer: the M behind each table's partitions, the shared expressions, and incremental refresh policies, read with Microsoft's Power Query parser, and the file's Power Query options. 16 rules check it: Microsoft's MINIMIZE_POWER_QUERY_TRANSFORMATIONS and 15 of pbiplint's own. A finding in M names the query and the step as Power Query's editor shows them, at the line and column in the TMDL file, and M that does not parse gets a PARSE_ISSUE error where the parser stopped. 122 rules in all, 40 of them built into pbiplint; the rules index filters to the Power Query ones.

Links

• Website: https://pbiplint.com
• Rule pages: https://pbiplint.com/rules
• The command line: https://pbiplint.com/cli/
• What a script can rely on: https://pbiplint.com/cli/#contract
• For AI assistants: https://pbiplint.com/llms.txt
• The pbiplint Privacy Promise: https://pbiplint.com/privacy/
• From the makers of The Data Practitioner

Contributing

See CONTRIBUTING.md.

License

Copyright (C) 2026 McKinley Consulting.

pbiplint is free software under the GNU Affero General Public License, version 3 or later. See LICENSE. You can use it, modify it, and share it. If you distribute a modified version, or run one as a service, you must publish your source under the same license. Other terms for closed products can be discussed with the copyright holder. The vendored Microsoft ruleset and PBI Inspector rule metadata have their own notices in NOTICE. The skill for AI assistants (packages/cli/skill/SKILL.md, which pbiplint skill prints and installs) is MIT-licensed, so it can be committed to any repository; its notice is at the end of the file.

The name pbiplint and its logo are trademarks of McKinley Consulting. The code license does not cover them. The logo files are in brand.