Skip to main content
Apply a forma to create or update infrastructure. apply reads a forma file, sends it to the agent, and reconciles or patches your resources depending on the apply mode.
The --mode flag is required, and a forma file argument is required.

​
Examples

For human output, apply always simulates first and shows the planned changes before asking you to confirm. Use --yes to skip the confirmation, or --simulate to stop after the dry run.

​
Flags

​
Property flags

Properties declared in your forma become flags on apply, so you can set them per run without editing the file. apply, destroy, and eval all support the properties declared by the forma they target. Run formae apply --help against a specific forma to see the property flags it exposes.

​
Resolve out-of-band changes

In interactive reconcile, choose absorb or revert for each out-of-band change that needs a decision in the affected stack, then review the combined simulation. Acceptance is recorded centrally when the real reconcile is submitted; --simulate alone does not record it. Noninteractive output returns out-of-band changes for the caller to resolve. After resolution, the CLI prints recorded resource identities, exact queries where supported, deletion guidance and an extract --command instruction for updating an optional IaC codebase. It does not edit source files automatically. See Deal with out-of-band changes.

​
Explicit controls for automation

A resolution controls file contains the returned ObservationID and a complete Decisions array, with a ResourceID and an Action of absorb or revert for each out-of-band change that needs a decision. Starting with formae 0.90.4, freeze evaluated input before the initial observation when Pkl generates values such as random passwords:
Save the returned observation and choose each action explicitly. Preview those choices against the same file:
The response includes the composed Simulation and its Review. For real machine submission, include the returned ReviewID and a stable IdempotencyKey in the controls file. Keep the reviewed declaration and controls together. A changed or stale observation requires fresh review; a retry of the same admitted operation uses the same key and inputs. Use the same explicit mode for evaluation, observation, review, and submission. An evaluated JSON file does not accept property overrides and can contain sensitive values. To start from recorded desired state, use extract --desired --output-schema json. Idempotency keys are scoped to the authenticated user when available. Without authentication, clients connected to the same agent share that scope. Generate a fresh unique key for each new operation and reuse it only when retrying that same operation. Machine mode never chooses actions for out-of-band changes or prompts for confirmation. Check the exit status and structured rejection output before continuing. --simulate never records the acceptance. Resolution controls belong to the command and are not saved in the Pkl source.

​
Command messages and input history

Messages are optional. In interactive review, you can accept a suggestion, edit it, or leave the message empty. An explicitly empty -m "" remains empty; noninteractive calls do not require a message. The command also retains input names, types and whether values came from supplied flags or the declaration. Only scalar values explicitly classified as non-sensitive are retained. Sensitive values are redacted and unclassified values are withheld. The absence of classification never makes an input public.