Features
Fourteen subcommands, grouped by purpose.
Every Folio capability is reachable from one binary. The commands below are grouped into five categories: foundational, observational, integrity, transformational, and collaborative. Each has a one-sentence purpose and a working example. For the narrative walkthrough, see the tutorial.
Group 01
Foundational.
The commands you use every day. Creating and committing datasheets.
Start a new Folio repository.
Creates .folio/config.toml and initializes git. Pick a tier that matches the read-access scope of the repo. If you're unsure, start with controlled.
folio init --tier controlled .
Scaffold a datasheet.
Creates the directory structure and seeds required files. Required flags: --owner. Optional: --classification, defaults to internal.
folio new payment-service --owner platform-team --classification internal
Commit, with validation.
Runs the validator, updates the auto-generated revision-history.md, and makes a git commit. Refuses if any datasheet fails validation.
folio checkpoint "onboarded payment-service"
Run the validator without committing.
Useful as a pre-commit hook or in CI. Validates one datasheet or all of them.
folio validate # all datasheets folio validate payment-service # just one
Group 02
Observational.
Commands that read the repository and tell you what's in it. None of these write to disk.
Tabular summary of every datasheet.
Filters by any manifest field with --filter field=value. Add --json for scripting.
folio list folio list --filter owner=platform-team folio list --filter lifecycle=deprecated --json
Render one datasheet to the terminal.
Formatted for reading at a glance. Manifest metadata at the top, section prose below.
folio show payment-service
Aggregate counts across the whole repo.
Breakdown by lifecycle, maturity, classification, owner. Age buckets for last-reviewed dates. Total references.
folio stats folio stats --json | jq '.owners'
Structural health check.
Nine checks: git integrity, .folio/config.toml presence, datasheet structure, manifest validity, required section files, orphan files, typst availability, working tree cleanliness, last-checkpoint age. Exit 0 on clean, 2 on warnings, 3 on failures.
folio doctor folio doctor --json # for CI parsing
Group 03
Integrity.
External-facing checks. Link reachability, document export.
HTTP-check every URL in the repo.
Parallel workers with configurable timeout and concurrency. Exit code is non-zero when any link is broken. Excellent in CI.
folio check-links folio check-links --timeout 30 --concurrency 16 folio check-links --json > link-report.json
Render a datasheet to PDF.
Shells out to typst (install separately). Output lands in out/. File name embeds the date so successive exports don't collide.
folio export payment-service wrote out/payment-service-2026-04-24.pdf
Group 04
Transformational.
Commands that programmatically modify datasheets across the repo. Rare, but when you need them, nothing else will do.
Apply a Rhai script to every datasheet.
Dry-run by default. Adds --apply to actually write. Scripts that produce invalid datasheets are rejected by the validator before any file is written.
Example: a Rhai migration to rename a field across the whole repo:
// migrations/rename-deprecated-to-retired.rhai
if datasheet.status.lifecycle == "deprecated" {
datasheet.status.lifecycle = "retired";
}
folio migrate --script migrations/rename-deprecated-to-retired.rhai # preview — nothing written folio migrate --script migrations/rename-deprecated-to-retired.rhai --apply # applied, one commit per touched file
Group 05
Collaborative.
Commands that shine when multiple people work on the same repo, or when you want to ask questions across every datasheet.
Semantic three-way merge.
When a teammate edits the same repo, folio sync merges their changes into yours with awareness of TOML and Markdown structure. Two engineers adding different links to the same datasheet is not a conflict. Two engineers disagreeing about classification is, and the prompt clusters identical-shape disagreements into one decision.
git fetch origin folio sync origin/main --dry-run folio sync origin/main folio sync origin/main --strategy=remote # non-interactive, take remote
SPARQL across the derived graph.
Every datasheet becomes RDF triples. Ask structural questions. The vocabulary is documented in folio-graph/src/vocab.rs; the prefix is always folio: <https://folio.tools/vocab#>.
folio query 'PREFIX folio: <https://folio.tools/vocab#>
SELECT ?ds WHERE {
?ds folio:classification "confidential" ;
folio:lifecycle "active"
}'
Inline query, or read from a file with --file <path>. Add --json for structured output. Dump the whole graph with --dump (useful for debugging vocabulary coverage).
Full-text search via BM25.
Indexes every manifest, teaser, and section body. Returns hits ranked by relevance. Fast enough to rebuild on every query; no index file to maintain, no staleness problems.
folio search "gRPC authentication" folio search "retry policy" --show-scores folio search "confidential" --limit 5 --json
Cross-cutting
Flags every command respects.
--repo <path>
Target a specific repository instead of walking up from the current directory. Useful when your working directory is outside the repo.
--json
Emit machine-readable JSON instead of the pretty text output. Supported on: list, check-links, query, search, doctor, stats. Pipes cleanly into jq.
--help and -h
Every command has its own help text. folio --help lists all subcommands. folio sync --help shows sync-specific options.
--version and -V
Prints the compiled version. Use this in bug reports.
Learning more
Go deeper.
The narrative-form tutorial walks through every command in order with a running example. The source code is organized into one crate per concern; start there if you want to understand how Folio actually works.