CLI Reference
featuresmith diff
CLI command reference for snapshot diffs
bash
featuresmith diff <old> <new> [options]Compares two dataset snapshots and outputs structural, schema, missingness, duplicate, cardinality, and distribution shifts.
Flags and Options
| <old> | Required argument: path to the older dataset version (CSV, Excel, Parquet). |
| <new> | Required argument: path to the newer dataset version. |
| --target TEXT | Name of the target column in both datasets to compare target leakage changes. |
| --format [table|json] | Output format to display (default: table). |
| --output PATH | Path to save the plain report or JSON output. |
| --fail-on [info|warning|critical] | Severity threshold for CI-gating exit codes (default: critical). |
| --quiet | Suppress all standard console report output. |
| --verbose | Show full Python tracebacks on error instead of generic messages. |
| --version | Show version info and exit. |
Exit Codes
The command returns exit codes based on structural regressions and quality drops:
0: Clean — no regression or quality drop meets or exceeds the severity threshold specified in--fail-on.1: Regressions (e.g. dropped columns, dtype mismatches, increased missingness, or target leakage escalation) meeting or exceeding the threshold were detected.2: Invalid usage, bad configuration, or target column missing.3: Source files missing or failed to parse.4: Internal error.
CLI Syntax Examples
bash
# Compare two dataset snapshotsfeaturesmith diff train_v1.csv train_v2.csv# Diff target leakage status changesfeaturesmith diff train_v1.csv train_v2.csv --target churn --fail-on warning# Output JSON reportfeaturesmith diff train_v1.csv train_v2.csv --format json --output diff_report.jsonNotes and Limitations
- Target validation: The target column is validated against the schema of both snapshot versions. Missing columns in either version result in an exit code 2.
- Deterministic summary: Deliberately uses the deterministic statistical profiling engine to generate snapshots, avoiding raw-data re-reads during comparisons.
Related Documentation
See the SDK equivalent fs.diff() and the review CLI reference featuresmith review.