# Formae

## Docs

- [Apply modes](https://docs.formae.io/documentation/concepts/apply-modes.md): What reconcile and patch modes each let formae do, and what they refuse to do.
- [Architecture](https://docs.formae.io/documentation/concepts/architecture.md): How the CLI, agent, metastructure, and plugins fit together.
- [Discovery](https://docs.formae.io/documentation/concepts/discovery.md): How formae finds resources you haven't told it about yet, and tracks them until you bring them under management.
- [Forma](https://docs.formae.io/documentation/concepts/forma.md): A forma is an infrastructure declaration: the unit formae applies, extracts, or destroys.
- [Label](https://docs.formae.io/documentation/concepts/label.md): The formae-side identifier you use to reference a stack or resource.
- [Plugins](https://docs.formae.io/documentation/concepts/plugin.md): How formae extends itself to new infrastructure through separate, independently versioned plugin processes.
- [Auto-reconcile policy](https://docs.formae.io/documentation/concepts/policies/auto-reconcile.md): Automatically re-apply a stack's declared state at a fixed interval, undoing drift.
- [TTL policy](https://docs.formae.io/documentation/concepts/policies/ttl.md): Automatically destroy a stack and its resources after a set duration.
- [Policy](https://docs.formae.io/documentation/concepts/policy.md): A policy is a lifecycle rule you attach to a stack: automatic cleanup after a duration, or automatic enforcement of declared state.
- [Properties](https://docs.formae.io/documentation/concepts/properties.md): Parameters that turn a forma into a reusable, type-safe template exposed as CLI flags.
- [Resolvable](https://docs.formae.io/documentation/concepts/resolvable.md): How you reference another resource's properties or a secret without knowing its value at write time.
- [Resources](https://docs.formae.io/documentation/concepts/resources.md): The infrastructure formae manages, and the difference between managed and unmanaged resources.
- [Stack](https://docs.formae.io/documentation/concepts/stack.md): formae's unit of lifecycle: the resources you create, reconcile, and destroy together.
- [Synchronization](https://docs.formae.io/documentation/concepts/synchronization.md): How formae keeps its recorded state current when a resource changes outside of formae.
- [Target](https://docs.formae.io/documentation/concepts/target.md): Where formae creates, manages, and discovers resources: a cloud account, region, or environment.
- [Values](https://docs.formae.io/documentation/concepts/values.md): The .opaque and .setOnce modifiers that give a plain value secret-handling or stable-once-generated behavior.
- [Ways to work with formae](https://docs.formae.io/documentation/concepts/ways-to-work.md): Three operating models, from Git as the strict source of truth to formae as the system of record.
- [Quick start](https://docs.formae.io/documentation/get-started/quickstart.md): Install formae and deploy your first infrastructure to AWS, Azure, or GCP in about ten minutes.
- [Quick start with an AI assistant](https://docs.formae.io/documentation/get-started/quickstart-ai-assistant.md): Deploy your first infrastructure by describing what you want to an AI coding assistant.
- [Write your first forma](https://docs.formae.io/documentation/get-started/write-your-first-forma.md): Build a forma from scratch: a stack, a target, resources, references, and properties.
- [AI assistants](https://docs.formae.io/documentation/guides/ai-coding-assistants.md): Connect formae to Claude Code, Codex, OpenCode, Cursor, or any MCP client, and manage infrastructure through conversation.
- [Bring existing resources under management](https://docs.formae.io/documentation/guides/bring-resources-under-management.md): Turn resources that already exist in your cloud into formae-managed code, without recreating anything.
- [Build self-service infrastructure](https://docs.formae.io/documentation/guides/build-self-service-infrastructure.md): Expose a clean, parameterized interface so developers deploy production-ready infrastructure with a few flags while your code enforces the standards.
- [Cancel a running command](https://docs.formae.io/documentation/guides/cancel-a-running-command.md): Stop an in-progress apply or destroy without leaving orphaned resources behind.
- [Run formae in CI/CD](https://docs.formae.io/documentation/guides/cicd.md): Drive formae non-interactively from a pipeline: validate changes in a pull request, apply on merge, pass values between stages, and manage the pipeline itself as a forma.
- [Create a target](https://docs.formae.io/documentation/guides/create-a-target.md): Register a cloud account and region with formae so it can deploy there and discover what already exists.
- [Deal with out-of-band changes](https://docs.formae.io/documentation/guides/deal-with-out-of-band-changes.md): Someone changed your infrastructure outside formae. See how formae detects the drift on the next reconcile, then absorb the change into your code or discard it.
- [Everyday changes](https://docs.formae.io/documentation/guides/everyday-changes.md): The routine operations once your infrastructure is under formae management: inspect it, change it surgically, and tear it down.
- [Explore your infrastructure](https://docs.formae.io/documentation/guides/explore-your-infrastructure.md): See what already exists in your infrastructure with formae, without changing anything.
- [Extend the agent image](https://docs.formae.io/documentation/guides/extend-the-agent-image.md): Build a derived agent image that layers extra plugins on top of the base formae image, then deploy it wherever you run the agent.
- [Incidents and recovery](https://docs.formae.io/documentation/guides/incidents-and-recovery.md): Fix a live infrastructure incident fast with a patch and settle up afterwards, and deal with a formae command that is itself the problem.
- [Install and run the agent](https://docs.formae.io/documentation/guides/install-agent.md): Stand up a production formae agent on AWS with the formae-bootstrap installer, then connect your CLI to it.
- [Install and run the agent on Azure](https://docs.formae.io/documentation/guides/install-agent-azure.md): Stand up a production formae agent on Azure with the formae-bootstrap installer, then connect your CLI to it.
- [Install the agent with Docker](https://docs.formae.io/documentation/guides/install-agent-docker.md): Run the formae agent as a container from the published image, for local evaluation or a self-managed host.
- [Install and run the agent on GCP](https://docs.formae.io/documentation/guides/install-agent-gcp.md): Stand up a production formae agent on GCP with the formae-bootstrap installer, then connect your CLI to it.
- [Install the agent with Helm](https://docs.formae.io/documentation/guides/install-agent-helm.md): Deploy the formae agent to a Kubernetes cluster with the formae Helm chart.
- [Manage profiles](https://docs.formae.io/documentation/guides/manage-profiles.md): Switch the formae CLI between environments with named configuration profiles.
- [Observe the agent](https://docs.formae.io/documentation/guides/observe-the-agent.md): Export the formae agent's metrics, logs, and traces through OpenTelemetry, or scrape them from a Prometheus endpoint.
- [Set up Pkl in your editor](https://docs.formae.io/documentation/guides/pkl-ide-support.md): Install the Pkl language server and editor support so writing formae is type-checked and autocompleted.
- [Manage stack policies](https://docs.formae.io/documentation/guides/policies.md): Attach a lifecycle policy to a stack: expire it after a duration with TTL, or keep it pinned to its declared state with auto-reconcile. Attach one inline, or define it once and reuse it across stacks.
- [Rename a resource](https://docs.formae.io/documentation/guides/rename-a-resource.md): Change a managed resource's label without recreating the cloud object, using alias.
- [Reuse infrastructure with modules](https://docs.formae.io/documentation/guides/reuse-with-modules.md): Structure formae code into Pkl modules and classes so you share configuration, compose resources, and write a pattern once instead of copying it across formae.
- [Read tfvars in a forma](https://docs.formae.io/documentation/guides/tfvars.md): Reuse existing Terraform and OpenTofu .tfvars files inside a forma, so one set of inputs drives both tools during a migration.
- [Troubleshoot a failed command](https://docs.formae.io/documentation/guides/troubleshoot-a-failed-command.md): Diagnose a failed apply or destroy with the detailed status layout: find the resource that broke and read its provider error.
- [formae documentation](https://docs.formae.io/documentation/index.md): Manage live infrastructure as code with precise, granular changes and minimal blast radius.
- [CLI reference](https://docs.formae.io/documentation/reference/cli.md): Reference for the formae command-line interface: global flags, the command index, and links to every command.
- [formae agent](https://docs.formae.io/documentation/reference/cli/agent.md): Start and stop the formae agent. Reference for formae agent and its subcommands.
- [formae apply](https://docs.formae.io/documentation/reference/cli/apply.md): Create or update infrastructure from a forma file. Reference for formae apply, its flags, and its required apply mode.
- [formae cancel](https://docs.formae.io/documentation/reference/cli/cancel.md): Cancel in-progress commands. Reference for formae cancel and its flags.
- [formae clean](https://docs.formae.io/documentation/reference/cli/clean.md): Clean up old formae software versions. Reference for formae clean and its flags.
- [formae destroy](https://docs.formae.io/documentation/reference/cli/destroy.md): Tear down resources from a forma file or a query. Reference for formae destroy and its flags.
- [formae eval](https://docs.formae.io/documentation/reference/cli/eval.md): Evaluate a forma and print the resolved result without applying it. Reference for formae eval and its flags.
- [formae extract](https://docs.formae.io/documentation/reference/cli/extract.md): Pull existing resources into a forma file. Reference for formae extract and its flags.
- [formae inventory](https://docs.formae.io/documentation/reference/cli/inventory.md): List resources, stacks, targets, and policies that formae manages. Reference for formae inventory and its subcommands.
- [formae plugin](https://docs.formae.io/documentation/reference/cli/plugin.md): Search, install, update, and scaffold formae plugins. Reference for formae plugin and its subcommands.
- [formae profile](https://docs.formae.io/documentation/reference/cli/profile.md): Manage named formae configuration profiles. Reference for formae profile and its subcommands.
- [formae project](https://docs.formae.io/documentation/reference/cli/project.md): Scaffold a forma project. Reference for formae project and its subcommands.
- [formae status](https://docs.formae.io/documentation/reference/cli/status.md): Query the agent and past commands. Reference for formae status and its subcommands.
- [formae update](https://docs.formae.io/documentation/reference/cli/update.md): Manage the formae binary version. Reference for formae update and its subcommands.
- [Configuration](https://docs.formae.io/documentation/reference/configuration.md): Complete reference for the formae Pkl configuration file: server, datastore, discovery, synchronization, logging, telemetry, plugins, and artifacts.
- [Pkl cheatsheet](https://docs.formae.io/documentation/reference/pkl-cheatsheet.md): Quick reference for Pkl syntax: comments, types, control flow, functions, and the standard library.
- [Plugin catalog](https://docs.formae.io/documentation/reference/plugin-catalog.md): Where to find every formae plugin, and which ones are documented here.
- [AWS configuration](https://docs.formae.io/documentation/reference/providers/aws/configuration.md): Configure an AWS target for formae: credentials and target settings.
- [A self-service database](https://docs.formae.io/documentation/reference/providers/aws/patterns/a-self-service-database.md): An AWS infrastructure pattern, deployed with formae.
- [Base VPC networking](https://docs.formae.io/documentation/reference/providers/aws/patterns/base-vpc-networking.md): An AWS infrastructure pattern, deployed with formae.
- [Bookstore on EKS](https://docs.formae.io/documentation/reference/providers/aws/patterns/bookstore-on-eks.md): An AWS infrastructure pattern, deployed with formae.
- [CloudFront edge](https://docs.formae.io/documentation/reference/providers/aws/patterns/cloudfront-edge.md): An AWS infrastructure pattern, deployed with formae.
- [Deploy a Lambda](https://docs.formae.io/documentation/reference/providers/aws/patterns/deploy-a-lambda.md): An AWS infrastructure pattern, deployed with formae.
- [Deploy an ECS service](https://docs.formae.io/documentation/reference/providers/aws/patterns/deploy-an-ecs-service.md): An AWS infrastructure pattern, deployed with formae.
- [ML platform](https://docs.formae.io/documentation/reference/providers/aws/patterns/ml-platform.md): An AWS infrastructure pattern, deployed with formae.
- [Static website (S3 + CloudFront)](https://docs.formae.io/documentation/reference/providers/aws/patterns/static-website-s3-cloudfront.md): An AWS infrastructure pattern, deployed with formae.
- [AWS supported resources](https://docs.formae.io/documentation/reference/providers/aws/supported-resources.md): The resource types the formae AWS plugin supports.
- [Azure configuration](https://docs.formae.io/documentation/reference/providers/azure/configuration.md): Configure an Azure target for formae: credentials and target settings.
- [Deploy a virtual machine](https://docs.formae.io/documentation/reference/providers/azure/patterns/deploy-a-virtual-machine.md): An Azure infrastructure pattern, deployed with formae.
- [Deploy the bookstore on AKS](https://docs.formae.io/documentation/reference/providers/azure/patterns/deploy-the-bookstore-on-aks.md): An Azure infrastructure pattern, deployed with formae.
- [Lay down base networking](https://docs.formae.io/documentation/reference/providers/azure/patterns/lay-down-base-networking.md): An Azure infrastructure pattern, deployed with formae.
- [Provision an AKS cluster](https://docs.formae.io/documentation/reference/providers/azure/patterns/provision-an-aks-cluster.md): An Azure infrastructure pattern, deployed with formae.
- [Run a PostgreSQL database](https://docs.formae.io/documentation/reference/providers/azure/patterns/run-a-postgresql-database.md): An Azure infrastructure pattern, deployed with formae.
- [Azure supported resources](https://docs.formae.io/documentation/reference/providers/azure/supported-resources.md): The resource types the formae Azure plugin supports.
- [GCP configuration](https://docs.formae.io/documentation/reference/providers/gcp/configuration.md): Configure a GCP target for formae: credentials and target settings.
- [Deploy an HTTP(S) load balancer](https://docs.formae.io/documentation/reference/providers/gcp/patterns/deploy-an-https-load-balancer.md): A GCP infrastructure pattern, deployed with formae.
- [Deploy base VPC networking](https://docs.formae.io/documentation/reference/providers/gcp/patterns/deploy-base-vpc-networking.md): A GCP infrastructure pattern, deployed with formae.
- [Deploy the bookstore on GKE](https://docs.formae.io/documentation/reference/providers/gcp/patterns/deploy-the-bookstore-on-gke.md): A GCP infrastructure pattern, deployed with formae.
- [GCP supported resources](https://docs.formae.io/documentation/reference/providers/gcp/supported-resources.md): The resource types the formae GCP plugin supports.
- [Kubernetes configuration](https://docs.formae.io/documentation/reference/providers/kubernetes/configuration.md): Configure a Kubernetes target for formae: credentials and target settings.
- [Deploy a Crossplane control plane](https://docs.formae.io/documentation/reference/providers/kubernetes/patterns/deploy-a-crossplane-control-plane.md): A Kubernetes infrastructure pattern, deployed with formae.
- [Deploy a Helm chart](https://docs.formae.io/documentation/reference/providers/kubernetes/patterns/deploy-a-helm-chart.md): Manage a Helm release as formae resources: reference a chart by name and version, set values inline, and apply it alongside your other Kubernetes resources.
- [Deploy the bookstore webapp](https://docs.formae.io/documentation/reference/providers/kubernetes/patterns/deploy-the-bookstore-webapp.md): A Kubernetes infrastructure pattern, deployed with formae.
- [Deploy the LGTM observability stack](https://docs.formae.io/documentation/reference/providers/kubernetes/patterns/deploy-the-lgtm-observability-stack.md): A Kubernetes infrastructure pattern, deployed with formae.
- [Kubernetes supported resources](https://docs.formae.io/documentation/reference/providers/kubernetes/supported-resources.md): The resource types the formae Kubernetes plugin supports.
- [OCI configuration](https://docs.formae.io/documentation/reference/providers/oci/configuration.md): Configure an OCI target for formae: credentials and target settings.
- [Deploy an OKE Kubernetes cluster](https://docs.formae.io/documentation/reference/providers/oci/patterns/deploy-an-oke-kubernetes-cluster.md): An OCI infrastructure pattern, deployed with formae.
- [Deploy base VCN networking](https://docs.formae.io/documentation/reference/providers/oci/patterns/deploy-base-vcn-networking.md): An OCI infrastructure pattern, deployed with formae.
- [OCI supported resources](https://docs.formae.io/documentation/reference/providers/oci/supported-resources.md): The resource types the formae OCI plugin supports.
- [Release notes](https://docs.formae.io/documentation/reference/release-notes.md): What changed in each formae release: new features, breaking changes, and bug fixes.
- [Security and networking](https://docs.formae.io/documentation/reference/security-and-networking.md): Reference for securing and reaching the formae agent: HTTP Basic Authentication, TLS, Tailscale networking, and the default API port.
- [CLI themes](https://docs.formae.io/documentation/reference/themes.md): Select a built-in CLI theme, choose a light or dark appearance, and author your own theme as a TOML file.
- [API schema versioning](https://docs.formae.io/plugin-development/concepts/api-versioning.md): Ship per-version schema subtrees and an ApiVersion Config field so formae narrows extract to the API version a target speaks.
- [Collection semantics](https://docs.formae.io/plugin-development/concepts/collection-semantics.md): How updateMethod and indexField control the way formae compares collection properties during apply.
- [Discovery filters](https://docs.formae.io/plugin-development/concepts/discovery-filters.md): Return MatchFilters from your plugin to keep resources that are managed by other resources out of formae's inventory.
- [Embedded types](https://docs.formae.io/plugin-development/concepts/embedded-types.md): Model nested resource properties with plain classes or SubResources, and know when each is the right choice.
- [Parent-child resources](https://docs.formae.io/plugin-development/concepts/parent-child-resources.md): Declare parent-child relationships so formae can discover resources in the right order and inject references automatically.
- [Resolvables](https://docs.formae.io/plugin-development/concepts/resolvables.md): Declare which resource properties other resources can reference, and let formae resolve them at apply time.
- [Publish a plugin](https://docs.formae.io/plugin-development/guides/publish-a-plugin.md): Register a plugin on the formae hub from its GitHub repository, install the hub's GitHub App, and confirm the details read from your manifest.
- [Register an organization](https://docs.formae.io/plugin-development/guides/register-your-org.md): Create an organization on the formae hub and verify the domain your plugins publish under.
- [Release a version](https://docs.formae.io/plugin-development/guides/release-a-version.md): Publish a plugin version by pushing a git tag, and pull a bad release with yank.
- [Scaffold a new plugin](https://docs.formae.io/plugin-development/guides/scaffold-a-plugin.md): Start a new formae plugin from the template, either with formae plugin init or by asking an AI assistant to build one for your technology.
- [Test a plugin locally](https://docs.formae.io/plugin-development/guides/test-a-plugin-locally.md): Install a plugin into a local formae agent and drive it end to end with local schema references, before publishing to the hub.
- [Troubleshoot a build](https://docs.formae.io/plugin-development/guides/troubleshoot-a-build.md): Read a failed plugin build on the hub, re-push a tag to fix it, and understand why a published tag is fixed.
- [Version a plugin's schema](https://docs.formae.io/plugin-development/guides/version-a-plugin-schema.md): Ship per-version schema subtrees, an apiVersion Config field, and a runtime resolver so formae narrows extract to the API version each target speaks.
- [Overview](https://docs.formae.io/plugin-development/index.md): Build plugins that let formae manage any infrastructure with an API, using the Go plugin SDK.
- [Manifest format](https://docs.formae.io/plugin-development/reference/manifest.md): The formae-plugin.pkl manifest fields that declare a plugin's identity, version, and requirements.
- [ResourcePlugin interface](https://docs.formae.io/plugin-development/reference/plugin-interface.md): Every method of the ResourcePlugin interface: parameters, return types, and behavioral contracts.
- [PKL schema reference](https://docs.formae.io/plugin-development/reference/schema.md): The full formae PKL schema a plugin author works with: resource and field annotations, relationship and ordering types, the value types you emit, and the schema module shape.
- [SDK release notes](https://docs.formae.io/plugin-development/release-notes.md): Release notes for the formae Plugin SDK packages: pkg/plugin, the conformance-test framework, and the plugin template.
- [01 - Project scaffold](https://docs.formae.io/plugin-development/tutorial/01-scaffold.md): Scaffold a new formae plugin project with formae plugin init and tour the generated files.
- [02 - Resource schema](https://docs.formae.io/plugin-development/tutorial/02-schema.md): Define the File resource type in PKL with ResourceHint and FieldHint annotations, and validate it.
- [03 - Target configuration](https://docs.formae.io/plugin-development/tutorial/03-target.md): Learn how a plugin receives target configuration, keep secrets out of targets, and parse the SFTP server URL.
- [04 - Plugin configuration](https://docs.formae.io/plugin-development/tutorial/04-configuration.md): Implement the RateLimit and LabelConfig methods every plugin needs, and see where DiscoveryFilters fits.
- [05 - Create](https://docs.formae.io/plugin-development/tutorial/05-create.md): Implement the async Create method and its Status polling companion, driven by an integration test.
- [06 - Read](https://docs.formae.io/plugin-development/tutorial/06-read.md): Implement the synchronous Read method and the NotFound semantics that let formae detect out-of-band deletions.
- [07 - Update](https://docs.formae.io/plugin-development/tutorial/07-update.md): Implement the synchronous Update method, comparing prior and desired state to apply minimal changes.
- [08 - Delete](https://docs.formae.io/plugin-development/tutorial/08-delete.md): Implement the synchronous Delete method, including idempotent NotFound handling for missing resources.
- [09 - List](https://docs.formae.io/plugin-development/tutorial/09-list.md): Implement the List method to enable discovery of unmanaged resources, with pagination and non-discoverable types.
- [10 - Error handling](https://docs.formae.io/plugin-development/tutorial/10-error-handling.md): A deep dive into OperationErrorCode, recoverable versus non-recoverable errors, and mapping infrastructure errors.
- [11 - Conformance tests](https://docs.formae.io/plugin-development/tutorial/11-conformance.md): Verify your plugin behaves correctly when orchestrated by the formae agent by running the conformance test suite against the full resource lifecycle.
- [12 - CI Setup](https://docs.formae.io/plugin-development/tutorial/12-ci-setup.md): Enable the plugin template's GitHub Actions workflow so build, lint, integration, and conformance tests run on every push and pull request.
- [13 - Local Testing](https://docs.formae.io/plugin-development/tutorial/13-local-testing.md): Install your plugin locally and run it end-to-end with the formae CLI: init a test project with @local resolution, apply a forma, verify, and clean up.
- [14 - Observability](https://docs.formae.io/plugin-development/tutorial/14-observability.md): Instrument your plugin with the SDK's structured logger and metric registry, pulled from the request context, for debugging and monitoring through the formae agent.
- [15 - Real-world plugins](https://docs.formae.io/plugin-development/tutorial/15-real-world-plugins.md): Wrap up the tutorial: the finished SFTP plugin, production plugins to study, and where to go next with the concepts and reference guides.
- [Build an SFTP plugin](https://docs.formae.io/plugin-development/tutorial/index.md): Tutorial: build a complete formae plugin that manages files on an SFTP server, from scaffold to conformance tests.