gdhealth

CLI Reference

All gdhealth subcommands, flags, output formats, and exit codes.

Global flags

FlagDescription
--config <path>Path to a gdhealth.toml, or to a gdsuite.toml with a [health] section. Defaults to gdsuite.toml's [health] section in the current directory, then gdhealth.toml; with neither, built-in defaults are used.
--versionPrint the gdhealth binary version and exit 0.
--schema-versionPrint the public JSON schema version and exit 0.

The schema version probe is also available as a subcommand:

gdhealth schema-version

Subcommands

gdhealth graph

Extract and render the file dependency graph.

gdhealth graph --root <path> [--format <fmt>] [--output <file>]
FlagDefaultDescription
--root <path>.Project root to analyze
--format <fmt>textOutput format (see table below)
--output <file>stdoutWrite output to a file instead of stdout
--include-testsoffInclude files matched by the test group

Always exits 0. Use policy --fail-on or health --fail-on to control CI behavior.


gdhealth metrics

Compute file and function-level complexity metrics.

gdhealth metrics --root <path> [--format json|text] [--output <file>]
FlagDefaultDescription
--root <path>.Project root to analyze
--format <fmt>textjson or text only
--output <file>stdoutWrite output to a file
--include-testsoffInclude files matched by the test group

Always exits 0. Does not support --fail-on.


gdhealth policy

Evaluate architecture and complexity policies.

gdhealth policy --root <path> [--format json|text] [--fail-on critical|warning|info]
FlagDefaultDescription
--root <path>.Project root to analyze
--format <fmt>textjson or text only
--output <file>stdoutWrite output to a file
--fail-on <sev>offExit 1 if any finding is at or above this severity

gdhealth health

Bundle a full health report. This is the recommended command for most users and CI.

gdhealth health --root <path> [--fail-on critical|warning|info]

When --output is not set, writes the full bundle to <root>/reports/code-health/:

reports/code-health/
├── graph.json
├── graph.dot
├── metrics.json
├── policy.json
├── health.json
└── summary.txt

When --output <file> is set, writes a single file in --format json|text instead.

FlagDefaultDescription
--root <path>.Project root to analyze
--format <fmt>textjson or text — only used when --output is set
--output <file>bundleWrite single file instead of the bundle
--fail-on <sev>offExit 1 if any finding is at or above this severity
--no-gitoffSkip git-derived signals even if [git] enabled = true

health.json additionally carries git_available, repo_bus_factor, top_churn_files, and top_co_changes. metrics.json carries duplication (clone pairs) and cycle/split-file policy findings may carry a suggested_fix. See Schema Reference.


gdhealth risk

Score a git commit or base..head range from diff shape alone (size, diffusion, author experience). Each feature is ranked against this repository's recent commit history and combined into a transparent heuristic score. It helps focus review; it is not a statistically validated defect predictor.

gdhealth risk [revspec] --root <path> [--format json|text]
FlagDefaultDescription
revspecHEADA commit (HEAD, abc123) or a range (HEAD~5..HEAD)
--root <path>.Project root (must be a git repository)
--format <fmt>textjson or text only
--no-gitoffN/A — risk always needs git; exits 1 if unavailable

Always exits 0 on a successfully scored change; exits 1 if git is unavailable or the revspec is invalid. Does not support --fail-on — it's diagnostic, not a CI gate.


gdhealth validate-defects

Self-check: do the files with the worst structural hotspot score actually carry more prior-defect history (from git) than the repo average? Prints "insufficient data" rather than a misleading number below 25 scored files or 5 files with defect history.

gdhealth validate-defects --root <path> [--format json|text]
FlagDefaultDescription
--root <path>.Project root to analyze
--format <fmt>textjson or text only
--no-gitoffSkip git-derived signals (report will read as unavailable)

Always exits 0. Diagnostic only — never part of health or CI gating.


Output format support matrix

Formatgraphmetricspolicyhealth
text✓✓✓✓
json✓✓✓✓
dot✓
emerge-json✓
emerge-html✓

emerge-html writes a self-contained browser viewer to reports/code-health/browser/emerge.html.

Using an unsupported format for a command exits 1 with an error message.


Exit codes

CodeMeaning
0Success. No findings at or above the --fail-on threshold (or --fail-on not set).
1Error: invalid config, I/O failure, unsupported format, or findings at/above --fail-on level.

--fail-on severity levels

ValueTriggers on
infoAny finding (info, warning, or critical)
warningWarning or critical findings
criticalCritical findings only