Skip to content
Folio

Folio

Portable, AI-native data sheets. A sheet is a directory you can tar — a contract, JSONL records, optional derivations, and append-only provenance — that humans and AI agents both read and write.
Get started → Read the concepts

Why Folio

A Folio sheet is two files at minimum: a contract (contract.yaml) and rows (records.jsonl). Add a derivations/ directory and Folio can fill in derived fields — through Python scripts, SQL, HTTP calls, sibling-sheet lookups, or AI — while keeping a tamper-evident record of who wrote what and when.

The whole sheet is portable: caches and runtimes live outside the directory, so tar czf sheet.tgz my-sheet/ is a complete, faithful copy. No environment. No databases. No vendor lock-in.

Spec Two files, one model ODCS-aligned contract + line-delimited records. 1 sheet = 1 model. Derivations Six built-in kinds ai · import · python · sql · http · cross_sheet — all share the cache + provenance loop. Provenance Append-only history Every cell knows who wrote it, when, and from what input hash. Surfaces CLI · SDK · MCP · Viewer Same sheet through four interfaces. Pick the one that fits the task.

From zero to a working sheet

Terminal window
# 1. Install (uv-managed Python toolchain)
uv tool install folio-kit       # → installs the `folio` command


# 2. Scaffold a new sheet
folio init --name my-sheet      # → ./my-sheet/{contract.yaml, records.jsonl, README.md, skills/}


# 3. Validate the spec, then run derivations and inspect provenance
folio validate ./my-sheet
folio materialize ./my-sheet --actor agent:demo
folio provenance ./my-sheet rec_001 country_code

A complete walkthrough lives in Your first sheet.

Architecture at a glance

my-sheet/                ← portable directory (tar this)
├── contract.yaml        Required. ODCS subset.
├── records.jsonl        Required. One JSON object per line.
├── derivations/         Optional. One YAML file per derivation.
│   └── industry.yaml
├── scripts/             Optional. Reusable Python/bash helpers.
├── skills/              Optional. Packaged operating procedures.
├── provenance.jsonl     Append-only audit trail.
└── README.md            Optional, with typed frontmatter.


# Lives outside the sheet (per ADR-0008):
~/Library/Caches/folio/<sheet-id>/cache/    Cached derivation outputs.
~/Library/Caches/folio/<sheet-id>/runtime/  Per-sheet venvs for scripts.

A sheet stays portable because the cache and runtime are addressed by sheet-id and live in the user cache, never inside the sheet itself.

Use it through the surface that fits

CLI folio init, validate, query, list, count, upsert, delete, materialize, status, provenance, serve, script, skill, export. SDK folio (Python) Sheet objects with the six core operations. AIClient and HTTPTransport are protocols you can stub. MCP folio-mcp FastMCP server exposing the SDK as nine tools, plus one MCP prompt per skill. Stdio or HTTP transport. UI folio-viewer Local-only FastAPI + React app. Records grid, dashboard, history timeline, SSE.

Where to next