Quick start

Step 1: Install formae

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

Verify:

formae --version

Step 2: Copy an example to your workspace

Browse the examples shipped with the installation:

ls /opt/pel/formae/examples/

Choose an example for the cloud you want to work with — each includes a README with setup details.

Copy the example to a working directory along with the PklProject and PklProject.deps.json from its parent directory. These files define the Pkl package dependencies (formae SDK, cloud-provider schemas) the example needs to resolve its imports:

cd ~/projects
cp -R /opt/pel/formae/examples/<CLOUD>/<EXAMPLE> ./
cp /opt/pel/formae/examples/<CLOUD>/PklProject* ./<EXAMPLE>/
cd <EXAMPLE>

Step 3: 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 4: Apply your first forma

In a new terminal window, provision the infrastructure defined in the example you chose:

cd ~/projects/<EXAMPLE>
formae apply --mode reconcile --watch <THE MAIN ENTRY POINT OF THE EXAMPLE - SEE README>

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 infrastructure provisioning progress as formae creates the resource, including the command ID, status, and elapsed time.

Note: The --mode parameter is mandatory. Learn about reconcile and patch modes in Apply modes.

Step 5: Verify your deployment

Verify in your cloud account using its web console or any other tool you prefer if the resources declared in the example of your choice have been created.

formae inventory:

Check that formae has the resource under management:

formae inventory resources

This command lists all resources currently managed by formae.

Step 6: Clean up resources

To avoid unnecessary charges, let's clean up the resources we created. Use the destroy command to delete resources you created during this quick start:

formae destroy --watch <THE MAIN ENTRY POINT OF THE EXAMPLE - SEE README>

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 resources, including the command ID, status, and elapsed time.

AI assistants (MCP)

With the agent running, install the formae MCP plugin. Example using Claude Code:

/plugin marketplace add platform-engineering-labs/formae-marketplace
/plugin install formae-mcp@formae-marketplace

Restart Claude Code, then verify:

/formae-status

See AI assistants for setup with Claude Code, Codex, OpenCode, and other MCP clients.

Plugin source: platform-engineering-labs/formae-mcp.

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.