> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elizaos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Management

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

<Tabs>
  <Tab title="Overview">
    ## Usage

    ```bash theme={null}
    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") |                                                                             |
  </Tab>

  <Tab title="Examples">
    ### Listing Available Plugins

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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
    ```

    <Warning>
      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.
    </Warning>

    #### Activating Plugins

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

    ```typescript character.ts theme={null}
    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"]
      }
    };
    ```

    <Note>
      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.
    </Note>

    ### Listing Installed Plugins

    ```bash theme={null}
    # Show plugins currently in your project's package.json
    elizaos plugins installed-plugins
    ```

    ### Removing Plugins

    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Features">
    ## Plugin Installation Formats

    The `add` command supports multiple plugin formats:

    ### Package Names

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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

    ```bash theme={null}
    elizaos create -t plugin my-awesome-plugin
    cd plugin-my-awesome-plugin
    ```

    ### 2. Install in Your Project

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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**](/cli-reference/publish).

    ```bash theme={null}
    # Test the publishing process before committing
    elizaos publish --test

    # Publish to the registry
    elizaos publish
    ```
  </Tab>

  <Tab title="Troubleshooting">
    ## Troubleshooting

    ### Plugin Installation Failures

    ```bash theme={null}
    # Clear cache and retry
    rm -rf ~/.eliza/cache
    elizaos plugins add plugin-name
    ```

    ### Bun Installation Issues

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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`](/cli-reference/create): Create a new project or plugin
    * [`env`](/cli-reference/env): Manage environment variables needed by plugins
    * [`publish`](/cli-reference/publish): Publish your plugin to the registry
  </Tab>
</Tabs>