Installation

Folio is distributed as a single Python package that registers three console scripts: folio, folio-mcp, and folio-viewer. Python 3.13+ is required.

Recommended: `uv`

uv installs each tool into an isolated venv and puts the entry point on your PATH.

uv tool install folio-kit

The PyPI distribution name is folio-kit; it puts three commands on your PATH: folio, folio-mcp, and folio-viewer.

Verify:

folio --help
folio-mcp --help
folio-viewer --help

From source

git clone https://github.com/nyuta01/folio.git
cd folio
uv sync                 # creates .venv with all dev dependencies
uv run folio --help     # use the dev install via uv run

make verify runs the full gate (harness checks, drift checks, doc validation, pytest, six smoke tests). Use it as your local CI before any commit.

With pip / pipx

If you prefer not to use uv:

pipx
pip (venv)

pipx install folio-kit

python3.13 -m venv .venv
source .venv/bin/activate
pip install folio-kit

What gets installed

Console script	Module	What it is
`folio`	`folio.cli:main`	The primary CLI: init / validate / query / list / count / upsert / delete / materialize / status / provenance / serve / script / skill / export
`folio-mcp`	`folio_mcp.cli:main`	FastMCP server; `--transport stdio` (default) or `http`
`folio-viewer`	`folio_viewer.cli:main`	FastAPI + React Viewer; binds to `127.0.0.1`

folio serve is an alias for folio-viewer serve, kept on the primary CLI for discoverability.

Optional dependencies

Folio ships with no required external services. A few features need extras the user supplies:

AI derivations. The default AIClient is the Anthropic SDK, which reads ANTHROPIC_API_KEY from the environment. The StubAIClient lets you run AI derivations offline for tests and demos.
Frictionless validation. folio export datapackage writes a valid Frictionless v1 descriptor; running frictionless validate against it requires the frictionless package separately.
MCP HTTP transport. folio-mcp serve --transport http does not require anything beyond the fastmcp dependency that ships in the wheel.

Let your AI coding agent drive Folio

If you use Claude Code, Cursor, Cline, Codex, Windsurf, Aider, Copilot, Gemini, or any other agent in the skills.sh ecosystem (18+ runtimes today), one extra command installs the Folio skill pack so the agent knows how to operate Folio sheets via the CLI:

# Project-scoped install in your repo (recommended for Folio work)
npx skills add nyuta01/folio

This drops SKILL.md files into your runtime’s discovery path (.claude/skills/, .cursor/skills/, etc.). The agent then picks them up automatically and uses its built-in Bash tool to invoke folio verbs — no daemon, no MCP server, every action visible in your shell history. See AI agent operates, human verifies for the end-to-end recipe.

The bundled skills today: folio-quickstart, add-derivation-ai, add-derivation-cross-sheet, debug-failed-materialize. The npm package is also TanStack Intent compatible.

Reach for folio-mcp instead when the agent is remote, sandboxed without shell access, or runs in an MCP-native runtime — see MCP overview for the trade-off table.

Confirm the install in 30 seconds

The fastest way to prove the install worked is to scaffold a fresh sheet with folio init and validate it:

folio init --name hello-folio
folio validate ./hello-folio
folio skill list ./hello-folio

Three commands, zero downloads — if all three exit 0 the install is healthy. Continue to the Quickstart to add records and see provenance, or read on for the longer “check against the bundled examples” route.

Confirm with the bundled examples

The repository ships examples/ with five sheets covering the four canonical use cases. Once installed:

git clone --depth 1 https://github.com/nyuta01/folio.git
cd folio

folio validate examples/customers
folio materialize examples/customers --actor agent:demo
folio serve examples/customers --port 3000 --actor agent:human
# → http://127.0.0.1:3000/

The Viewer auto-detects viewer/dist/ next to the working directory if you have run npm run build inside viewer/. Otherwise the API still works on its own.