CLI Reference

Full command reference. Run cfgdrift COMMAND --help for the up-to-date options on your installed version. The feature list lives in README.en.md — Features at a Glance; this page expands it command by command.

Commands

init
scan
baseline create / list / show / rollback
diff
compare
severity
report
ignore
serve
daemon
alert
constraint
corpus
remediate

`init`

cfgdrift init

Initializes the SQLite database. Idempotent.

`scan`

cfgdrift scan PATH [--baseline B] [--save-as-baseline NAME] [--format FMT]
                  [--watch] [--interval N] [--description TEXT]
                  [--sensitive-keys K] [--no-line] [--builtin / --no-builtin]
                  [--constraints FILE] [--report-violations / --no-report-violations]
                  [--no-hint]

Scans a file or directory, records history, and optionally diffs against a baseline or saves a new baseline version. With --watch it polls periodically. --report-violations (off by default) reports pre-existing baseline constraint violations.

Typical output includes drift items with severity badges, key paths, and a Summary: added=… removed=… modified=… type_changed=… ignored=… total=… max=… line.

`baseline create / list / show / rollback`

cfgdrift baseline create NAME --file PATH        # snapshot a single file
cfgdrift baseline list                            # latest version of each baseline
cfgdrift baseline show NAME                       # metadata and data
cfgdrift baseline rollback NAME                   # drop latest version; previous becomes current

Baselines are versioned: creating the same name again bumps the version. rollback makes the previous version current.

`diff`

cfgdrift diff [PATH] --baseline NAME [--format FMT] [--color / --no-color]
               [--compare] [--env1 A --env2 B] [--sensitive-keys K] [--no-line]
               [--builtin / --no-builtin] [--constraints FILE] [--explain]
               [--schema FILE] [--llm / --no-llm] [--no-hint]

Diffs a file/directory against a baseline and prints the drift report. Each CRITICAL/WARN item gets a [hint] block (expected value / rollback command / provenance). --no-hint restores byte-identical v0.12.0 output. --explain appends a business-impact narrative. Exit codes: 0 = no drift, 1 = drift, 2 = error.

Typical output:

[CRITICAL] server.port (app.toml:12): 修改 9090 -> 9091
  [hint] 期望值 9090（基线 prod v3）
  [hint] 修复   cfgdrift remediate --baseline prod --apply
  [hint] 溯源   commit a3f2c9e "adjust prod port"
Summary: added=0 removed=0 modified=1 type_changed=0 ignored=0 total=1 max=CRITICAL

`compare`

cfgdrift compare ENV1 ENV2... [--severity S] [--json] [--no-line]
                  [--builtin / --no-builtin] [--constraints FILE]

Compares multiple environments' baselines against the first one. The header shows both baseline versions: compare A -> B (vX vs vY). With --constraints each side is also checked against the constraint library; violations are informational and never change the exit code.

`severity`

cfgdrift severity add|list|remove|enable|disable

Custom severity override rules (severity.yaml). Note: severity add --key-pattern / --value-pattern / --file-pattern are regex; the patterns in masking.yaml are glob (fnmatch). Never mix the two. Invalid regex → exit 2. v0.8.0 adds an extra AND condition --constraint-id.

`report`

cfgdrift report [--scan-id N] [--json out.json] [--html out.html] [--csv out.csv]
                [--diff A B] [--no-line] [--no-hint]

Renders a stored scan report. --json writes a JSON report; --html writes a single-file offline HTML report (summary cards + severity distribution + change list, zero external dependencies) usable as a CI artifact; --csv exports masked drift items; --diff A B compares two scans' drift items.

`ignore`

cfgdrift ignore add|list|remove   # exact / prefix / regex rules

`serve`

cfgdrift serve    # local Web dashboard at http://127.0.0.1:8080 (requires [web] extra)

See Web Dashboard.

`daemon`

cfgdrift daemon start [--target PATH] [--baseline B] [--interval N] [--remediate] [--dry-run]
cfgdrift daemon stop
cfgdrift daemon status
cfgdrift daemon enable-autostart [--target PATH] [--baseline B] [--interval N] [--user|--system] [--dry-run]
cfgdrift daemon disable-autostart
cfgdrift daemon autostart-status     # exit 0 = enabled / 1 = disabled / 2 = error

Background drift monitoring with periodic scans and automatic alerting. Auto-start works on systemd / launchd / schtasks across three platforms. With --remediate the daemon auto-repairs drifted keys per remediate.yaml (see Self-Healing).

`alert`

cfgdrift alert add|list|remove|enable|disable
cfgdrift alert add --name nginx-webhook --type webhook --url http://x --retry-count 5
cfgdrift alert add --name ops-email --type email --smtp-host ... --retry-delay 2,10,60
cfgdrift alert add --name x --type webhook --url http://x --retry-delay 1 --retry-delay 5 --retry-delay 30

Three channels: webhook / email / script. Rule-level retry: retry_count = total attempts (default 3), retry_delays = waits between attempts. Debounce cooldown is 600s. v0.10.0 adds --mute-until (rule-level silence) and event-level ack. See Alerting.

`constraint`

cfgdrift constraint add|list|remove|enable|disable|mine
cfgdrift constraint add --rule '{"id":"my_port","type":"range","keys":["server.port"],"min":1,"max":65535}'
cfgdrift constraint list [--source builtin|user]
cfgdrift constraint mine [--min-support N] [--source scans|corpus] [--json]

Five constraint types: range / enum / conditional_required / correlation / mutual_exclusion. mine discovers candidates (enabled:false, pending) for human review before promotion. See Constraints.

`corpus`

cfgdrift corpus init|fetch|export|validate|annotate|kappa|stats
cfgdrift corpus init --workspace <dir>
cfgdrift corpus fetch --workspace <dir>
cfgdrift corpus export --workspace <dir>
cfgdrift corpus validate --workspace <dir>
cfgdrift corpus annotate --workspace <dir> --annotator alice [--batch labels.yaml]
cfgdrift corpus kappa --workspace <dir> [--annotator-a A --annotator-b B] [--weighted linear|quadratic] [--json]
cfgdrift corpus stats --workspace <dir> [--json]

Benchmark corpus toolchain for academic reproducibility: mines config change pairs from real git history, standardizes them into instances.jsonl, supports dual annotation + Cohen's kappa. See Corpus Benchmark.

`remediate`

cfgdrift remediate [--baseline B] [--path REL] [--rule NAME] [--dry-run | --apply]
cfgdrift remediate list
cfgdrift remediate validate

Key-level auto-remediation: only the drifted value's text span is rewritten; every other byte (comments / indentation / key order / sibling keys) is preserved. Default is dry-run (preview only); --apply writes files. Every action lands in the remediation_log audit table. See Self-Healing.