Day-to-day operations

Regular infrastructure work with formae.

Scenarios covered:

I want to see what resources formae is managing

When to use this

Use this workflow when you:

  • Are onboarding to an existing project and need to understand what's deployed
  • Want to audit current state before making changes — know what you're working with
  • Need a quick inventory of what's managed vs. what's just discovered

What you'll do

  1. List managed resources — see everything formae controls
  2. Filter by stack, type, or label — narrow down to what you care about
  3. Check stacks and targets — get the bigger picture

Step-by-step

Before you begin: review the baseline prerequisites.

Step 1: List all managed resources

formae inventory resources --query="managed:true"

This shows every resource formae actively manages — resources it can update, delete, and track through code.

To see more than the default 10 results:

formae inventory resources --query="managed:true" --max-results=100

Step 2: Filter by stack or type

Narrow it down by stack:

formae inventory resources --query="stack:production"

By resource type:

formae inventory resources --query="type:AWS::S3::Bucket"

Combine filters:

formae inventory resources --query="stack:production type:AWS::EC2::SecurityGroup"

Step 3: Check stacks and targets

formae inventory stacks
formae inventory targets

Tips + gotchas

Tip Details
Managed vs unmanaged managed:true shows what formae controls. managed:false shows discovered resources not yet under management.
Query fields stack, label, type, managed, commandid — combine as many as you need.
Machine-readable output Add --output-consumer=machine --output-schema=json for scripts or dashboards.

Common gotcha: Stack and label names are case-sensitive in queries. stack:Production and stack:production return different results.

What's next

Goal Guide
Find a specific resource I want to find a specific resource by type or name (below)
Understand managed vs unmanaged Core Concepts → Unmanaged Resources
CLI reference CLI → Inventory

I want to make surgical changes with minimal blast radius

When to use this

Use this workflow when you:

  • Need to add or update a few resources without risking the rest of your stack
  • Are working in production and want the safest possible change path
  • Don't want to redeclare your entire stack just to tweak one thing

Patch mode is the tool here. It creates and updates — but never destroys. You tell formae exactly what to touch, and everything else stays put.

What you'll do

  1. Write a minimal forma — only the resources you're changing
  2. Simulate, then apply with patch mode

Step-by-step

Before you begin: review the baseline prerequisites and know the stack and target for the resources you want to change.

Step 1: Write a focused forma

Include only the resources you're adding or updating — you don't need to redeclare the entire stack:

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

forma {
  new formae.Stack {
    label = "production"
  }

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

  new bucket.Bucket {
    label = "reports-bucket"
    bucketName = "acme-reports-2026"
  }
}

Note: This example uses AWS. The same workflow applies to any technology that has a formae plugin.

Step 2: Simulate and apply

Preview first — no cloud API calls, instant:

formae apply --mode patch --simulate my-change.pkl

Then apply:

formae apply --mode patch --watch my-change.pkl

Tips + gotchas

Tip Details
Patch = additive only Creates and updates, never destroys. The safest way to evolve infrastructure.
Skip confirmation Add --yes to bypass the prompt.
Verify after applying formae inventory resources --query="stack:production label:reports-bucket"

Common gotcha: If you later run formae apply --mode reconcile with a forma that doesn't include your patch additions, reconcile will destroy them. Make sure your source-of-truth forma includes everything in the stack.

What's next

Goal Guide
Understand patch vs reconcile Core Concepts → Apply Modes
Emergency changes I want to make a quick fix during an incident
Automate in a pipeline CI/CD Integration

I want to find a specific resource by type or name

When to use this

Use this workflow when you:

  • Need to look up a resource before editing or debugging it
  • Want to check if something exists across your stacks
  • Are searching for a resource but only know its name, type, or which stack it belongs to

What you'll do

  1. Search by label, type, or a combination of filters
  2. Extract the full configuration for inspection

Step-by-step

Before you begin: review the baseline prerequisites.

Step 1: Search with filters

By label:

formae inventory resources --query="label:api-sg"

By type:

formae inventory resources --query="type:AWS::EC2::SecurityGroup"

Combine as many filters as you need:

formae inventory resources --query="stack:production label:api-sg"
formae inventory resources --query="managed:false type:AWS::EC2::VPC"

Step 2: Extract for full details

Pull a resource's full configuration into a Pkl file — useful for inspection, diffing, or as a starting point for changes:

formae extract --query="label:api-sg" api-sg.pkl

Tips + gotchas

Tip Details
Available query fields stack, label, type, managed (true/false), commandid
Increase results Default is 10 results. Add --max-results=50 to see more.
Type queries are case-insensitive type:aws::ec2::securitygroup works the same as type:AWS::EC2::SecurityGroup.

Common gotcha: Stack and label values are case-sensitive. label:Api-SG and label:api-sg are different queries.

What's next

Goal Guide
See the full inventory I want to see what resources formae is managing (above)
Make a targeted change I want to make surgical changes with minimal blast radius
CLI reference CLI → Inventory