> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reconifyhq.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Reconify's API reference is read-only for customer data. Do not invent endpoints or authentication behavior beyond the OpenAPI contract.
> The public OpenAPI document contains only the documented external /v2 contract.
# Run it with an agent
> Drive Reconify end to end from an agent, from discovery through reconciliation to explanation, all machine-readable.
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
| 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
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
reconify capabilities
```
This is the correct first call, because commands, formats, and matching passes vary by version.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
reconify inspect path/to/left-file.csv
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"error": "...",
"code": "...",
"ok": false,
"schema": "reconify.engine.diagnostic.v1",
"diagnostic": {
"code": "INFERENCE_AMBIGUOUS",
"category": "inference",
"message": "...",
"details": {},
"suggestions": [""]
}
}
```
`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
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```