§ All pages

All pages

Every page of the documentation, by section.

Learn

New to CUE or pravo? Lessons in order, with exercises.

Learn: Two tracks in order. Track A teaches CUE from zero. Track B teaches pravo. Each lesson takes between 6 and 20 minutes.

Track A · CUE from zero

Your data is already CUE: A CUE file may contain plain JSON. You shorten it one piece of punctuation at a time, and the data never changes.
A value can be a type: In CUE, int and 30 are both values. One allows every integer and the other allows one.
Writing a field twice: Writing a field twice adds detail. The copies must agree, and a disagreement is an error, not an override.
Order does not matter: Lines and files can come in any order. The result is the same, so there is no precedence list to learn.
Constraints narrow a value: A rule in CUE is a value written on the field. Bounds and regular expressions narrow what the field may hold.
Choices and defaults: Offer a short list of values, mark one as the default, and select it from the command line.
Required, optional, regular: Decide for each field whether it must be supplied, may be supplied, or is a plain field.
Definitions reject typos: Write a shape once, build values from it, and let the shape refuse every field it does not declare.
One rule for every entry: Write a rule once for every entry of a collection with a pattern. Each entry states only what differs.
Generating fields from data: Build fields from a list or a struct with for. Choose keys that stay the same when the data is reordered.
Naming a value once: Use the value of one field in another. Keep helper values out of the output with let. Share them across files with hidden fields.
Conditions and strings: Include a field only when a condition holds. Build strings from values. See why a condition needs a concrete value.
Packages and the standard library: Import validators and functions from the standard library, and share a definition between directories with your own package.
Project, three environments from one definition: Write one specification from a brief. It runs in dev, staging and prod, is stricter in prod, and refuses every other environment.

Track A · Companions

Reading a CUE error: The four parts of a pravo error, the three stages that produce one, and the messages you meet first.
Why is my value incomplete?: The three causes of an incomplete value, each with the error pravo prints, how to read it and the fix.
Closed or open?: Which structs refuse a field they do not declare, how definitions combine, and the real errors when they do not.
eval and validate: What pravo eval and pravo validate check, what they print, and what the flags -c, -e and -O change.
CUE cheat sheet: Every construct of Track A on one page. Each has a short example and the output that pravo prints.

Track B · pravo

Providers and resources: A provider is a struct built from a generated definition. A resource is a struct built through it. Its address is its path.
Reading a plan: A plan is a diff with a legend. Learn the glyphs, unknown values, the replacement marker and the Graph line, then predict three plans.
Apply, outputs, state: Apply a plan, read the outputs and open the state. A plan with no changes shows that a refactor changed nothing.
Inputs, tags, environments: Run one specification as dev, staging and prod. Use a constrained field, a tag and a state path derived from it.
Many resources from one rule: A comprehension produces resources. Each key becomes the last element of an address, so reordering the source replaces nothing.
Modules, providers, credentials: Share one definition between instances, pass a provider in as an input, and keep a credential out of the state.
Changing live infrastructure: Save a plan, apply exactly that plan or nothing, and apply it in stages. Read the refusal when the plan is stale.
Renames, moves, imports: Keep the object of a resource when its address changes, and adopt an object that already exists.
Drift: find and reconcile changes: Change a resource outside pravo, find the change with pravo drift, and reconcile it in both directions.
Policy on providers and on plans: A constraint on a provider binds every resource built through it, and a policy file judges what a plan does.

Track B · Labs and project

Lab 1: break it: Cause ten failures one at a time and read each message. Match each failure to the exit code that a pipeline sees.
Lab 2: two applies at once: Run three applies against one state while one of them holds a lock. Read the locks and the log afterwards.
Project: an estate in three environments: Build three environments from one definition, with a policy, a secret, a drift check and a destroy. A script checks the outcomes.

Migrate

From OpenTofu or Terraform: a gated runbook, a concept map and a worked example.

Migrate from OpenTofu or Terraform: A gated path from an OpenTofu or Terraform project to pravo, with the promise it keeps, what it applies to, and three ways to go.

Runbook

