formae extract

Extract resources that formae knows about into a forma file, so you can bring existing infrastructure under management as code. Select the resources with a query and give a target file to write.

formae extract [flags] <target file>

Examples

formae extract --query 'type:AWS::S3::Bucket' ./buckets.pkl
formae extract --query 'type:GCP::Compute::* managed:false' ./gcp-unmanaged.pkl
formae extract --query 'stack:prod target:eu target:us' ./prod.pkl

Flags

Flag	Default	Description
`--query <query>`		Find resources by their attributes. `*` works as a wildcard.
`--output-schema <pkl>`	`pkl`	Output schema. Only `pkl` is currently supported.
`--schema-location <remote\|local>`	`remote`	How plugin PKL schemas are referenced in the generated PklProject. `remote` emits `package://` URIs fetched from the hub. `local` emits local file imports against the agent’s on-disk PklProject paths, and requires the CLI and agent to share a filesystem.
`--yes`	`false`	Overwrite existing files without prompting.
`--config <path>`		Path to a config file.
`--profile <name>`		Named profile to use.

Plugin dependencies

The extracted file needs every plugin whose resources it declares to be a dependency of the PklProject that covers it. When you extract into a directory that already has a PklProject, extract adds any plugin namespace the resources need but the project is missing and re-resolves the project — silently, as part of extracting. Only the missing entries are added; your existing dependencies (including your pinned formae version) are preserved. If a resource needs a plugin the agent does not report as installed, extract fails with an actionable message instead of producing a file that can’t be generated:

resource type "AZURE::Network::Subnet" requires plugin namespace "azure", but the agent does not report it installed. Install it with `formae plugin install azure` and retry

Missing plugin dependencies are added automatically, because the extracted file cannot be generated without them. The formae core schema version is handled differently: extract only notifies you (see below) and never rewrites it.

Schema version compatibility

Extracted forma files use extends "@formae/forma.pkl" (see Properties), a shape introduced in formae 0.88.0. A PklProject pinning an older formae cannot evaluate a freshly extracted file, because the Pkl evaluator fails to resolve the extends. When you extract into a directory already covered by a PklProject, formae checks the formae version it pins:

Pinned formae version	Result
`< 0.88.0`	The file is written, then extract prints the notice below
`>= 0.88.0`	No notice
No `PklProject`, or no formae dependency	No notice

The extracted .pkl is always written. The notice is advisory: extract never rewrites your PklProject, so it introduces no surprise diff into your working tree.

'<dir>/PklProject' is using formae version 0.87.0, however CLI is at version 0.88.0. Please update to 0.88.0 or greater and run 'pkl project resolve', in order to ensure extracted file evaluates.

To resolve it, bump the formae dependency in your PklProject to 0.88.0 or greater, then run:

pkl project resolve

The extracted file then evaluates correctly.

Get started

Guides

Concepts

Reference

formae extract

Examples

Flags

Plugin dependencies

Schema version compatibility

​Examples

​Flags

​Plugin dependencies

​Schema version compatibility

Examples

Flags

Plugin dependencies

Schema version compatibility