Skip to content

CLI reference ​

JSON schemaVersion: 1 remains additive across the 6.x line. Scan exits remain 0 · 1 · 2 · 10 · 20, while verdict vocabulary includes WORTHY, NEEDS WORK, FORGED, UNKNOWN, and UNWORTHY.

Help ​

bash
mjolnir --help            # grouped overview: Scan · CI & PRs · Forensics · Maintenance · Meta
mjolnir help <verb>       # per-command page with copy-pasteable examples
mjolnir <verb> --help     # the same page, from the verb itself

mjolnir help is a verb — it never scans. A folder named help/ is still scanned as mjolnir ./help.

Usage errors (exit 10 preserved) ​

An unknown flag prints a friendly error on stderr: the offending flag, up to three nearest real flags (edit distance ≤ 2), and the exact help command:

text
mjolnir: unknown flag "--jso"
  Did you mean: --json
  Run mjolnir --help for the full flag list.

A crash (exit 20) prints a plain-language note and the stack trace only under --debug.

mjolnir scan --format github-summary [mjolnir.json] ​

Turns a saved --json report into GitHub CI output. One emitter, one code path — the scan itself never prints annotations.

bash
mjolnir --json > mjolnir.json && mjolnir scan mjolnir.json --format github-summary
  • Annotations (one per finding) go to stdout only when GITHUB_ACTIONS=true. Messages are truncated (~250 chars) with a pointer to the step summary; full text lives in the summary.
  • Step summary markdown goes to $GITHUB_STEP_SUMMARY when set, and to stdout otherwise: score + verdict band, a text score bar, the dimensions table, collapsible per-severity finding groups with Fix: lines, and an honesty notice for partial/no-score reports (reason: "no-tests-found" never fabricates a number).
  • Exit codes: 0 once rendered. The render never gates: the scan that wrote the report already returned its own exit code. 2 the report is not valid JSON or not a Mjölnir report. 10 the file does not exist. See exit codes.

Pointed at a directory instead of a report, --format github-summary scans it and prints the step summary markdown to stdout, with the scan's exit code.

mjolnir scan --format pr-comment [mjolnir.json] ​

Turns a saved --json report into the pull-request comment, without a second scan, so the comment describes the result the gate read.

bash
mjolnir --json > mjolnir.json && mjolnir scan mjolnir.json --format pr-comment > comment.md

The comment states the commit the scan recorded only while the repository holding the report is still at that commit; otherwise it reads unknown. Exit 0 once rendered, 10 when the report cannot be read. Pointed at a directory, it scans and renders, with the scan's exit code.

Live scan progress ​

The scan paints an event-driven progress line on stderr (Discovering files… → Parsing frameworks… → Running rules… → Scoring…). It advances only on real events — no timers — and erases itself when the report begins.

Auto-disabled (nothing is ever written) when: stderr is not a TTY, the output is a machine format (--json, --format sarif|mermaid), GITHUB_ACTIONS=true/CI=true, or --no-progress is passed. stdout stays byte-identical in every mode.

FlagMeaning
--no-progressnever render the live progress line
FORCE_COLOR0/false/empty forces plain output; any other value forces color even piped (wins over NO_COLOR)
--ascii / --no-asciiforce plain-ASCII or Unicode glyphs (auto-detected by default)

The remediation loop (why / handoff / install) ​

Mjölnir provides evidence and verification. The agent (or human) remains responsible for every change.

SCAN → DETECT → EVIDENCE → EXPLAIN → HANDOFF → FIX → RE-SCAN → VERIFY

mjolnir explain <file>:<line> ​

Occurrence-level evidence query — informational, NOT a gate. Exact file+line match over the report; renders the finding's severity, message/why/fix, evidence level (E0–E2), trust level (L0–L5 runtime corroboration), measured FP rate (or "ships on assumption"), and the suppression contract (ignore entries in mjolnir.config.json: reason required; only an explicit ISO expires date is bounded). Saved-report mode (--json <mjolnir.json>) is authoritative; live scan runs otherwise. Exit 0 match, 1 no match, 10 usage, 2 invalid report.

mjolnir handoff [mjolnir.json] ​

Turns a saved --json report into a deterministic remediation plan: per-rule sections (what is wrong / why / evidence boundary / occurrences capped at 25 / fix / constraints), a self-contained per-rule copy block and a one-shot handoff prompt, and the verification contract:

  • TARGET_RESOLVED — every fingerprint (ruleId + file + message) from the document is absent from the post-fix scan.
  • TARGET_REMAINS — at least one still present; report honestly.
  • NEW_FINDINGS_INTRODUCED — new fingerprints appeared; report them.
  • VERIFICATION_NOT_RUN — no post-fix scan, or a partial scan.

A clean --scope changed run verifies the changed-scope surface only — it is never a statement that the entire repository is clean. Exit 0 on success (10 missing file, 2 invalid JSON). Zero findings → a clean, non-actionable artifact.

mjolnir install [--staged-hook] [--dry-run] [--force] ​

Installs the trust-loop brief into detected instruction surfaces (.claude/commands/mjolnir.md, .kilo/command/mjolnir.md, .cursor/rules/mjolnir.mdc, marker-appended AGENTS.md) — version pinned, never @latest. --staged-hook adds a NON-BLOCKING pre-commit hook (mjolnir --staged --blocking warning), reusing .husky or core.hooksPath when present. Marker-based idempotency; --dry-run writes nothing; refuses (exit 10) before overwriting anything not Mjölnir-marked.

--score, --category, --staged, --blocking ​

FlagEffect
--scorestdout is ONLY the score (unknown when no tests); scan semantics and exit codes unchanged
--category <cat>presentation filter on rendered findings — never a scan/data/score filter; score keeps reflecting the full scan
--stagedscan-surface restriction to git staged files; the score reflects that surface and is labeled
--blocking <level>exit-status override (error/warning/none); detection and rendering identical; E0 findings never block

Released under the MIT License.