First steps

These scenarios help you get oriented and see what's in your cloud.

Scenarios covered:

I want to safely explore what's in my cloud account

When to use this

Use this workflow when you:

  • Are new to formae and want to understand what's already deployed in your cloud account
  • Want to audit existing infrastructure without making any changes
  • Plan to gradually adopt formae alongside other tools (Terraform, Pulumi, manual deployments)
  • Need visibility across resources not yet under formae management

This is the safest starting point. formae will discover and catalog your resources, but won't touch anything until you explicitly ask it to.

What you'll do

  1. Create and apply a discoverable target — tells formae which account/region to scan
  2. View discovered resources — see what exists in your cloud without modifying anything

Step-by-step

Before you begin: make sure formae is installed, your cloud provider credentials are configured, and the agent is running (see CLI → agent).

Step 1: Create a discoverable target

Create a file called discovery-target.pkl with your cloud account configuration:

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

forma {
  new formae.Target {
    label = "my-account"
    discoverable = true // Enable discovery for this target
    config = new aws.Config {
      region = "us-east-1"
    }
  }
}

Step 2: Apply the target

Note: This is safe — no resources will be affected!

formae apply --mode reconcile discovery-target.pkl

Step 3: Wait for discovery to complete

Discovery runs automatically every 10 minutes by default. You can check the status of your configured targets:

formae inventory targets --query='discoverable:true'

Note: First discovery may take a few minutes depending on the size of your account. As soon as you apply your target for the first time, discovery will start.

Step 4: View discovered resources

Once discovery runs, view what formae found. These are unmanaged resources that exist in your cloud but aren't controlled by formae yet:

View all discovered (unmanaged) resources
formae inventory resources --query="managed:false"
View more results (default is 10)
formae inventory resources --query="managed:false" --max-results=50
Just S3 buckets
formae inventory resources --query="managed:false type:AWS::S3::Bucket"

Next: Extract and manage

Ready to turn discovered resources into code? See I want to turn existing cloud resources into infrastructure code.

Tips + gotchas

Tip Details
Multi-region support Create multiple targets (one per region) to discover across regions.
Coexists with other tools Resources managed by Terraform or other tools appear as unmanaged. formae won't interfere.

Common gotcha: If formae inventory resources returns empty results immediately after applying a target, discovery hasn't completed yet. Wait a few minutes or check logs at ~/.pel/formae/log/formae.log.

What's next

Goal Guide
Create new resources Formae 101 → Fundamentals
Understand discovery in depth Discovery
Configure discovery settings Configuration → Discovery
See supported AWS resources AWS Infrastructure