CLI Reference
All gdhealth subcommands, flags, output formats, and exit codes.
Global flags
| Flag | Description |
|---|---|
--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. |
--version | Print the gdhealth binary version and exit 0. |
--schema-version | Print the public JSON schema version and exit 0. |
The schema version probe is also available as a subcommand:
gdhealth schema-versionSubcommands
gdhealth graph
Extract and render the file dependency graph.
gdhealth graph --root <path> [--format <fmt>] [--output <file>]| Flag | Default | Description |
|---|---|---|
--root <path> | . | Project root to analyze |
--format <fmt> | text | Output format (see table below) |
--output <file> | stdout | Write output to a file instead of stdout |
--include-tests | off | Include 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>]| Flag | Default | Description |
|---|---|---|
--root <path> | . | Project root to analyze |
--format <fmt> | text | json or text only |
--output <file> | stdout | Write output to a file |
--include-tests | off | Include 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]| Flag | Default | Description |
|---|---|---|
--root <path> | . | Project root to analyze |
--format <fmt> | text | json or text only |
--output <file> | stdout | Write output to a file |
--fail-on <sev> | off | Exit 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.txtWhen --output <file> is set, writes a single file in --format json|text instead.
| Flag | Default | Description |
|---|---|---|
--root <path> | . | Project root to analyze |
--format <fmt> | text | json or text — only used when --output is set |
--output <file> | bundle | Write single file instead of the bundle |
--fail-on <sev> | off | Exit 1 if any finding is at or above this severity |
--no-git | off | Skip 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]| Flag | Default | Description |
|---|---|---|
revspec | HEAD | A commit (HEAD, abc123) or a range (HEAD~5..HEAD) |
--root <path> | . | Project root (must be a git repository) |
--format <fmt> | text | json or text only |
--no-git | off | N/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]| Flag | Default | Description |
|---|---|---|
--root <path> | . | Project root to analyze |
--format <fmt> | text | json or text only |
--no-git | off | Skip git-derived signals (report will read as unavailable) |
Always exits 0. Diagnostic only — never part of health or CI gating.
Output format support matrix
| Format | graph | metrics | policy | health |
|---|---|---|---|---|
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
| Code | Meaning |
|---|---|
0 | Success. No findings at or above the --fail-on threshold (or --fail-on not set). |
1 | Error: invalid config, I/O failure, unsupported format, or findings at/above --fail-on level. |
--fail-on severity levels
| Value | Triggers on |
|---|---|
info | Any finding (info, warning, or critical) |
warning | Warning or critical findings |
critical | Critical findings only |