plugin command

Manage formae plugins.

Usage

formae plugin [OPTIONS] [COMMAND]

Commands

Command	Description
`list`	List installed plugins
`search`	Search the catalog of available plugins
`info`	Show detailed information about a plugin
`install`	Install one or more plugins
`uninstall`	Remove one or more plugins (alias: `remove`)
`update`	Update installed plugins
`init`	Scaffold a new plugin from the template

Where plugins are installed. formae plugin install, uninstall, and update run locally. /opt/pel is root-owned and the agent runs as the pel user, so the install commands typically need sudo. Resource plugins (e.g. aws, gcp, azure) must therefore be installed on the host that runs the agent. Auth plugins (e.g. auth-basic) run on both the agent and the CLI, so they must be installed on each host that runs either — same command, run twice. See Resource vs auth plugins below.

list

Lists plugins installed on the agent and on locally. Each row is annotated with where the plugin lives so dual-install drift on auth plugins is visible at a glance.

Usage

formae plugin list

Example output

Resource plugins:
  ✓ aws            0.1.5  (agent + cli)
  ✓ azure          0.1.2  (agent + cli)
  ✓ grafana        0.1.2  (agent)

Auth plugins:
  ✓ auth-basic     0.1.0  (agent + cli)
  ⚠ auth-oidc      agent 0.5.0 / cli 0.4.1  version mismatch

The annotations:

Tag	Meaning
`(agent + cli)`	Same plugin at the same version on both sides
`(agent)`	Only installed on the agent host
`(cli)`	Only installed on the local CLI host
`version mismatch`	Installed on both sides but versions differ — typically auth-plugin drift

If the CLI cannot reach the agent (or the agent is offline), list falls back to showing only the local view.

search

Search for available plugins. Without a query, all available plugins are listed.

Usage

formae plugin search [<query>] [--category <c>] [--type resource|auth] [--channel <c>]

Flags

Flag	Description
`--category`	Filter by category (e.g. `cloud`, `auth`, `observability`)
`--type`	Filter by plugin type: `resource` or `auth`
`--channel`	Search a non-default channel (e.g. `dev`)

Examples

# All available plugins
formae plugin search

# All AWS-related plugins
formae plugin search aws

# All auth plugins on the dev channel
formae plugin search --type auth --channel dev

Example output

  aws             AWS resources via CloudControl  ✓ installed
  azure           Azure Resource Manager resources
  gcp             Google Cloud Platform resources
  oci             Oracle Cloud Infrastructure
  ovh             OVHCloud
  auth-basic      HTTP Basic auth between CLI and agent

The ✓ installed marker shows plugins already present on the agent.

info

Show detailed information about a single plugin: type, namespace, category, summary, publisher, and the latest available + currently installed versions.

Usage

formae plugin info <name>

Example output

aws 0.1.5 (installed)
  Type:          resource
  Namespace:     AWS
  Category:      cloud
  Summary:       AWS resources via CloudControl
  Publisher:     platform.engineering

install

Install one or more plugins into the local /opt/pel tree on the host where you run the command. Use name to install the latest version, or name@version to pin.

formae plugin install does not call the agent. Because /opt/pel is root-owned, the install commands typically need sudo, so you'll see a sudo prompt unless you've already invoked sudo formae plugin install.

Usage

sudo formae plugin install <name>[@<version>]...

Examples

# Latest stable
sudo formae plugin install aws

# Pin a specific version
sudo formae plugin install azure@0.1.2

# Several at once (mix of pinned and latest)
sudo formae plugin install aws@0.1.5 grafana sftp

Where to run it

Plugin type	Where to install	Restart
Resource (e.g. `aws`)	On the agent host	Restart the agent to load the new plugin
Auth (e.g. `auth-basic`)	On every host that runs the CLI or the agent	Restart the agent on the agent host

For auth plugins, run the same command twice — once on each host. There is no automatic dual install in 0.85; the CLI installs only on the host it runs on. Container deployments are the natural single-step case: the Dockerfile's RUN ops install … (or RUN formae plugin install …) line bakes the plugins into the image, so the running container is immutable and no extra step is needed at start time.

After every successful install the command prints:

  ! If this host runs the formae agent, restart it to load the new plugins: formae agent restart

Re-running

install is idempotent — re-running it for an already-installed package at the same version is a no-op. If the install fails partway through (e.g., a network blip during the sudo re-exec), simply re-run the same command.

uninstall

Remove plugins from the local /opt/pel tree. remove is an alias.

Usage

sudo formae plugin uninstall <name>...
sudo formae plugin remove <name>...

Example

sudo formae plugin uninstall grafana sftp
sudo formae plugin uninstall auth-basic

Like install, this command is local-only — run it on every host where the plugin is installed (both the agent host and each CLI host for auth plugins). Restart the agent on the agent host afterwards so it stops loading the removed plugin.

update

Update installed plugins to the latest available version (in the channel they were installed from). With no arguments, every installed plugin is considered for update.

Usage

# Upgrade everything
sudo formae plugin update

# Upgrade specific plugins
sudo formae plugin update aws azure

# Pin to a specific update target
sudo formae plugin update aws@0.1.6

Like install, update is local-only. For auth plugins, run it on each host the plugin lives on. Restart the agent on the agent host to load the updated binaries.

Resource vs auth plugins

formae has two plugin shapes, distinguished by the type field in their manifest:

Type	Runs in	Installed on	Examples
`resource`	Agent process	Agent host	`aws`, `azure`, `gcp`, `oci`, `ovh`, `compose`, `grafana`, `sftp`
`auth`	Agent and CLI	Agent host and CLI host	`auth-basic`

Resource plugins talk to cloud APIs to create, read, update, delete, and discover infrastructure. They only need to be on the agent because that's where the orchestration happens.

Auth plugins are different — they participate in every CLI ⇄ agent exchange. The CLI runs the auth plugin to construct an authentication header; the agent runs the same plugin to verify it. That means the same auth plugin must be present on both sides, at the same version.

In 0.85, the install, uninstall, and update commands act on the host they run on — there is no automatic dual install. For auth plugins, run the same command on each host where the plugin needs to live. On a single-host deployment that's one host; with separate CLI and agent hosts it's two. formae plugin list shows agent and CLI views together with version-mismatch warnings, so drift is easy to spot. A future release will restore the single-command "install everywhere it needs to live" UX.

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: