plugin command

This command can be used to work with the plugin system.

Usage

formae plugin [OPTIONS] [COMMAND]

Commands

Command Description
list List all active plugins
init Initialize a new plugin from template

list

Lists all active plugins currently loaded by the formae agent.

Usage

formae plugin list

Output

aws 0.80.0 resource
pkl 0.80.0 schema

Each line shows: plugin name, version, and type (resource, schema, or network).

init

Initialize a new formae plugin project from the official template. This command can run interactively (prompting for values) or non-interactively using command-line flags.

Usage

# Interactive mode (default)
formae plugin init

# Non-interactive mode
formae plugin init --name <name> --namespace <ns> --description <desc> \
  --author <author> --module-path <path> [--license <license>] [--output-dir <dir>] --no-input

Flags

Flag Required Description
--name Yes* Plugin name (lowercase, letters/numbers/hyphens)
--namespace Yes* Target technology namespace (e.g., AWS, GCP)
--description Yes* Brief description of the plugin
--author Yes* Plugin author for license copyright
--module-path Yes* Go module path (e.g., github.com/your-org/formae-plugin-foo)
--license No SPDX license identifier (default: Apache-2.0)
--output-dir No Target directory (default: ./<name>)
--no-input No Disable interactive prompts; requires all flags marked with *

Interactive Prompts

When running without --no-input, the command prompts for:

Prompt Required Description
Plugin name Yes Lowercase identifier (letters, numbers, hyphens)
Namespace Yes Resource type prefix (e.g., AWS, MYCLOUD)
Description Yes Brief description of the plugin
Author Yes Your name or organization (used in license)
Module path Yes Go module path for imports (e.g., github.com/your-org/formae-plugin-foo)
License No SPDX license identifier (default: Apache-2.0)
Output directory No Where to create the project (default: ./<name>)

If flags are provided, those values are used and only missing values are prompted.

Examples

Interactive mode:

$ formae plugin init
Formae Plugin Initialization

Plugin name: mycloud
Namespace: MYCLOUD
Description: MyCloud provider plugin
Author: Acme Corp
Module path: github.com/acme-corp/formae-plugin-mycloud
License [Apache-2.0]:
Output directory [./mycloud]:

Downloading template from GitHub...
Initializing plugin 'mycloud' from template...

Done! Next steps:
  1. cd mycloud
  2. Define your resources in schema/pkl/
  3. Implement ResourcePlugin interface in mycloud.go
  4. Run 'make build' to build the plugin

Non-interactive mode (for automation/CI):

formae plugin init \
  --name mycloud \
  --namespace MYCLOUD \
  --description "MyCloud provider plugin" \
  --author "Acme Corp" \
  --module-path github.com/acme-corp/formae-plugin-mycloud \
  --license MIT \
  --output-dir ./plugins/mycloud \
  --no-input

Partial flags (prompts for missing values):

# Provides name and namespace, prompts for the rest
formae plugin init --name mycloud --namespace MYCLOUD

Generated Project Structure

mycloud/
├── formae-plugin.pkl      # Plugin manifest
├── mycloud.go             # ResourcePlugin implementation
├── main.go                # Entry point
├── schema/pkl/
│   ├── PklProject
│   └── mycloud.pkl        # Resource schemas
├── conformance_test.go    # Conformance tests
├── scripts/ci/            # CI hooks
├── go.mod
└── Makefile

Validation Rules

Plugin name:

  • Must start with a letter
  • Can only contain letters, numbers, and hyphens

Namespace:

  • Must start with a letter
  • Can only contain letters and numbers

Next Steps

After running formae plugin init, see the Plugin SDK documentation for guidance on: