Plugin Management

Overview
Examples
Features
Troubleshooting

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”)
`upgrade`		Upgrade a plugin from version 0.x to 1.x using AI-powered migration	`<path>` (GitHub repository URL or local folder path)	`--api-key`, `--skip-tests`, `--skip-validation`, `--quiet`, `--verbose`, `--debug`, `--skip-confirmation`
`generate`		Generate a new plugin using AI-powered code generation		`--api-key`, `--skip-tests`, `--skip-validation`, `--skip-prompts`, `--spec-file`

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

Upgrading Plugins (AI-Powered)

# Upgrade a plugin from v0.x to v1.x using AI migration
elizaos plugins upgrade https://github.com/user/plugin-v0

# Upgrade from local folder
elizaos plugins upgrade ./path/to/old-plugin

# Provide API key directly
elizaos plugins upgrade ./my-plugin --api-key your-api-key

# Skip test validation
elizaos plugins upgrade ./my-plugin --skip-tests

# Skip production readiness validation
elizaos plugins upgrade ./my-plugin --skip-validation

# Run upgrade with all skips (faster but less safe)
elizaos plugins upgrade ./my-plugin --skip-tests --skip-validation

# Run upgrade in quiet mode (minimal output)
elizaos plugins upgrade ./my-plugin --quiet

# Run upgrade with verbose output for debugging
elizaos plugins upgrade ./my-plugin --verbose

# Run upgrade with debug information
elizaos plugins upgrade ./my-plugin --debug

# Skip confirmation prompts (useful for automation)
elizaos plugins upgrade ./my-plugin --skip-confirmation

Generating New Plugins (AI-Powered)

# Generate a new plugin interactively
elizaos plugins generate

# Generate with API key directly
elizaos plugins generate --api-key your-api-key

# Generate from specification file (non-interactive)
elizaos plugins generate --spec-file ./plugin-spec.json --skip-prompts

# Skip test validation during generation
elizaos plugins generate --skip-tests

# Skip production readiness validation
elizaos plugins generate --skip-validation

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

AI-Powered Plugin Development

elizaOS includes AI-powered features to help with plugin development:

Plugin Generation

The generate command uses AI to create a new plugin based on your specifications:

Interactive Mode: Guides you through plugin requirements
Code Generation: Creates complete plugin structure with actions, providers, and tests
Validation: Ensures generated code follows elizaOS best practices

Plugin Migration

The upgrade command helps migrate v0.x plugins to v1.x format:

Automated Analysis: Analyzes existing plugin structure
Code Transformation: Updates APIs, imports, and patterns
Test Migration: Converts tests to new format
Validation: Ensures migrated plugin works correctly

Requirements

Both AI features require an Anthropic API key:

Set via environment: export ANTHROPIC_API_KEY=your-api-key
Or pass directly: --api-key your-api-key

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

AI Feature Issues

# Missing API key error
export ANTHROPIC_API_KEY=your-anthropic-key-here

# Or pass directly to command
elizaos plugins generate --api-key your-anthropic-key-here

# Invalid specification file
# Ensure spec file is valid JSON
cat plugin-spec.json | jq .

# Generation/Upgrade timeout
# Skip validation for faster iteration
elizaos plugins generate --skip-tests --skip-validation

# Out of memory during AI operations
# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=8192" elizaos plugins upgrade ./my-plugin

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

Getting Started

Commands

Usage

Subcommands

Listing Available Plugins

Adding Plugins

Activating Plugins

Listing Installed Plugins

Removing Plugins

Upgrading Plugins (AI-Powered)

Generating New Plugins (AI-Powered)

Plugin Installation Formats

Package Names

GitHub Integration

Version Control

Plugin Development Workflow

1. Create a Plugin

2. Install in Your Project

3. Test Your Plugin

4. Publish Your Plugin

AI-Powered Plugin Development

Plugin Generation

Plugin Migration

Requirements

Troubleshooting

Plugin Installation Failures

Bun Installation Issues

Network Issues

Plugin Not Found

Dependency Conflicts

Environment Variable Issues

Branch/Tag Issues

AI Feature Issues

Getting Started

Commands

​Usage

​Subcommands

​Listing Available Plugins

​Adding Plugins

​Activating Plugins

​Listing Installed Plugins

​Removing Plugins

​Upgrading Plugins (AI-Powered)

​Generating New Plugins (AI-Powered)

​Plugin Installation Formats

​Package Names

​GitHub Integration

​Version Control

​Plugin Development Workflow

​1. Create a Plugin

​2. Install in Your Project

​3. Test Your Plugin

​4. Publish Your Plugin

​AI-Powered Plugin Development

​Plugin Generation

​Plugin Migration

​Requirements

​Troubleshooting

​Plugin Installation Failures

​Bun Installation Issues

​Network Issues

​Plugin Not Found

​Dependency Conflicts

​Environment Variable Issues

​Branch/Tag Issues

​AI Feature Issues

​Related Commands

Usage

Subcommands

Listing Available Plugins

Adding Plugins

Activating Plugins

Listing Installed Plugins

Removing Plugins

Upgrading Plugins (AI-Powered)

Generating New Plugins (AI-Powered)

Plugin Installation Formats

Package Names

GitHub Integration

Version Control

Plugin Development Workflow

1. Create a Plugin

2. Install in Your Project

3. Test Your Plugin

4. Publish Your Plugin

AI-Powered Plugin Development

Plugin Generation

Plugin Migration

Requirements

Troubleshooting

Plugin Installation Failures

Bun Installation Issues

Network Issues

Plugin Not Found

Dependency Conflicts

Environment Variable Issues

Branch/Tag Issues

AI Feature Issues

Related Commands