§ Reference

Reference

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

View as Markdown

On this page

Reference is for lookup. Each page opens with a table and keeps its prose short. To learn by doing, use Learn. To do one task, use How-to. To understand how pravo behaves, use Concepts.

Which page

You want	Page
The flags of a command, its exit codes and an example	Commands
The flags every command accepts, the environment variables, the exit codes	Global flags, environment and exit codes
What a field of the specification means	Language
To write a plan policy	Policies
The JSON of a plan, or the files of the state	Data and formats
An error message you do not recognise	Errors
The meaning of a word	Glossary
To know whether pravo has a feature of OpenTofu	Not in pravo

Commands

Every page opens with the synopsis, the flags with their defaults, and the exit codes. Then it shows examples with output captured from the binary.

Command	Does	Page
`pravo init`	Installs providers, writes the lock file, generates the CUE packages.	init
`pravo plan`	Shows the actions that apply takes. Saves, refreshes, reserves, judges.	plan
`pravo apply`	Applies the specification or a saved plan, whole or in closed parts.	apply
`pravo destroy`	Destroys everything in the state.	destroy
`pravo show`	Prints a saved plan.	show
`pravo output`	Prints the outputs the last apply recorded.	output
`pravo state`	Lists, shows, moves and forgets nodes. Reads the log and the locks. Queries, copies and converts the state.	state
`pravo import`	Brings an existing object under management.	import
`pravo providers`	Lists providers, pins hashes, copies a provider to a registry.	providers
`pravo validate`, `eval`, `fmt`, `gen`	Checks the specification, prints its value, formats the files, regenerates the packages.	validate, eval, fmt and gen
`pravo schema`	Prints the definition of one resource type.	schema
`pravo why`, `drift`	Explains a change. Reports what changed outside pravo.	why and drift
`pravo mcp`	Serves pravo to an agent over the Model Context Protocol.	mcp
`pravo mod`	Creates, fetches, publishes and verifies CUE modules.	mod
`pravo version`	Prints the version of pravo and of CUE.	version
Flags, environment, exit codes	The parts every command shares.	global flags

Language

The fields and definitions that a specification uses.

Page	Covers
Overview	What a root is and how pravo finds the resources in it.
Settings	The `$settings` block.
Resources	Resources, data sources, ephemeral resources and function calls.
Providers	Provider declarations and their `$` fields.
Moves and imports	`$from` and `$import`.
Outputs	`pravo.#Output`.
Environment and remote outputs	Environment values, secret environment values and the outputs of another root.
Meta fields	`$lifecycle`, `$depends_on` and the other `$` fields of a resource.
Tags and variables	`@tag()` fields and how a command fills them.
Modules	Modules that hold resources.
Generated packages	The packages under `cue.mod/gen`.

Policies

A plan policy is a CUE file that a plan must satisfy.

Page	Covers
Overview	What a policy is, where it is judged, what it binds.
The plan document	The fields a policy can see.
Writing a policy	The shapes that work.
Operating policies	Naming, testing and rolling out policies.

Data and formats

Page	Covers
State format	The files of the state directory.
The plan document	The JSON that `pravo plan --json` prints.
Exit codes	The exit code of each command, for pipelines.
Telemetry	Traces and metrics.
Compatibility	Which versions work together.
S3-compatible stores	The conditional requests that locks need, and how to test a store.

Lookup

Page	Covers
Errors	Symptom, cause and fix for the messages pravo prints.
Glossary	The terms of CUE and of pravo.
FAQ	Short answers.
Not in pravo	Features that pravo does not have, and what to use.

Reading the examples

In a synopsis, words in capitals are values you supply. Square brackets mark an optional part. Three dots mark a part that repeats.
An example opens with the directory it runs in: an empty directory, named demo when the name shows. Commands never use cd.
Output that differs between runs is shown with a placeholder: <txn> for a transaction, <time> for a time, <age> for an age.
Every example ran on the version named in the footer of the page. The providers are random, local, null and tls, and the functions of kubernetes, so an example needs no account.
A long output is cut. Three dots on a line of their own stand for the lines that were left out.