Quickstart

Build a verified ledger in 60 seconds

Eight short steps: make a few events, turn them into a single append-only ledger file, query and total it in place without decompressing, then watch the hash chain catch a single tampered byte and point at exactly where it broke. Everything here is copy-pasteable. For the full picture, see the Ledger reference and the product page.

1. Install

The full CLI ships as a self-contained binary from npm — no Python required (pnpm/yarn/bun work too).

npm install -g @tinyfiles/cli

2. Make some events

Drop a tiny events.csv in your working directory — a timestamp, a user, and an action per row:

ts,user,action
1704067200000,alice,LOGIN
1704067201000,bob,READ
1704067202000,alice,DELETE

…and a second batch, more.csv, to append later:

ts,user,action
1704067203000,carol,LOGIN
1704067204000,bob,DELETE

3. Create the ledger (the first append makes it)

There is no init step. The first append creates audit.at1, stores the rows verbatim (lossless), hashes the frame, and seeds the chain:

at1 ledger append audit.at1 events.csv
# the file didn't exist — the first append creates it (no init step):
#   appends (frames): 1
#   events (rows):    3
#   chain head:       9f2c1a7b4e8d3052

4. Grow it (in place)

Append the second batch to the same file. The first frame is left byte-identical; a new chained frame is added and the chain head advances:

at1 ledger append audit.at1 more.csv
# the same file grows in place — prior frames stay byte-identical:
#   appends (frames): 2
#   events (rows):    5
#   chain head:       3d7e09c5a1f6b248

5. Prove it's append-only

verify re-derives every frame hash and re-chains every link. An intact chain is evidence the history is append-only — nothing inserted, deleted, reordered, or altered:

at1 ledger verify audit.at1
# -> OK  APPEND-ONLY INTACT — 5 events across 2 appends, chain head 3d7e09c5a1f6b248

6. Query & total — without decompressing

The ledger is also an analytical store. Columns are addressed by index, and queries and aggregates span every append — the aggregate reads a compact roll-up from the footer rather than rehydrating the data:

# columns are addressed by index (0 = ts, 1 = user, 2 = action)
at1 ledger query audit.at1 --where 2:DELETE:DELETE
#   1704067202000,alice,DELETE
#   1704067204000,bob,DELETE

# total without decompressing — read straight from the footer roll-up
at1 ledger agg audit.at1 2 --op count
#   count(2) = 5

7. The money shot — catch tampering

Now flip a single byte deep inside an old frame, the way a quiet edit would, and re-verify. The chain breaks at exactly the frame that changed — and verify tells you where:

# flip one byte deep inside an OLD frame (simulate a quiet edit)
python -c "b=bytearray(open('audit.at1','rb').read()); b[64]^=1; open('audit.at1','wb').write(b)"

at1 ledger verify audit.at1
# -> !!  BROKEN at frame 0 (inserted / deleted / reordered / altered)

# restore the real file (e.g. from backup or git) and it re-verifies clean:
at1 ledger verify audit.at1
# -> OK  APPEND-ONLY INTACT — 5 events across 2 appends, chain head 3d7e09c5a1f6b248

That's the whole guarantee in one move: you couldn't change a past event without the file announcing it. Restore the real bytes and the ledger verifies INTACT again.

8. (Optional) Forget a person, keep the proof

If a column holds PII, tag it on append and bind each row to a subject. Later you can honor a “forget me” request without breaking the chain:

# tag a column as PII and bind each row to a subject on append
at1 ledger append audit.at1 events.csv --subject user --pii user

# later: honor a "forget me" request — the proof survives
at1 ledger erase audit.at1 --subject alice

at1 ledger verify audit.at1
# -> OK  APPEND-ONLY INTACT — … 1 subject AUTHORIZED-ERASED (ledger bytes did not move)

How it stays intact: the PII is per-subject encrypted, so erasesimply destroys that subject's key. The ciphertext bytes never move, so every frame hash and every link still re-derive — the data is unrecoverable, but the append-only proof is untouched. More in the right-to-erasure guide.

What just happened

One audit.at1 is four things at once: a log you only ever append to, an index you can query and aggregate in place, a tamper proof that pinpoints any altered frame, and — where enabled — erasable per subject for GDPR/CCPA. No database, no server, no separate ledger service.

AT-1 Ledger is tamper-evident via hash-chaining — it detects tampering rather than preventing it, the same well-known family as Certificate Transparency, Amazon QLDB, and blockchain ledgers. What AT-1 adds is putting that chain inside a single compressed, queryable, byte-exact, erasable file you own.

Decoding and verifying are always free and never need an account; the append and query paths are metered against the account whose API key the host process supplies — same as the rest of AT-1. Next: the Ledger reference or the product page.