Quick Start

In this guide you will install Reconlify, create two small CSV files, write a config, and run your first reconciliation. It takes about five minutes.

What you will do

1. Install the Reconlify CLI
2. Create a source and target CSV
3. Write a minimal YAML config
4. Run the comparison
5. Read the JSON report

Prerequisites

• Python 3.11 or later
• pip (included with Python)
• A terminal (macOS, Linux, or WSL on Windows)

Install Reconlify CLI

pip install reconlify-cli

Verify the installation:

reconlify run --help

Create example data

Imagine you are validating a user migration. The legacy system exported user records, and you need to confirm they all arrived in the new platform.

Create two files in a working directory.

legacy_users.csv (source)

user_id,email,created_at
101,alice@example.com,2024-06-15
102,bob@corp.io,2024-07-01
103,carol@example.com,2024-08-20
104,dan@corp.io,2024-09-10

new_users.csv (target)

id,email,created_at
102,bob@corp.io,2024-07-01
104,dan@corp.io,2024-09-10
101,alice@example.com,2024-06-15
105,eve@newco.com,2025-01-05

A few things to notice:

• The rows are in a different order
• The key column is named user_id in source but id in target
• Carol (103) is missing from the target
• Eve (105) appears in the target but not in the source

Write a config file

Create config.yaml in the same directory:

type: tabular
source: legacy_users.csv
target: new_users.csv
 
keys:
  - user_id
 
column_mapping:
  user_id: id

This tells Reconlify to:

• Compare two CSV files as tabular data
• Match rows by user_id (mapped to id in the target)
• Compare all remaining columns (email, created_at)

Run the comparison

reconlify run config.yaml

Reconlify prints a summary to the terminal and writes a detailed report to report.json.

The process exits with code 1. This is expected — it means differences were found. It is not an error. Exit codes:

Understand the report

Open report.json. The key sections are:

• summary — total rows, matched rows, mismatched rows, rows missing from each side
• details — which columns were compared, which keys were used
• samples — example rows that differ, showing source and target values side by side

In this example the report shows:

• 3 matched rows — Alice (101), Bob (102), and Dan (104) all exist on both sides with identical values
• 1 missing in target — Carol (103) was not migrated
• 1 missing in source — Eve (105) is an unexpected record in the new platform

Why key-based matching matters

Reconlify matches rows by business key, not by position. Alice is row 1 in the source but row 3 in the target — Reconlify still pairs them correctly because they share the same user_id.

This means row order does not matter. Systems often export data in different sort orders, and key-based matching eliminates the false positives that line-based diff tools would produce.

Use a custom output path

By default the report is written to report.json. To write it somewhere else:

reconlify run config.yaml --out results/my-report.json

Next steps

You have run your first Reconlify comparison. Here are features to explore next:

• Column Mapping — compare datasets where source and target use different column names
• Tolerance — allow small numeric differences (e.g. rounding) without flagging them as mismatches
• Normalization and Rules — transform columns before comparison using concat, map, date formatting, and more
• Text mode — compare log files and unstructured text line by line

See the User Guide for an overview of all features.