← All guides

Pre-flight CLI / UPDATED 10 OCTOBER 2026

Check before you push

Run NodeDots locally on working changes, staged files, or two commits. Local advisory analysis for Node.js 22+.

Run Pre-flight

You need Node.js 22 or newer, Git, and a repository with an existing commit. Run the command inside your repository. npm downloads the CLI on first use; analysis runs locally. No GitHub sign-in, App installation, or running web server is required. This first release is advisory.

Terminal
npx nodedots check --staged
npx nodedots check --format json

Check your repository

Use --cwd to check another local repository. The default compares tracked working-tree contents with HEAD. Untracked files are excluded unless explicitly requested; ignored files remain excluded.

Terminal
npx nodedots check --cwd /path/to/repository
npx nodedots check --cwd /path/to/repository --include-untracked

Choose the right snapshot

--staged reads Git index contents and ignores unstaged edits. --base and --head compare committed snapshots and ignore local file contents. The comparison is direct: choose a merge-base yourself if your workflow needs one. Required commits must already exist locally. Resolve index conflicts and create a first commit before checking.

Terminal
npx nodedots check --staged
npx nodedots check --base HEAD~1 --head HEAD --format json

Install the standalone command

Install the command globally if you prefer a persistent executable. The bundle needs Node and Git and has no runtime npm dependencies or install hooks. Release checks passed on Linux, Windows, and macOS with Node 22, 24, and 26.

Terminal
npm install --global nodedots
nodedots check --staged
nodedots check --help

Use optional failure policies

Reports are advisory by default. --fail-on high, medium, or low returns exit 1 when a non-uncertain observation meets that threshold. --require-full returns exit 3 for incomplete coverage or withheld findings and takes precedence over finding gates. Exit 2 means input or runtime failure. Exit 0 only means the selected policy passed; it does not establish safety.

JSON output on stdout includes schemaVersion, cliVersion, the selected snapshot, exitCode, and the engine report. Errors go to stderr. In CI, make both commit objects available and install a pinned CLI version. No hooks or branch protection are configured automatically.

Terminal
nodedots check --staged --fail-on high --require-full
nodedots check --base HEAD~1 --head HEAD --format json > preflight.json

Build and validate from source

Contributors can build the standalone package from the NodeDots repository. The release check runs engine tests and installs the archive against TypeScript, React, and Prisma repository fixtures.

Terminal
git clone https://github.com/0xUkobong/nodedots.git
cd nodedots
npm ci
npm run cli:release-check

Read the limits with the findings

Pre-flight uses deterministic analysis for supported JavaScript, TypeScript, Prisma, test-import, and environment-reference patterns. It performs no external AI calls, source uploads, fetching, fixes, or repository-code execution. Git clean filters and filesystem-monitor helpers are disabled for reads. Local checks can examine public or private repositories you can access; hosted beta repository restrictions are separate.

Private .env files, .dev.vars, credential extensions, linked paths, generated files, dependencies, binary content, and unsupported changes are excluded with coverage notes. Use .env.example or --env-example for a non-secret inventory. Source evidence may appear in reports; handle exported output accordingly.

Limits are 1 MB per file, 500 changed files, 10,000 eligible files, and 100 MB each for Git blobs and working content. Dynamic relationships, graph limits, omitted findings, and unsupported patterns remain limitations. Keep tests and human review in your shipping workflow.