codecharter analyze [path] [options]
[path] is the path to a .sln, .slnx, or .csproj file. When omitted, or
when it points at an existing directory, that directory (the working directory
when omitted) is searched recursively (skipping bin, obj, .git, and
node_modules) and the shallowest .sln/.slnx is analyzed, falling back to a
.csproj when no solution exists. If several candidates are found the shallowest,
alphabetically first one is used and the others are listed; pass a path to a
specific file to override. If nothing is found, analyze stops with exit code 2.
Examples
# Auto-discover the solution under the current directory
codecharter analyze
# Default run against an explicit solution, output to console
codecharter analyze MySolution.sln
# JSON output to a file
codecharter analyze MySolution.sln --output json --output-file findings.json
# Only errors as build blockers, GitHub annotations for PR inline comments
codecharter analyze MySolution.sln --output github-annotations --fail-on error
# Rule set from a different directory
codecharter analyze MySolution.sln --rules ./shared-rules
# Diff-only: report and gate on lines changed against the base branch
codecharter analyze MySolution.sln --git-ref origin/main..HEAD --fail-on error
# Diff-only from a pre-computed diff (or stdin with '-')
git diff origin/main..HEAD | codecharter analyze MySolution.sln --diff -
Options
| Option | Default | Description |
|---|---|---|
--rules <dir> |
./rules |
Directory containing .ccr rules. Default is ./rules in the current directory. |
--output <format> |
console |
Output format: console, json, sarif, github-annotations. Repeatable with format:path for multiple outputs in one run. See Output Formats. |
--output-file <path> |
stdout | Write output to a file instead of stdout. Only valid for the single-output form; cannot be combined with format:path. |
--severity <level> |
info |
Minimum severity shown in output: info, warn, error. |
--fail-on <level> |
not set | Exit code 1 for findings at or above this severity: info, warn, error. Without this flag, any finding shown at the current --severity threshold causes exit code 1. Pass --fail-on error to gate only on errors. |
--no-color |
off | Disable ANSI color codes in console output. |
--verbose |
off | Detailed diagnostic logs. |
--progress |
off | Live progress on stderr while analyzing. Shows i/N plus a percentage per project and per rule; the solution-load phase shows a spinner only (no measurable sub-progress). In a terminal it updates a single spinner line; when stderr is redirected (as in CI) it prints throttled progress lines. Can be combined with --verbose. |
--workspace-root <path> |
not set | Path prefix to strip from file paths. Useful for github-annotations. |
--diff <path\|-> |
not set | Diff-only mode: report and gate on only the lines added or modified by this unified diff. Pass a diff file path, or - to read the diff from stdin. Mutually exclusive with --git-ref. |
--git-ref <range> |
not set | Diff-only mode: report and gate on only the lines changed in this git ref range (e.g. origin/main..HEAD); runs git diff <range> --unified=0. A two-dot range is diffed from the merge base, an explicit three-dot range is used as typed, and a bare ref or SHA keeps git's meaning of "working tree against that commit". Mutually exclusive with --diff. |
--diff-context |
off | With --diff/--git-ref, also report findings in the touched files whose line is not among the changed lines — a class-level finding such as a newly introduced God-class, for example. They join the reported findings and the --fail-on gate. Without the flag they are only counted on stderr. |
--write-baseline <file> |
not set | Run the analysis and write the current findings' fingerprints to this baseline file, then exit 0 without reporting findings or gating. See Baseline gate. |
--baseline <file> |
not set | Suppress findings recorded in this baseline file so output and --fail-on apply only to new findings. A missing file analyzes everything (with a warning). See Baseline gate. |
--telemetry |
off | Opt-in: after the run, send one anonymous usage event (tool name, latency bucket, per-rule finding counts, hashed workspace id) to the CodeCharter endpoint. Off by default; no source, file paths, or code are ever sent. Best-effort — never affects the run. |
--telemetry-endpoint <url> |
portal | Override the telemetry ingestion endpoint. |
--license <path> |
not set | Path to the license file, overriding the default search locations. Every run passes the license check. See License File. |
Diff-only mode
--diff and --git-ref restrict the run to findings on added or modified lines. The whole solution is still loaded and analyzed (rules need the full type model), but both the reported findings and the --fail-on gate are scoped to the diff — so a pull request fails only on issues it introduced. Diff paths are resolved against the git repository root, so a solution in a subfolder works. When the diff touches no analyzed line, the run reports nothing and exits 0.
--git-ref diffs a two-dot range such as origin/main..HEAD from the merge base of the two commits — git's three-dot form — so commits that landed on the base branch since you branched off are not counted as your changes. Write the three-dot form explicitly and it is used as typed; pass a bare ref or SHA and it keeps git's own meaning of "working tree against that commit". coverage --git-ref takes the same range syntax.
Some findings are attributed to a line your diff never touched even though your change caused them — a class that only became a God-class once you added a method, for example. Diff mode counts these on stderr instead of hiding them; add --diff-context to report them and include them in the --fail-on gate.
Baseline gate
--baseline reports and gates only on findings that are not in an accepted baseline, so existing findings are tolerated while new ones fail the build — see the Baseline gate guide. It composes with diff mode (both filters apply).
Platform profiles
When your repository's .codecharter/config.yml declares platform profiles, analyze picks it up automatically (the file is found by walking up from the analysed file) and runs only the portal rule bundles for those profiles. Profiles and local rules are mutually exclusive, not additive: an explicit --rules <dir> bypasses profiles entirely and always wins, while without it configured profiles take over the run and any local ./rules directory is ignored (the CLI logs which source is active). Only when no profiles are configured does the discovered local ./rules folder apply. See Using platform profiles. When you run with built-in or local rules only and no platform profiles are configured, the CLI prints a deprecation warning on stderr pointing to platform profiles. Setting the environment variable CODECHARTER_SUPPRESS_DEPRECATION_WARNING=1 suppresses the warning (the value must be exactly 1); the warning never affects findings or the exit code.
Suppressions
The ignore and exclude sections of .codecharter/config.yml, and // codecharter-disable / // codecharter-disable-next-line comments in source files, suppress findings before output and gating, so suppressed findings neither appear in the results nor affect the exit code. See Suppressions.
Exit Codes
0: Run successful, zero findings at or above the active threshold.1: One or more findings at or above the threshold. Without--fail-on, any finding at or above the--severitythreshold triggers exit 1.2: Usage or configuration error (for example invalid flag combinations, a missing diff file, no rules directory found, or a corrupt baseline file).3: Analysis failed, for example because the solution or a project could not be loaded.6: License error (missing, expired, or not valid for this CLI version).
With platform profiles configured, the pre-run check can also exit 2 (lockfile missing), 3 (profile cache incomplete and portal unreachable), or 4 (lockfile out of date). More at Exit Codes.