formae-plugin.pkl) declares your plugin’s identity, version, and requirements. The formae agent reads this file when discovering and loading plugins.
Location
The manifest must be namedformae-plugin.pkl and placed in the root of your plugin directory:
Format
The manifest is a PKL file with the following structure:Fields
name
Type:String
Required: Yes
Plugin identifier used in file names and references. Must be:
- Lowercase
- Start with a letter
- Contain only letters, numbers, and hyphens
version
Type:String
Required: Yes
Semantic version following SemVer format.
Examples:
namespace
Type:String
Required: Yes
Prefix for all resource types managed by this plugin. Must be:
- Uppercase
- Start with a letter
- Contain only letters and numbers
NAMESPACE::SERVICE::RESOURCE.
Examples:
description
Type:String
Required: Yes
Human-readable description of what the plugin does.
Example:
category
Type:String
Required: Yes
Hub catalog category for your plugin. It must be one of a closed set of values, mirroring the category allowlist the formae Hub accepts:
cloud, auth, config, observability, cicd, network, data, security, containers, other
formae plugin init prompts for this value in interactive mode and defaults it to other when run with --no-input. Pick the category that best describes what your plugin manages.
Example:
license
Type:String
Required: Yes
SPDX license identifier for your plugin.
Common values:
Example:
minFormaeVersion
Type:String
Required: Yes (managed automatically)
Minimum formae version required to run this plugin. The agent will refuse to load plugins that require a newer version.
You do not need to maintain this value by hand. The make build target in the plugin template reads the MinFormaeVersion constant exported by the SDK (pkg/plugin) and rewrites this field in the manifest before packaging the plugin. Bumping your SDK dependency with go get automatically raises minFormaeVersion on the next build.
Example:
output
Type:Object
Required: Yes
Output configuration for PKL evaluation.
Example:
Complete example
Validation
The manifest is validated when:- Plugin init -
formae plugin initvalidates input before scaffolding - Build -
make buildreads the manifest to determine output names - Install -
make installcopies the manifest to the installation directory - Agent startup - The agent validates manifests when discovering plugins
Validation rules
See also
- Tutorial: Scaffold - Creating a plugin with
formae plugin init

