CLI reference

The npm package ships two executables:

Binary	Purpose in 1.2.1
signalint	Explicit terminal CLI: init, check, stats, doctor, help, version
signalint-mcp	Stdio MCP server; also dispatches recognized CLI verbs since 1.1.1

After a local installation use npx --no-install signalint, pnpm exec signalint, or yarn run signalint in the intended project.

signalint-mcp doctor and signalint-mcp check . now dispatch to the CLI. Recognized first arguments are init, check, doctor, stats, help, --help, -h, --version, and -v. A bare interactive TTY launch prints guidance to stderr and exits 2; a non-TTY MCP client launch starts stdio normally. Unknown first arguments are not automatically treated as CLI verbs by the MCP entry point.

init

npx --no-install signalint init

Detects native configurations, creates a missing signalint.config.json, automatically appends .signalint/ to .gitignore when needed, and asks before writing a selected client entry. Existing Signalint configuration is not overwritten. It warns when no linter can be resolved, or when a detected TypeScript setup has no available compiler; it does not install the engines for you.

See installation for optional-peer setup and strict JSON-merger caveats.

check

npx --no-install signalint check .

Checks the current project or one or more relative paths. The default output is pretty-printed schema 1.4 JSON, with clusters and flat remaining records, not a prose report or an MCP transport envelope.

The first positional path selects one TypeScript configuration. A directory such as src requires src/tsconfig.json; additional paths do not select more programs. See engine selection. The expanded snapshot can refuse a large . check even when only one path was supplied.

Output format

npx --no-install signalint check . --format json
npx --no-install signalint check . --format github

Supported formats are json and github. GitHub output emits an annotation for each collected normalized issue, including its file, line, column, rule, severity, and message; it is not restricted to summary samples. There is no --format text option.

Compact keys

npx --no-install signalint check . --compact

--compact or SIGNALINT_COMPACT=1 abbreviates check keys and omits projectRoot. The JSON output is still pretty-printed by the CLI. --compact is not a --minify flag, and is independent of MCP payload mode. See the key mapping.

Failure threshold

By default, clean exits 0; non-clean results exit 1.

npx --no-install signalint check . --fail-on-priority 3

In 1.2.1 this tests returned clusters and returned flat records. Flat priorities are derived from severity/fixability when absent. A threshold of 3 includes errors at priorities 1–3; 5 includes warnings too. The parser accepts positive integer thresholds; the semantic priority ladder itself is 1–5.

Still inspect status. Omitted flat records are not independently examined. Engine failure without a qualifying returned issue can exit 0 with this flag. Inspect JSON status and engines, and keep native compiler/linter CI checks when completeness matters.

Invalid command usage returns 2; unexpected CLI failures return 1 with a concise stderr message.

doctor

npx --no-install signalint doctor

Reports:

• Working-directory root and configuration-file existence.
• JS/TS project markers.
• Package metadata for Oxlint, TypeScript, Biome, and ESLint.
• Effective MCP payload mode it resolves, plus missing-linter/TypeScript hints.
• Some detected stale cwd entries and Signalint-labeled legacy Antigravity entries.

Doctor attempts to load configuration for payload mode, but can swallow parse errors and still report PASSED. Missing-engine warnings are not necessarily blocking. Package inspection is not a successful engine run, and the report does not validate every client setting, root override, or editor trust requirement. Confirm the actual MCP root and a real diagnostic result.

stats

npx --no-install signalint stats
npx --no-install signalint stats --json

Reads retained MCP check metrics from .signalint/session.jsonl and .1, deduplicating retained overlap. --json returns the machine-readable aggregate instead of the human report.

JSON field	Meaning
checks, payloadSamples	Retained valid entries and entries with a non-zero normalized baseline
averagePayloadReductionPercent	Arithmetic mean of per-check minified normalized-to-response byte reductions; can be negative or null
cacheHits, cacheMisses, cacheHitRatePercent	Completed-task engine-file lookups, not database row/disk counts
latencySamples, averageLatencyMs, maxLatencyMs	Retained measured check latency; missing averages are null
loopWarningsTriggered	Distinct diagnostic signatures with retained loop warnings, not all conversations or churn events
malformedLinesSkipped	Invalid retained lines skipped while reading statistics

Metrics are recorded before MCP transport formatting. They do not count both channel duplication or RPC framing, and changing mcpPayload is not directly reflected as measured wire savings. CLI check does not populate this MCP session history. Empty stats before MCP checks are expected.

Help and version

npx --no-install signalint --help
npx --no-install signalint --version

MCP initialize now derives its version from the installed package through resolveSignalintVersion(). The previous hardcoded 0.4.2 mismatch is fixed in 1.2.0.

Hooks and workspace/state controls

signalint hooks preview|install|run --runtime claude|cursor|codex|vscode manages emitted verify-after-edit hooks. Preview first; installation can replace existing targeted hook entries. Hook decisions are JSON, not a conventional lint exit gate. Read hooks.

SIGNALINT_MONOREPO_MODE=off|auto|strict overrides workspace planning config. SIGNALINT_STATE_DIR redirects supported cache/session/normal TypeScript state; use an absolute separate destination where isolation matters. SIGNALINT_PROJECT_ROOT is a server root override, not a replacement for choosing the intended CLI working directory. See monorepos.