Plugin Management

Manage elizaOS plugins within a project - list, add, remove

Overview

Usage

elizaos plugins [options] [command]

Subcommands

Subcommand	Aliases	Description	Arguments	Options
list	l, ls	List available plugins to install into the project (shows v1.x plugins by default)		--all (detailed version info), --v0 (v0.x compatible only)
add	install	Add a plugin to the project	<plugin> (plugin name e.g., “abc”, “plugin-abc”, “elizaos/plugin-abc”)	-s, --skip-env-prompt, --skip-verification, -b, --branch, -T, --tag
installed-plugins		List plugins found in the project dependencies
remove	delete, del, rm	Remove a plugin from the project	<plugin> (plugin name e.g., “abc”, “plugin-abc”, “elizaos/plugin-abc”)

Examples

Listing Available Plugins

# List available v1.x plugins (default behavior)
elizaos plugins list

# Using alias
elizaos plugins l

# List all plugins with detailed version information
elizaos plugins list --all

# List only v0.x compatible plugins
elizaos plugins list --v0

Adding Plugins

# Add a plugin by short name (looks up '@elizaos/plugin-openai')
elizaos plugins add openai

# Add a plugin by full package name
elizaos plugins add @elizaos/plugin-anthropic

# Add plugin and skip environment variable prompts
elizaos plugins add google-ai --skip-env-prompt

# Skip plugin verification after installation
elizaos plugins add discord --skip-verification

# Add plugin from specific branch (for monorepo development)
elizaos plugins add custom-plugin --branch feature/new-api

# Add a specific version/tag of a plugin from npm
elizaos plugins add elevenlabs --tag latest

# Install plugin directly from GitHub (HTTPS URL)
elizaos plugins add https://github.com/owner/my-plugin

# Install from GitHub with branch reference
elizaos plugins add https://github.com/owner/my-plugin/tree/feature-branch

# Install using GitHub shorthand syntax
elizaos plugins add github:owner/my-plugin

# Install specific branch using GitHub shorthand
elizaos plugins add github:owner/my-plugin#feature-branch

# Using alias
elizaos plugins install openai

After installing plugins via CLI, you must add them to your character file (.json or .ts) to activate them. Installing only adds the package to your project dependencies.

Activating Plugins

character.json

{
  "name": "MyAgent",
  "plugins": [
    "@elizaos/plugin-sql",
    "@elizaos/plugin-openai",
    "@elizaos/plugin-discord"
  ],
  "bio": ["Your agent's description"],
  "style": {
    "all": ["conversational", "friendly"]
  }
}

character.ts

import { Character } from '@elizaos/core';

export const character: Character = {
  name: "MyAgent",
  plugins: [
    // Core plugins
    "@elizaos/plugin-sql",
    
    // Conditional plugins based on environment variables
    ...(process.env.OPENAI_API_KEY ? ["@elizaos/plugin-openai"] : []),
    ...(process.env.DISCORD_API_TOKEN ? ["@elizaos/plugin-discord"] : []),
    ...(process.env.ANTHROPIC_API_KEY ? ["@elizaos/plugin-anthropic"] : [])
  ],
  bio: ["Your agent's description"],
  style: {
    all: ["conversational", "friendly"]
  }
};

The SQL plugin (@elizaos/plugin-sql) is typically included by default as it provides core database functionality. Other plugins can be loaded conditionally based on environment variables to avoid loading unnecessary dependencies.

Listing Installed Plugins

# Show plugins currently in your project's package.json
elizaos plugins installed-plugins

Removing Plugins

# Remove plugin by short name
elizaos plugins remove openai

# Remove plugin by full package name
elizaos plugins remove @elizaos/plugin-anthropic

# Using aliases
elizaos plugins delete openai
elizaos plugins del twitter
elizaos plugins rm discord

Features

Plugin Installation Formats

The add command supports multiple plugin formats:

Package Names

# Short name (auto-resolves to @elizaos/plugin-*)
elizaos plugins add openai

# Full package name
elizaos plugins add @elizaos/plugin-openai

# Scoped packages
elizaos plugins add @company/plugin-custom

GitHub Integration

# HTTPS URL
elizaos plugins add https://github.com/user/my-plugin

# GitHub shorthand
elizaos plugins add github:user/my-plugin

# With branch/tag
elizaos plugins add github:user/my-plugin#feature-branch

Version Control

# Specific npm tag
elizaos plugins add plugin-name --tag beta

# Development branch (for monorepo)
elizaos plugins add plugin-name --branch main

Plugin Development Workflow

1. Create a Plugin

elizaos create -t plugin my-awesome-plugin
cd plugin-my-awesome-plugin

2. Install in Your Project

# During development, install from local directory
elizaos plugins add ./path/to/plugin-my-awesome-plugin

# Or install from your development branch
elizaos plugins add my-awesome-plugin --branch feature/new-feature

3. Test Your Plugin

# Start development mode
elizaos dev

# Run tests
elizaos test

4. Publish Your Plugin

For detailed instructions on authentication, plugin requirements, and the full publishing process, see the publish command documentation.

# Test the publishing process before committing
elizaos publish --test

# Publish to the registry
elizaos publish

Troubleshooting

Troubleshooting

Plugin Installation Failures

# Clear cache and retry
rm -rf ~/.eliza/cache
elizaos plugins add plugin-name

Bun Installation Issues

# If you see "bun: command not found" errors
# Install Bun using the appropriate command for your system:

# Linux/macOS:
curl -fsSL https://bun.sh/install | bash

# Windows:
powershell -c "irm bun.sh/install.ps1 | iex"

# macOS with Homebrew:
brew install bun

# After installation, restart your terminal or:
source ~/.bashrc  # Linux
source ~/.zshrc   # macOS with zsh

# Verify installation:
bun --version

Network Issues

# For GitHub authentication problems
git config --global credential.helper store

# For registry issues
bun config set registry https://registry.npmjs.org/
elizaos plugins add plugin-name

Plugin Not Found

# Check exact plugin name in registry
elizaos plugins list

# Try different naming formats
elizaos plugins add openai                    # Short name
elizaos plugins add @elizaos/plugin-openai   # Full package name
elizaos plugins add plugin-openai            # With plugin prefix

Dependency Conflicts

# If dependency installation fails
cd your-project
bun install

# Check for conflicting dependencies
bun pm ls

# Force reinstall
rm -rf node_modules
bun install

Environment Variable Issues

# If plugin prompts for missing environment variables
elizaos env set OPENAI_API_KEY your-key

# Skip environment prompts during installation
elizaos plugins add plugin-name --skip-env-prompt

Branch/Tag Issues

# If branch doesn't exist
git ls-remote --heads https://github.com/user/repo

# If tag doesn't exist
git ls-remote --tags https://github.com/user/repo

# Use correct branch/tag name
elizaos plugins add plugin-name --branch main
elizaos plugins add plugin-name --tag v1.0.0

Related Commands

• create: Create a new project or plugin
• env: Manage environment variables needed by plugins
• publish: Publish your plugin to the registry