Plugin CLI

python -m server plugin … — scaffold, install, and manage plugins from a shell. Generated from the argparse definition in graph/plugins/cli.py.

Two deliberate non-behaviors, because both are consent boundaries (ADR 0027): install does not enable a plugin, and install does not install its Python dependencies. Fetching code is not running it, so each step is a separate, explicit act — on the desktop app too, where the one exception is the explicit --install-runtime-deps opt-in unattended provisioning passes (required deps go into the app's managed Python runtime as part of the install).

Command	Purpose
new	scaffold a new plugin skeleton on disk (ready to fill in + enable)
new-bundle	scaffold a plugin BUNDLE (protoagent.bundle.yaml, ADR 0040)
install	install a plugin — or a bundle of plugins — from a git URL (does NOT enable it)
list	list git-installed plugins (from plugins.lock)
uninstall	remove a git-installed plugin (code + lock + enabled ref)
update-bundle	re-resolve a bundle's ref + reinstall members at the new pins (#2718; code+lock only — a running server picks the new code up on restart/reload)
uninstall-bundle	remove a bundle: its exclusively-owned members + the lock row (shared members stay)
sync	re-clone locked plugins at their pinned SHA (reproducible set)
install-deps	pip-install a plugin's declared requires_pip (explicit code-exec)

new

python -m server plugin new [-h] [--summary SUMMARY] [--view] [--skill] [--workflow] [--comms] [--tests] [--git] [--dir DIR] name

Scaffold a new plugin skeleton on disk (ready to fill in + enable).

Argument	Meaning
name	human name (the id is slugified from it, e.g. "My Plugin" -> my-plugin)
--summary	one-line description for the manifest (default 'A protoAgent plugin.')
--view	include a console view (sandboxed iframe + router)
--skill	include a SKILL.md skill stub
--workflow	include a workflow YAML stub
--comms	a communication plugin (ChatAdapter, ADR 0029) instead of a tool plugin
--tests	include a host-free test suite + CI + requirements-dev (for a standalone-repo plugin)
--git	git init + initial commit — a repo from birth (ADR 0096 D6)
--dir	target dir (default: the live plugins dir the loader discovers)

new-bundle

python -m server plugin new-bundle [-h] [--summary SUMMARY] [--member id=url[@ref]] [--builtin id] [--dir DIR] name

Scaffold a plugin BUNDLE (protoagent.bundle.yaml, ADR 0040).

Argument	Meaning
name	human name for the bundle (slugified to its id)
--summary	one-line description (default 'A protoAgent plugin bundle.')
--member	a git plugin member; repeatable (e.g. --member board=https://github.com/you/board@v0.1.0) (default [])
--builtin	a built-in member that ships with protoAgent; repeatable (e.g. --builtin delegates) (default [])
--dir	target dir (default: the live plugins dir)

install

python -m server plugin install [-h] [--ref REF] [--force] [--install-runtime-deps] url

Install a plugin — or a bundle of plugins — from a git URL (does NOT enable it).

Argument	Meaning
url	git URL (https://, ssh://, git@, or a local path) of a plugin or a bundle repo
--ref	tag, branch, or commit SHA to pin (default: default branch HEAD)
--force	replace an already-installed plugin of the same id
--install-runtime-deps	desktop app only: also pip missing required deps into its managed Python runtime as part of the install (the non-interactive opt-in fleet/archetype provisioning uses; by default they are left for plugin install-deps or the console's confirm). No effect on a server install.

list

python -m server plugin list [-h]

List git-installed plugins (from plugins.lock).

uninstall

python -m server plugin uninstall [-h] [--purge] id

Remove a git-installed plugin (code + lock + enabled ref).

Argument	Meaning
id	the plugin id to remove (as it appears in plugin list)
--purge	also remove the plugin's config section + secrets

update-bundle

python -m server plugin update-bundle [-h] [--ref REF] [--install-runtime-deps] id

Re-resolve a bundle's ref + reinstall members at the new pins (#2718; code+lock only — a running server picks the new code up on restart/reload).

Argument	Meaning
id	the bundle id (see plugins.lock bundles[])
--ref	override the recorded ref (tag/branch/SHA)
--install-runtime-deps	desktop app only: also pip missing required deps into its managed Python runtime as part of the install (the non-interactive opt-in fleet/archetype provisioning uses; by default they are left for plugin install-deps or the console's confirm). No effect on a server install.

uninstall-bundle

python -m server plugin uninstall-bundle [-h] [--purge] id

Remove a bundle: its exclusively-owned members + the lock row (shared members stay).

Argument	Meaning
id	the bundle id
--purge	also remove each member's config + secrets

sync

python -m server plugin sync [-h]

Re-clone locked plugins at their pinned SHA (reproducible set).

install-deps

python -m server plugin install-deps [-h] id

Pip-install a plugin's declared requires_pip (explicit code-exec).

Argument	Meaning
id	the plugin id whose declared deps to install