tf2okf

tf2okf generates deterministic Open Knowledge Format v0.2 Markdown from Terraform-family repositories.

Install and run

Requires Python 3.10 or newer.

Install from this repository (local source)

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m pip install .
tf2okf --help

Install for use in other repositories

Install once, then run tf2okf from any Terraform/Terragrunt project.

If published on PyPI:

python3 -m pip install tf2okf

If not published on PyPI, install directly from Git:

python3 -m pip install "git+https://github.com/<owner>/tf2okf.git"

For isolated global CLI usage across projects (pipx):

pipx install "git+https://github.com/<owner>/tf2okf.git"

Common commands:

tf2okf frameworks
tf2okf discover .
tf2okf init .
tf2okf generate .
tf2okf check .
tf2okf diff .

Framework selection

tf2okf frameworks
tf2okf discover .
tf2okf init . --framework auto
tf2okf init . --framework tfscaffold
tf2okf init . --framework terragrunt
tf2okf init . --framework plain-terraform

Configuration:

version: '2'
framework:
  type: auto

auto detects known framework signatures. Explicit selection always wins.

tfscaffold adapter

Discovers independent components/, reusable modules/, and etc/*.tfvars environment metadata.

Terragrunt adapter

Discovers each terragrunt.hcl unit, static terraform.source, include, dependency.config_path, shared HCL and terragrunt.stack.hcl files. .terragrunt-cache and generated .terragrunt-stack content are ignored.

Plain Terraform adapter

Parses Terraform source directly from the configured root.

Commands

• init — create configuration, detect/select framework, create initial OKF and Copilot instructions
• discover — show detected framework and reasons without changing files
• generate — regenerate machine-owned OKF
• check — fail when committed generated OKF has drifted
• diff — show generated knowledge diff
• frameworks — list supported adapters

No LLM is needed for generation.

Security defaults

tf2okf is intentionally source-only: it does not read Terraform state, plans, cloud credentials, or execute Terraform. Repository-relative configuration paths are containment-checked; symlinked Terraform files are ignored; source files over 2 MiB are skipped; likely secret-bearing attributes are redacted; and optional terraform-docs execution has a timeout and captured-output limit. See SECURITY.md for the threat model.

Open-source release checklist

Before publishing: enable GitHub private vulnerability reporting, branch protection/rulesets, required CI/CodeQL/dependency review checks, Dependabot security updates, secret scanning/push protection where available, and PyPI trusted publishing for the pypi environment. Run python -m build && python -m twine check dist/* locally or in CI.