CLI reference

flowly plugins commands

Complete reference for the flowly plugins CLI subcommand. All commands run synchronously and exit with code 0 on success, non-zero on failure.

flowly plugins list

List all discovered plugins with their version, source, status, and description.

bash

flowly plugins list

Sample output:

text

                              Plugins
┏━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Key          ┃ Version ┃ Source  ┃ Status  ┃ Description         ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ auto-commit  │ 1.0.0   │ user    │ enabled │ Automatically...    │
│ disk-cleanup │ 1.0.0   │ bundled │ enabled │ Auto-track and...   │
└──────────────┴─────────┴─────────┴─────────┴─────────────────────┘

Status values:

enabled — plugin loaded successfully on the last gateway start
available — discovered but not in plugins.enabled; needs flowly plugins enable
disabled — explicitly listed in plugins.disabled
error — manifest parsed but register(ctx) raised; check gateway logs

Source values:

bundled — ships with Flowly (flowly/plugins_bundled/)
user — installed at $FLOWLY_HOME/plugins/
project — discovered at ./.flowly/plugins/ (only when FLOWLY_ENABLE_PROJECT_PLUGINS=1)

flowly plugins install

Install a plugin from a Git URL, owner/repo shorthand, or local path.

bash

flowly plugins install <source> [--enable | --no-enable] [--force]

Sources:

GitHub shorthand — owner/repo, resolved to https://github.com/owner/repo.git
Full Git URL — https://gitlab.com/..., git@github.com:..., ssh://git@...
Local directory — absolute or ~-relative path. Copied into $FLOWLY_HOME/plugins/.

Flags:

--enable (default on) — add to plugins.enabled after install. Pass --no-enable to skip.
--force, -f — overwrite if a plugin with this manifest name already exists. Without it, install fails fast.

Examples:

bash

# GitHub shorthand, auto-enable
flowly plugins install nocetic/flowly-weather

# Private repo via SSH, install only (don't enable yet)
flowly plugins install git@github.com:acme/internal-plugin.git --no-enable

# Local development copy, force-overwrite
flowly plugins install /Users/me/code/my-plugin --force

The plugin's install path comes from its manifest name, not the source. So flowly plugins install /tmp/build lands at $FLOWLY_HOME/plugins/<manifest.name>/, regardless of the source path.

flowly plugins enable

Add a plugin to the plugins.enabled allowlist.

bash

flowly plugins enable <name>

The name comes from the manifest. Use the same name shown in flowly plugins list.

Restart required

Plugin discovery only runs at gateway startup. Run flowly service restart (or quit and reopen the desktop app) for the change to take effect.

flowly plugins disable

Add a plugin to the plugins.disabled list.

bash

flowly plugins disable <name>

The disabled list takes precedence over enabled. Disabling a bundled plugin is the only way to opt out of the default-on plugins.

Disable doesn't delete files. Run flowly plugins remove to actually uninstall.

flowly plugins remove

Uninstall a plugin — deletes its directory under $FLOWLY_HOME/plugins/.

bash

flowly plugins remove <name> [--yes]

Flags:

--yes, -y — skip confirmation prompt. Useful in scripts.

The plugin is also removed from plugins.enabled and plugins.disabled automatically.

Bundled plugins (flowly/plugins_bundled/) can't be removed via this command — they live inside the package. Use flowly plugins disable instead.

config.json structure

The CLI reads and writes the plugins key in $FLOWLY_HOME/config.json. Schema:

json

{
  "plugins": {
    "enabled": [
      "auto-commit",
      "weather"
    ],
    "disabled": [
      "some-plugin-i-dont-like"
    ]
  }
}

You can edit this file directly — but the CLI is safer (atomic writes, deduplication, validation). External edits take effect on the next gateway start.

Plugin-specific settings

Don't put plugin-specific config in this file. Each plugin owns its own $FLOWLY_HOME/<plugin-name>/config.json — see Configuration.