> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formae.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manifest format

> The formae-plugin.pkl manifest fields that declare a plugin's identity, version, and requirements.

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:

```
my-plugin/
├── formae-plugin.pkl    # Manifest (required)
├── main.go
├── plugin.go
└── schema/pkl/
```

## Format

The manifest is a PKL file with the following structure:

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
// Plugin identifier (required)
name = "mycloud"

// Semantic version (required)
version = "1.0.0"

// Resource type namespace (required)
namespace = "MYCLOUD"

// Human-readable description (required)
description = "MyCloud provider plugin for formae"

// Hub catalog category (required)
category = "cloud"

// SPDX license identifier (required)
license = "Apache-2.0"

// Minimum formae version required
// (auto-managed by `make build` from the SDK constant)
minFormaeVersion = "0.84.0"

// Output configuration (required)
output {
  renderer = new JsonRenderer {}
}
```

## 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:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
name = "aws"
name = "my-cloud"
name = "openstack-v2"
```

***

### version

**Type:** `String`
**Required:** Yes

Semantic version following [SemVer](https://semver.org/) format.

**Examples:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
version = "1.0.0"
version = "0.1.0-beta"
```

***

### 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:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
namespace = "AWS"       // Resources: AWS::EC2::Instance, AWS::S3::Bucket
namespace = "AZURE"     // Resources: AZURE::Compute::VM
namespace = "MYCLOUD"   // Resources: MYCLOUD::Storage::Item
```

***

### description

**Type:** `String`
**Required:** Yes

Human-readable description of what the plugin does.

**Example:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
description = "Amazon Web Services (AWS) provider plugin for formae"
```

***

### 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:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
category = "cloud"
```

***

### license

**Type:** `String`
**Required:** Yes

[SPDX license identifier](https://spdx.org/licenses/) for your plugin.

**Common values:**

| License                    | SPDX ID        |
| -------------------------- | -------------- |
| Apache License 2.0         | `Apache-2.0`   |
| MIT License                | `MIT`          |
| Mozilla Public License 2.0 | `MPL-2.0`      |
| Functional Source License  | `FSL-1.1-ALv2` |

**Example:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
license = "Apache-2.0"
```

***

### 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](https://github.com/platform-engineering-labs/formae-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:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
minFormaeVersion = "0.84.0"   // rewritten by `make build` from SDK.MinFormaeVersion
```

***

### output

**Type:** `Object`
**Required:** Yes

Output configuration for PKL evaluation.

**Example:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
output {
  renderer = new JsonRenderer {}
}
```

***

## Complete example

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
/*
 * formae Plugin Manifest
 *
 * MyCloud provider plugin for managing cloud resources.
 */

name = "mycloud"
version = "1.2.0"
namespace = "MYCLOUD"
description = "MyCloud infrastructure provider for formae"
category = "cloud"
license = "Apache-2.0"
minFormaeVersion = "0.84.0"   // auto-managed by `make build`

output {
  renderer = new JsonRenderer {}
}
```

## 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

| Field              | Rule                                  |
| ------------------ | ------------------------------------- |
| `name`             | Matches pattern `^[a-z][a-z0-9-]*$`   |
| `version`          | Valid semantic version                |
| `namespace`        | Matches pattern `^[A-Z][A-Za-z0-9]*$` |
| `category`         | One of the closed category values     |
| `minFormaeVersion` | Valid semantic version                |

## See also

* [Tutorial: Scaffold](/plugin-development/tutorial/01-scaffold) - Creating a plugin with `formae plugin init`