fledge-example-plugin

Example plugins for fledge, the dev-lifecycle CLI. Use these as starting points for building your own community extensions.

What are fledge plugins?

Plugins extend fledge with new commands, lane steps, and template post-processors. A plugin is a git repository containing:

1. A plugin.toml manifest describing the plugin
2. One or more executable scripts or binaries that implement the commands

Once installed, plugin commands appear alongside built-in fledge commands.

Plugin manifest format

Every plugin needs a plugin.toml at its root:

[plugin]
name = "fledge-myplugin"
version = "0.1.0"
description = "What this plugin does"
author = "your-github-handle"

[[commands]]
name = "mycommand"
description = "What the command does"
binary = "bin/fledge-mycommand"   # path relative to the plugin directory

[hooks]
post_install = "hooks/post-install.sh"   # optional — runs after install
post_remove  = "hooks/post-remove.sh"    # optional — runs after remove

Key fields

Field	Required	Description
plugin.name	yes	Must start with fledge-
plugin.version	yes	Semver version string
plugin.description	yes	One-line summary
plugin.author	yes	GitHub username or org
commands[].name	yes	The subcommand name (e.g. deploy becomes fledge deploy)
commands[].binary	yes	Path to the executable, relative to the plugin directory
hooks.post_install	no	Script to run after fledge plugin install
hooks.post_remove	no	Script to run after fledge plugin remove

Plugin discovery

Plugins are found through three mechanisms:

1. Installed plugins in ~/.config/fledge/plugins/
2. PATH lookup for executables named fledge-<name> (git-style)
3. GitHub topic search using the fledge-plugin topic (for fledge plugin search)

To make your plugin discoverable, add the fledge-plugin topic to your GitHub repository.

Plugin lifecycle

# Search for plugins
fledge plugin search docker

# Install from GitHub
fledge plugin install corvid-agent/fledge-example-plugin
# => clones to ~/.config/fledge/plugins/fledge-example-plugin/
# => symlinks binaries to ~/.config/fledge/plugins/bin/

# List installed plugins
fledge plugin list

# Use a plugin command
fledge docker-build --tag myapp:latest

# Remove a plugin
fledge plugin remove docker

Example plugins in this repo

docker/ — Docker build and push

Adds docker-build and docker-push commands for building and pushing container images. Demonstrates multi-command plugins and hook scripts.

fledge docker-build --tag myapp:latest --dockerfile Dockerfile
fledge docker-push --tag myapp:latest --registry ghcr.io

coverage/ — Test coverage reporting

Adds a coverage command that runs tests with coverage and reports results. Demonstrates single-command plugins with language auto-detection.

fledge coverage --format html --threshold 80

Creating your own plugin

1. Create a new repository named fledge-<name>
2. Add a plugin.toml manifest (see format above)
3. Create your command executables in a bin/ directory
4. Make them executable: chmod +x bin/*
5. Optionally add hooks/post-install.sh for setup tasks
6. Add the fledge-plugin topic to your GitHub repo
7. Test locally: fledge plugin install . (from the repo directory)

License

MIT