Before you start: Make the OpenTofu plan empty, back up the state and the code, scan for constructs that need a decision, preview the conversion and write the recovery plan.
Concept map: Each OpenTofu construct, command and function beside its pravo equivalent, with one example for each group and the rows that have none.
A worked example: One stack with a module, a for_each, a remote output, a sensitive value and a moved history, translated by hand, converted and planned to empty.
Translate the specification: Rewrite each OpenTofu construct as CUE in a fixed order, and check every step with pravo validate.
Convert the state: Convert the OpenTofu state into pravo records, point each record at its address, and plan until nothing changes.
Rewrite the checks on plans: Turn the CI checks that read the OpenTofu plan JSON into plan policies, and run both until they agree.
Cut over: Remove OpenTofu's claim on the objects, move the pipeline to pravo, order roots that share outputs, and archive the old state.
Roll back: Where the migration can be undone by deleting the pravo files, and what to do after the first apply that changes an object.
Pitfalls: Symptoms you may meet while you translate, convert and cut over, with the cause, the fix and the message as pravo prints it.
Not in pravo: what to use instead: The OpenTofu features that pravo does not have, what to use in each case, and the parts of a state that the conversion does not carry over.
After the migration: Rewrite the faithful translation in the idiom of CUE, one idea per commit, and let a policy confirm that no commit changes an object.

Annexes

Function map: Every OpenTofu built-in function, with the CUE expression that replaces it, or the statement that none does.
Command map: Each OpenTofu command, flag, environment variable and file beside the pravo command, flag, variable or file that replaces it.
Construct matrix: Which OpenTofu constructs pravo supports, supports in part, or does not support, with the replacement for each.

How-to

You know the basics and need to do one thing.

How-to: Task-shaped pages for a reader who knows the basics. Each page shows how to do one thing and stops there.

Get started

Quick start: Twelve minutes from install to a first plan, an apply, a conflict and a destroy. No account and no cloud.

Specify

Run one specification in several environments: Select dev, staging or prod with a tag, keep the differences in one table and give each environment its own state.
Share code between roots in one repository: Keep shared modules in one repository, run one root per environment and see how a change to shared code reaches every root.
Publish a module: Create a module in a git repository, try it from an example, and publish a version to a registry that others can use.
Use a published module: Add a published module to a root, lock it, read an upgrade before you take it and know what happens in CI and offline.

Providers and state

Keep the state in a shared bucket: Store the state in an S3 bucket so that a team shares it, move an existing local state into the bucket and read another root's outputs.
Install providers from your own registry: Copy a provider into a container registry, install it from there and move a root that has resources to the copy without touching them.
Rename, move and adopt resources: Rename a resource without recreating it, move a group of resources, adopt an object that already exists and forget one without destroying it.

Operate

Run pravo in a pipeline: Validate without credentials, plan under a policy, apply a saved plan, find drift and test offline, with the exit code of every step.
Write and roll out plan policies: Write a plan policy, test it on fixtures with the matching cue version, roll a new rule out as advice, exempt by type and name the policy in the apply job.
Let an agent plan and apply: Give a program or an AI agent the schema, a plan file, a reservation and a tool server bound to a policy, and see what that does and does not protect.
Keep secrets out of the state: Read a secret from the environment with pravo.#SecretEnv, hand it to a provider and see where pravo allows the value and where it refuses.

Maintain

Find out why a run fails: Read an evaluation error, ask pravo what it decided with -v, ask why a resource changes, check for drift and follow a run in a trace.
Upgrade pravo and providers: Replace the pravo binary, move a provider to a newer version through the lock file, pin the archives of every platform and review the plan that follows.

Concepts

How pravo behaves, with diagrams.

Concepts: How pravo behaves, with diagrams. Each page explains one part of the system.
How pravo works: One run of pravo in seven stages, from the CUE files of a directory to the providers, the state and the output.
Evaluation: How pravo turns the CUE files of a directory into one value, finds resources by identity and builds the dependency graph before any provider is asked anything.
Resources and addresses: What makes a struct a resource, how its address is its path, and what renaming, moving or reordering does to the record of an object.
Plans: What a plan contains, how pravo decides which resources a plan reaches, what an unknown value is, how refresh age works and how a saved plan is checked.
State: What pravo records for each resource, how revisions, locks and transactions work, why the cost of a run follows the change, and where the state lives.
What a plan reaches: Change one setting, replace a root key, add a zone or run two applies on one estate, and see which resources each plan reaches and which locks each apply holds.
Providers: How pravo finds, installs, locks, starts and talks to a provider, how a provider becomes a CUE struct, and how an instance is named.
Policies: two moments, one idea: One idea at two moments: a constraint on a provider is checked at evaluation, a policy file against a plan. What each binds and what neither guarantees.
Secrets and ephemeral values: Which values pravo records in state, saved plans and outputs, what an ephemeral value is, where it may go, and what hiding a value does and does not do.

Reference

Lookup: one page per command and per specification topic.

Reference: Lookup pages for every command, every field of a specification, plan policies, file formats and error messages. Each page opens with a table.

Commands

