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:
- To try it:
npx pbiplint path/to/project. The first time, npm asks before it installs the package (--yesskips the question), then runs it. - To pin a version in a project:
npm install --save-dev pbiplint, then add a script topackage.json, such as"lint:pbi": "pbiplint .", and runnpm run lint:pbi. Everyone on the project, and its CI, then runs the same version. - For one machine:
npm install --global pbiplint, then runpbiplintfrom anywhere.
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
- text is for reading in a terminal: the "Report at a glance" block when the input has a report, the five groups to fix first, then every finding with a link to its rule's page.
- markdown is for pasting where Markdown renders: a pull request comment, a wiki page, or an issue.
- sarif is for code scanning and editors. GitHub code scanning and the SARIF viewers for editors such as VS Code read it and put each finding on its line. From 0.3.0, the run's
executionSuccessfulisfalsewhen a rule could not finish. - json is for scripts: the summary, the findings in their groups, the notices, and the report's facts, as data.
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.
- Claude Code and Cowork: run
/plugin marketplace add pbiplint/claude-plugin, then/plugin install pbiplint@pbiplintfor the skill and/plugin install pbiplint-mcp@pbiplintfor this MCP server. - Claude Desktop's chat: download the
.mcpbfile from the plugin's latest release (opens in a new tab) and open it, and Claude Desktop installs the server in one click. The file carries pbiplint itself, so nothing is downloaded when it runs.
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
- With
--format json,sarif, ormarkdown, stdout carries exactly one document and nothing else, so it can be piped straight into a parser or a file. So doespbiplint explain --format json(from 0.2.5). - Notices (
pbiplint: notice: ...), the one-line summary--outputprints, a config's unknown rule ids, and every error go to stderr. The text and Markdown reports also list each notice in the report. - In a run over several projects (from 0.3.0), each notice and each line for a rule that could not finish names its project first, as its path relative to the folder named, since the paths in it are relative to that project:
pbiplint: notice: <path>: ...and<path>: rule <RULE_ID> failed: .... The path runs up to the first:only when the path holds none, so a script that must tell the path from the message when paths may hold:reads the JSON document, where each project's notices sit under its ownpath. --helpand--versionprint text, whatever the format.pbiplintalone prints the help and exits0; options with no path and no--sampleexit2(from 0.2.5), so an empty path in a script never passes as a clean run.- With
--output, stdout is empty: the report goes to the file and the one-line summary to stderr. - Colour codes appear only in the text report written to a terminal, or through a pipe when
FORCE_COLORturns colour on.FORCE_COLORworks as Node defines it (opens in a new tab):1,true, the empty string,2, or3turns colour on and outranksNO_COLORandTERM=dumb, and any other value, such as0, turns it off, in a terminal too. They never appear in JSON, SARIF, Markdown,--quiet, or a file--outputwrites, so a script reads the same bytes whatever it runs in.NO_COLORset to any value but the empty string turns them off, as no-color.org (opens in a new tab) asks: "Command-line software which adds ANSI color to its output by default should check for aNO_COLORenvironment variable that, when present and not an empty string (regardless of its value), prevents the addition of ANSI color." WithoutFORCE_COLOR,TERM=dumbturns them off too.
Exit codes
0: nothing at or above--fail-on. With--rule(from 0.2.5), only the findings shown count.pbiplint rules,pbiplint explainwith a rule it knows,pbiplint reference(from 0.4.0),pbiplint skill(from 0.2.5) when it prints, shows, or installs the skills,pbiplint mcp(from 0.2.5) when the app closes its input,--help, and--versionexit0too.1: something at or above--fail-on. From 0.3.0 that includes a rule that could not finish, through itsRULE_COULD_NOT_FINISHerror finding, which the rule's page says how to keep from failing a gate while a fix ships. In a run over several projects (from 0.3.0), the run exits1when any project has something at or above its gate, and a project pbiplint cannot read is aPARSE_ISSUEerror finding of that project's, so it fails the default gate, unless the project's config turnsPARSE_ISSUEoff or lowers it below its gate.2, with nothing on stdout and the reason on stderr:- a usage error, such as an unknown option, an option with no value or a value it does not take, two paths, or options with no path; from 0.2.5 also an unknown rule id given to
explainor--rule, or--quietwith a format other than text; - a config file it cannot use;
- an input it cannot read, such as a path that is not there, a
.pbixfile, or a model folder with no.tmdlfiles; - a run that reads nothing it can lint, such as a report stored only as
report.json; - a
.pbipfile, given as the path, that names several reports, naming each (in a run over several projects, such a.pbipis a project that cannot be read, aPARSE_ISSUEof its own); - a folder that holds more than 200 projects (from 0.3.0), naming the folders below it that hold them and how many each holds;
- a folder of several projects none of which can be read (from 0.3.0), naming each and why;
- before 0.3.0, also a folder that holds several projects, naming each;
pbiplint skill --installfinding a copy that differs from the one it would write, without--force(from 0.2.5); from 0.4.0 it then writes neither skill, prints nothing on stdout, and names each copy that differs on stderr;- an unexpected error.
- a usage error, such as an unknown option, an option with no value or a value it does not take, two paths, or options with no path; from 0.2.5 also an unknown rule id given to
The JSON document
--format json prints one object. For a run over one project, version is 1, and its fields are:
tool:nameandversion.summary: the number offilesread, and offindings,errors,warnings, andinfos;rulesRun, the number of rules that ran;rulesSkipped, each withidandreason;ruleErrors, each withidandmessage, for a rule that could not finish (from 0.3.0, themessagenames the kind of error and, for a Power Query rule's error in one query, the query, as inquery 'Sales': TypeError, never the error's own message, and the rule's findings on its other queries stand; each entry is also aRULE_COULD_NOT_FINISHfinding unless the config or an annotation says otherwise; the summary line and the text and Markdown notices name each one too);ignored, the number of findings an annotation ignored; andunknownRules, the config's rule ids that match no rule. From 0.4.0, aruleErrorsentry for a custom rule also hasruleFile, the rule file ascustomRulesnames it, and when the config names custom rules,customRuleslists each file in that order, withfile,rules(every rule id it holds, as written),asBuiltIn(the ids of its unchanged copies of rules Microsoft or Tabular Editor published, whose pbiplint rule runs in their place, at the copy's severity when the team changed it and the config sets none),replaced(the ids of its other rules that share an id with one of pbiplint's, which run in place of pbiplint's rule; an id the config turns off is in neither list, as neither rule runs, and nor is a rule left out for an earlier one with its id, which a notice names), andnotRun(its rules that could not run, a rule with one of pbiplint's ids that pbiplint could not read among them: pbiplint's rule runs, and the team's is aRULE_COULD_NOT_FINISHfinding). Under--rule(from 0.2.5),shownholdsrules,findings,errors,warnings, andinfosfor what is shown, while the other counts stay the whole run's.layers:modelandreport, eachpresent: truewithfiles, the number read, orpresent: falsewithreason.facts: what the report is at a glance, each withlayer,label,value, and an optionaldetailandruleId.diagnostics: the notices, each withkind,message, and an optionalpath. From 0.4.0, custom rules add the kindscustom-rules(a file's rules that share an id with one of pbiplint's),custom-rule-duplicate(a rule left out because an earlier one has its id), andcustom-rule-left-out(objects a rule left out for a value the files leave unset), each with the rule file aspath.groups: the findings by rule, errors first. Each hasrule(id,name,category,severityfrom1for info to3for error,layer,slug,url, andstatus),count, andfindings, each withlayer,objectType,objectName, and an optionalobjectId,file,line,column(1-based, from 0.3.0, where the finding has one), anddetail, and, from 0.3.2, where there is adetail,messageId, the stable identifier of the message the detail was written from, andparams, the values filled into it; a name from the project is a value as written, except that a Power Query query or step name, and a model object's table in atableRefparam, are written as TMDL writes a reference to it, such as'Sales'; and a value can itself be a message,{ "id", "params" }. A rule'slayerismodel,report,project(a rule that reads both), or, from 0.3.0,powerquery(a rule that reads the Power Query M in a model's files). A finding'slayeris the file family that holds it,modelorreport, so a Power Query rule's findings aremodel. From 0.4.0, a custom rule'sstatusiscustom, itsurlishttps://pbiplint.com/custom-rules/, and itsrulealso hascustom(true),ruleFile, anddescription, the rule's own; its findings have nodetail,messageId, orparams. A custom rule that cannot run is oneRULE_COULD_NOT_FINISHfinding whosedetailnames the rule, its file, and the reason.
A run over a folder that holds several projects prints version 2 (from 0.3.0), whose fields are:
tool:nameandversion.summary: the whole run's counts:projects, the number of projects;files, the number of files read, a model several projects read counted once;findings,errors,warnings, andinfos;ignored, the number of findings an annotation ignored; andruleErrors, the number of rules that could not finish, counted once for each project they failed in (a number here, where each project'sruleErrorslists them). Under--rule,shownholdsrules,findings,errors,warnings, andinfosfor what is shown across the projects.projects: one entry for each project, in the order the report lists them, each the version1document's fields withoutversionandtool, pluspath, the project's path relative to the folder named, with forward slashes. A model several projects' reports read is linted with each of them, and its findings are listed under the first only; each of those projects says so in adiagnosticsentry of kindshared-model. A project pbiplint cannot read has onePARSE_ISSUEfinding, no layer present, andfiles0.
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.
- It reads the files that describe a project, under the path you give it: the
.pbipfile, the model's.tmdlfiles, and the report'sdefinition.pbir,.platform, and JSON files, along with the report or model folder a.pbipfile or a report'sdefinition.pbirpoints to inside the folder you name, or the project folder (the folder that holds the.pbip); a reference that leads outside both, by its path or through a link, is not read, and the run says so in a notice. So a report whose model sits in a shared folder beside its own, such as../models, is linted with its model when you name the folder that holds both. From 0.3.0, when several reports share one model folder, naming the folder that holds them all lints the model with each of them, and it is read from disk once. It also reads the nearestpbiplint.config.json, or the one--confignames, and from 0.4.0 the rule files that config'scustomRulesnames. In a report'sStaticResourcesfolder it opens only the JSON files directly inSharedResources/BaseThemes,SharedResources/BuiltInThemes, andRegisteredResources, up to 5 MB each, and it uses only the themes the report'sreport.jsonnames. It lists folders to find those files, and opens nothing else: it never enters the.pbifolder, where Power BI Desktop keeps the model's local data cache, nor.git,node_modules, or a report'sCustomVisualsfolder, and it does not follow a symbolic link below the path you give.pbiplint skillreads the skill files it ships with (two from 0.4.0), and any copy already installed below the current folder.pbiplint reference(from 0.4.0) reads nothing: it prints what this version can run.pbiplint mcpreads what itslinttool is given, aspbiplint <path>does; from 0.4.0, given apath,explain_ruleandlist_rulesread the nearestpbiplint.config.jsonfrom that path up and the rule files itscustomRulesnames, andcustom_rules_referencereads nothing. - It writes the report to your terminal, or to the file
--outputnames (creating its folder if needed). Notices, and with--outputa one-line summary, go to stderr.pbiplint skill --installwrites each skill'sSKILL.mdinto the folder the assistant reads, below the current folder, when you ask it to: from 0.4.0 two files,pbiplint/SKILL.mdandpbiplint-custom-rules/SKILL.mdin that folder, or one with--name.pbiplint mcpwrites only its MCP messages, to stdout, for the app that started it. Nothing else: no cache, no settings file, no log. - It sends nothing. It makes no network request: no telemetry, no update check, no call home.
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
npm view pbiplint dependenciesprints nothing: the package has no runtime dependencies, so nothing else is installed with it.npm pack pbiplint --dry-runlists what it ships: thedist/pbiplint.mjsbundle, the sample project, the skill (skill/SKILL.md) and from 0.4.0 the custom rules skill (skill/pbiplint-custom-rules/SKILL.md), the README,NOTICE,LICENSE, andpackage.json.npm audit signatures, in an empty folder where you install only pbiplint, reports "1 package has a verified registry signature" and "1 package has a verified attestation". Releases are published from GitHub Actions with npm provenance, and the npm page (opens in a new tab) links the commit and the workflow run that built each version.
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.