Skip to content

Quick Start

Get up and running with formae in under 15 minutes. This guide will walk you through installing formae, configuring your environment, and deploying your first infrastructure with a forma.

What you'll accomplish

By the end of this guide, you'll have:

  • Installed formae and configured your development environment
  • Set up AWS credentials for infrastructure provisioning
  • Created your first formae project
  • Deployed infrastructure using a forma definition
  • Verified your deployment in AWS and with formae
  • Cleaned up resources using the destroy command

Prerequisites

Before you begin, ensure you have:

  • A Unix-based operating system (macOS or Linux)
  • An AWS account with programmatic access credentials
  • Basic familiarity with command-line tools
  • (Optional) A code editor with Pkl support for the best development experience

Estimated time: 15 minutes

Step 1: Install formae

Download and install formae using our installation script:

/bin/bash -c "$(curl -fsSL https://hub.platform.engineering/setup/formae.sh)"

This script will install formae to /opt/pel/formae/ and make the CLI tools available on your system.

Step 2: Configure shell PATH

Add formae to your shell's PATH so you can run commands from anywhere:

For zsh users (macOS default):

echo 'export PATH=/opt/pel/formae/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

For bash users:

echo 'export PATH=/opt/pel/formae/bin:$PATH' >> ~/.profile
source ~/.profile

Verify the installation:

formae --version

You should see the formae version number displayed.

Step 3: Configure AWS credentials

formae uses the AWS SDK to provision and manage infrastructure. Add your AWS credentials to ~/.aws/credentials:

[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

Security recommendation: For initial testing and development, we recommend using a dedicated AWS account or a sandboxed environment. Configuring fine-grained IAM permissions for production use is covered in the Configuration section.

Step 4: Create your first formae project

Generate a new project with the Pkl schema template:

cd ~/YourProjectsDir
formae project init ./myproject
cd myproject

This creates a new project directory with:

  • main.pkl - Your main forma definition file
  • PklProject - Pkl project configuration
  • Schema imports for type-safe infrastructure definitions

Step 5: Define your first resource

Open main.pkl in your editor. The project init command created a basic structure for you. Let's add a simple AWS S3 bucket resource.

First, add the import for the S3 bucket module at the top of the file with the other imports:

import "@aws/s3/bucket.pkl"

Then, in the main.pkl file, you'll see a section marked // My Resources. Add your first resource there:

local randomId = random.id(6).toString()

// My Resources
new bucket.Bucket {
  label = "my-s3-bucket"
  bucketName = "my-first-bucket-\(randomId)"
}

The randomId ensures your bucket name is globally unique across all AWS accounts, preventing naming conflicts.

Your complete main.pkl should now look like this:

/*
 * © 2025 Platform Engineering Labs Inc.
 *
 * SPDX-License-Identifier: FSL-1.1-ALv2
 */

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

local randomId = random.id(6).toString()

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

forma {
  new formae.Stack {
    label = "my-stack"
    description = "Stack for my resources"
  }

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

  // My Resources
  new bucket.Bucket {
    label = "my-s3-bucket"
    bucketName = "my-first-bucket-\(randomId)"
  }
}

This defines an S3 bucket with a unique name in the us-east-2 region.

Step 6: Start the formae agent

The formae agent manages infrastructure operations and state synchronization. Start it in a terminal window:

formae agent start

The agent will run in the foreground and display a message indicating it has started successfully. Keep this terminal open and use a separate terminal for the next steps.

Step 7: Apply your first forma

In a new terminal window, deploy the infrastructure you just defined:

cd ~/YourProjectsDir/myproject
formae apply --mode reconcile --watch main.pkl

When you run an apply command, formae executes it asynchronously on the agent. The --watch flag allows you to track live updates on the progress of your forma command. You can safely exit the watch at any time (Ctrl+C) - the operation will continue running on the agent in the background.

Expected output:

You'll see live updates on the deployment progress as formae creates your S3 bucket, including the command ID, status, and elapsed time.

Note: The --mode parameter is mandatory. We'll explore different apply modes in detail in the Workflows section.

Step 8: Verify your deployment

Now that your forma has been applied, you can verify the S3 bucket was created in two ways:

AWS Console:

Navigate to the AWS S3 console in your browser. You should see your bucket listed with the name you specified.

Formae inventory:

Check that formae has the resource under management:

formae inventory resources

This command lists all resources currently managed by formae, including your newly created S3 bucket.

Step 9: Clean up resources

To avoid unnecessary AWS charges, let's clean up the resources we created. Use the destroy command to delete the S3 bucket:

formae destroy --watch main.pkl

The destroy command removes all resources defined in the specified forma file. The --watch flag allows you to monitor the deletion progress in real-time.

Expected output:

You'll see live updates as formae removes the S3 bucket, including the command ID, status, and elapsed time.

Step 10: Explore example formas

Now that you've deployed your first forma, explore the included examples to see more complex infrastructure patterns:

cd ~/YourProjectsDir
cp -Rp /opt/pel/formae/examples ./formae-examples
cd formae-examples
pkl project resolve  # Downloads required Pkl packages

Browse the examples to see real-world infrastructure patterns and best practices including multi-resource stacks, cross-resource dependencies, and advanced configuration techniques.

What's next?

Now that you have formae up and running, explore these topics:

Want to learn more? Check out our Architecture guide to understand how formae works under the hood.