> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# doctor
> Scan a repository, evaluate Charter's rules, and compute an AI-agent-readiness score.
`charter doctor` is the primary Charter command. It resolves the target repository, loads the effective score threshold from `charter.yaml` or the `--threshold` flag, evaluates the full rule set, renders the result, and exits with a code that is safe to use in local workflows, pre-commit hooks, and CI pipelines.
## Usage
```bash Standard scan theme={null}
charter doctor
```
```bash With explicit path and threshold theme={null}
charter doctor --path /path/to/repo --threshold 90
```
```bash SARIF output for CI theme={null}
charter doctor --format sarif --out charter.sarif
```
```bash Quiet mode for pre-commit hook theme={null}
charter doctor --quiet --threshold 80
```
```bash Single-rule targeted scan theme={null}
charter doctor --rule AE-SEC-001
```
## Flags
Explicit repository root to scan. Defaults to the current working directory.
Minimum passing score. Overrides the threshold or profile value in `charter.yaml` when provided.
Output format. Defaults to `text`. In a TTY, `text` renders styled terminal output; when piped or redirected, it falls back to a plain byte-stable stream.
Write the rendered output to a file instead of stdout.
Comma-separated rule IDs for a scoped text-only view. Omits the overall score and exits `1` if any named rule fired. Incompatible with `--interactive`.
Suppress non-failure output. Useful in hooks and CI. Applies to text output only — JSON, Markdown, and SARIF still emit the full payload.
Color output mode for text rendering. Defaults to `auto`.
Disable color. Equivalent to `--color=never` and wins over `--color` when both are set.
Open the interactive TUI. Requires a real terminal.
## Output Formats
Styled terminal output with a category scorecard, per-finding evidence rows, and a score hero at the bottom. In a TTY, Charter renders color and box-drawing characters. When stdout is piped or redirected, it falls back to a plain, byte-stable stream safe for log capture.
```bash theme={null}
charter doctor
charter doctor --format text --out scan.txt
```
Machine-readable payload for scripts and tooling. The top-level shape includes:
```json theme={null}
{
"score": 87,
"passed": true,
"threshold": 80,
"findings": [
{
"rule_id": "AE-ENV-001",
"severity": "Medium",
"category": "Environment",
"summary": "No .env.example found",
"evidence": "No .env.example detected in the repository root.",
"locations": ["/.env.example"],
"remediation": "Create a .env.example listing required environment variable names."
}
]
}
```
```bash theme={null}
charter doctor --format json
charter doctor --format json --out result.json
```
Formatted for GitHub PR comments. Paste directly into a PR description or post it via a CI step.
```bash theme={null}
charter doctor --format markdown
charter doctor --format markdown --out charter-summary.md
```
SARIF 2.1.0 format for GitHub Code Scanning. Upload the output file as a Code Scanning artifact to surface findings inline in pull requests.
```bash theme={null}
charter doctor --format sarif --out charter.sarif
```
In a GitHub Actions workflow:
```yaml theme={null}
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: charter.sarif
```
## Interactive TUI
`charter doctor -i` opens a full-screen terminal UI over a single scan result. It is a browser over the findings, not a different scan engine.
The TUI supports filter and search, drill-in on individual findings, rule-focused browsing, and in-place rescan. It is intentionally human-only — you cannot combine it with `--out`, `--quiet`, non-text `--format`, or `--rule`.
`-i` requires a real TTY. It exits with code `2` if stdin is not a terminal.
## Exit codes
| Code | Meaning | When |
| ---- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `0` | Pass | Score ≥ threshold, or `--rule` view found no matching findings |
| `1` | Fail | Score \< threshold, or `--rule` view found at least one matching finding |
| `2` | Error | Invalid `--format`, unknown rule ID in `--rule`, `--interactive` on a non-TTY, malformed `charter.yaml`, or unreadable files |
## Related
Gate pull requests on the Charter score in CI.
How the 0–100 score and severity caps are computed.
Apply diff-first auto-repair for supported findings.