Distribution

Distributing your plugin

Once your plugin works locally, share it with others. Flowly accepts three install sources — local path, GitHub URL, owner/repo shorthand.

Installing plugins

The flowly plugins install command accepts three source forms.

GitHub shorthandrecommended

bash

flowly plugins install owner/repo
flowly plugins install nocetic/flowly-weather

Resolves to https://github.com/owner/repo.git and clones via git clone --depth 1. The quickest way to install from a public repo.

Full git URL

bash

flowly plugins install https://gitlab.com/team/internal-plugin.git
flowly plugins install git@github.com:owner/repo.git

Use this for non-GitHub hosts, private repos accessible via SSH, or self-hosted git servers.

Local directory

bash

flowly plugins install /Users/me/code/my-plugin
flowly plugins install ~/Desktop/dev-plugin

Copies the directory into ~/.flowly/plugins/. Best for development before pushing to a remote.

The plugin's name comes from its manifest, not the source path — so flowly plugins install /tmp/build lands at ~/.flowly/plugins/<manifest.name>/.

Managing plugins

Installation copies files but doesn't activate the plugin. User-installed plugins are opt-in — you must enable them explicitly:

bash

flowly plugins enable my-plugin     # add to plugins.enabled
flowly plugins disable my-plugin    # add to plugins.disabled
flowly plugins list                 # see all discovered plugins + status
flowly plugins remove my-plugin     # uninstall (delete from disk)

Configuration lives in ~/.flowly/config.json under the plugins key.

json

{
  "plugins": {
    "enabled": ["my-plugin", "auto-commit"],
    "disabled": []
  }
}

The --enable flag (default on for install) auto-enables after install. Pass --no-enable to install without activating.

Restart required

Plugin discovery runs at gateway startup. enable / disable take effect on the next restart of the agent or gateway service.

Publishing on GitHub

The simplest way to share a plugin is a public GitHub repository. Flowly clones the default branch, so your manifest and code must live at the repo root.

Create the repo. Use kebab-case naming convention: flowly-<your-plugin>.

Repo root layout:

text

flowly-weather/
├── plugin.yaml
├── __init__.py
├── README.md
└── LICENSE

Add a clear README. What it does, what env vars it needs, what permissions it uses (which hooks/tools), how to uninstall.
Tag releases. Bump version in the manifest with each release. Use git tag v1.2.0.

Share the install command. Users run:

bash

flowly plugins install nocetic/flowly-weather

Versioning

Plugins follow semver. Bump the version in plugin.yaml on every release.

The manifest_version field declares which Flowly plugin schema your plugin targets. Today's value is 1. If we ever introduce breaking schema changes, your plugin keeps working — Flowly only loads manifests at or below the version it knows.

yaml

# plugin.yaml — declare your plugin's compatibility surface
name: my-plugin
version: 1.4.2
manifest_version: 1

Security checklist

Plugins run as Python code with full filesystem and network access. Before you publish, check that:

No hardcoded secrets. API keys, tokens, passwords come from environment variables. Document required env vars in requires_env.
No silent network calls. If your plugin sends data anywhere, document the destination in the README.
No surprising filesystem access. Restrict writes to ~/.flowly/ or paths the user explicitly passes in.
Honest manifest. provides_tools and provides_hooks should list everything you register — they're the user's first line of trust.
Errors don't leak. Catch exceptions in handlers and return a clean error string. Never let unhandled errors crash the agent.