Skip to content

Plugins Overview

Amadla uses plugins to extend core tools with external integrations. Each plugin is a standalone CLI executable that communicates via stdin/stdout/stderr following the Plugin Protocol.

Plugins can be written in any language — Go, Python, Bash, or anything that follows the protocol. Go framework libraries are available as optional convenience wrappers.

Plugin Categories

Category Host Tool Naming Count Active Planned/Stubs
Raise Plugins raise raise-* 10 3 7
Doorman Plugins doorman doorman-* 16 1 15
Judge Plugins judge judge-* 3 1 2
Weaver Plugins weaver weaver-* 4 0 4
Total 33 5 28

Naming Convention

Plugins use the <tool>-<name> pattern, where the prefix matches the host tool name:

  • doorman-vault — Doorman plugin for HashiCorp Vault
  • judge-application — Judge plugin for application validation
  • weaver-jinja — Weaver plugin for Jinja2 templates

Tools discover plugins by scanning $PATH for binaries matching their prefix.

Plugin Protocol Summary

Every plugin must implement:

<plugin> info              # JSON metadata (name, version, supported entities)
<plugin> <verb> [flags]    # Business logic

Standard I/O:

Channel Purpose
stdin Entity data (YAML or JSON, auto-detected)
stdout Result data (-o table|json|yaml)
stderr Diagnostics and errors
exit code 0 success, 1 failure, 2 usage error

See Plugin System Architecture for the full protocol specification.

Go Frameworks (Optional)

Framework For Provides
LibraryDoormanFramework Doorman plugins Secret-fetching boilerplate, output formatting
LibraryJudgeFramework Judge plugins Validation boilerplate, pass/fail reporting
— Weaver plugins No framework yet (direct protocol implementation)

These frameworks are convenience wrappers that reduce boilerplate for Go authors. They are not required — any language that implements the protocol works.

Development Status

Active plugins serve as reference implementations:

  • raise-libvirt — Reference Raise plugin (Go) — local KVM/QEMU VMs
  • raise-virtualbox — Raise plugin for VirtualBox (Go)
  • raise-wsl — Raise plugin for WSL2 (Go)
  • doorman-keepassxc — Reference Doorman plugin (Go)
  • judge-application — Reference Judge plugin (Go)

raise-xen is the next planned plugin — required for building the Amadla Linux distro.