Commands

The same commands work in every language

One install, then mlreps in any project — Java, Python, PHP, Node, anything the reader can read. Node.js 20 or newer on your machine is the only requirement. Teams without Node use the GitHub App instead, which installs nothing.

Install

once, on your machine

npm install -g mlreps

Or without installing anything, npx mlreps@latest works in place of mlreps in every command below. The install touches nothing in your project.

Account

mlreps setup [path]

Connect this repository: one click to authorise this machine, a publishing key kept outside the repository, and the first scan published.

setup example

mlreps setup

mlreps whoami

Which account and organisation this machine publishes to, and what it may publish.

whoami example

mlreps whoami

mlreps switch

Sign this machine out and let another account take it. Whoever approves in the browser becomes the account.

switch example

mlreps switch

mlreps login

Authorise this machine — one click in your browser, and it lasts thirty days.

mlreps login

mlreps logout

Forget this machine's authorisation. The credentials it minted keep working: they belong to the project.

logout example

mlreps logout

Scan and publish

mlreps scan [path]

The graph, what a change would reach, and what the rules found. The default command.

scan example

mlreps scan . --publish

Flags: --publish · --dry-run · --over-limit · --json · --record · --limit <n>

mlreps impact [path]

What this branch's change reaches, against its merge base.

impact example

mlreps impact --base main

Flags: --base <ref> · --fail-on-exposed · --json · --record · --limit <n>

mlreps history [path]

What the last scans found, and what changed between them.

history example

mlreps history --last 10

Flags: --last <n> · --json

mlreps badge [path]

The README line for this repository's badge — the date of its last audit. Free, and needs no key.

badge example

mlreps badge

mlreps doctor [path]

What this machine needs in order to read each language here.

doctor example

mlreps doctor

Pull requests and CI

mlreps check [path]

Post the result to this pull request with the CI's own token. Sends us nothing, and never fails the build.

check example

npx mlreps@latest check .

Flags: --dry-run · --json · --limit <n>

Guard

mlreps guard [path]

What changed since this repository's base scan, answered by the resident process.

guard example

mlreps guard

Flags: --status · --stop · --daemon · --idle <s>

mlreps hooks

Install a guard check — into a coding agent, or as a git pre-commit hook.

hooks example

mlreps hooks --git pre-commit

Flags: --agent <name> · --git <hook> · --print · --yes

mlreps mcp [path]

Answer an agent's questions about this repository's stored map, over stdio. Six read-only tools.

mcp example

mlreps mcp

Rules file

mlreps rules [path]

What mlreps.rules.yml says, and --starter to write five defaults you can edit.

rules example

mlreps rules --starter

Flags: --starter

Operators

mlreps register

Print the GitHub App manifest for a deployment of MLReps. For operators running their own.

mlreps register --base-url https://mlreps.acme.internal

Flags: --base-url <url>

mlreps help

This list, in the terminal.

help example

mlreps help

Per-language notes

The commands do not change. What changes is what a language needs installed before calls can be followed all the way through — and for most of them, nothing.

Language	For full resolution
Python	npm i -g pyright
PHP	npm i -g intelephense
Java	download jdtls, set MLREPS_JDTLS_HOME (and a JDK 25 on JAVA_HOME)
Ruby	gem install ruby-lsp (Ruby 3+)
C	install clangd (LLVM, or Xcode command-line tools)
C++	install clangd (LLVM, or Xcode command-line tools)
Dart	install the Dart SDK (puts dart on PATH)
Swift	install the Swift toolchain / Xcode (sourcekit-lsp); build the project for its index
Kotlin	download kotlin-language-server; set MLREPS_KOTLIN_JAVA_HOME to a JDK 17-21
Rust	install rust-analyzer and the Rust toolchain (rustup component add rust-analyzer)
C#	dotnet tool install --global csharp-ls (symbols only today)

Every other language the reader supports needs nothing installed. mlreps doctor says what this machine has, and a scan that could not follow a call says so rather than leaving it out.

Connecting a repository for the first time is Setup, and the GitHub App path — which installs nothing on your machine — is here.