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

charter doctor --path /path/to/repo --threshold 90

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

charter doctor --quiet --threshold 80

charter doctor --rule AE-SEC-001

charter doctor TTY output — charter doctor — styled terminal output with category scorecard and findings

Flags

string

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

int

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

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.

string

Write the rendered output to a file instead of stdout.

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.

boolean

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

auto | always | never

Color output mode for text rendering. Defaults to auto.

boolean

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

boolean

Open the interactive TUI. Requires a real terminal.

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

GitHub Action

Gate pull requests on the Charter score in CI.

Scoring and caps

How the 0–100 score and severity caps are computed.

fix

Apply diff-first auto-repair for supported findings.

​Usage

​Flags

​Output Formats

​Interactive TUI

​Exit codes

​Related

GitHub Action

Scoring and caps

fix

Usage

Flags

Output Formats

Interactive TUI

Exit codes

Related