Guide

Select Dialects and Policy Packs

On this pageOverview

Most projects need no Rootform configuration. The binary embeds the RF Vocabulary and 19 Dialects. A plan or state JSON is still required: --project selects content from a directory; it never analyzes that directory as evidence.

Need	Selection
Analyze with embedded Dialects	No lock or preparation.
Try a local Dialect or Policy Pack once	Pass `--dialect` to `run` or `--policy-pack` to `check`.
Keep external content selected across runs	Record it with `add`, commit `rootform.lock`, and prepare it with `init`.
Exclude or replace an embedded Dialect owner	Record the decision with `remove --embedded` or `add --replace`.

Use embedded Dialects

With a plan JSON in the current project, run an analysis to see the default catalog. No rootform init is needed.

rootform run plan.json --no-serve

Excerpt from standard output OUTPUT

Plan analyzed
Stage              Planned
Stages             Recorded (reconstructed), Refreshed, Planned
Architecture
  Instances    2
  Interpreted  2

Interpreted counts the instances that a Rule from the selected Dialects matched: both here. If a resource has no matching Rule, inspect its Representation and coverage limits.

To inspect one embedded owner before relying on it, list its catalog entry:

rootform list dialects aws --format wide

Embedded Dialect OUTPUT

NAME  VERSION  ORIGIN    CONCEPTS  CONTEXTS  RELATIONS  RULES
aws   0.1.0    embedded        64         0          1    108

embedded means the Dialect ships in this binary. Its version changes with the Rootform release, not with a project lock. Use rootform show aws for its declarations or rootform show aws.rule.vpc for a Rule's definition. Dialect concepts explains how Rules turn instance evidence into architecture.

Try one local Policy Pack

An override lets you evaluate a reviewed local Policy Pack without changing project selection. This command uses a plan export and a Policy Pack at ./policies:

rootform check plan.json --plan-file plan.tfplan --require-enrichment \
  --policy-pack ./policies -o report.md

The command pairs the saved plan with the export, writes a Policy report, and exits 0 only when all selected evaluations pass. A violation exits 1; indeterminate or zero evaluated targets exits 3. Read the report's target counts before calling the result compliant. The override applies only to this check. A lock remains unchanged. Understand Policy outcomes gives a complete Policy example.

Keep external content selected

Use rootform.lock when the project needs an external Dialect or Policy Pack on every machine. Run add from the project root, then commit the lock with the selected local source or exact OCI identity. A local source path is recorded relative to that root; OCI entries carry exact digests. Terraform and OpenTofu provider selections remain in their own lock file.

rootform init prepares an existing selection. It verifies selected local, installed, or vendored content and may acquire a missing exact OCI pin unless --offline forbids network access. It does not detect providers, choose packages, or write rootform.lock. Check the selection in automation without allowing an absent lock:

rootform init . --locked --offline --no-input

Prepared project OUTPUT

Project ready

External content  none

For this embedded-only example, the committed empty lock requires no external content. --locked requires a valid lock even when its arrays are empty; --offline prevents acquisition; --no-input refuses an interactive decision. Omit --locked for an ordinary embedded-only project with no lock.

Inspect what the selected project loads before analysis:

rootform list dialects --format wide
rootform list policy-packs
rootform list policies

The first command lists embedded and selected Dialects. The other two show selected Policy Packs and Policies; an empty Policy list means there is no governance decision. A lock selecting only Dialects does not select a Policy Pack. Add external content gives the full add, update, vendor, and registry procedure.

Use project selection in a run

Point --project at the root containing rootform.lock. Add --locked when this run must refuse a missing or drifted selection:

rootform run plan.json --project ./infra --locked --no-serve -o analysis.json

The Form records the active Dialects, selection, plan or state input, stages, and closures. Analysis accepts --dialect as an invocation-local override; check --policy-pack supplies a Policy Pack for one check. The CLI refuses an override with --locked. Use an override while authoring, then add reviewed content to the lock for repeatable work.

Every command that reads or changes the selection accepts --project: run, check, list, show, explain, add, remove, update, vendor, and the validation of a named Rule, Concept, Context, Relation, or Policy. The current directory stays the default and Rootform never changes directory: paths you type, including add sources and vendor --to, stay relative to where you run the command, while rootform.lock and its vendored copies belong to the selected project. With --project, add, remove, and update name those files as reached from where you run the command, for example ../infra/rootform.lock updated. init, test, and validate dialects take the project as their directory argument instead. A rootform.lock that cannot be read exits 4; one that is read but invalid exits 3.

Exclude or replace an embedded owner

An exclusion removes one embedded owner's Rules from the active catalog. A replacement selects another Dialect with the same owner and explicitly authorizes that collision. The reserved rf vocabulary cannot be excluded or replaced. These changes belong in the lock and can change interpretation without changing the plan JSON. Review the resulting Form before adopting them. Replace or exclude an embedded Dialect has the commands; reproduce an analysis offline shows how to move the exact selection.