§ Reference · Commands
pravo discover
Run the discoveries of the specification, show what they found against the state, show the objects that are meant to stay unmanaged apart and write the resource that adopts one.
On this page
Quick reference
| Synopsis | pravo discover [NAME...], pravo discover show [NAME...], pravo discover adopt NAME ID |
| Changes infrastructure | No. A discovery lists. |
| Starts providers | discover and adopt --read. The other subcommands read the state and start nothing. |
| Writes | discover: one object for each discovery it runs, discovery/runs/<name>.json. Nothing else: no record, no transaction and no lock. |
| Requires | A discovery in the specification, built from a provider that implements list resources. Discovery explains what one is. |
| Taught in | Find what nothing manages. |
A discovery is written name: $provider.#Discovery.<type> & {scope...} and may set $limit, the most objects that one run keeps, and $ack, the list of what is known and left alone. NAME is the address of the struct, such as servers or network.vpcs. A name that no discovery has is an error that lists the names that exist. A discovery cannot be called show or adopt: a first argument that is one of them is the subcommand.
pravo discover
Runs discoveries. Without names it runs the ones that have not run yet and the ones whose scope changed since they ran. With names it runs those, and with --all every one. For each it starts the provider, converts the scope against the schema of the list resource, lists, and stores the result. It then prints what the run found, as show prints it.
A discovery that fails does not stop the others. Its error is printed, its last run stays in the state, and the exit code is 1.
| Flag | Default | Meaning |
|---|---|---|
--all |
off | Run every discovery. Not with names. |
-t, --tag key=value |
none | Inject a value for an @tag() field. Repeatable. |
-T, --inject-vars |
off | Inject the system variables of CUE. |
With --json it prints one document, the one of show --json for the discoveries it ran.
pravo discover show
Prints what the last run of each discovery found, set against the records of the state and the declarations of the specification. It reads and writes nothing and starts no provider. In a sealed state it needs the identity of a reader, as state show does, since it compares attributes of records.
For each discovery it prints the name, the type and the provider instance, the scope, the time of the last run and the counts. A discovery that has not run, whose scope cannot be listed with, whose scope changed since it ran, or that the specification does not declare says so, and Run: pravo discover NAME is the command that fixes the first two kinds. Then it lists the objects in groups: UNMANAGED with the command that adopts each, ADOPTING with the resource that adopts it, ACKNOWLEDGED with the $ack entry that covers it and its reason. A group lists 20 objects, then says how many more there are; --json lists them all. The managed objects are counted.
| Flag | Default | Meaning |
|---|---|---|
--exit-code |
off | Exit 2 when an object that is shown is unmanaged. |
--managed |
off | List the managed objects too. |
pravo discover adopt
pravo discover adopt NAME ID [--read] prints the CUE of a resource that adopts one object of the last run: a struct of the type of the discovery, built through its provider, with $import set to the identity of the object, the attributes the provider listed it by. ID is the id that the listing shows, or the whole identity. Nothing is written to the specification or the state.
Without --read the resource has the import and nothing else. With it the provider is asked for the object, as a plan of an $import asks, and the attributes it has are written into the resource: the ones that are not computed alone, no null, no write-only attribute. A sensitive attribute is named in a comment and its value is not written. The result is laid out as pravo fmt does.
The identity is written as the provider gave it, whatever it is made of, and no id has to be found. An attribute that is null is left out, since the provider fills it in. An object that is managed is refused. An object that a resource already adopts is printed with a note.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The command did what it was asked. |
| 1 | A discovery failed to run: the provider returned an error, the scope has no value, or the provider cannot list the type. An argument that is wrong. |
| 2 | show --exit-code found an unmanaged object. |
| 6 | The specification does not load, or NAME is not a discovery, or the object is not in the last run, or the object is managed, or an $ack entry of the specification is not valid: it has no pattern, a pattern that is empty, longer than 512 bytes or made of * alone, or more than 10000 patterns. |
The global flags apply.
The state
| Object | Holds |
|---|---|
discovery/runs/<name>.json |
The last run of one discovery: the type, the provider, the scope and its digest, the limit, when and by whom, complete or truncated, the warnings, and for each object its key, id, display name, identity and import id. The name is the address, with the characters that a file name cannot hold written as %XXXX. |
It is not sealed. pravo state pull and pravo state push copy it with the records. The acknowledgements are not in the state: they are the $ack of the specification.
The viewer
pravo serve shows the same data in the Discovery section: each discovery as a card, the unmanaged objects first. It reads the runs and the specification and writes nothing. It offers the commands above as text.