codecharter analyze [path] [options]
[path] is the path to a .sln, .slnx, or .csproj file. When omitted, the
working directory 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
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, with a fallback to the sample rules next to the CLI. |
--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. Mutually exclusive with --diff. |
--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.
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 rules folder (local ./rules, then the bundled fallback) apply. See Using platform rules. 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: Configuration or rule error.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.