spb/air Public MIT

1<!--2Projet : AIR — Accounting Intermediate Representation3Auteur : Simon-Pierre Boucher4Contact : contact@spboucher.ai5Fichier : cli-reference.md6-->78# AIR CLI Reference910Install with `pip install -e .` and the `air` command is on your PATH11(equivalently: `python -m sdk.cli`).1213Global concept: the **AIR home** (`--home <dir>`) is your managed books14directory — meta, hash-chained ledger, content-addressed document archive,15exports, and the review inbox. Most commands take `--home`; `--policies`16defaults to the home's configured policy set.1718## Lifecycle1920| Command | What it does |21|---|---|22| `air init --home books --policies alsl/policies/ca-qc-2026.yaml [--name x]` | Create a managed AIR home |23| `air status --home books` | Entries, chain validity, archives, exports |24| `air audit --home books` | Render + verify the hash-chained syscall audit log |2526## Compile & post2728| Command | What it does |29|---|---|30| `air compile doc.yaml --home books` | Compile AIR events → post to the native ledger; archives the document |31| `air compile doc.yaml --home books --optimize` | Same, with duplicate detection, netting, and payment fusion |32| `air compile doc.yaml --home books --report trial-balance --format markdown` | Post, then print statements |33| `air compile doc.yaml --home books --backend csv` | Export a universal CSV journal instead |34| `air compile doc.yaml --home books --backend qbo-export` | QuickBooks-shaped JSON export — **no QuickBooks account needed** |35| `air verify doc.yaml --policies <set>` | Compile without posting; print diagnostics |36| `air recompile old.yaml new.yaml --home books` | Incremental: diff by content fingerprint, post reversal + replacement entries only |3738## Statements3940| Command | What it does |41|---|---|42| `air report trial-balance --home books` | Also: `general-ledger`, `income-statement`, `balance-sheet` |43| `... --format text\|markdown\|csv\|json` | Any statement, four formats |4445## Ingestion (document → books)4647| Command | What it does |48|---|---|49| `air ingest invoice.txt --home books` | Extract events (offline mock extractor), validate against the AIR schema, route by confidence |50| `air ingest invoice.txt --home books --llm` | Use the Claude extractor (needs `pip install anthropic` + `ANTHROPIC_API_KEY`) |51| `air ingest ... --threshold 0.9` | Auto-approve threshold (default 0.85); schema-invalid always goes to a human |52| `air inbox --home books` | List extractions awaiting review |53| `air approve inbox_00000 --home books --approver name` | Stamp approver + timestamp, compile, post |54| `air reject inbox_00000 --home books --reason "duplicate"` | Reject (archived, never deleted) |5556## Bank reconciliation5758| Command | What it does |59|---|---|60| `air reconcile statement.xml --home books` | camt.053 / MT940 / CSV, auto-detected; exits 0 clean, 2 with differences |61| `... --cash-account 1000 --tolerance-days 3` | Matching knobs |6263## Agent surface (Python)6465```python66from sdk.syscalls import AirKernel6768k = AirKernel("books", actor="agent:alice")69k.create_economic_event({...})   # schema-validated draft70k.validate(); k.compile()        # dry runs71k.post()                         # deterministic compile -> books (idempotent)72k.merge()                        # post with netting + fusion73k.reverse("je_evt_x")            # contra entry, never an edit74k.close_period("2026-01")        # later posts into it are refused (AIR-E700)75k.reconcile("statement.mt940")   # bank matching76k.generate_report("balance-sheet", "markdown")77# every call above — success or refusal — is one hash-chained audit record78```7980## Demo8182```bash83air init --home /tmp/demo --policies alsl/policies/ca-qc-2026.yaml84air compile tests/fixtures/demo_document.yaml --home /tmp/demo --report balance-sheet85python -m sdk.demo_agent --home /tmp/demo      # scripted agent, syscalls only86air audit --home /tmp/demo87```88