pravo
GitHub Quick start

§ Reference · Language

The specification

What a root is, which constructs pravo reads from it, and the page that describes each one.

View as Markdown

On this page

A root is a directory that holds one CUE package. pravo unifies every .cue file of the package into one value and reads the constructs below from it. Everything else in the value is yours.

Construct Written as Page
Settings $settings: pravo.#Settings & {...} Settings
Provider $aws: awsp.#Provider & {...} Providers
Managed resource $aws.#Resource.<type> & {...} Resources
Data source $aws.#Data.<type> & {...} Resources
Ephemeral resource $aws.#Ephemeral.<type> & {...} Resources
Function call $aws.#Function.<name> & {args: [...]} Resources
Output pravo.#Output & {value: ...} Outputs
Environment variable pravo.#Env, pravo.#SecretEnv Environment and remote outputs
Outputs of another root pravo.#RemoteOutputs Environment and remote outputs
Rename, move, adopt $from, $import Moves and imports
Dependencies, lifecycle $depends_on, $lifecycle Meta fields
Input a field with @tag(name) Tags and variables
Module a definition or a package Modules
Provider and pravo packages cue.mod/gen/ Generated packages

A complete root

Work in an empty directory. The root below uses two providers and publishes one output.

main.cue
package demo

import (
	"pravo.dev/pravo"
	rnd "pravo.dev/providers/hashicorp/random"
	loc "pravo.dev/providers/hashicorp/local"
)

$settings: pravo.#Settings & {state: path: "pravo.state"}

$random: rnd.#Provider & {$version: "~> 3.6"}
$local:  loc.#Provider

pet: $random.#Resource.random_pet & {length: 2}

hello: $local.#Resource.local_file & {
	filename: "hello.txt"
	content:  "Hello, \(pet.id)!\n"
}

file: pravo.#Output & {value: hello.filename}
terminal
$pravo init
Configuration does not load yet; generating schemas for the declared providers first.
Created cue.mod/module.cue
Providers:
  local = hashicorp/local v2.9.1
  random = hashicorp/random v3.9.1
Up to date cue.mod/gen/pravo.dev/providers/hashicorp/local (2 resource types, 3 data sources, 1 ephemeral, 1 functions)
Up to date cue.mod/gen/pravo.dev/providers/hashicorp/random (10 resource types, 0 data sources, 2 ephemeral, 0 functions)

pravo has been initialised. Run "pravo plan" to see what it would do.
terminal
$pravo validate
Success! 2 resources, 0 data sources, 0 ephemeral, 0 function calls, 1 outputs across 2 providers.

pravo validate counts what it found: two resources, one output and two providers. The resources have the addresses pet and hello. The output has the name file.

terminal
$pravo plan | grep '^ #'
  # pet (random_pet) will be created
  # hello (local_file) will be created

What makes a root

Rule Effect
The directory holds .cue files with one package clause. The files are unified into one value. A conflict between files is an evaluation error.
A file without a package clause is an error. Nothing is evaluated. The error names the file and the package of the other files. pravo.lock.cue and the files whose names start with . or _ are not part of the package.
Two package names in one directory are an error. Nothing is evaluated. The error names the file and the package of the other files.
$settings is the one reserved top-level field. pravo reads it and never searches it for resources.

Two files of one package merge:

base.cue
package demo

size: 3
more.cue
package demo

name: "web\(size)"
terminal
$pravo eval -e name
$pravo eval -e size
"web3"
3

A file without a package clause stops the load. pravo names the file:

notes.cuerejected
size: 99
terminalexit 6
$pravo eval
Error: loading .:
notes.cue has no package clause; the other files are package demo

Remove the file. A file with another package name stops the load in the same way:

terminal
$rm notes.cue
more.cuerejected
package other

name: "web"
terminalexit 6
$pravo eval
Error: loading .:
more.cue is package other; the other files are package demo

What pravo reads

pravo walks the evaluated value and collects every struct that carries the identity fields $kind, $type and $source of a generated definition. Those fields come from the definition, so a struct built through a provider has them without you writing them. Resources lists what the walk enters and what it skips.

A struct that does not carry them is data. It can hold any value, and it is evaluated with the rest of the package.

Files in a root

Path Written by Contents
cue.mod/module.cue pravo init The CUE module of the root.
cue.mod/gen/ pravo init, pravo gen One CUE package per provider and the pravo.dev/pravo package. See Generated packages.
pravo.lock.cue pravo init The pinned provider versions and archive hashes. Commit it.
pravo.state/ any command that writes the state The state of the root. See State format. The location is set in Settings.

See also