Output formats#

Three formats, one flag apart. The terminal report is for humans; --json is the stable contract for scripts and agents; --sarif is for CI annotation.

--json#

agentdoctor --no-user --json

{
  "version": 1,
  "tool": "agentdoctor",
  "toolVersion": "0.1.0",
  "root": "/work/api",
  "scannedFiles": [
    { "path": ".claude/settings.json", "kind": "settings", "scope": "project", "bytes": 512 }
  ],
  "skippedFiles": ["/home/u/.claude/.credentials.json"],
  "rulesRun": ["correctness/invalid-json", "..."],
  "suppressed": 0,
  "grade": "D",
  "summary": { "error": 2, "warning": 1, "info": 0 },
  "findings": [
    {
      "ruleId": "security/unrestricted-bash",
      "severity": "error",
      "category": "security",
      "message": "\"Bash(*)\" auto-approves every shell command, including ones you have not seen.",
      "help": "Replace the wildcard with the specific commands you actually want unattended...",
      "file": ".claude/settings.json",
      "absolutePath": "/work/api/.claude/settings.json",
      "line": 4,
      "column": 7,
      "configPath": "permissions.allow[0]",
      "snippet": "Bash(*)"
    }
  ]
}

Field notes:

• grade is the health grade, computed from the post-filter findings: A+ zero findings, A info only, B 1-2 warnings, C 3+ warnings, D 1-2 errors, F 3+ errors.
• version is the format version. Additions are the only change ever made to shape 1; removals or renames would bump it.
• findings is sorted: severity first (error > warning > info), then file, then line.
• column, configPath, snippet, and help are null when not applicable.
• snippet never contains an unredacted secret — credential-shaped values are truncated to a prefix/suffix with (redacted).
• file is display-relative (repo-relative, or ~/-prefixed for user scope); absolutePath is absolute.
• A machine-readable JSON Schema ships in the package: schemas/report.schema.json.

--list-rules --json emits the catalogue as [{ id, severity, title }].

--sarif#

SARIF 2.1.0, consumable by GitHub code scanning and any SARIF-aware tool. Findings appear as inline annotations on the PR diff.

agentdoctor --no-user --sarif > agentdoctor.sarif

Properties worth knowing:

• Severities map error → error, warning → warning, info → note.
• partialFingerprints.agentdoctorFingerprint gives stable finding identity across runs, so GitHub tracks findings as "existing" rather than re-announcing them per commit.
• Artifact URIs are repo-relative. Files outside the repo (user scope) are shortened to a suffix rather than leaking an absolute home path into CI logs.
• Every rule referenced by a result includes its full description and help text in tool.driver.rules, so the annotation is self-explanatory in the GitHub UI.

Wiring for GitHub Actions is in the CI guide.

Terminal report#

The default. Grouped by file so you fix one file at a time; within a file, sorted by severity then line. Color respects NO_COLOR, FORCE_COLOR, and TTY detection, and degrades to plain text in pipes. Every finding ends with its rule id so --explain is always one copy-paste away.

The summary line always includes: the grade, counts by severity, rules run, elapsed time, suppressed findings (baseline + inline), and how many credential files were skipped unread.

Exit codes (all formats)#