pravo init: Install the providers a root needs, write the lock file and generate the CUE packages that a specification imports.
pravo plan: Show the actions that apply takes. A plan changes no infrastructure, and it can be saved, judged by a policy and applied later.
pravo apply: Plan, ask for confirmation and apply, or apply a saved plan exactly as it was reviewed, in whole or in closed parts.
pravo destroy: Destroy every resource recorded in the state, dependents first, after a plan and a confirmation.
pravo show: Print a saved plan, with the time, the command and the actor that made it, and a warning when it cannot be applied.
pravo output: Print the output values that the last apply recorded in the state, as CUE or as JSON.
pravo state: Inspect and edit the state graph: list, show, move or forget a node, read the log and the locks, copy the state, query it, convert an OpenTofu state file.
pravo import: Bring an existing object under management from the command line, by the address of a declared resource and the provider's import id.
pravo providers: List the providers a root resolves, print a provider's schema, pin archive hashes for more platforms and copy a provider to a container registry.
pravo validate, eval, fmt and gen: Check a specification without planning it, print its evaluated value, format the CUE files and regenerate the provider packages.
pravo schema: Print the CUE definition of a resource, data source, ephemeral resource or function type, with the provider's documentation.
pravo why and pravo drift: Explain why a plan creates, changes, replaces or skips a resource, and read the records that a plan does not read to report what changed outside pravo.
pravo mcp: Serve pravo to an agent over the Model Context Protocol on stdio. Thirteen tools, applies only from saved plans, and plan policies the agent cannot remove.
pravo mod: Create, fetch and publish CUE modules for sharing, list the modules a root loads and verify them against the lock file.
pravo version: Print the version of pravo and the version of CUE that is built into it.
Global flags, environment and exit codes: The flags every pravo command accepts, the flags several commands share, the debug log, JSON output, the environment variables and where the exit codes are listed.

Language

The specification: What a root is, which constructs pravo reads from it, and the page that describes each one.
Settings: The $settings block. It sets where the state lives and the default refresh age, and nothing else.
Resources, data sources and calls: How to declare managed resources, data sources, ephemeral resources and function calls, how pravo finds them, and how they are addressed.
Provider declarations: How to declare a provider, the $-fields that tell pravo how to obtain it, instance keys, and rules that bind every resource built through a provider.
Moves and imports: $from renames or moves a record to a new address. $import adopts an existing object. Both are fields of the resource they describe.
Outputs: pravo.#Output publishes a value. It is recorded in state when a plan is applied and printed by pravo output.
Environment and remote outputs: pravo.#Env and pravo.#SecretEnv read environment variables. pravo.#RemoteOutputs reads the outputs another root has recorded.
Meta fields: The $-prefixed fields that resources, data sources and ephemeral resources accept in addition to the provider schema.
Tags and variables: Inputs are fields with a @tag attribute. -t and -T inject their values. Defaults and constraints are plain CUE.
Modules: A module is a CUE definition or package that contains resources. Instantiating it is enough. pravo finds the resources inside the instance.
Generated packages: The CUE packages that pravo init writes under cue.mod/gen, one per provider and one for pravo itself.

Policies

Policies overview: A plan policy is one CUE file that a plan must satisfy. It is named with --policy by whoever runs pravo and never by the specification.
The plan document in a policy: What a policy is unified with. How absent, null and unknown values behave, and what differs when a saved plan is applied.
Writing policies: The four rules for writing a plan policy, each with a captured run, plan-wide rules, and the typos that forbid nothing.
Operating policies: Where each command judges a policy, what a plan does before the verdict, how to roll a policy out and test it, and what a policy does and does not guarantee.

Data and formats

State format: The files of the state graph: nodes, outputs, transactions, locks and the metadata that identifies a store.
The plan document: The JSON document that pravo plan --json prints, the form of a saved plan file, and the events that apply and destroy stream.
Exit codes: The exit status of every pravo command, what each code means, and how --json reports an error.
Telemetry: OpenTelemetry traces and metrics for every command, resource and provider call, configured with the standard OTEL variables.
Compatibility: The versions and formats that pravo reads and writes, the provider protocol it speaks, and what it does with a version it does not know.
S3-compatible stores: The three conditional requests that the S3 backend needs, how pravo checks that a store honours them, and how to test a store before it holds a state.

Lookup

Error catalogue: Every error a user is likely to meet, as pravo prints it: the symptom, the cause and the fix.
Glossary: The terms of CUE and of pravo, each with a definition of one or two sentences and a link to the lesson that teaches it.
FAQ: Short, factual answers to the questions asked first.
Not in pravo: The commands, flags, blocks and files of OpenTofu and Terraform that pravo does not have, and what to use in each place.