Skip to main content
The plugin manifest (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 named formae-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
Examples:

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
Resource types follow the pattern 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:
  1. Plugin init - formae plugin init validates input before scaffolding
  2. Build - make build reads the manifest to determine output names
  3. Install - make install copies the manifest to the installation directory
  4. Agent startup - The agent validates manifests when discovering plugins

Validation rules

See also