Skip to main content
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. Use --desired when you need the complete recorded declaration of a stack, rather than its current observed inventory.

​
Examples

​
Flags

​
Complete desired stacks

Use desired extraction to prepare a normal reconcile from formae’s recorded intent:
This includes the complete selected stack declaration, even if it currently has no resources, and preserves its policies, generators and references. Select stacks using literal selectors such as stack:prod stack:staging; resource-type filters and wildcards do not describe a complete desired stack. A referenced resource’s presence in another stack does not bring that other stack under the new declaration’s management. Desired intent can differ from observed inventory after out-of-band changes or a failed operation. Review the next apply’s simulation and resolve out-of-band changes before submitting a reconcile. Secret hashes cannot replace unavailable plaintext in an apply. A failed creation can remain in desired state even though the resource does not appear in inventory. If its declaration references a resource that was deleted, extraction preserves the declaration and writes an explicit repair placeholder at the unresolved reference. The Pkl cannot evaluate until you remove the owning declaration, change the reference, or explicitly restore the dependency. To abandon a failed creation, remove its declaration from the complete extracted stack and apply that stack. formae records the withdrawal even when no cloud operations are needed, so the declaration does not return on the next extraction. The original failed command remains in history. Withdrawing intent does not prove that a partially completed cloud operation left no resource behind.

​
Save desired state as JSON

Starting with formae 0.90.4, export a complete desired declaration directly as JSON for review and replay:
The JSON file preserves the complete declaration without generating a Pkl project or resolving schema packages. It is written with owner-only permissions. Keep the same file and explicit mode throughout review and submission. Review freshness checks still apply, and unavailable secret plaintext is not recovered by choosing JSON output. JSON output is limited to complete desired extraction. It cannot be combined with ordinary inventory extraction, --command, --from-json, or --schema-location local.

​
Update source from a recorded command

After a shared decision about out-of-band changes, extract that command’s recorded desired changes:
Fold the returned declarations and deletion guidance into the maintained project. This delta remains tied to the recorded command even if later syncs or patches change inventory. Check the command’s outcome separately.
A command delta is a partial source-edit snippet. Do not apply it as a complete reconcile: omission of other resources could plan their deletion. Use --desired when you need a complete stack.

​
Render a retrieved bundle

Integrations can retrieve a Forma and the installation’s plugin information, then render them without resolving a profile again:
The JSON bundle carries Forma and Plugins; - reads it from standard input. The renderer reuses normal Pkl generation and dependency handling. Schema packages may still be downloaded. Keep the generated project and dependency files alongside the Pkl while evaluating or editing it; temporary authoring can remove the whole directory afterward. Bundle rendering, command-delta extraction, and query-based extraction are separate input modes. Rendering supplied data does not verify that an agent supports desired extraction, or turn a partial Forma into a complete stack.

​
Plugin dependencies

An extracted Pkl 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:
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: 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.
To resolve it, bump the formae dependency in your PklProject to 0.88.0 or greater, then run:
The extracted file then evaluates correctly.