DEVELOPER GUIDE & CLI REFERENCE

CLI-first reconciliation.
Zero overhead.

Rift runs as a self-contained, statically compiled binary or containerized job. No background daemons, no database write access, and no permanent application tier required.

Interactive Command Line Simulator

Select commands below to inspect real outputs, exit codes, and JSON payloads.

rift-cli v0.1.1 (x86_64 / aarch64)

$rift compare source.parquet target.csv --schema schema.json --key id --engine external --memory-limit-mb 64

[INFO] Rift v0.1.1 — Deterministic Exact Reconciliation Engine

[INFO] Loading canonical schema: schema.json (5 fields, PK: id)

[INFO] Engine mode: External Sort/Merge (Sorter budget: 64 MB, Disk limit: 50 GB)

[INFO] Source A: source.parquet (1,000,000 records)

[INFO] Target B: target.csv (1,000,000 records)

.............................................................. [100%]

--- RECONCILIATION SUMMARY ---

Total records processed: 1,000,000

Exact matches: 997,659 (99.77%)

Discrepancies detected: 2,341 ( 0.23%)

- Modified values: 1,902

- Missing in target: 310

- Extra in target: 129

--- EXECUTION METRICS ---

Total elapsed time: 2.03s

Engine throughput: 492,610 rows/s

Peak Resident Memory (RSS): 97.3 MB

Spill disk written: 48.2 MB

[RESULT] Discrepancies detected. Exit code: 1

Exit status: 1Deterministic execution · No LLM required for reconciliation

CORE COMMAND

rift compare <SOURCE> <TARGET>

Compare two datasets exactly and surface discrepancies without full-table diff dumps.

Key CLI Flags:

-s, --schema <FILE>: Path to canonical schema JSON file.
-k, --key <COLUMNS>: Primary key column name(s). Comma-separate for composite keys (e.g. --key org_id,user_id).
--unkeyed: Reconcile datasets as unkeyed multisets (using hash multisets).
--engine <MODE>: Execution engine (in-memory or external). Default: in-memory.
--memory-limit-mb <MB>: Sorter buffer allocation budget for external sort (default: 256 MB).
-o, --output <FORMAT>: Output format (text or json).
--non-interactive: Disable interactive prompts (recommended for CI/CD and AI agents).

Verified Command Examples:

# Reconcile Parquet against CSV with composite key
rift compare tx.parquet st.csv -s schema.json -k org_id,tx_id

# Reconcile 5M rows with 64MB memory limit
rift compare a.parquet b.parquet -s schema.json -k id --engine external --memory-limit-mb 64

# Emit machine-readable JSON for agents/scripts
rift compare a.parquet b.parquet -s s.json -k id -o json --non-interactive

INVESTIGATION ENGINE

rift explain <SOURCE> <TARGET>

Automatically discover candidate RTL explanations from observed dataset differences.

When datasets diverge, rift explain initiates a multi-stage Parameterized Graph Discrepancy Search. It discovers candidate invariants across divergent attributes (e.g., fee subtractions, percentage discounts, status transitions) and verifies candidate rules via an authoritative verification pass.

$ rift explain source.parquet target.parquet --schema schema.json --key id -o json

DATA CONTRACT

Canonical Schema JSON Specification

Rift requires an explicit schema JSON declaring fields and canonical primitive types.

// schema.json format

{
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "amount",
      "type": "decimal",
      "precision": 18,
      "scale": 2
    },
    {
      "name": "account_id",
      "type": "int64"
    },
    {
      "name": "created_at",
      "type": "timestamp"
    },
    {
      "name": "is_settled",
      "type": "boolean"
    }
  ],
  "primary_key": ["id"]
}

Supported Primitive Types

string: UTF-8 encoded text.
int64: Signed 64-bit integer values.
decimal: Arbitrary precision fixed-point decimal (prevents float rounding drift).
timestamp: ISO 8601 formatted datetime with microsecond precision.
boolean: True / false flags.
float: 64-bit IEEE-754 bit-preserving float.

CI/CD SPECIFICATION

Deterministic Exit Codes

Exit Code	Constant Name	Semantics & Behavior
0	EXIT_OK	Datasets match exactly (zero discrepancies detected) or 100% verified explanation.
1	EXIT_DISCREPANCIES	One or more discrepancies found (INSERTED, DELETED, MODIFIED) or partial explanation.
2	EXIT_ERROR	Operational or user input error occurred (file not found, schema mismatch, invalid syntax).

Licensing & Binary Distribution

Rift is proprietary commercial software developed and licensed by Eagle Eye Research and Deployment Labs Private Limited. Binaries and registry access are distributed privately under enterprise evaluation or commercial licensing agreements. Prior Apache-2.0 grants on historical releases (v0.1.1 and earlier) remain valid for those historical artifacts.

Request Developer Access

CLI-first reconciliation. Zero overhead.