The pbiplint CLI

The pbiplint CLI is the linter this site runs, with a folder walk in front of it. Point it at a Power BI project on your own machine and it reads the files you name, checks them against the same rules, and writes the findings to your terminal or to a file you name. It sends nothing anywhere, and the checks below let you see that for yourself. To run it in GitHub Actions or Azure Pipelines, see Pipelines, which covers the step each has for it.

The package is pbiplint on npm (opens in a new tab). It is built on @pbiplint/core (opens in a new tab), the library behind both the CLI and this site, which is there for anyone who wants to embed the linter in a tool of their own.

Get it

pbiplint runs on Node.js 20.19 or a later 20 release, or 22.12 or later (the package's engines field reads ^20.19.0 || >=22.12.0). There are three ways to run it:

Where the public npm registry is off limits, install from your organization's registry mirror, or fetch the package once with npm pack pbiplint and install the .tgz file it writes with npm install ./pbiplint-<version>.tgz.

The source is on GitHub (opens in a new tab), and each version is built from the release tag (opens in a new tab) of the same number.

Use it

npx pbiplint path/to/Model.SemanticModel
npx pbiplint --sample        # the sample project that comes with the package
npx pbiplint path/to/model --format sarif --output pbiplint.sarif
npx pbiplint path/to/model --format markdown
npx pbiplint rules           # every rule with its status and severity
npx pbiplint explain HIDE_FOREIGN_KEYS   # one rule's guidance, offline (--format json too)
npx pbiplint reference                   # what a custom rule can use, from 0.4.0 (--format json too)
npx pbiplint skill --install claude      # the skills for AI assistants, where Claude Code reads them
npx pbiplint mcp                         # a local MCP server, for an AI assistant to start
npx pbiplint --help          # every option, in one screen
npx pbiplint --version

The path can be a PBIP folder, a .pbip file, a .SemanticModel folder, a .Report folder, a definition folder, or one .tmdl file. Given a folder that is not a project but holds one in a folder below it, as a repository often does, pbiplint lints that project and names it in a notice.

From 0.3.0, given a folder that holds several projects, pbiplint lints every one in one run, whether they sit in folders below it or side by side in it, as Power BI Desktop saves two projects into one folder, and gives one exit code for them all. Each project is linted as a run naming it would lint it, with the nearest pbiplint.config.json from its own folder up, or the one --config names, and a report's reference to its model is followed anywhere inside the folder you named. A project pbiplint cannot read, such as a model stored as model.bim, is listed with one PARSE_ISSUE error that says why, and the others are linted. The report opens with the run's counts and a line for each project, then each project's findings under its path. A model several of the projects' reports read is linted with each of them, and its findings are listed once, under the first of them, and NOT_REACHED_FROM_REPORT counts a field as reached when any of those reports reaches it. One run lints at most 200 projects; above that it is refused with a list of the folders below that hold them, so you can lint each. A folder that is itself a project lints that project only, as before, even when more projects sit deeper.

These are the options pbiplint --help lists:

Option What it does
--sample Lints the sample project that comes with the package instead of a path.
--format <name> text (the default), json, sarif, or markdown.
--fail-on <level> The lowest severity that makes the run exit 1: error (the default), warning, info, or none.
--config <file> The pbiplint.config.json to use, instead of the nearest one above the project.
--output <file> Writes the report to a file instead of the terminal, with a one-line summary on stderr.
--quiet Prints the summary and what was read or skipped, any notices, then one line per rule with findings (its severity, id, and count), then the next step. Text only.
--rule <RULE_ID> Shows only that rule's findings, in any format; give it more than once for several. Every rule still runs, the summary says how many findings are shown of how many, and --fail-on counts only the ones shown. From 0.3.0, a RULE_COULD_NOT_FINISH finding about a rule you name is shown and counted too, since that rule's findings are incomplete; one about another rule is not.
--help, --version Prints the help text, or the version.

Choose a format

Read a rule's guidance

pbiplint explain <RULE_ID> prints what a rule checks, an example, why it matters, how to fix it, when to ignore it, and its quirks, from the rule's page as the installed version carries it, with no network. The id is the one each finding names, in any case; the page name from its link works too. --format json prints the same as one document, each section a field of its own, for a script or an AI assistant. An id it does not know exits 2 and names the nearest ones. From 0.4.0, it also takes the id of a custom rule that a config's customRules names, read from --config <file> or, without it, the nearest pbiplint.config.json above the working folder, and prints the rule's file, description, scope, and expression. The text report ends by pointing at it when there are findings.

An AI assistant that lints after each edit can keep its context small: pbiplint <path> --quiet for the counts, pbiplint <path> --rule <RULE_ID> for one rule's findings, and pbiplint explain <RULE_ID> for how to fix them. When there are findings, the quiet output's last line names the other two.

Give an AI assistant the skill

pbiplint skill prints a skill, in the Agent Skills (opens in a new tab) format, that tells a coding assistant when to run pbiplint, how to keep its output short, how to read the results, and what to leave to you, such as ignoring a finding or editing files while Power BI Desktop has the project open. It ships with the CLI, so it always matches the version installed, and an assistant can read it from that command without installing anything.

From 0.4.0 the CLI ships a second skill, pbiplint-custom-rules, which takes an assistant through writing a team's own rule and checking it (see Write a custom rule). pbiplint skill --name pbiplint-custom-rules prints it; pbiplint skill alone still prints the first, as before.

To keep them in a project, run pbiplint skill --install <assistant> from the project's or repository's root folder. From 0.4.0 it writes both skills, each in a folder named after it:

Assistant Folders it writes
claude (Claude Code) .claude/skills/pbiplint/, and from 0.4.0 .claude/skills/pbiplint-custom-rules/
copilot (GitHub Copilot) .github/skills/pbiplint/, and from 0.4.0 .github/skills/pbiplint-custom-rules/
codex (Codex) or gemini (Gemini CLI) .agents/skills/pbiplint/, and from 0.4.0 .agents/skills/pbiplint-custom-rules/

GitHub Copilot reads all three folders, so one copy of each skill is enough for it. --install never replaces a copy that differs from the one it would write, an edited copy or one from another version, unless you add --force. It is all or nothing (from 0.4.0): it checks every copy before it writes any, and when one differs it writes neither, exits 2, and names each copy that differs. --dry-run says what it would do and writes nothing. --show lists each folder, whether each skill is there, and whether that copy matches the version installed. --name <skill> (from 0.4.0), pbiplint or pbiplint-custom-rules, limits printing, --install, and --show to that skill. To remove a skill, delete the folder --show names.

Serve an AI assistant over MCP (from 0.2.5)

pbiplint mcp is a local MCP (opens in a new tab) server for an AI assistant that runs local servers, such as Claude Desktop, Claude Code, VS Code with GitHub Copilot, or Cursor. The assistant starts it and talks to it over stdin and stdout; it opens no port. It is the way to lint from an app that gives the assistant no terminal, such as Claude Desktop's chat. Its four tools only read, and each carries MCP's read-only annotation, so an app can approve them once:

Tool What it returns
lint What pbiplint <path> --format json prints, or with quiet, what --quiet prints. rules and failOn work as --rule and --fail-on do. A path it cannot read comes back as an error with the CLI's own message.
explain_rule What pbiplint explain <RULE_ID> --format json prints. From 0.4.0, given a path in a project, it also explains the custom rules that the nearest pbiplint.config.json above that path names, as --config with that file does.
list_rules Every rule with its layer, status, severity, and category, as JSON. From 0.4.0, given a path in a project, it adds the custom rules that the nearest config above that path names, each with custom, ruleFile, replaces for one that runs in place of pbiplint's rule of its id, and problem for one pbiplint could not read; an unchanged copy of a published rule runs as pbiplint's rule, so it is listed as that.
custom_rules_reference From 0.4.0, what pbiplint reference prints, or with format json, what --format json prints.

With Claude, pbiplint for Claude (opens in a new tab) is the easy route: the skill and this MCP server as two plugins. Each of its releases is pinned to a pbiplint release.

To set it up by hand, in Claude or another app: give lint an absolute path, and the path of explain_rule and list_rules too, since a relative one is taken from the folder the app started the server in. To add it to Claude Code, run claude mcp add pbiplint -- npx -y pbiplint mcp. Claude Desktop and Cursor take a server like this in their MCP settings, and VS Code in .vscode/mcp.json under servers rather than mcpServers:

{
  "mcpServers": {
    "pbiplint": { "command": "npx", "args": ["-y", "pbiplint", "mcp"] }
  }
}

Pin a version, as in pbiplint@0.2.5, to keep every machine on the same rules.

Write a custom rule (from 0.4.0)

A team can add rules of its own, in Tabular Editor's Best Practice Analyzer format, in a file that customRules in pbiplint.config.json names, and pbiplint runs them beside its own. An assistant with the pbiplint-custom-rules skill writes one in a loop: it asks what the rule should catch, with one object that should be flagged and one that should not; reads what a rule can use at the installed version from pbiplint reference (or the MCP tool custom_rules_reference); writes the rule into the team's file and checks that the nearest config names that file; runs pbiplint <path> --rule <RULE_ID> and checks that it flags the objects meant and nothing else, with pbiplint explain <RULE_ID> --config <file>, where <file> is the project's pbiplint.config.json, showing the rule as pbiplint read it; and when the rule gives RULE_COULD_NOT_FINISH, reads the reason, fixes the rule, and runs it again. Severity, and any change to a rule the team already has, stay the team's call. Custom rules covers the format, the worked examples, and everything a rule can use.

To lint a folder named explain, reference, rules, skill, or mcp, give it as ./explain, ./reference, ./rules, ./skill, or ./mcp (reference is a command from 0.4.0).

Gate a build on it

pbiplint exits 0 when nothing is at or above --fail-on, 1 when something is, and 2 for a usage or input error, such as a path that is not there. Any CI system that fails a step on a nonzero exit can use it as a gate. --fail-on error is the default; --fail-on warning and --fail-on info tighten the gate, and --fail-on none never exits 1, for a run that reports without blocking. What a script can rely on lists every cause of 2.

In GitHub Actions and Azure Pipelines, pbiplint's own step runs the CLI for you and puts the findings on the run; Pipelines covers both, with what each sends where.

Configure it

A pbiplint.config.json next to the project, or in any folder above it, turns rules off, changes their severity, and sets the gate. The nearest one wins, and --config names one explicitly:

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

From 0.4.0, customRules names your team's own rule files, in Tabular Editor's Best Practice Analyzer format, by their paths from the folder the config is in, and pbiplint runs them beside its own rules. The rules entries work on their ids too:

{
  "$schema": "https://pbiplint.com/schema/pbiplint.config.schema.json",
  "customRules": ["rules/team.json"],
  "rules": {
    "TEAM_MEASURE_DESCRIPTIONS": "error"
  }
}

A rule file that cannot be read stops the run with exit 2, naming the config and the file, so a gate never passes without the team's rules. Custom rules has the format, what happens to a rule with one of pbiplint's ids, and what a rule can use.

To ignore a rule on one object, add annotation pbiplint.ignore = HIDE_FOREIGN_KEYS under the object in its TMDL file, or a pbiplint.ignore entry in the annotations array of a page's or a visual's JSON file. Power BI Desktop keeps both. The CLI's README (opens in a new tab) has the details, and each rule's page lists the options the rule takes.

What a script can rely on

Scripts, pipelines, and AI assistants read what the CLI prints, so these parts of its behavior are promised, and the CLI's contract tests (opens in a new tab) pin each one. This page follows the main branch: a promise marked "from 0.2.5" holds from that release on, and pbiplint --version says which you have.

stdout and stderr

Exit codes

The JSON document

--format json prints one object. For a run over one project, version is 1, and its fields are:

A run over a folder that holds several projects prints version 2 (from 0.3.0), whose fields are:

A reader checks version before anything else. A new field is additive and keeps version where it is, so a reader should ignore fields it does not know. New values can appear in a field that names one of a set, such as a skipped rule's reason, a notice's kind, or a rule's category and status, also without a version change. A field removed or renamed, or one whose meaning changes, raises version.

SARIF results carry messageId and params in each result's properties. From 0.4.0, a custom rule's descriptor has its name as shortDescription, its description as fullDescription and help, no helpUri, and custom and ruleFile in its properties, as each of its results does.

The quiet output (from 0.2.5)

--quiet prints the summary on the first line, which starts pbiplint: . Each line that starts with error , warning , or info is a rule line: the severity, the rule id, and the number of findings, separated by single spaces. A rule id holds no spaces. A custom rule's id can (from 0.4.0), so on a rule line each space in a custom id is written %20, which a script decodes as a URL does, and the line still splits into three fields. --rule and explain accept the id as quiet output writes it. When there are findings, the last line starts Next: . The lines between, what was read and any notices, are for reading, and their wording is not promised.

In a run over several projects (from 0.3.0), the first line gives the whole run's counts, and a line that starts project opens each project: project <path>: and that project's summary, its path relative to the folder named. The rule lines after it, up to the next project line or the Next: line, are that project's. A run over one project prints no such line. The path runs up to the first : only when the path holds none, so when paths may hold : , a script reads the JSON document instead.

pbiplint explain --format json (from 0.2.5)

One object: version (1), tool, rule (the JSON document's rule fields plus description, what the rule checks), and sections: example, whyItMatters, howToFixIt, whenToIgnoreIt, and quirks, each in Markdown. whyItMatters and howToFixIt are always there; the others are left out when the rule's page has none. For a custom rule (from 0.4.0), rule also has custom (true), ruleFile, scope (the rule's scopes, as its file names them), and expression, plus replaces, the id of the pbiplint rule it runs in place of, when it shares that id; sections is empty. The same rule for changes applies.

pbiplint reference --format json (from 0.4.0)

One object: version (1), tool, and formats, which holds tabularEditor, what a Tabular Editor rule that a config's customRules names can use at the installed version: fields, severities, scopes, types, methods, valueProperties, statics, staticValues, conversions, enums, syntax, tokens, regex, notRun, and limits. Another rule format would be added beside tabularEditor. The same rule for changes applies. Without --format json, pbiplint reference prints the same as text.

Not promised

The text format's layout and wording, which are for people and may change; the Markdown export's layout; the wording of any message, notice, or error; and the SARIF document beyond what SARIF 2.1.0 defines.

What it reads, writes, and sends

This is the command line's part of the pbiplint Privacy Promise, in detail.

The network steps that are not pbiplint's own belong to npm. Installing the package fetches it from the registry. And npx pbiplint asks the registry for the package's details on every run, even when a copy is already in npm's cache, to see whether a newer version matches; with no network, npm retries for about a minute before it runs the cached copy. Neither request carries anything from your project. To run with no network request at all, run an installed copy, or npx --offline pbiplint, which uses the cached copy without asking.

How to check it

From quickest to strongest. Each check lints the sample with --sample; put the path to one of your own projects in its place to check it on yours.

1. Run it offline

Install it with npm install --global pbiplint, turn off the network (airplane mode, or unplug the cable), and run pbiplint --sample. It works, because it never needed the network. (It exits 1 on the sample in this check and the ones below, because the sample has findings; 2 would mean it could not run.)

2. Run it where the network is refused

Node's permission model can refuse a program any network access. Under --permission, Node denies the network unless --allow-net is given, so pbiplint runs as usual and anything that tried to connect would fail with ERR_ACCESS_DENIED. This check needs Node 25 or later. Node 22 and 24 accept --permission but do not restrict the network under it, so a run there proves nothing about the network; Node 20 does not accept the flag.

On macOS and Linux:

node --permission --allow-fs-read='*' "$(npm root -g)/pbiplint/dist/pbiplint.mjs" --sample

On Windows, in PowerShell:

node --permission --allow-fs-read=* "$(npm root -g)\pbiplint\dist\pbiplint.mjs" --sample

--allow-fs-read='*' lets pbiplint read files as it always can, so the check takes away only the network. Reading is left open because pbiplint looks for a pbiplint.config.json in every folder above the project, and a narrower grant stops the run there. With --output, also allow writing to the folder the file goes in, such as --allow-fs-write="$PWD/reports" for --output reports/pbiplint.sarif; the file alone is not enough, since pbiplint creates the folder first. For a copy installed in a project rather than globally, the bundle is at node_modules/pbiplint/dist/pbiplint.mjs. To see the refusal for yourself, run node --permission -e "fetch('https://example.com').catch(e => console.log(e.cause.code))", which prints ERR_ACCESS_DENIED.

On a Mac with any Node version, the system's own sandbox can refuse the network instead:

sandbox-exec -p '(version 1)(allow default)(deny network*)' pbiplint --sample

Apple marks sandbox-exec as deprecated, but it is still on every Mac. On Linux, a container started with --network none has no network at all. This one, for bash, runs your installed copy, mounted read-only:

docker run --rm --network none -v "$(npm root -g)/pbiplint:/opt/pbiplint:ro" node:26 node /opt/pbiplint/dist/pbiplint.mjs --sample

To lint a project of your own, mount it too, with -v "$PWD/MyProject:/work:ro", and give /work in place of --sample. Inside the container pbiplint cannot see a pbiplint.config.json above the project, so mount that folder instead, or pass the file with --config, if the project uses one.

3. Watch it

On Linux, strace -f -e trace=network pbiplint --sample lists every network call the process and its children make, and shows none. On Windows, Resource Monitor (resmon) has a Network tab that lists each process with network activity while it happens; pbiplint runs as node.exe. A lint takes seconds, so this is a weak check on its own; the permission-model check above refuses the network outright.

4. Check what you installed

5. Read the code

The CLI is one bundle, dist/pbiplint.mjs, built from packages/cli (opens in a new tab). A check that runs on every change (opens in a new tab), and before every release, fails if that bundle imports any module but node:fs, node:path, node:process (which the MCP server's stdio transport names), and node:url, or refers to a network API.

If you ever find pbiplint breaking the Promise, that is a security bug. Report it privately, as the security policy (opens in a new tab) describes.