Charter — AI-Agent Readiness Scanner

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

charter doctor

Flags

--path

string

Explicit repository root to scan. Defaults to the current working directory.

--threshold

int

Minimum passing score. Overrides the threshold or profile value in charter.yaml when provided.

--format

text | json | markdown | sarif

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.

--out

string

Write the rendered output to a file instead of stdout.

--rule

string

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.

--quiet

boolean

Suppress non-failure output. Useful in hooks and CI. Applies to text output only — JSON, Markdown, and SARIF still emit the full payload.

--color

auto | always | never

Color output mode for text rendering. Defaults to auto.

--no-color

boolean

Disable color. Equivalent to --color=never and wins over --color when both are set.

-i, --interactive

boolean

Open the interactive TUI. Requires a real terminal — exits with code 2 if stdin is not a TTY.

Output Formats

Text (default)
JSON
Markdown
SARIF

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.

charter doctor
charter doctor --format text --out scan.txt

Machine-readable payload for scripts and tooling. The top-level shape includes:

{
  "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."
    }
  ]
}

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.

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.

charter doctor --format sarif --out charter.sarif

In a GitHub Actions workflow:

- 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 non-TTY, malformed `charter.yaml`, unreadable files

​Usage

​Flags

​Output Formats

​Interactive TUI

​Exit Codes

Usage

Flags

Output Formats

Interactive TUI

Exit Codes