plugins add

One command installs a plugin package and tells you exactly which plugins registered — or exits non-zero if nothing did. Previously a package could pip install cleanly yet register nothing — a silent failure. plugins add turns that into a surfaced non-zero exit.

Quick Start

Install a plugin

praisonai plugins add praisonai-my-plugin

praisonai-my-plugin is a placeholder — replace it with a real pip requirement spec.

Upgrade an installed plugin

praisonai plugins add praisonai-my-plugin --upgrade

Verify without installing

praisonai plugins add praisonai-my-plugin --dry-run

--dry-run skips installation and reports whether anything new would register from what’s already installed.

After installing, run praisonai plugins reload to pick the plugin up in the current process without a restart — see Plugins CLI → reload.

How It Works

The command snapshots registered plugins, installs, refreshes discovery, then reports the diff.

Step	What happens
Snapshot	Records current entry-point plugin names via `get_plugin_manager().list_plugins()`
Install	Skipped on `--dry-run`; otherwise runs the resolved installer command
Refresh	`get_plugin_manager().discover_entry_points()` scans the `praisonai.plugins` group
Diff	`sorted(after − before)` — new names become table rows

Built-in names can’t be taken over. PraisonAI’s registries subclass the base PluginRegistry, so since PR #4176 an entry point whose name (case-insensitive) matches a shipped built-in is skipped during discovery — it never appears in the “Registered” diff, and a DEBUG line notes the collision. Ship your plugin under a distinct name, or override deliberately with a runtime register(...) call. See Plugin Precedence.

Options

Argument / flag	Type	Default	Description
`package`	positional `str`	(required)	pip requirement spec — anything `pip install` / `uv pip install` accepts (name, `name==1.2.3`, VCS URL, path, extras)
`--dry-run`	flag	`False`	Skip installation; run discovery only. Exits non-zero if nothing new is discovered
`--upgrade`, `-U`	flag	`False`	Append `--upgrade` so an already-installed package is upgraded
`--global`	flag	`False`	Install into the ambient/system environment instead of the CLI interpreter

How the Installer Is Chosen

The command pins installation to the interpreter running the CLI so the package lands where discovery will look — not in a nearby .venv that uv might auto-discover. --upgrade appends --upgrade to whichever command runs, then the package spec.

Exit Codes

Situation	Exit code
At least one new plugin registered	`0`
Installer command returned non-zero	`1`
Install succeeded but nothing new discovered	`1`
`--dry-run` and nothing new discovered	`1`
`praisonaiagents` not importable at all	`1`

Output Shape

A successful run prints a Rich table titled Registered N plugin(s) from <package>:

        Registered 1 plugin from praisonai-my-plugin
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Plugin        ┃ Type      ┃ Hooks                  ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ my_plugin     │ plugin    │ before_tool,after_tool │
└───────────────┴───────────┴────────────────────────┘

On --dry-run the title verb is Discovered instead of Registered.

Common Patterns

Default (pin to CLI interpreter)
Global install
CI verification

praisonai plugins add praisonai-my-plugin

When uv is present, the package is pinned to the CLI interpreter so discovery finds it — not a nearby .venv.

praisonai plugins add praisonai-my-plugin --global

Installs into the ambient/system environment (uv pip install --system, or plain pip install).

praisonai plugins add praisonai-my-plugin --dry-run

Fails the job (exit 1) if the package no longer registers after another change — a cheap regression guard.

Best Practices

Use --dry-run in CI to catch silent breakage

A package can install cleanly yet register nothing. --dry-run exits non-zero when discovery finds nothing new, turning a silent failure into a failed check.

Prefer the default over --global

The default pins to the CLI interpreter so the plugin is discoverable by the same process. Reach for --global only when you deliberately want the system environment.

Pin versions for reproducible installs

Pass a full spec like praisonai-my-plugin==1.2.3 so the installed version is deterministic across machines.

Inspect after installing

Run praisonai plugins list to see everything registered, not just what this command added.

Plugins

Write, load, and configure plugins

Message-Lifecycle Plugins

Override before_message, after_message, message_sent, and message_undelivered

Plugins CLI

List, enable, disable, reload, and diagnose plugins

tools add

Install a tool package and verify its tools

Tool Source Registry

Plug third-party tool sources via entry points

Tool Resolver

Single source of truth for loading tools

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Options

How the Installer Is Chosen

Exit Codes

Output Shape

Common Patterns

Best Practices

Plugins

Message-Lifecycle Plugins

Plugins CLI

tools add

Tool Source Registry

Tool Resolver

​Quick Start

​How It Works

​Options

​How the Installer Is Chosen

​Exit Codes

​Output Shape

​Common Patterns

​Best Practices

​Related

Plugins

Message-Lifecycle Plugins

Plugins CLI

tools add

Tool Source Registry

Tool Resolver

Quick Start

How It Works

Options

How the Installer Is Chosen

Exit Codes

Output Shape

Common Patterns

Best Practices

Related