Forma

A forma (plural: formae) is a configuration file that contains stacks and resources. When you apply a forma, formae processes it to create, update, or delete resources in your infrastructure.

Think of a forma as a container for your infrastructure definitions. It gives you precise control over what changes you want to make. Unlike tools that force you to deploy everything at once, formae lets you choose exactly which resources to include in each forma.

This flexibility works in every situation—whether you're rolling out a complete infrastructure for the first time, upgrading a production environment, or deploying an urgent fix at 2 AM. When you need to minimize risk, you can create a forma with just the specific changes you want to make, rather than hoping a tool can correctly predict the impact of your changes.

Formae work in both directions: you can apply them to update infrastructure, and you can extract them from existing resources. This means you can pull infrastructure definitions from what's currently running, modify them, and apply them elsewhere. This creates a powerful workflow for refining and reusing infrastructure patterns.

A forma can be temporary (used once and discarded) or saved to version control for long-term management—you choose what works for your situation.

Example

A simple forma in Pkl:

amends "@formae/forma.pkl"
import "@formae/formae.pkl"
import "@aws/aws.pkl"
import "@aws/s3/bucket.pkl"

forma {
  new formae.Stack {
    label = "my-app"
    description = "My application stack"
  }

  new formae.Target {
    label = "my-aws-target"
    config = new aws.Config {
      region = "us-east-1"
    }
  }

  new bucket.Bucket {
    label = "app-bucket"
    bucketName = "my-unique-bucket-name"
  }
}

A forma can also include optional blocks:

description - A user-facing message displayed before applying the forma:

description {
  text = """
  This forma creates production infrastructure.
  Make sure you've reviewed the changes before proceeding.
  """
  confirm = true  // Requires user confirmation (Y) before applying
}

properties - Define configurable parameters (see Properties for details):

properties {
  bucketName = new formae.Prop {
    flag = "bucketName"
    default = "my-default-bucket"
  }
}

Working with Formae

Evaluating a forma:

Before applying, you can evaluate a forma to validate your Pkl syntax and see the resulting configuration:

formae eval my-infrastructure.pkl

This renders the forma into the output format, helping you verify the configuration is correct. See the eval command for more details.

Applying a forma:

formae apply --mode reconcile my-infrastructure.pkl

See the apply command for more details.

Destroying resources:

formae destroy my-infrastructure.pkl

This removes all resources defined in the forma. See the destroy command for more details.

Common Workflows

Full infrastructure deployment: Create a forma with all your stacks and resources, then apply it to set up a complete environment.

Targeted updates: Create a forma with just the resources you want to change, minimizing the blast radius of your deployment.

Environment cloning: Extract a forma from one environment, modify it (like changing region or size), and apply it to create a new environment.

Note: A forma might not complete successfully—many things can fail between the agent and the final resource. However, an incomplete forma will always leave your infrastructure in a consistent state. If the failure was recoverable or due to a user error, you can simply reapply the forma to eventually reach full consistency. The agent also automatically retries incomplete formas when possible.