Run it with an agent

Reconify is built to be driven by an agent. Every command emits versioned JSON, every error is structured, and the binary describes its own capabilities before you run anything. There’s no account, no API key, and no network call standing between an agent and a first result: it can install the binary and use it in the same turn.

The workflow

Workflow from capabilities discovery through file inspection, config inference and validation, reconciliation, and explanation.

Step	Command	Returns
Discover	`reconify capabilities`	`reconify.engine.capabilities.v1`: version, commands, formats, passes, exit codes
Profile	`reconify inspect FILE`	`reconify.engine.profile.v1`: per-column type inference, date layouts, samples
Propose	`reconify config infer --left --right`	`reconify.engine.config-proposal.v1`: candidate mapping and confidence
Confirm	`reconify config validate`	pass/fail
Run	`reconify reconcile`	`reconify.engine.result.v1`
Summarise	`reconify explain results.ndjson`	`reconify.engine.explanation.v1`: counts and top exceptions

An agent can skip steps it already has what it needs for; calling reconcile directly with a hand-written config is fine. It should not assume an output shape without calling capabilities first, since passes, formats, and schemas vary by installed version.

Discover what this build can do

reconify capabilities

This is the correct first call, because commands, formats, and matching passes vary by version.

{
  "schema": "reconify.engine.capabilities.v1",
  "protocol_version": "v1",
  "engine": { "name": "Reconify Engine", "version": "0.4.0" },
  "commands": { "reconcile": { "description": "...", "interactive": false } },
  "formats": { "reconcile": { "formats": ["json", "json-stream", "ndjson", "csv", "table"], "default": "json" } },
  "matching": { "passes": [], "default_passes": ["reference_one_to_one"], "group_keys": ["reference", "name", "group_key"] },
  "result_modes": ["all", "exceptions_only", "summary_only"],
  "schemas": { "result": "reconify.engine.result.v1", "diagnostic": "reconify.engine.diagnostic.v1" },
  "exit_codes": { "0": "Success." }
}

Profile a file before mapping it

reconify inspect path/to/left-file.csv

{
  "schema": "reconify.engine.profile.v1",
  "file": "path/to/left-file.csv",
  "columns": [
    {
      "name": "date",
      "inferred_type": "date",
      "ambiguous": false,
      "candidates": [{ "type": "date", "confidence": 0.99 }, { "type": "text", "confidence": 0.01 }],
      "date_layout": "2006-01-02",
      "sample_values": ["2024-01-01", "2024-01-02", "2024-01-03"]
    }
  ]
}

ambiguous is a fact about the column, not a decision. It’s true when the top two type candidates are within 0.10 confidence of each other. inspect never proposes a mapping; config infer builds on this profile to do that.

Let it propose the config

reconify config infer --left path/to/left-file.csv --right path/to/right-file.csv --out reconify.yaml

A proposal is ready only when the date, amount, and reference mappings each reach 0.90 confidence, each leads its runner-up by 0.10, and at least 100 rows parsed successfully per source. Otherwise it returns needs_input and names which column it couldn’t resolve. It never guesses. Without --out, a needs_input proposal is still exit code 0; that’s not a failure, just an unresolved column. With --out, ambiguity writes nothing and exits 2 with INFERENCE_AMBIGUOUS.

The `--agent` flag

--agent changes two defaults: JSON diagnostics on stderr, and for reconcile, NDJSON output with exceptions_only. Any flag you set explicitly overrides it. The precedence rule, stated once: explicit flag > pair/config value > --agent default > built-in default. --agent also refuses interactive commands like config init. It returns a structured diagnostic naming a non-interactive alternative (config infer, or a hand-written reconify.yaml) instead of hanging on a prompt. That’s the difference between an agent failing fast and an agent timing out.

One-shot reconciliation

reconify reconcile payments.csv ledger.csv --auto --out results.json

--auto takes exactly two positional files: no --config, --pair, --left-file, or --right-file. It applies the same confidence gates as config infer before reconciling. On success, run_info carries inferred_config (the exact YAML used) and inference_confidence, so the run is reproducible non-auto by writing that config to a file. On a gate failure, it returns INFERENCE_AMBIGUOUS with exit code 2 and no result data.

When something fails

{
  "error": "...",
  "code": "...",
  "ok": false,
  "schema": "reconify.engine.diagnostic.v1",
  "diagnostic": {
    "code": "INFERENCE_AMBIGUOUS",
    "category": "inference",
    "message": "...",
    "details": {},
    "suggestions": ["<actionable next step>"]
  }
}

suggestions is there specifically so an agent has a next action instead of a dead end.

Exit codes

Code	Meaning
`0`	Success.
`1`	Unexpected or internal error.
`2`	Config or validation error.
`3`	Reconcile completed with unmatched rows (`--fail-if-unmatched` only).
`4`	Reconcile completed with exception events (`--fail-if-exceptions`; takes precedence over `3`).

The one that trips people up: 3 and 4 are not failures. The run completed and found unmatched rows or exceptions. Those codes only fire when you’ve explicitly opted in with --fail-if-unmatched or --fail-if-exceptions.

Install ready-made skills

npx @reconifyhq/skills

This copies skill files into .agents/skills/, plus adapters in .claude/skills/ and .codex/skills/: reusable workflows an agent picks up automatically instead of you re-explaining the CLI in every prompt.

Skill	Purpose
`reconify-engine-reconcile`	End-to-end discovery, configuration, reconciliation, and explanation
`reconify-engine-cli`	CLI commands, flags, and output formats
`reconify-engine-config`	YAML configuration and validation
`reconify-engine-debug`	Result artifacts and exception diagnosis
`reconify-engine-performance`	Streaming, indexes, and benchmarks
`reconify-engine-bootstrap`	New reconciliation setup
`reconify-engine-ci`	Deterministic CI workflows and exit codes

Give your agent context

reconify capabilities is the live source of truth for what a given build supports; prefer it over a cached description of the CLI. This site also publishes llms.txt and llms-full.txt for agents that read documentation directly. A short system-prompt snippet, if you’re wiring Reconify into a fixed agent role:

Reconify is a local CLI that reconciles two transaction sources into matched,
amount_diff, timing_diff, unmatched, and duplicate outcomes. It needs no
account or network. Run `reconify capabilities` first to see what this
build supports, then follow: inspect, config infer, config validate,
reconcile, explain.

Start here

Concepts

Guides

Reference

Help

The workflow

Discover what this build can do

Profile a file before mapping it

Let it propose the config

The `--agent` flag

One-shot reconciliation

When something fails

Exit codes

Install ready-made skills

Give your agent context

​The workflow

​Discover what this build can do

​Profile a file before mapping it

​Let it propose the config

​The --agent flag

​One-shot reconciliation

​When something fails

​Exit codes

​Install ready-made skills

​Give your agent context

The workflow

Discover what this build can do

Profile a file before mapping it

Let it propose the config

The `--agent` flag

One-shot reconciliation

When something fails

Exit codes

Install ready-made skills

Give your agent context