Plugin Development Guide#

This page is an overview. Detailed plugin development instructions are now part of each extension type’s development guide.

What is a Plugin?#

A plugin is a standalone executable that extends scafctl by communicating over gRPC using hashicorp/go-plugin . Plugins run in separate processes, providing crash isolation and independent distribution.

scafctl supports two types of plugins:

Architecture#

flowchart LR
  A["scafctl<br/>- Discovers plugin<br/>- Configures providers<br/>- Calls extensions<br/>- Manages lifecycle"] <-- "gRPC" --> B["Your Plugin<br/>- Implements gRPC<br/>- Exposes handlers<br/>- Handles execution<br/>- Calls HostService"]

Each plugin binary exposes one extension type (provider OR auth handler). The handshake cookie determines which type the host expects.

Plugin Lifecycle#

1. Discovery – scafctl finds the plugin binary (via catalog auto-fetch or directory scanning)
2. Load – scafctl starts the plugin process and negotiates protocol version
3. Configure – scafctl calls ConfigureProvider once per provider with host settings (quiet, color, binary name, HostService broker ID)
4. Execute – scafctl invokes providers as needed (unary or streaming)
5. Callbacks – plugins can call back to the host for secrets and auth tokens via the HostService gRPC service
6. Shutdown – scafctl terminates the plugin process when done

Plugin Discovery#

scafctl resolves plugins through two mechanisms:

1. Catalog Auto-Fetch (Recommended) — Declare plugins in bundle.plugins and scafctl fetches, caches, and loads them automatically:

   spec:
     bundle:
       plugins:
         - name: my-plugin
           kind: provider          # or "auth-handler"
           version: ">=1.0.0"

2. Directory Scanning — For local development, place plugin binaries in the plugin cache:

   mkdir -p "$(scafctl paths cache)/plugins"
   cp my-plugin "$(scafctl paths cache)/plugins/"

   $pluginDir = "$(scafctl paths cache)/plugins"
   New-Item -ItemType Directory -Force -Path $pluginDir
   Copy-Item my-plugin $pluginDir

Plugin CLI Commands#

# Pre-fetch plugins declared in a solution
scafctl plugins install -f my-solution.yaml

# List cached plugin binaries (remote download cache only)
scafctl plugins list

# Push to a remote registry
scafctl catalog push my-plugin@1.0.0 --catalog ghcr.io/myorg

# Pre-fetch plugins declared in a solution
scafctl plugins install -f my-solution.yaml

# List cached plugin binaries (remote download cache only)
scafctl plugins list

# Push to a remote registry
scafctl catalog push my-plugin@1.0.0 --catalog ghcr.io/myorg

Note: plugins list shows only plugins fetched from the remote catalog cache. Local builds loaded via --plugin-dir are not listed. To see all available versions (including pre-release), use: scafctl catalog list --kind provider --pre-release --all-versions

Next Steps#

• Extension Concepts – Provider vs Auth Handler vs Plugin terminology
• Provider Development Guide – Build providers (builtin + plugin)
• Auth Handler Development Guide – Build auth handlers (builtin + plugin)
• Plugin Auto-Fetching Tutorial – Catalog-based distribution and signature verification