> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bensevern.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GoldenMatch CLI

> Every GoldenMatch command and the key flags for the dedupe pipeline.

## Commands

| Command                                                                                            | Purpose                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `goldenmatch dedupe FILE [...]`                                                                    | Deduplicate one or more CSV / Parquet / Excel files.                                                                                                                                                                                                                                                                                                                                               |
| `goldenmatch match TARGET --against REF`                                                           | Match a target against a reference file.                                                                                                                                                                                                                                                                                                                                                           |
| `goldenmatch sync --table TABLE --connection-string "$DB"`                                         | Incremental Postgres database sync.                                                                                                                                                                                                                                                                                                                                                                |
| `goldenmatch watch --table TABLE --config CONFIG`                                                  | Live stream mode: poll a table and match new records continuously.                                                                                                                                                                                                                                                                                                                                 |
| `goldenmatch serve FILE [...]`                                                                     | Start the REST API server (default `127.0.0.1:8080`).                                                                                                                                                                                                                                                                                                                                              |
| `goldenmatch mcp-serve FILE [...]`                                                                 | Start the MCP server (stdio or HTTP transport).                                                                                                                                                                                                                                                                                                                                                    |
| `goldenmatch interactive FILE [...]`                                                               | Launch the interactive TUI.                                                                                                                                                                                                                                                                                                                                                                        |
| `goldenmatch serve-ui [--project DIR]`                                                             | Start the web UI workbench.                                                                                                                                                                                                                                                                                                                                                                        |
| `goldenmatch setup`                                                                                | Interactive setup wizard (GPU, API keys, database).                                                                                                                                                                                                                                                                                                                                                |
| `goldenmatch demo`                                                                                 | Run the built-in demo with sample data.                                                                                                                                                                                                                                                                                                                                                            |
| `goldenmatch init`                                                                                 | Interactive config wizard.                                                                                                                                                                                                                                                                                                                                                                         |
| `goldenmatch profile FILE`                                                                         | Profile data quality.                                                                                                                                                                                                                                                                                                                                                                              |
| `goldenmatch evaluate FILE --gt GT.csv`                                                            | Evaluate matching accuracy against ground truth.                                                                                                                                                                                                                                                                                                                                                   |
| `goldenmatch incremental BASE --new NEW`                                                           | Match new records against an existing base.                                                                                                                                                                                                                                                                                                                                                        |
| `goldenmatch analyze-blocking FILE`                                                                | Analyze data and suggest blocking strategies.                                                                                                                                                                                                                                                                                                                                                      |
| `goldenmatch label FILE --config --gt`                                                             | Interactively label pairs to build ground truth.                                                                                                                                                                                                                                                                                                                                                   |
| `goldenmatch review --config CONFIG`                                                               | Guided review loop: walk borderline pairs (and the stale-correction queue) one at a time. Decisions feed Learning Memory.                                                                                                                                                                                                                                                                          |
| `goldenmatch rollback RUN_ID`                                                                      | Undo a previous merge run.                                                                                                                                                                                                                                                                                                                                                                         |
| `goldenmatch unmerge RECORD_ID --clusters FILE`                                                    | Remove a record from its cluster and re-cluster the rest; writes the updated clusters CSV. Use `--shatter` to break the whole cluster apart.                                                                                                                                                                                                                                                       |
| `goldenmatch runs`                                                                                 | List previous runs for rollback.                                                                                                                                                                                                                                                                                                                                                                   |
| `goldenmatch memory stats\|learn\|export\|import\|show`                                            | Manage the Learning Memory store.                                                                                                                                                                                                                                                                                                                                                                  |
| `goldenmatch config save\|load\|list\|show`                                                        | Manage config presets.                                                                                                                                                                                                                                                                                                                                                                             |
| `goldenmatch import-splink SETTINGS.json -o CONFIG.yaml [--model-out MODEL.json] [--upgrade DATA]` | Convert a Splink settings or trained-model JSON to a GoldenMatch config; `--model-out` persists trained m/u probabilities for reuse. `--upgrade DATA.parquet` additionally runs the data-aware upgrade pass (TF tables, measured distance thresholds, fan-out defenses: NE suggestion + cluster-guard tuning, threshold calibration) and writes the faithful baseline alongside as `*.baseline.*`. |
| `goldenmatch compare-clusters A B`                                                                 | Cluster comparison (unchanged / merged / partitioned / overlapping).                                                                                                                                                                                                                                                                                                                               |
| `goldenmatch sensitivity FILE`                                                                     | Parameter sweep over threshold, blocking, and matchkey.                                                                                                                                                                                                                                                                                                                                            |
| `goldenmatch pprl link FILE_A FILE_B`                                                              | Privacy-preserving record linkage.                                                                                                                                                                                                                                                                                                                                                                 |

## Key dedupe flags

| Flag                                | Effect                                                                                                                                                                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tui`                             | Open the interactive review TUI instead of running directly. `dedupe` is **non-interactive by default** — it auto-configs, writes golden records, and prints a summary. (`--no-tui` is accepted as a no-op for back-compat.) |
| `--output-all` / `--output-dir DIR` | Write every artifact (golden/clusters/dupes/unique/report) / choose the output directory. On the zero-config path, golden records are written by default.                                                                    |
| `--anomalies`                       | Detect fake emails, placeholder data, and suspicious records.                                                                                                                                                                |
| `--preview`                         | Preview results on a sample without writing files.                                                                                                                                                                           |
| `--merge-preview`                   | Show the merge preview (what will change) without writing.                                                                                                                                                                   |
| `--diff` / `--diff-html`            | Generate a before/after change report.                                                                                                                                                                                       |
| `--dashboard`                       | Before/after data-quality dashboard (HTML).                                                                                                                                                                                  |
| `--html-report`                     | Detailed match report with charts.                                                                                                                                                                                           |
| `--chunked`                         | Large-dataset mode (process in chunks).                                                                                                                                                                                      |
| `--backend ray`                     | Force a backend.                                                                                                                                                                                                             |
| `--llm-boost`                       | Improve accuracy with LLM-labeled training.                                                                                                                                                                                  |

## Cloud storage

Read directly from cloud storage by passing a URI:

```bash theme={null}
goldenmatch dedupe s3://bucket/customers.csv
goldenmatch dedupe gs://bucket/customers.csv
goldenmatch dedupe az://container/customers.csv
```