codecharter config

The config command group reads and edits .codecharter/config.yml for you. Every write keeps your comments, key order, and formatting intact, validates the change before touching the file, and never leaves the file half-written.

codecharter config <subcommand> [arguments] [options]

For the configuration file format itself — profiles, parameters, severities, rule activation, and path scopes — see Configuration file. This page covers the commands that change it.

Inspecting the configuration

• codecharter config explain <path> shows the effective configuration for one source file, with the layer each value came from. Add --json for machine-readable output.
• codecharter config validate checks the file for structural errors, unknown rules, invalid parameter values, and entries that never match anything.
• codecharter config schema emits a JSON Schema for editor completion. Pass --out <file> to write it to disk.
• codecharter config get <key> prints the raw value of a single key.
• codecharter config list [section] prints a summary of all sections, or the entries of one section (profiles, params, overrides, ignore, include, exclude, scopes).

get takes a dotted key: params.<rule>.<name>, overrides.<rule>.severity, or profiles.<slug>. Add --scope "<glob>" to read from a scope whose match equals that glob instead of the base layer.

Editing values: set and unset

codecharter config set <key> <value> [--scope <glob>] [--local] [--dry-run] [--rules <dir>]
codecharter config unset <key> [--local] [--dry-run]

set writes a parameter, a severity override, or a profile version:

codecharter config set params.cyclomatic-complexity.max 15
codecharter config set overrides.magic-number.severity warning
codecharter config set profiles.dotnet-base 1.4.2

The value is validated before the file is written: an unknown rule, a parameter the rule does not expose, an out-of-range value, or an invalid severity is rejected and the file is left untouched (exit code 10). unset removes a params or overrides entry again.

To validate parameter values against your rules, point --rules at a directory of .cgr files. When omitted, ./rules and the bundled rules are tried, the same discovery analyze uses.

Managing lists: add and remove

codecharter config add <section> [value] [--in <ns>] [--match <glob>] [--path <file>] [--scope <glob>] [--local] [--dry-run]
codecharter config remove <section> [value] [--in <ns>] [--match <glob>] [--path <file>] [--scope <glob>] [--local]

add and remove manage the list-valued sections:

codecharter config add exclude "**/Migrations/**"
codecharter config add profiles security@latest
codecharter config add ignore todo-comment --in Acme.Generated
codecharter config add include todo-comment --match "*Dto"

For ignore and include, --in narrows the entry to a namespace and --match to entities whose name matches a glob. For profiles, use --path to reference a local bundle file instead of a slug. remove deletes the matching entry; an ambiguous removal that matches more than one entry is reported as a usage error rather than guessing.

Targeting scopes and the local overlay

Two options change where a write lands; they apply to set, unset, add, and remove:

• --scope "<glob>" writes into the scope whose match equals that glob, creating the scope at the end of the file if it does not exist yet. Without it, writes go to the base layer.
• --local targets .codecharter/config.local.yml — your personal, machine-local overlay — instead of the committed config.yml.

--dry-run prints the unified diff of what would change and writes nothing. Combine it with any write to preview the edit first.

Scaffolding and cleanup: init and tidy

codecharter config init [--at <dir>] [--profiles <csv>] [--local] [--force] [--dry-run]
codecharter config tidy [--local] [--dry-run]

init creates a minimal .codecharter/config.yml (just version: 1). Seed profiles with --profiles "[email protected],security@latest", choose the directory with --at, create the local overlay instead with --local, and overwrite an existing file with --force.

tidy removes empty sections that earlier edits may have left behind, keeping the file clean.

The local overlay: config local

codecharter config local clone [--force] [--dry-run]
codecharter config local diff
codecharter config local clear [keys...] [--dry-run]

.codecharter/config.local.yml overrides config.yml on your machine and is never committed (add it to .gitignore). The local subgroup manages it:

• clone copies the committed config to config.local.yml as a starting point. --force overwrites an existing overlay.
• diff shows what the overlay currently overrides.
• clear removes specific dotted keys from the overlay, or deletes the whole overlay file when no keys are given.

Moving settings between layers: promote and demote

codecharter config promote [key] [--all] [--keep] [--dry-run] [--rules <dir>]
codecharter config demote [key] [--all] [--dry-run] [--rules <dir>]

• promote moves a setting out of your local overlay into the committed config.yml — for when a personal tweak should become the team default. --keep copies instead of moving (the entry stays in the overlay), and --all promotes the entire overlay and then clears it.
• demote copies a committed setting into your local overlay, so you can then let it float locally without changing the shared file. --all copies the whole committed config into the overlay.

A common pattern: demote profiles.dotnet-base followed by set profiles.dotnet-base latest --local pins the team to an exact version while you track the newest on your machine.

Exit codes

The reading commands get and list use:

• 0: success.
• 1: no .codecharter/config.yml was found.
• 2: usage error (for example an unparseable key).

The editing commands (set, unset, add, remove, init, tidy, the local subgroup, promote, demote) use:

• 0: success, including --dry-run previews.
• 2: usage error (bad arguments, or an ambiguous remove).
• 10: validation error — the change was rejected and the file left untouched.